Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
987 changed files with 12379 additions and 14083 deletions

View File

@@ -3,16 +3,13 @@ title: AllPages
description: Returns a collection of all pages in all languages.
categories: []
keywords: []
action:
related:
- methods/site/Pages
- methods/site/RegularPages
- methods/site/Sections
returnType: page.Pages
signatures: [SITE.AllPages]
params:
functions_and_methods:
returnType: page.Pages
signatures: [SITE.AllPages]
---
This method returns all page [kinds](g) in all languages. That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
This method returns all page [kinds](g) in all languages, in the [default sort order](g). That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
In most cases you should use the [`RegularPages`] method instead.

View File

@@ -3,14 +3,10 @@ title: BaseURL
description: Returns the base URL as defined in the site configuration.
categories: []
keywords: []
action:
related:
- functions/urls/AbsURL
- functions/urls/AbsLangURL
- functions/urls/RelURL
- functions/urls/RelLangURL
returnType: string
signatures: [SITE.BaseURL]
params:
functions_and_methods:
returnType: string
signatures: [SITE.BaseURL]
---
Site configuration:
@@ -25,13 +21,12 @@ Template:
{{ .Site.BaseURL }} → https://example.org/docs/
```
{{% note %}}
There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration.
> [!note]
> There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration.
>
> Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead.
Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead.
[`absURL`]: /functions/urls/absURL/
[`absLangURL`]: /functions/urls/absLangURL/
[`relURL`]: /functions/urls/relURL/
[`absURL`]: /functions/urls/absURL/
[`relLangURL`]: /functions/urls/relLangURL/
{{% /note %}}
[`relURL`]: /functions/urls/relURL/

View File

@@ -3,10 +3,10 @@ title: BuildDrafts
description: Reports whether the current build includes draft pages.
categories: []
keywords: []
action:
related: []
returnType: bool
signatures: [SITE.BuildDrafts]
params:
functions_and_methods:
returnType: bool
signatures: [SITE.BuildDrafts]
---
By default, draft pages are not published when building a site. You can change this behavior with a command line flag:

View File

@@ -3,20 +3,17 @@ title: Config
description: Returns a subset of the site configuration.
categories: []
keywords: []
action:
related: []
returnType: page.SiteConfig
signatures: [SITE.Config]
toc: true
params:
functions_and_methods:
returnType: page.SiteConfig
signatures: [SITE.Config]
---
The `Config` method on a `Site` object provides access to a subset of the site configuration, specifically the `services` and `privacy` keys.
## Services
These are the default service settings, typically used by Hugo's built-in templates and shortcodes.
{{< code-toggle config=services />}}
See [configure services](/configuration/services).
For example, to use Hugo's built-in Google Analytics template you must add a [Google tag ID]:
@@ -37,9 +34,7 @@ You must capitalize each identifier as shown above.
## Privacy
These are the default privacy settings, typically used by Hugo's built-in templates and shortcodes:
{{< code-toggle config=privacy />}}
See [configure privacy](/configuration/privacy).
For example, to disable usage of the built-in YouTube shortcode:

View File

@@ -1,12 +1,12 @@
---
title: Copyright
description: Returns the copyright notice as defined in the site configuration.
description: Returns the copyright notice as defined in the site configuration.
categories: []
keywords: []
action:
related: []
returnType: string
signatures: [SITE.Copyright]
params:
functions_and_methods:
returnType: string
signatures: [SITE.Copyright]
---
Site configuration:

View File

@@ -3,25 +3,16 @@ title: Data
description: Returns a data structure composed from the files in the data directory.
categories: []
keywords: []
action:
related:
- functions/collections/IndexFunction
- functions/transform/Unmarshal
- functions/collections/Where
- functions/collections/Sort
returnType: map
signatures: [SITE.Data]
params:
functions_and_methods:
returnType: map
signatures: [SITE.Data]
---
Use the `Data` method on a `Site` object to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML.
[mounted]: /hugo-modules/configuration/#module-configuration-mounts
{{% note %}}
Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method.
[`transform.Unmarshal`]: /functions/transform/unmarshal/
{{% /note %}}
> [!note]
> Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method.
Consider this `data` directory:
@@ -37,23 +28,23 @@ data/
And these data files:
{{< code file=data/books/fiction.yaml lang=yaml >}}
```yaml {file="data/books/fiction.yaml"}
- title: The Hunchback of Notre Dame
author: Victor Hugo
isbn: 978-0140443530
- title: Les Misérables
author: Victor Hugo
isbn: 978-0451419439
{{< /code >}}
```
{{< code file=data/books/nonfiction.yaml lang=yaml >}}
```yaml {file="data/books/nonfiction.yaml"}
- title: The Ancien Régime and the Revolution
author: Alexis de Tocqueville
isbn: 978-0141441641
- title: Interpreting the French Revolution
author: François Furet
isbn: 978-0521280495
{{< /code >}}
```
Access the data by [chaining](g) the [identifiers](g):
@@ -108,3 +99,5 @@ In the template examples above, each of the keys is a valid identifier. For exam
```
[`index`]: /functions/collections/indexfunction/
[`transform.Unmarshal`]: /functions/transform/unmarshal/
[mounted]: /configuration/module/#mounts

View File

@@ -3,15 +3,15 @@ title: DisqusShortname
description: Returns the Disqus shortname as defined in the site configuration.
categories: []
keywords: []
action:
related: []
returnType: string
signatures: [SITE.DisqusShortname]
params:
functions_and_methods:
returnType: string
signatures: [SITE.DisqusShortname]
expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0
---
{{% deprecated-in 0.120.0 %}}
{{< deprecated-in 0.120.0 >}}
Use [`Site.Config.Services.Disqus.Shortname`] instead.
[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config/
{{% /deprecated-in %}}
{{< /deprecated-in >}}

View File

@@ -3,12 +3,10 @@ title: GetPage
description: Returns a Page object from the given path.
categories: []
keywords: []
action:
related:
- methods/page/GetPage
returnType: page.Page
signatures: [SITE.GetPage PATH]
toc: true
params:
functions_and_methods:
returnType: page.Page
signatures: [SITE.GetPage PATH]
---
The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See&nbsp;[details].

View File

@@ -3,15 +3,15 @@ title: GoogleAnalytics
description: Returns the Google Analytics tracking ID as defined in the site configuration.
categories: []
keywords: []
action:
related: []
returnType: string
signatures: [SITE.GoogleAnalytics]
params:
functions_and_methods:
returnType: string
signatures: [SITE.GoogleAnalytics]
expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0
---
{{% deprecated-in 0.120.0 %}}
{{< deprecated-in 0.120.0 >}}
Use [`Site.Config.Services.GoogleAnalytics.ID`] instead.
[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config/
{{% /deprecated-in %}}
{{< /deprecated-in >}}

View File

@@ -3,10 +3,10 @@ title: Home
description: Returns the home Page object for the given site.
categories: []
keywords: []
action:
related: []
returnType: page.Page
signatures: [SITE.Home]
params:
functions_and_methods:
returnType: page.Page
signatures: [SITE.Home]
---
This method is useful for obtaining a link to the home page.

View File

@@ -3,15 +3,15 @@ title: IsDevelopment
description: Reports whether the current running environment is “development”.
categories: []
keywords: []
action:
related: []
returnType: bool
signatures: [SITE.IsDevelopment]
params:
functions_and_methods:
returnType: bool
signatures: [SITE.IsDevelopment]
expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0
---
{{% deprecated-in 0.120.0 %}}
{{< deprecated-in 0.120.0 >}}
Use [`hugo.IsDevelopment`] instead.
[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment/
{{% /deprecated-in %}}
{{< /deprecated-in >}}

View File

@@ -3,15 +3,15 @@ title: IsMultiLingual
description: Reports whether there are two or more configured languages.
categories: []
keywords: []
action:
related: []
returnType: bool
signatures: [SITE.IsMultiLingual]
params:
functions_and_methods:
returnType: bool
signatures: [SITE.IsMultiLingual]
expiryDate: 2026-03-16 # deprecated 2024-03-16 in 0.124.0
---
{{% deprecated-in 0.124.0 %}}
{{< deprecated-in 0.124.0 >}}
Use [`hugo.IsMultilingual`] instead.
[`hugo.IsMultilingual`]: /functions/hugo/ismultilingual/
{{% /deprecated-in %}}
{{< /deprecated-in >}}

View File

@@ -3,15 +3,15 @@ title: IsServer
description: Reports whether the built-in development server is running.
categories: []
keywords: []
action:
related: []
returnType: bool
signatures: [SITE.IsServer]
params:
functions_and_methods:
returnType: bool
signatures: [SITE.IsServer]
expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0
---
{{% deprecated-in 0.120.0 %}}
{{< deprecated-in 0.120.0 >}}
Use [`hugo.IsServer`] instead.
[`hugo.IsServer`]: /functions/hugo/isserver/
{{% /deprecated-in %}}
{{< /deprecated-in >}}

View File

@@ -1,14 +1,12 @@
---
title: Language
description: Returns the language object for the given site.
description: Returns the language object for the given site.
categories: []
keywords: []
action:
related:
- methods/page/language
returnType: langs.Language
signatures: [SITE.Language]
toc: true
params:
functions_and_methods:
returnType: langs.Language
signatures: [SITE.Language]
---
The `Language` method on a `Site` object returns the language object for the given site. The language object points to the language definition in the site configuration.
@@ -27,7 +25,7 @@ languageName = 'Deutsch'
weight = 1
{{< /code-toggle >}}
###### Lang
### Lang
(`string`) The language tag as defined by [RFC 5646].
@@ -35,7 +33,7 @@ weight = 1
{{ .Site.Language.Lang }} → de
```
###### LanguageCode
### LanguageCode
(`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
@@ -43,7 +41,7 @@ weight = 1
{{ .Site.Language.LanguageCode }} → de-DE
```
###### LanguageDirection
### LanguageDirection
(`string`) The language direction from the site configuration, either `ltr` or `rtl`.
@@ -51,7 +49,7 @@ weight = 1
{{ .Site.Language.LanguageDirection }} → ltr
```
###### LanguageName
### LanguageName
(`string`) The language name from the site configuration.
@@ -59,7 +57,7 @@ weight = 1
{{ .Site.Language.LanguageName }} → Deutsch
```
###### Weight
### Weight
(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.

View File

@@ -3,12 +3,10 @@ title: LanguagePrefix
description: Returns the URL language prefix, if any, for the given site.
categories: []
keywords: []
action:
related:
- functions/urls/AbsLangURL
- functions/urls/RelLangURL
returnType: string
signatures: [SITE.LanguagePrefix]
params:
functions_and_methods:
returnType: string
signatures: [SITE.LanguagePrefix]
---
Consider this site configuration:

View File

@@ -3,11 +3,10 @@ title: Languages
description: Returns a collection of language objects for all sites, ordered by language weight.
categories: []
keywords: []
action:
related:
- methods/site/Language
returnType: langs.Languages
signatures: [SITE.Languages]
params:
functions_and_methods:
returnType: langs.Languages
signatures: [SITE.Languages]
---
The `Languages` method on a `Site` object returns a collection of language objects for all sites, ordered by language weight. Each language object points to its language definition in the site configuration.

View File

@@ -3,15 +3,15 @@ title: LastChange
description: Returns the last modification date of site content.
categories: []
keywords: []
action:
related: []
returnType: time.Time
signatures: [SITE.LastChange]
params:
functions_and_methods:
returnType: time.Time
signatures: [SITE.LastChange]
expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0
---
{{% deprecated-in 0.123.0 %}}
{{< deprecated-in 0.123.0 >}}
Use [`.Site.Lastmod`] instead.
[`.Site.Lastmod`]: /methods/site/lastmod/
{{% /deprecated-in %}}
{{< /deprecated-in >}}

View File

@@ -3,10 +3,10 @@ title: Lastmod
description: Returns the last modification date of site content.
categories: []
keywords: []
action:
related: []
returnType: time.Time
signatures: [SITE.Lastmod]
params:
functions_and_methods:
returnType: time.Time
signatures: [SITE.Lastmod]
---
{{< new-in 0.123.0 />}}

View File

@@ -1,18 +1,17 @@
---
title: MainSections
description: Returns a slice of the main section names as defined in the site configuration, falling back to the top level section with the most pages.
description: Returns a slice of the main section names as defined in the site configuration, falling back to the top-level section with the most pages.
categories: []
keywords: []
action:
related: []
returnType: '[]string'
signatures: [SITE.MainSections]
params:
functions_and_methods:
returnType: '[]string'
signatures: [SITE.MainSections]
---
Site configuration:
{{< code-toggle file=hugo >}}
[params]
mainSections = ['books','films']
{{< /code-toggle >}}
@@ -22,7 +21,7 @@ Template:
{{ .Site.MainSections }} → [books films]
```
If `params.mainSections` is not defined in the site configuration, this method returns a slice with one element---the top level section with the most pages.
If `mainSections` is not defined in the site configuration, this method returns a slice with one element---the top-level section with the most pages.
With this content structure, the "films" section has the most pages:
@@ -44,7 +43,7 @@ Template:
{{ .Site.MainSections }} → [films]
```
When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct site authors to set `params.mainSections` in their site configuration.
When creating a theme, instead of hardcoding section names when listing the most relevant pages on the front page, instruct site authors to set `mainSections` in their site configuration.
Then your home template can do something like this:

View File

@@ -3,21 +3,16 @@ title: Menus
description: Returns a collection of menu objects for the given site.
categories: []
keywords: []
action:
related:
- methods/page/IsMenuCurrent
- methods/page/HasMenuCurrent
returnType: navigation.Menus
signatures: [SITE.Menus]
params:
functions_and_methods:
returnType: navigation.Menus
signatures: [SITE.Menus]
---
The `Menus` method on a `Site` object returns a collection of menus, where each menu contains one or more entries, either flat or nested. Each entry points to a page within the site, or to an external resource.
{{% note %}}
Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples.
[menus]: /content-management/menus/
{{% /note %}}
> [!note]
> Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples.
A site can have multiple menus. For example, a main menu and a footer menu:
@@ -88,7 +83,7 @@ You will typically render a menu using a partial template. As the active menu en
The example above is simplistic. Please see the [menu templates] section for more information.
[menu templates]: /templates/menu/
[`partial`]: /functions/partials/include/
[`partialCached`]: /functions/partials/includecached/
[menu templates]: /templates/menu/
[menus]: /content-management/menus/

View File

@@ -3,16 +3,13 @@ title: Pages
description: Returns a collection of all pages.
categories: []
keywords: []
action:
related:
- methods/site/AllPages
- methods/site/RegularPages
- methods/site/Sections
returnType: page.Pages
signatures: [SITE.Pages]
params:
functions_and_methods:
returnType: page.Pages
signatures: [SITE.Pages]
---
This method returns all page [kinds](g) in the current language. That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
This method returns all page [kinds](g) in the current language, in the [default sort order](g). That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
In most cases you should use the [`RegularPages`] method instead.

View File

@@ -3,10 +3,10 @@ title: Param
description: Returns the site parameter with the given key.
categories: []
keywords: []
action:
related: []
returnType: any
signatures: [SITE.Param KEY]
params:
functions_and_methods:
returnType: any
signatures: [SITE.Param KEY]
---
The `Param` method on a `Site` object is a convenience method to return the value of a user-defined parameter in the site configuration.

View File

@@ -3,13 +3,10 @@ title: Params
description: Returns a map of custom parameters as defined in the site configuration.
categories: []
keywords: []
action:
related:
- functions/collections/indexFunction
- methods/page/Params
- methods/page/Param
returnType: maps.Params
signatures: [SITE.Params]
params:
functions_and_methods:
returnType: maps.Params
signatures: [SITE.Params]
---
With this site configuration:

View File

@@ -3,16 +3,13 @@ title: RegularPages
description: Returns a collection of all regular pages.
categories: []
keywords: []
action:
related:
- methods/site/AllPages
- methods/site/RegularPages
- methods/site/Sections
returnType: page.Pages
signatures: [SITE.RegularPages]
params:
functions_and_methods:
returnType: page.Pages
signatures: [SITE.RegularPages]
---
The `RegularPages` method on a `Site` object returns a collection of all [regular pages](g).
The `RegularPages` method on a `Site` object returns a collection of all [regular pages](g), in the [default sort order](g).
```go-html-template
{{ range .Site.RegularPages }}
@@ -20,14 +17,9 @@ The `RegularPages` method on a `Site` object returns a collection of all [regula
{{ end }}
```
By default, Hugo sorts page collections by:
{{% glossary-term "default sort order" %}}
1. The page `weight` as defined in front matter
1. The page `date` as defined in front matter
1. The page `linkTitle` as defined in front matter
1. The file path
If the `linkTitle` is not defined, Hugo evaluates the `title` instead.
[default sort order](g)
To change the sort order, use any of the `Pages` [sorting methods]. For example:

View File

@@ -1,17 +1,16 @@
---
title: Sections
description: Returns a collection of first level section pages.
description: Returns a collection of top-level section pages.
categories: []
keywords: []
action:
related:
- methods/site/AllPages
- methods/site/Pages
- methods/site/RegularPages
returnType: page.Pages
signatures: [SITE.Sections]
params:
functions_and_methods:
returnType: page.Pages
signatures: [SITE.Sections]
---
The `Sections` method on a `Site` object returns a collection of top-level [section pages](g), in the [default sort order](g).
Given this content structure:
```text

View File

@@ -3,10 +3,10 @@ title: Sites
description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight.
categories: []
keywords: []
action:
related: []
returnType: page.Sites
signatures: [SITE.Sites]
params:
functions_and_methods:
returnType: page.Sites
signatures: [SITE.Sites]
---
With this site configuration:

View File

@@ -3,14 +3,10 @@ title: Store
description: Returns a "scratch pad" to store and manipulate data, scoped to the current site.
categories: []
keywords: []
action:
related:
- methods/page/store
- functions/hugo/store
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [site.Store]
toc: true
params:
functions_and_methods:
returnType: maps.Scratch
signatures: [site.Store]
---
{{< new-in 0.139.0 />}}
@@ -19,7 +15,7 @@ Use the `Store` method on a `Site` object to create a [scratch pad](g) to store
## Methods
###### Set
### Set
Sets the value of a given key.
@@ -27,7 +23,7 @@ Sets the value of a given key.
{{ site.Store.Set "greeting" "Hello" }}
```
###### Get
### Get
Gets the value of a given key.
@@ -36,7 +32,7 @@ Gets the value of a given key.
{{ site.Store.Get "greeting" }} → Hello
```
###### Add
### Add
Adds a given value to existing value(s) of the given key.
@@ -58,9 +54,9 @@ For single values, `Add` accepts values that support Go's `+` operator. If the f
{{ site.Store.Set "greetings" (slice "Hello") }}
{{ site.Store.Add "greetings" (slice "Welcome" "Cheers") }}
{{ site.Store.Get "greetings" }} → [Hello Welcome Cheers]
```
```
###### SetInMap
### SetInMap
Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
@@ -70,7 +66,7 @@ Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to th
{{ site.Store.Get "greetings" }} → map[english:Hello french:Bonjour]
```
###### DeleteInMap
### DeleteInMap
Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
@@ -81,7 +77,7 @@ Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
{{ site.Store.Get "greetings" }} → map[french:Bonjour]
```
###### GetSortedMapValues
### GetSortedMapValues
Returns an array of values from `key` sorted by `mapKey`.
@@ -91,7 +87,7 @@ Returns an array of values from `key` sorted by `mapKey`.
{{ site.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
```
###### Delete
### Delete
Removes the given key.

View File

@@ -3,15 +3,15 @@ title: Taxonomies
description: Returns a data structure containing the site's Taxonomy objects, the terms within each Taxonomy object, and the pages to which the terms are assigned.
categories: []
keywords: []
action:
related: []
returnType: page.TaxonomyList
signatures: [SITE.Taxonomies]
params:
functions_and_methods:
returnType: page.TaxonomyList
signatures: [SITE.Taxonomies]
---
Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such&nbsp;as:
{{< code-toggle >}}
{{< code-toggle file=hugo >}}
taxonomy a:
- term 1:
- page 1
@@ -50,7 +50,7 @@ content/
Conceptually, the taxonomies data structure looks like:
{{< code-toggle >}}
{{< code-toggle file=hugo >}}
genres:
- suspense:
- And Then There Were None
@@ -89,13 +89,10 @@ Hugo renders this to:
</ul>
```
{{% note %}}
Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages.
Please see the [taxonomies] section for a complete explanation and examples.
[taxonomies]: /content-management/taxonomies/
{{% /note %}}
> [!note]
> Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages.
>
> Please see the [taxonomies] section for a complete explanation and examples.
## Examples
@@ -143,7 +140,7 @@ The following example displays all terms in a site's tags taxonomy:
```
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
{{< code file=layouts/partials/all-taxonomies.html >}}
```go-html-template {file="layouts/partials/all-taxonomies.html"}
{{ with .Site.Taxonomies }}
{{ $numberOfTerms := 0 }}
{{ range $taxonomy, $terms := . }}
@@ -174,4 +171,6 @@ This example will list all taxonomies and their terms, as well as all the conten
</ul>
{{ end }}
{{ end }}
{{< /code >}}
```
[taxonomies]: /content-management/taxonomies/

View File

@@ -3,10 +3,10 @@ title: Title
description: Returns the title as defined in the site configuration.
categories: []
keywords: []
action:
related: []
returnType: string
signatures: [SITE.Title]
params:
functions_and_methods:
returnType: string
signatures: [SITE.Title]
---
Site configuration:

View File

@@ -4,10 +4,5 @@ linkTitle: Site
description: Use these methods with Site objects.
categories: []
keywords: []
menu:
docs:
parent: methods
aliases: [/variables/site/]
---
Use these methods with Site objects. A multilingual project will have two or more sites, one for each language.