Skip to content

Commit b819cc5

Browse files
jmooringjmooring
committed
content: Add hugo.Sites and update the other Sites methods
1 parent f4d7f12 commit b819cc5

File tree

4 files changed

+148
-15
lines changed

4 files changed

+148
-15
lines changed

‎content/en/_common/functions/hugo/sites-collection.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
_comment: Do not remove front matter.
3+
---
4+
5+
The returned collection follows a tiered sort based on the [dimensions](g) of your project where each dimension is evaluated according to the following priority.
6+
7+
1. [Language](g) sorted by [weight](g) in ascending order. If weights are tied or undefined Hugo defaults to lexicographical order.
8+
1. [Role](g) sorted by weight in ascending order. If weights are tied or undefined Hugo defaults to lexicographical order.
9+
1. [Version](g) sorted by weight in ascending order. If weights are tied or undefined Hugo defaults to sorting semantically in descending order.
10+
11+
The logic follows a hierarchical structure where each subsequent dimension acts as a tie-breaker for the one above it.

‎content/en/functions/hugo/Sites.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: hugo.Sites
3+
description: Returns a collection of all sites for all dimensions.
4+
categories: []
5+
keywords: []
6+
params:
7+
functions_and_methods:
8+
aliases: []
9+
returnType: page.Sites
10+
signatures: [hugo.Sites]
11+
---
12+
13+
{{< new-in 0.156.0 />}}
14+
15+
{{% include "/_common/functions/hugo/sites-collection.md" %}}
16+
17+
With this site configuration:
18+
19+
{{< code-toggle file=hugo >}}
20+
defaultContentLanguage = 'de'
21+
defaultContentLanguageInSubdir = true
22+
defaultContentVersionInSubdir = true
23+
24+
[languages.de]
25+
contentDir = 'content/de'
26+
languageCode = 'de-DE'
27+
languageDirection = 'ltr'
28+
languageName = 'Deutsch'
29+
title = 'Projekt Dokumentation'
30+
weight = 1
31+
32+
[languages.en]
33+
contentDir = 'content/en'
34+
languageCode = 'en-US'
35+
languageDirection = 'ltr'
36+
languageName = 'English'
37+
title = 'Project Documentation'
38+
weight = 2
39+
40+
[versions.'v1.0.0']
41+
[versions.'v2.0.0']
42+
[versions.'v3.0.0']
43+
{{< /code-toggle >}}
44+
45+
This template:
46+
47+
```go-html-template
48+
<ul>
49+
{{ range hugo.Sites }}
50+
<li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
51+
{{ end }}
52+
</ul>
53+
```
54+
55+
Produces a list of links to each home page:
56+
57+
```html
58+
<ul>
59+
<li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
60+
<li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
61+
<li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
62+
<li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
63+
<li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
64+
<li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
65+
</ul>
66+
```
67+
68+
To render a link to the home page of the [default site](g):
69+
70+
<!-- TODO See https://github.com/gohugoio/hugo/issues/14531
71+
```go-html-template
72+
{{ with hugo.Sites.Default }}
73+
<a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
74+
{{ end }}
75+
```
76+
77+
This is equivalent to:
78+
-->
79+
80+
```go-html-template
81+
{{ with index hugo.Sites 0 }}
82+
<a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
83+
{{ end }}
84+
```

‎content/en/methods/page/Sites.md‎

Lines changed: 26 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,57 @@
11
---
22
title: Sites
3-
description: Returns a collection of all Site objects, one for each language, ordered by language weight.
3+
description: Returns a collection of all sites for all dimensions.
44
categories: []
55
keywords: []
66
params:
77
functions_and_methods:
88
returnType: page.Sites
99
signatures: [PAGE.Sites]
10+
expiryDate: '2028-02-17' # deprecated 2026-02-17 in v0.156.0
1011
---
1112

12-
This is a convenience method to access `.Site.Sites`.
13+
{{< deprecated-in 0.156.0 >}}
14+
Use [`hugo.Sites`] instead.
15+
16+
[`hugo.Sites`]: /functions/hugo/sites/
17+
{{< /deprecated-in >}}
18+
19+
{{% include "/_common/functions/hugo/sites-collection.md" %}}
1320

1421
With this site configuration:
1522

1623
{{< code-toggle file=hugo >}}
1724
defaultContentLanguage = 'de'
18-
defaultContentLanguageInSubdir = false
25+
defaultContentLanguageInSubdir = true
26+
defaultContentVersionInSubdir = true
1927

2028
[languages.de]
29+
contentDir = 'content/de'
2130
languageCode = 'de-DE'
2231
languageDirection = 'ltr'
2332
languageName = 'Deutsch'
2433
title = 'Projekt Dokumentation'
2534
weight = 1
2635

2736
[languages.en]
37+
contentDir = 'content/en'
2838
languageCode = 'en-US'
2939
languageDirection = 'ltr'
3040
languageName = 'English'
3141
title = 'Project Documentation'
3242
weight = 2
43+
44+
[versions.'v1.0.0']
45+
[versions.'v2.0.0']
46+
[versions.'v3.0.0']
3347
{{< /code-toggle >}}
3448

3549
This template:
3650

3751
```go-html-template
3852
<ul>
3953
{{ range .Sites }}
40-
<li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li>
54+
<li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
4155
{{ end }}
4256
</ul>
4357
```
@@ -46,23 +60,27 @@ Produces a list of links to each home page:
4660

4761
```html
4862
<ul>
49-
<li><a href="https://example.org/de/">Projekt Dokumentation</a></li>
50-
<li><a href="https://example.org/en/">Project Documentation</a></li>
63+
<li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
64+
<li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
65+
<li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
66+
<li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
67+
<li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
68+
<li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
5169
</ul>
5270
```
5371

5472
To render a link to the home page of the [default site](g):
5573

5674
```go-html-template
5775
{{ with .Sites.Default }}
58-
<a href="{{ .Home.Permalink }}">{{ .Title }}</a>
76+
<a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
5977
{{ end }}
6078
```
6179

6280
This is equivalent to:
6381

6482
```go-html-template
6583
{{ with index .Sites 0 }}
66-
<a href="{{ .Home.Permalink }}">{{ .Title }}</a>
84+
<a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
6785
{{ end }}
6886
```

‎content/en/methods/site/Sites.md‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,57 @@
11
---
22
title: Sites
3-
description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight.
3+
description: Returns a collection of all sites for all dimensions.
44
categories: []
55
keywords: []
66
params:
77
functions_and_methods:
88
returnType: page.Sites
99
signatures: [SITE.Sites]
10+
expiryDate: '2028-02-17' # deprecated 2026-02-17 in v0.156.0
1011
---
1112

13+
{{< deprecated-in 0.156.0 >}}
14+
Use [`hugo.Sites`] instead.
15+
16+
[`hugo.Sites`]: /functions/hugo/sites/
17+
{{< /deprecated-in >}}
18+
19+
{{% include "/_common/functions/hugo/sites-collection.md" %}}
20+
1221
With this site configuration:
1322

1423
{{< code-toggle file=hugo >}}
1524
defaultContentLanguage = 'de'
16-
defaultContentLanguageInSubdir = false
25+
defaultContentLanguageInSubdir = true
26+
defaultContentVersionInSubdir = true
1727

1828
[languages.de]
29+
contentDir = 'content/de'
1930
languageCode = 'de-DE'
2031
languageDirection = 'ltr'
2132
languageName = 'Deutsch'
2233
title = 'Projekt Dokumentation'
2334
weight = 1
2435

2536
[languages.en]
37+
contentDir = 'content/en'
2638
languageCode = 'en-US'
2739
languageDirection = 'ltr'
2840
languageName = 'English'
2941
title = 'Project Documentation'
3042
weight = 2
43+
44+
[versions.'v1.0.0']
45+
[versions.'v2.0.0']
46+
[versions.'v3.0.0']
3147
{{< /code-toggle >}}
3248

3349
This template:
3450

3551
```go-html-template
3652
<ul>
3753
{{ range .Site.Sites }}
38-
<li><a href="{{ .Home.Permalink }}">{{ .Title }}</a></li>
54+
<li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
3955
{{ end }}
4056
</ul>
4157
```
@@ -44,23 +60,27 @@ Produces a list of links to each home page:
4460

4561
```html
4662
<ul>
47-
<li><a href="https://example.org/de/">Projekt Dokumentation</a></li>
48-
<li><a href="https://example.org/en/">Project Documentation</a></li>
63+
<li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
64+
<li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
65+
<li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
66+
<li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
67+
<li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
68+
<li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
4969
</ul>
5070
```
5171

5272
To render a link to the home page of the [default site](g):
5373

5474
```go-html-template
5575
{{ with .Site.Sites.Default }}
56-
<a href="{{ .Home.Permalink }}">{{ .Title }}</a>
76+
<a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
5777
{{ end }}
5878
```
5979

6080
This is equivalent to:
6181

6282
```go-html-template
6383
{{ with index .Site.Sites 0 }}
64-
<a href="{{ .Home.Permalink }}">{{ .Title }}</a>
84+
<a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
6585
{{ end }}
6686
```

0 commit comments

Comments
 (0)