diff options
| author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2025-04-10 13:04:51 +0200 |
|---|---|---|
| committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2025-04-10 13:04:51 +0200 |
| commit | 653f1c1d462332bccf303a5040e5cd99c89a4378 (patch) | |
| tree | c993984f169a240567526e9993261241c0cda771 /docs/content/en/methods | |
| parent | 208a0de6c31354df6f9463d49e90db9dec935169 (diff) | |
| parent | 5be51ac3db225d5df501ed1fa1499c41d97dbf65 (diff) | |
| download | hugo-653f1c1d462332bccf303a5040e5cd99c89a4378.tar.gz hugo-653f1c1d462332bccf303a5040e5cd99c89a4378.zip | |
Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'
Diffstat (limited to 'docs/content/en/methods')
277 files changed, 1692 insertions, 2921 deletions
diff --git a/docs/content/en/methods/_index.md b/docs/content/en/methods/_index.md index e45f2fef7..39f2b6146 100644 --- a/docs/content/en/methods/_index.md +++ b/docs/content/en/methods/_index.md @@ -1,17 +1,8 @@ --- title: Methods - description: Use these methods within your templates. categories: [] keywords: [] -menu: - docs: - identifier: methods-in-this-section - parent: methods - weight: 10 weight: 10 -showSectionMenu: true aliases: ['/variables/'] --- - -Use these methods within your templates. diff --git a/docs/content/en/methods/duration/Abs.md b/docs/content/en/methods/duration/Abs.md index d035f97b6..2e85797ea 100644 --- a/docs/content/en/methods/duration/Abs.md +++ b/docs/content/en/methods/duration/Abs.md @@ -3,12 +3,10 @@ title: Abs description: Returns the absolute value of the given time.Duration value. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: time.Duration - signatures: [DURATION.Abs] +params: + functions_and_methods: + returnType: time.Duration + signatures: [DURATION.Abs] --- ```go-html-template diff --git a/docs/content/en/methods/duration/Hours.md b/docs/content/en/methods/duration/Hours.md index 5b2d893b9..23655510e 100644 --- a/docs/content/en/methods/duration/Hours.md +++ b/docs/content/en/methods/duration/Hours.md @@ -3,12 +3,10 @@ title: Hours description: Returns the time.Duration value as a floating point number of hours. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: float64 - signatures: [DURATION.Hours] +params: + functions_and_methods: + returnType: float64 + signatures: [DURATION.Hours] --- ```go-html-template diff --git a/docs/content/en/methods/duration/Microseconds.md b/docs/content/en/methods/duration/Microseconds.md index c8b210c94..c090316d0 100644 --- a/docs/content/en/methods/duration/Microseconds.md +++ b/docs/content/en/methods/duration/Microseconds.md @@ -3,12 +3,10 @@ title: Microseconds description: Returns the time.Duration value as an integer microsecond count. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: int64 - signatures: [DURATION.Microseconds] +params: + functions_and_methods: + returnType: int64 + signatures: [DURATION.Microseconds] --- ```go-html-template diff --git a/docs/content/en/methods/duration/Milliseconds.md b/docs/content/en/methods/duration/Milliseconds.md index 32809027a..288f3695a 100644 --- a/docs/content/en/methods/duration/Milliseconds.md +++ b/docs/content/en/methods/duration/Milliseconds.md @@ -3,12 +3,10 @@ title: Milliseconds description: Returns the time.Duration value as an integer millisecond count. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: int64 - signatures: [DURATION.Milliseconds] +params: + functions_and_methods: + returnType: int64 + signatures: [DURATION.Milliseconds] --- ```go-html-template diff --git a/docs/content/en/methods/duration/Minutes.md b/docs/content/en/methods/duration/Minutes.md index d3e57fba5..aec904fa7 100644 --- a/docs/content/en/methods/duration/Minutes.md +++ b/docs/content/en/methods/duration/Minutes.md @@ -3,12 +3,10 @@ title: Minutes description: Returns the time.Duration value as a floating point number of minutes. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: float64 - signatures: [DURATION.Minutes] +params: + functions_and_methods: + returnType: float64 + signatures: [DURATION.Minutes] --- ```go-html-template diff --git a/docs/content/en/methods/duration/Nanoseconds.md b/docs/content/en/methods/duration/Nanoseconds.md index 66d2981f2..fd1b9e496 100644 --- a/docs/content/en/methods/duration/Nanoseconds.md +++ b/docs/content/en/methods/duration/Nanoseconds.md @@ -3,12 +3,10 @@ title: Nanoseconds description: Returns the time.Duration value as an integer nanosecond count. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: int64 - signatures: [DURATION.Nanoseconds] +params: + functions_and_methods: + returnType: int64 + signatures: [DURATION.Nanoseconds] --- ```go-html-template diff --git a/docs/content/en/methods/duration/Round.md b/docs/content/en/methods/duration/Round.md index 0722a6076..dfd06253f 100644 --- a/docs/content/en/methods/duration/Round.md +++ b/docs/content/en/methods/duration/Round.md @@ -3,12 +3,10 @@ title: Round description: Returns the result of rounding DURATION1 to the nearest multiple of DURATION2. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: - signatures: [DURATION1.Round DURATION2] +params: + functions_and_methods: + returnType: + signatures: [DURATION1.Round DURATION2] --- ```go-html-template diff --git a/docs/content/en/methods/duration/Seconds.md b/docs/content/en/methods/duration/Seconds.md index d23d5ec15..8b6d060b9 100644 --- a/docs/content/en/methods/duration/Seconds.md +++ b/docs/content/en/methods/duration/Seconds.md @@ -3,12 +3,10 @@ title: Seconds description: Returns the time.Duration value as a floating point number of seconds. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: float64 - signatures: [DURATION.Seconds] +params: + functions_and_methods: + returnType: float64 + signatures: [DURATION.Seconds] --- ```go-html-template diff --git a/docs/content/en/methods/duration/Truncate.md b/docs/content/en/methods/duration/Truncate.md index 78cddc27a..5a785a77a 100644 --- a/docs/content/en/methods/duration/Truncate.md +++ b/docs/content/en/methods/duration/Truncate.md @@ -3,12 +3,10 @@ title: Truncate description: Returns the result of rounding DURATION1 toward zero to a multiple of DURATION2. categories: [] keywords: [] -action: - related: - - functions/time/Duration - - functions/time/ParseDuration - returnType: time.Duration - signatures: [DURATION1.Truncate DURATION2] +params: + functions_and_methods: + returnType: time.Duration + signatures: [DURATION1.Truncate DURATION2] --- ```go-html-template diff --git a/docs/content/en/methods/duration/_index.md b/docs/content/en/methods/duration/_index.md index 9fc4f814c..aeb113820 100644 --- a/docs/content/en/methods/duration/_index.md +++ b/docs/content/en/methods/duration/_index.md @@ -4,9 +4,4 @@ linkTitle: Duration description: Use these methods with time.Duration values. categories: [] keywords: [] -menu: - docs: - parent: methods --- - -Use these methods with time.Duration values. diff --git a/docs/content/en/methods/menu-entry/Children.md b/docs/content/en/methods/menu-entry/Children.md index ad671b2d0..ecad415fa 100644 --- a/docs/content/en/methods/menu-entry/Children.md +++ b/docs/content/en/methods/menu-entry/Children.md @@ -3,11 +3,10 @@ title: Children description: Returns a collection of child menu entries, if any, under the given menu entry. categories: [] keywords: [] -action: - related: - - methods/menu-entry/HasChildren - returnType: navigation.Menu - signatures: [MENUENTRY.Children] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENUENTRY.Children] --- Use the `Children` method when rendering a nested menu. diff --git a/docs/content/en/methods/menu-entry/HasChildren.md b/docs/content/en/methods/menu-entry/HasChildren.md index fac03b7ae..03e6cb672 100644 --- a/docs/content/en/methods/menu-entry/HasChildren.md +++ b/docs/content/en/methods/menu-entry/HasChildren.md @@ -3,11 +3,10 @@ title: HasChildren description: Reports whether the given menu entry has child menu entries. categories: [] keywords: [] -action: - related: - - methods/menu-entry/Children - returnType: bool - signatures: [MENUENTRY.HasChildren] +params: + functions_and_methods: + returnType: bool + signatures: [MENUENTRY.HasChildren] --- Use the `HasChildren` method when rendering a nested menu. diff --git a/docs/content/en/methods/menu-entry/Identifier.md b/docs/content/en/methods/menu-entry/Identifier.md index ba8b77ece..809624459 100644 --- a/docs/content/en/methods/menu-entry/Identifier.md +++ b/docs/content/en/methods/menu-entry/Identifier.md @@ -1,18 +1,16 @@ --- title: Identifier -description: Returns the `identifier` property of the given menu entry. +description: Returns the `identifier` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.Identifier] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Identifier] --- The `Identifier` method returns the `identifier` property of the menu entry. If you define the menu entry [automatically], it returns the page's section. -[automatically]: /content-management/menus/#define-automatically - {{< code-toggle file=hugo >}} [[menus.main]] identifier = 'about' @@ -37,8 +35,7 @@ This example uses the `Identifier` method when querying the translation table on </ul> ``` -{{% note %}} -In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. +> [!note] +> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. -[details]: /content-management/menus/#properties-front-matter -{{% /note %}} +[automatically]: /content-management/menus/#define-automatically diff --git a/docs/content/en/methods/menu-entry/KeyName.md b/docs/content/en/methods/menu-entry/KeyName.md index 409cb31d6..d614a5a87 100644 --- a/docs/content/en/methods/menu-entry/KeyName.md +++ b/docs/content/en/methods/menu-entry/KeyName.md @@ -1,12 +1,12 @@ --- title: KeyName -description: Returns the `identifier` property of the given menu entry, falling back to its `name` property. +description: Returns the `identifier` property of the given menu entry, falling back to its `name` property. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.KeyName] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.KeyName] --- In this menu definition, the second entry does not contain an `identifier`, so the `Identifier` method returns its `name` property instead: diff --git a/docs/content/en/methods/menu-entry/Menu.md b/docs/content/en/methods/menu-entry/Menu.md index 79b400f1f..074911eeb 100644 --- a/docs/content/en/methods/menu-entry/Menu.md +++ b/docs/content/en/methods/menu-entry/Menu.md @@ -3,12 +3,10 @@ title: Menu description: Returns the identifier of the menu that contains the given menu entry. categories: [] keywords: [] -action: - related: - - methods/page/IsMenuCurrent - - methods/page/HasMenuCurrent - returnType: string - signatures: [MENUENTRY.Menu] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Menu] --- ```go-html-template diff --git a/docs/content/en/methods/menu-entry/Name.md b/docs/content/en/methods/menu-entry/Name.md index fb5fc1b5b..706d0f8c8 100644 --- a/docs/content/en/methods/menu-entry/Name.md +++ b/docs/content/en/methods/menu-entry/Name.md @@ -3,15 +3,15 @@ title: Name description: Returns the `name` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.Name] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Name] --- If you define the menu entry [automatically], the `Name` method returns the page's [`LinkTitle`], falling back to its [`Title`]. -If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`]. +If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`]. [`LinkTitle`]: /methods/page/linktitle/ [`Title`]: /methods/page/title/ diff --git a/docs/content/en/methods/menu-entry/Page.md b/docs/content/en/methods/menu-entry/Page.md index d177a1af0..489ee7acc 100644 --- a/docs/content/en/methods/menu-entry/Page.md +++ b/docs/content/en/methods/menu-entry/Page.md @@ -3,10 +3,10 @@ title: Page description: Returns the Page object associated with the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: page.Page - signatures: [MENUENTRY.Page] +params: + functions_and_methods: + returnType: page.Page + signatures: [MENUENTRY.Page] --- Regardless of how you [define menu entries], an entry associated with a page has access to its [methods]. diff --git a/docs/content/en/methods/menu-entry/PageRef.md b/docs/content/en/methods/menu-entry/PageRef.md index 368579796..979879b03 100644 --- a/docs/content/en/methods/menu-entry/PageRef.md +++ b/docs/content/en/methods/menu-entry/PageRef.md @@ -3,12 +3,10 @@ title: PageRef description: Returns the `pageRef` property of the given menu entry. categories: [] keywords: [] -action: - related: - - /methods/menu-entry/URL - returnType: string - signatures: [MENUENTRY.PageRef] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.PageRef] --- The use case for this method is rare. @@ -31,28 +29,15 @@ If a matching page is not found: - The [`Page`] method returns nil - The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return `false` -{{% note %}} -In almost also scenarios you should use the [`URL`] method instead. - -[`URL`]: /methods/menu-entry/url/ -{{% /note %}} - -[defining a menu entry]: /content-management/menus/#define-in-site-configuration -[`Page`]: /methods/menu-entry/page/ -[`URL`]: /methods/menu-entry/url/ -[`IsMenuCurrent`]: /methods/page/ismenucurrent/ -[`HasMenuCurrent`]: /methods/page/hasmenucurrent/ -[`RelPermalink`]: /methods/page/relpermalink/ +> [!note] +> In almost also scenarios you should use the [`URL`] method instead. ## Example This example is contrived. -{{% note %}} -In almost also scenarios you should use the [`URL`] method instead. - -[`URL`]: /methods/menu-entry/url/ -{{% /note %}} +> [!note] +> In almost also scenarios you should use the [`URL`] method instead. Consider this content structure: @@ -77,13 +62,13 @@ weight = 20 With this template code: -{{< code file=layouts/partials/menu.html >}} +```go-html-template {file="layouts/partials/menu.html"} <ul> {{ range .Site.Menus.main }} <li><a href="{{ .URL }}">{{ .Name }}</a></li> {{ end }} </ul> -{{< /code >}} +``` Hugo render this HTML: @@ -98,13 +83,13 @@ In the above note that the `href` attribute of the second `anchor` element is bl With this template code: -{{< code file=layouts/partials/menu.html >}} +```go-html-template {file="layouts/partials/menu.html"} <ul> {{ range .Site.Menus.main }} <li><a href="{{ or .URL .PageRef }}">{{ .Name }}</a></li> {{ end }} </ul> -{{< /code >}} +``` Hugo renders this HTML: @@ -116,3 +101,9 @@ Hugo renders this HTML: ``` In the above note that Hugo populates the `href` attribute of the second `anchor` element with the `pageRef` property as defined in the site configuration because the template code falls back to the `PageRef` method. + +[`HasMenuCurrent`]: /methods/page/hasmenucurrent/ +[`IsMenuCurrent`]: /methods/page/ismenucurrent/ +[`Page`]: /methods/menu-entry/page/ +[`URL`]: /methods/menu-entry/url/ +[defining a menu entry]: /content-management/menus/#define-in-site-configuration diff --git a/docs/content/en/methods/menu-entry/Params.md b/docs/content/en/methods/menu-entry/Params.md index 4d3e8bdaf..20c4f7fc7 100644 --- a/docs/content/en/methods/menu-entry/Params.md +++ b/docs/content/en/methods/menu-entry/Params.md @@ -3,10 +3,10 @@ title: Params description: Returns the `params` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: maps.Params - signatures: [MENUENTRY.Params] +params: + functions_and_methods: + returnType: maps.Params + signatures: [MENUENTRY.Params] --- When you define menu entries [in site configuration] or [in front matter], you can include a `params` key to attach additional information to the entry. For example: diff --git a/docs/content/en/methods/menu-entry/Parent.md b/docs/content/en/methods/menu-entry/Parent.md index af1b4afe6..7c617527b 100644 --- a/docs/content/en/methods/menu-entry/Parent.md +++ b/docs/content/en/methods/menu-entry/Parent.md @@ -3,10 +3,10 @@ title: Parent description: Returns the `parent` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.Parent] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Parent] --- With this menu definition: @@ -40,7 +40,7 @@ This template renders the nested menu, listing the `parent` property next each o {{ if .HasChildren }} <ul> {{ range .Children }} - <li><a href="{{ .URL }}">{{ .Name }}</a> ({{ .Parent }})</li> + <li><a href="{{ .URL }}">{{ .Name }}</a> ({{ .Parent }})</li> {{ end }} </ul> {{ end }} diff --git a/docs/content/en/methods/menu-entry/Post.md b/docs/content/en/methods/menu-entry/Post.md index b2fa2da5b..2da8c38d8 100644 --- a/docs/content/en/methods/menu-entry/Post.md +++ b/docs/content/en/methods/menu-entry/Post.md @@ -1,13 +1,12 @@ --- title: Post -description: Returns the `post` property of the given menu entry. +description: Returns the `post` property of the given menu entry. categories: [] keywords: [] -action: - related: - - methods/menu-entry/Pre - returnType: template.HTML - signatures: [MENUENTRY.Post] +params: + functions_and_methods: + returnType: template.HTML + signatures: [MENUENTRY.Post] --- -{{% include "methods/menu-entry/_common/pre-post.md" %}} +{{% include "/_common/menu-entries/pre-and-post.md" %}} diff --git a/docs/content/en/methods/menu-entry/Pre.md b/docs/content/en/methods/menu-entry/Pre.md index df7c8f16e..19af243e7 100644 --- a/docs/content/en/methods/menu-entry/Pre.md +++ b/docs/content/en/methods/menu-entry/Pre.md @@ -1,13 +1,12 @@ --- title: Pre -description: Returns the `pre` property of the given menu entry. +description: Returns the `pre` property of the given menu entry. categories: [] keywords: [] -action: - related: - - methods/menu-entry/Post - returnType: template.HTML - signatures: [MENUENTRY.Pre] +params: + functions_and_methods: + returnType: template.HTML + signatures: [MENUENTRY.Pre] --- -{{% include "methods/menu-entry/_common/pre-post.md" %}} +{{% include "/_common/menu-entries/pre-and-post.md" %}} diff --git a/docs/content/en/methods/menu-entry/Title.md b/docs/content/en/methods/menu-entry/Title.md index 64bba2d44..526132d7c 100644 --- a/docs/content/en/methods/menu-entry/Title.md +++ b/docs/content/en/methods/menu-entry/Title.md @@ -1,15 +1,15 @@ --- title: Title -description: Returns the `title` property of the given menu entry. +description: Returns the `title` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.Title] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.Title] --- -The `Title` method returns the `title` property of the given menu entry. If the `title` is not defined, and the menu entry resolves to a page, the `Title` returns the page [`Title`]. +The `Title` method returns the `title` property of the given menu entry. If the `title` is not defined, and the menu entry resolves to a page, the `Title` returns the page [`Title`]. [`Title`]: /methods/page/title/ diff --git a/docs/content/en/methods/menu-entry/URL.md b/docs/content/en/methods/menu-entry/URL.md index 47db9153e..e29a6f058 100644 --- a/docs/content/en/methods/menu-entry/URL.md +++ b/docs/content/en/methods/menu-entry/URL.md @@ -3,10 +3,10 @@ title: URL description: Returns the relative permalink of the page associated with the given menu entry, else its `url` property. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [MENUENTRY.URL] +params: + functions_and_methods: + returnType: string + signatures: [MENUENTRY.URL] --- For menu entries associated with a page, the `URL` method returns the page's [`RelPermalink`], otherwise it returns the entry's `url` property. diff --git a/docs/content/en/methods/menu-entry/Weight.md b/docs/content/en/methods/menu-entry/Weight.md index eab935736..b96e2cc87 100644 --- a/docs/content/en/methods/menu-entry/Weight.md +++ b/docs/content/en/methods/menu-entry/Weight.md @@ -1,17 +1,17 @@ --- title: Weight -description: Returns the `weight` property of the given menu entry. +description: Returns the `weight` property of the given menu entry. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [MENUENTRY.Weight] +params: + functions_and_methods: + returnType: int + signatures: [MENUENTRY.Weight] --- -If you define the menu entry [automatically], the `Weight` method returns the page’s [`Weight`]. +If you define the menu entry [automatically], the `Weight` method returns the page's [`Weight`]. -If you define the menu entry [in front matter] or [in site configuration], the `Weight` method returns the `weight` property, falling back to the page’s `Weight`. +If you define the menu entry [in front matter] or [in site configuration], the `Weight` method returns the `weight` property, falling back to the page's `Weight`. [`Weight`]: /methods/page/weight/ [automatically]: /content-management/menus/#define-automatically diff --git a/docs/content/en/methods/menu-entry/_common/_index.md b/docs/content/en/methods/menu-entry/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/methods/menu-entry/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/methods/menu-entry/_common/pre-post.md b/docs/content/en/methods/menu-entry/_common/pre-post.md deleted file mode 100644 index da3d584d1..000000000 --- a/docs/content/en/methods/menu-entry/_common/pre-post.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -In this site configuration we enable rendering of [emoji shortcodes], and add emoji shortcodes before (pre) and after (post) each menu entry: - -{{< code-toggle file=hugo >}} -enableEmoji = true - -[[menus.main]] -name = 'About' -pageRef = '/about' -post = ':point_left:' -pre = ':point_right:' -weight = 10 - -[[menus.main]] -name = 'Contact' -pageRef = '/contact' -post = ':arrow_left:' -pre = ':arrow_right:' -weight = 20 -{{< /code-toggle >}} - -To render the menu: - -```go-html-template -<ul> - {{ range .Site.Menus.main }} - <li> - {{ .Pre | markdownify }} - <a href="{{ .URL }}">{{ .Name }}</a> - {{ .Post | markdownify }} - </li> - {{ end }} -</ul> -``` - -[emoji shortcodes]: /quick-reference/emojis/ diff --git a/docs/content/en/methods/menu-entry/_index.md b/docs/content/en/methods/menu-entry/_index.md index d89663593..129e9bcdc 100644 --- a/docs/content/en/methods/menu-entry/_index.md +++ b/docs/content/en/methods/menu-entry/_index.md @@ -4,9 +4,4 @@ linkTitle: Menu entry description: Use these methods in your menu templates. categories: [] keywords: [] -menu: - docs: - parent: methods --- - -Use these methods in your menu templates. diff --git a/docs/content/en/methods/menu/ByName.md b/docs/content/en/methods/menu/ByName.md index 2e28016b6..d98a4aced 100644 --- a/docs/content/en/methods/menu/ByName.md +++ b/docs/content/en/methods/menu/ByName.md @@ -3,10 +3,10 @@ title: ByName description: Returns the given menu with its entries sorted by name. categories: [] keywords: [] -action: - related: [] - returnType: navigation.Menu - signatures: [MENU.ByName] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENU.ByName] --- The `Sort` method returns the given menu with its entries sorted by `name`. diff --git a/docs/content/en/methods/menu/ByWeight.md b/docs/content/en/methods/menu/ByWeight.md index 7ba27031a..013d37e13 100644 --- a/docs/content/en/methods/menu/ByWeight.md +++ b/docs/content/en/methods/menu/ByWeight.md @@ -3,10 +3,10 @@ title: ByWeight description: Returns the given menu with its entries sorted by weight, then by name, then by identifier. categories: [] keywords: [] -action: - related: [] - returnType: navigation.Menu - signatures: [MENU.ByWeight] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENU.ByWeight] --- The `ByWeight` method returns the given menu with its entries sorted by [`weight`](g), then by `name`, then by `identifier`. This is the default sort order. @@ -53,11 +53,8 @@ Hugo renders this to: </ul> ``` -{{% note %}} -In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. - -[details]: /content-management/menus/#properties-front-matter -{{% /note %}} +> [!note] +> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables. You can also sort menu entries using the [`sort`] function. For example, to sort by `weight` in descending order: diff --git a/docs/content/en/methods/menu/Limit.md b/docs/content/en/methods/menu/Limit.md index 23a523dbd..005fef144 100644 --- a/docs/content/en/methods/menu/Limit.md +++ b/docs/content/en/methods/menu/Limit.md @@ -3,10 +3,10 @@ title: Limit description: Returns the given menu, limited to the first N entries. categories: [] keywords: [] -action: - related: [] - returnType: navigation.Menu - signatures: [MENU.Limit N] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENU.Limit N] --- The `Limit` method returns the given menu, limited to the first N entries. diff --git a/docs/content/en/methods/menu/Reverse.md b/docs/content/en/methods/menu/Reverse.md index a3fe09dce..1ee31aa51 100644 --- a/docs/content/en/methods/menu/Reverse.md +++ b/docs/content/en/methods/menu/Reverse.md @@ -3,10 +3,10 @@ title: Reverse description: Returns the given menu, reversing the sort order of its entries. categories: [] keywords: [] -action: - related: [] - returnType: navigation.Menu - signatures: [MENU.Reverse] +params: + functions_and_methods: + returnType: navigation.Menu + signatures: [MENU.Reverse] --- The `Reverse` method returns the given menu, reversing the sort order of its entries. diff --git a/docs/content/en/methods/menu/_index.md b/docs/content/en/methods/menu/_index.md index f5b925fd6..41084fdba 100644 --- a/docs/content/en/methods/menu/_index.md +++ b/docs/content/en/methods/menu/_index.md @@ -4,9 +4,4 @@ linkTitle: Menu description: Use these methods when ranging through menu entries. categories: [] keywords: [] -menu: - docs: - parent: methods --- - -Use these methods when ranging through menu entries. diff --git a/docs/content/en/methods/page/Aliases.md b/docs/content/en/methods/page/Aliases.md index 15e73384b..775404bd3 100644 --- a/docs/content/en/methods/page/Aliases.md +++ b/docs/content/en/methods/page/Aliases.md @@ -3,10 +3,10 @@ title: Aliases description: Returns the URL aliases as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: '[]string' - signatures: [PAGE.Aliases] +params: + functions_and_methods: + returnType: '[]string' + signatures: [PAGE.Aliases] --- The `Aliases` method on a `Page` object returns the URL [aliases] as defined in front matter. diff --git a/docs/content/en/methods/page/AllTranslations.md b/docs/content/en/methods/page/AllTranslations.md index 51d82d4f9..62117b429 100644 --- a/docs/content/en/methods/page/AllTranslations.md +++ b/docs/content/en/methods/page/AllTranslations.md @@ -1,15 +1,12 @@ --- title: AllTranslations -description: Returns all translations of the given page, including the current language. +description: Returns all translations of the given page, including the current language. categories: [] keywords: [] -action: - related: - - methods/page/Translations - - methods/page/IsTranslated - - methods/page/TranslationKey - returnType: page.Pages - signatures: [PAGE.AllTranslations] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.AllTranslations] --- With this site configuration: diff --git a/docs/content/en/methods/page/AlternativeOutputFormats.md b/docs/content/en/methods/page/AlternativeOutputFormats.md index 03e14e287..c4075d010 100644 --- a/docs/content/en/methods/page/AlternativeOutputFormats.md +++ b/docs/content/en/methods/page/AlternativeOutputFormats.md @@ -3,20 +3,19 @@ title: AlternativeOutputFormats description: Returns a slice of OutputFormat objects, excluding the current output format, each representing one of the output formats enabled for the given page. categories: [] keywords: [] -action: - related: - - methods/page/OutputFormats - returnType: page.OutputFormats - signatures: [PAGE.AlternativeOutputFormats] +params: + functions_and_methods: + returnType: page.OutputFormats + signatures: [PAGE.AlternativeOutputFormats] --- {{% glossary-term "output format" %}} -The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page.. See [details](/templates/output-formats/). +The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/). ## Methods -{{% include "methods/page/_common/output-format-methods.md" %}} +{{% include "/_common/methods/page/output-format-methods.md" %}} ## Example @@ -29,7 +28,7 @@ Generate a `link` element in the `<head>` of each page for each of the alternati {{ if .IsHome }} {{ $title = site.Title }} {{ end }} - {{ range .AlternativeOutputFormats -}} + {{ range .AlternativeOutputFormats }} {{ printf `<link rel=%q type=%q href=%q title=%q>` .Rel .MediaType.Type .Permalink $title | safeHTML }} {{ end }} ... diff --git a/docs/content/en/methods/page/Ancestors.md b/docs/content/en/methods/page/Ancestors.md index 4fb00fc06..d8275cf76 100644 --- a/docs/content/en/methods/page/Ancestors.md +++ b/docs/content/en/methods/page/Ancestors.md @@ -1,23 +1,14 @@ --- title: Ancestors -description: Returns a collection of Page objects, one for each ancestor section of the given page. +description: Returns a collection of Page objects, one for each ancestor section of the given page. categories: [] keywords: [] -action: - related: - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: page.Pages - signatures: [PAGE.Ancestors] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.Ancestors] --- -{{% glossary-term section %}} - With this content structure: ```text diff --git a/docs/content/en/methods/page/BundleType.md b/docs/content/en/methods/page/BundleType.md index b7d15ce4c..e919511da 100644 --- a/docs/content/en/methods/page/BundleType.md +++ b/docs/content/en/methods/page/BundleType.md @@ -3,10 +3,10 @@ title: BundleType description: Returns the bundle type of the given page, or an empty string if the page is not a page bundle. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [PAGE.BundleType] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.BundleType] --- A page bundle is a directory that encapsulates both content and associated [resources](g). There are two types of page bundles: [leaf bundles](g) and [branch bundles](g). See [details](/content-management/page-bundles/). diff --git a/docs/content/en/methods/page/CodeOwners.md b/docs/content/en/methods/page/CodeOwners.md index c0baf26ad..00afa7549 100644 --- a/docs/content/en/methods/page/CodeOwners.md +++ b/docs/content/en/methods/page/CodeOwners.md @@ -3,11 +3,10 @@ title: CodeOwners description: Returns of slice of code owners for the given page, derived from the CODEOWNERS file in the root of the project directory. categories: [] keywords: [] -action: - related: - - methods/page/GitInfo - returnType: '[]string' - signatures: [PAGE.CodeOwners] +params: + functions_and_methods: + returnType: '[]string' + signatures: [PAGE.CodeOwners] --- GitHub and GitLab support CODEOWNERS files. This file specifies the users responsible for developing and maintaining software and documentation. This definition can apply to the entire repository, specific directories, or to individual files. To learn more: diff --git a/docs/content/en/methods/page/Content.md b/docs/content/en/methods/page/Content.md index 373c6590a..21348ebe6 100644 --- a/docs/content/en/methods/page/Content.md +++ b/docs/content/en/methods/page/Content.md @@ -3,16 +3,10 @@ title: Content description: Returns the rendered content of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/RawContent - - methods/page/Plain - - methods/page/PlainWords - - methods/page/RenderShortcodes - returnType: template.HTML - signatures: [PAGE.Content] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.Content] --- The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. diff --git a/docs/content/en/methods/page/ContentWithoutSummary.md b/docs/content/en/methods/page/ContentWithoutSummary.md index 527f5d962..4923b1197 100644 --- a/docs/content/en/methods/page/ContentWithoutSummary.md +++ b/docs/content/en/methods/page/ContentWithoutSummary.md @@ -3,16 +3,10 @@ title: ContentWithoutSummary description: Returns the rendered content of the given page, excluding the content summary. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/RawContent - - methods/page/Plain - - methods/page/PlainWords - - methods/page/RenderShortcodes - returnType: template.HTML - signatures: [PAGE.ContentWithoutSummary] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.ContentWithoutSummary] --- {{< new-in 0.134.0 />}} diff --git a/docs/content/en/methods/page/CurrentSection.md b/docs/content/en/methods/page/CurrentSection.md index 1684ee483..93457f13f 100644 --- a/docs/content/en/methods/page/CurrentSection.md +++ b/docs/content/en/methods/page/CurrentSection.md @@ -3,24 +3,16 @@ title: CurrentSection description: Returns the Page object of the section in which the given page resides. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: page.Page - signatures: [PAGE.CurrentSection] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.CurrentSection] --- {{% glossary-term section %}} -{{% note %}} -The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself. -{{% /note %}} +> [!note] +> The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself. Consider this content structure: diff --git a/docs/content/en/methods/page/Data.md b/docs/content/en/methods/page/Data.md index b3df243c5..ae0bdc57f 100644 --- a/docs/content/en/methods/page/Data.md +++ b/docs/content/en/methods/page/Data.md @@ -3,24 +3,18 @@ title: Data description: Returns a unique data object for each page kind. categories: [] keywords: [] -action: - related: [] - returnType: page.Data - signatures: [PAGE.Data] -toc: true +params: + functions_and_methods: + returnType: page.Data + signatures: [PAGE.Data] --- The `Data` method on a `Page` object returns a unique data object for each [page kind](g). -{{% note %}} -The `Data` method is only useful within [taxonomy](g) and [term](g) templates. - -Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`] - -[`Pages`]: /methods/page/pages/ -[`RegularPages`]: /methods/page/regularpages/ -[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/ -{{% /note %}} +> [!note] +> The `Data` method is only useful within [taxonomy](g) and [term](g) templates. +> +> Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`] The examples that follow are based on this site configuration: @@ -67,11 +61,8 @@ Terms {{ $taxonomyObject := .Data.Terms }} ``` -{{% note %}} -Once you have captured the `Taxonomy` object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages. - -[taxonomy methods]: /methods/taxonomy/ -{{% /note %}} +> [!note] +> Once you have captured the `Taxonomy` object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages. Learn more about [taxonomy templates]. @@ -102,5 +93,9 @@ Term Learn more about [term templates]. +[`Pages`]: /methods/page/pages/ +[`RegularPages`]: /methods/page/regularpages/ +[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/ +[taxonomy methods]: /methods/taxonomy/ [taxonomy templates]: /templates/types/#taxonomy [term templates]: /templates/types/#term diff --git a/docs/content/en/methods/page/Date.md b/docs/content/en/methods/page/Date.md index 113d6ca09..b6c2042c2 100644 --- a/docs/content/en/methods/page/Date.md +++ b/docs/content/en/methods/page/Date.md @@ -3,13 +3,10 @@ title: Date description: Returns the date of the given page. categories: [] keywords: [] -action: - related: - - methods/page/ExpiryDate - - methods/page/LastMod - - methods/page/PublishDate - returnType: time.Time - signatures: [PAGE.Date] +params: + functions_and_methods: + returnType: time.Time + signatures: [PAGE.Date] --- Set the date in front matter: @@ -19,11 +16,8 @@ title = 'Article 1' date = 2023-10-19T00:40:04-07:00 {{< /code-toggle >}} -{{% note %}} -The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details]. - -[details]: /getting-started/configuration/#configure-dates -{{% /note %}} +> [!note] +> The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details]. The date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods]. @@ -34,6 +28,7 @@ The date is a [time.Time] value. Format and localize the value with the [`time.F In the example above we explicitly set the date in front matter. With Hugo's default configuration, the `Date` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the date is not defined in front matter. See [details]. [`time.Format`]: /functions/time/format/ -[details]: /getting-started/configuration/#configure-dates +[details]: /configuration/front-matter/#dates +[details]: /configuration/front-matter/#dates [time methods]: /methods/time/ [time.Time]: https://pkg.go.dev/time#Time diff --git a/docs/content/en/methods/page/Description.md b/docs/content/en/methods/page/Description.md index 67171fe01..5287aa699 100644 --- a/docs/content/en/methods/page/Description.md +++ b/docs/content/en/methods/page/Description.md @@ -3,11 +3,10 @@ title: Description description: Returns the description of the given page as defined in front matter. categories: [] keywords: [] -action: - related: - - methods/page/Summary - returnType: string - signatures: [PAGE.Description] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Description] --- Conceptually different from a [content summary], a page description is typically used in metadata about the page. @@ -17,12 +16,12 @@ title = 'How to make spicy tuna hand rolls' description = 'Instructions for making spicy tuna hand rolls.' {{< /code-toggle >}} -{{< code file=layouts/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} <head> ... <meta name="description" content="{{ .Description }}"> ... </head> -{{< /code >}} +``` [content summary]: /content-management/summaries/ diff --git a/docs/content/en/methods/page/Draft.md b/docs/content/en/methods/page/Draft.md index fd55a9bc9..482a370bf 100644 --- a/docs/content/en/methods/page/Draft.md +++ b/docs/content/en/methods/page/Draft.md @@ -3,10 +3,10 @@ title: Draft description: Reports whether the given page is a draft as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [PAGE.Draft] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.Draft] --- By default, Hugo does not publish draft pages when you build your site. To include draft pages when you build your site, use the `--buildDrafts` command line flag. diff --git a/docs/content/en/methods/page/Eq.md b/docs/content/en/methods/page/Eq.md index 99a9fc50f..4947a4bfa 100644 --- a/docs/content/en/methods/page/Eq.md +++ b/docs/content/en/methods/page/Eq.md @@ -3,17 +3,17 @@ title: Eq description: Reports whether two Page objects are equal. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [PAGE1.Eq PAGE2] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE1.Eq PAGE2] --- In this contrived example from a single template, we list all pages in the current section except for the current page. ```go-html-template {{ $currentPage := . }} -{{ range .CurrentSection.Pages }} +{{ range .CurrentSection.Pages }} {{ if not (.Eq $currentPage) }} <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> {{ end }} diff --git a/docs/content/en/methods/page/ExpiryDate.md b/docs/content/en/methods/page/ExpiryDate.md index 9b95ebc65..a72155c33 100644 --- a/docs/content/en/methods/page/ExpiryDate.md +++ b/docs/content/en/methods/page/ExpiryDate.md @@ -1,15 +1,12 @@ --- title: ExpiryDate -description: Returns the expiry date of the given page. +description: Returns the expiry date of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Date - - methods/page/LastMod - - methods/page/PublishDate - returnType: time.Time - signatures: [PAGE.ExpiryDate] +params: + functions_and_methods: + returnType: time.Time + signatures: [PAGE.ExpiryDate] --- By default, Hugo excludes expired pages when building your site. To include expired pages, use the `--buildExpired` command line flag. @@ -30,6 +27,6 @@ The expiry date is a [time.Time] value. Format and localize the value with the [ In the example above we explicitly set the expiry date in front matter. With Hugo's default configuration, the `ExpiryDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the expiry date is not defined in front matter. See [details]. [`time.Format`]: /functions/time/format/ -[details]: /getting-started/configuration/#configure-dates +[details]: /configuration/front-matter/#dates [time methods]: /methods/time/ [time.Time]: https://pkg.go.dev/time#Time diff --git a/docs/content/en/methods/page/File.md b/docs/content/en/methods/page/File.md index 359c1ad2e..2af60a719 100644 --- a/docs/content/en/methods/page/File.md +++ b/docs/content/en/methods/page/File.md @@ -3,36 +3,33 @@ title: File description: For pages backed by a file, returns file information for the given page. categories: [] keywords: [] -action: - related: [] - returnType: hugolib.fileInfo - signatures: [PAGE.File] -toc: true +params: + functions_and_methods: + returnType: hugolib.fileInfo + signatures: [PAGE.File] --- -By default, not all pages are backed by a file, including top level [section pages](g), [taxonomy pages](g), and [term pages](g). By definition, you cannot retrieve file information when the file does not exist. +By default, not all pages are backed by a file, including top-level [section pages](g), [taxonomy pages](g), and [term pages](g). By definition, you cannot retrieve file information when the file does not exist. To back one of the pages above with a file, create an `_index.md` file in the corresponding directory. For example: ```text content/ └── books/ - ├── _index.md <-- the top level section page + ├── _index.md <-- the top-slevel section page ├── book-1.md └── book-2.md ``` -{{% note %}} -Code defensively by verifying file existence as shown in the examples below. -{{% /note %}} +> [!note] +> Code defensively by verifying file existence as shown in the examples below. ## Methods -{{% note %}} -The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system. -{{% /note %}} +> [!note] +> The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system. -###### BaseFileName +### BaseFileName (`string`) The file name, excluding the extension. @@ -42,7 +39,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### ContentBaseName +### ContentBaseName (`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `TranslationBaseName`. @@ -52,7 +49,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Dir +### Dir (`string`) The file path, excluding the file name, relative to the `content` directory. @@ -62,7 +59,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Ext +### Ext (`string`) The file extension. @@ -72,7 +69,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Filename +### Filename (`string`) The absolute file path. @@ -82,21 +79,19 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### IsContentAdapter +### IsContentAdapter {{< new-in 0.126.0 />}} (`bool`) Reports whether the file is a [content adapter]. -[content adapter]: /content-management/content-adapters/ - ```go-html-template {{ with .File }} {{ .IsContentAdapter }} {{ end }} ``` -###### LogicalName +### LogicalName (`string`) The file name. @@ -106,7 +101,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Path +### Path (`string`) The file path, relative to the `content` directory. @@ -116,9 +111,9 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Section +### Section -(`string`) The name of the top level section in which the file resides. +(`string`) The name of the top-level section in which the file resides. ```go-html-template {{ with .File }} @@ -126,7 +121,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### TranslationBaseName +### TranslationBaseName (`string`) The file name, excluding the extension and language identifier. @@ -136,7 +131,7 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### UniqueID +### UniqueID (`string`) The MD5 hash of `.File.Path`. @@ -184,7 +179,7 @@ UniqueID|15be14b...|186868f...|7d9159d... Some of the pages on a site may not be backed by a file. For example: -- Top level section pages +- Top-level section pages - Taxonomy pages - Term pages @@ -195,3 +190,5 @@ Without a backing file, Hugo will throw an error if you attempt to access a `.Fi {{ .ContentBaseName }} {{ end }} ``` + +[content adapter]: /content-management/content-adapters/ diff --git a/docs/content/en/methods/page/FirstSection.md b/docs/content/en/methods/page/FirstSection.md index 29fbdc841..73ddd2d7b 100644 --- a/docs/content/en/methods/page/FirstSection.md +++ b/docs/content/en/methods/page/FirstSection.md @@ -1,26 +1,18 @@ --- title: FirstSection -description: Returns the Page object of the top level section of which the given page is a descendant. +description: Returns the Page object of the top-level section of which the given page is a descendant. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: page.Page - signatures: [PAGE.FirstSection] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.FirstSection] --- {{% glossary-term section %}} -{{% note %}} -When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself. -{{% /note %}} +> [!note] +> When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself. Consider this content structure: @@ -49,7 +41,7 @@ content/ └── _index.md <-- first section: home ``` -To link to the top level section of which the current page is a descendant: +To link to the top-level section of which the current page is a descendant: ```go-html-template <a href="{{ .FirstSection.RelPermalink }}">{{ .FirstSection.LinkTitle }}</a> diff --git a/docs/content/en/methods/page/Fragments.md b/docs/content/en/methods/page/Fragments.md index 581cbf7c3..2c0460def 100644 --- a/docs/content/en/methods/page/Fragments.md +++ b/docs/content/en/methods/page/Fragments.md @@ -3,12 +3,10 @@ title: Fragments description: Returns a data structure of the fragments in the given page. categories: [] keywords: [] -action: - related: - - methods/page/TableOfContents - returnType: tableofcontents.Fragments - signatures: [PAGE.Fragments] -toc: true +params: + functions_and_methods: + returnType: tableofcontents.Fragments + signatures: [PAGE.Fragments] --- In a URL, whether absolute or relative, the [fragment](g) links to an `id` attribute of an HTML element on the page. @@ -25,43 +23,53 @@ Use the `Fragments` method on a `Page` object to create a table of contents with ## Methods -Headings -: (`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure: +### Headings + +(`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure: ```go-html-template <pre>{{ debug.Dump .Fragments.Headings }}</pre> ``` -HeadingsMap -: (`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure: +### HeadingsMap + +(`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure: ```go-html-template <pre>{{ debug.Dump .Fragments.HeadingsMap }}</pre> ``` -Identifiers -: (`slice`) A slice containing the `id` of each heading on the page. To inspect the data structure: +### Identifiers + +(`slice`) A slice containing the `id` attribute of each heading on the page. If so configured, will also contain the `id` attribute of each description term (i.e., `dt` element) on the page. + +See [configure Markup](/configuration/markup/#parserautodefinitiontermid). + +To inspect the data structure: ```go-html-template <pre>{{ debug.Dump .Fragments.Identifiers }}</pre> ``` -Identifiers.Contains ID -: (`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook](g). +### Identifiers.Contains ID + +(`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook](g). ```go-html-template {{ .Fragments.Identifiers.Contains "section-2" }} → true ``` -Identifiers.Count ID -: (`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates. +### Identifiers.Count ID + +(`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates. ```go-html-template {{ .Fragments.Identifiers.Count "section-2" }} → 1 ``` -ToHTML -: (`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list). +### ToHTML + +(`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list). Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your site configuration. @@ -88,13 +96,14 @@ Hugo renders this to: </nav> ``` -{{% note %}} -It is safe to use the `Fragments` methods within a render hook, even for the current page. - -When using the `Fragments` methods within a shortcode, call the shortcode using the `{{</* */>}}` notation. If you use the `{{%/* */%}}` notation, the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop. -{{% /note %}} +> [!note] +> It is safe to use the `Fragments` methods within a render hook, even for the current page. +> +> When using the `Fragments` methods within a shortcode, call the shortcode using [standard notation]. If you use [Markdown notation] the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop. -[atx]: https://spec.commonmark.org/0.30/#atx-headings +[`TableOfContents`]: /methods/page/tableofcontents/ +[ATX]: https://spec.commonmark.org/0.30/#atx-headings +[Markdown notation]: /content-management/shortcodes/#notation [setext]: https://spec.commonmark.org/0.30/#setext-headings +[standard notation]: /content-management/shortcodes/#notation [table of contents]: /methods/page/tableofcontents/ -[`tableofcontents`]: /methods/page/tableofcontents/ diff --git a/docs/content/en/methods/page/FuzzyWordCount.md b/docs/content/en/methods/page/FuzzyWordCount.md index 8523edf8c..815a07402 100644 --- a/docs/content/en/methods/page/FuzzyWordCount.md +++ b/docs/content/en/methods/page/FuzzyWordCount.md @@ -1,14 +1,12 @@ --- title: FuzzyWordCount -description: Returns the number of words in the content of the given page, rounded up to the nearest multiple of 100. +description: Returns the number of words in the content of the given page, rounded up to the nearest multiple of 100. categories: [] keywords: [] -action: - related: - - methods/page/WordCount - - methods/page/ReadingTime - returnType: int - signatures: [PAGE.FuzzyWordCount] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.FuzzyWordCount] --- ```go-html-template diff --git a/docs/content/en/methods/page/GetPage.md b/docs/content/en/methods/page/GetPage.md index 7c71c5afa..02f6888e0 100644 --- a/docs/content/en/methods/page/GetPage.md +++ b/docs/content/en/methods/page/GetPage.md @@ -1,13 +1,12 @@ --- title: GetPage -description: Returns a Page object from the given path. +description: Returns a Page object from the given path. categories: [] keywords: [] -action: - related: - - methods/site/GetPage - returnType: page.Page - signatures: [PAGE.GetPage PATH] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.GetPage PATH] aliases: [/functions/getpage] --- @@ -38,7 +37,7 @@ content/ The examples below depict the result of rendering works/paintings/the-mona-lisa.md: -{{< code file=layouts/works/single.html >}} +```go-html-template {file="layouts/works/single.html"} {{ with .GetPage "starry-night" }} {{ .Title }} → Starry Night {{ end }} @@ -62,4 +61,4 @@ The examples below depict the result of rendering works/paintings/the-mona-lisa. {{ with .GetPage "/works/sculptures/david" }} {{ .Title }} → David {{ end }} -{{< /code >}} +``` diff --git a/docs/content/en/methods/page/GetTerms.md b/docs/content/en/methods/page/GetTerms.md index 3020e4c2e..53b996fc5 100644 --- a/docs/content/en/methods/page/GetTerms.md +++ b/docs/content/en/methods/page/GetTerms.md @@ -3,10 +3,10 @@ title: GetTerms description: Returns a collection of term pages for terms defined on the given page in the given taxonomy, ordered according to the sequence in which they appear in front matter. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGE.GetTerms TAXONOMY] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.GetTerms TAXONOMY] --- Given this front matter: diff --git a/docs/content/en/methods/page/GitInfo.md b/docs/content/en/methods/page/GitInfo.md index a05916d79..5fde05b07 100644 --- a/docs/content/en/methods/page/GitInfo.md +++ b/docs/content/en/methods/page/GitInfo.md @@ -3,19 +3,16 @@ title: GitInfo description: Returns Git information related to the last commit of the given page. categories: [] keywords: [] -action: - related: - - methods/page/CodeOwners - returnType: source.GitInfo - signatures: [PAGE.GitInfo] -toc: true +params: + functions_and_methods: + returnType: source.GitInfo + signatures: [PAGE.GitInfo] --- The `GitInfo` method on a `Page` object returns an object with additional methods. -{{% note %}} -Hugo's Git integration is performant, but may increase build times on large sites. -{{% /note %}} +> [!note] +> Hugo's Git integration is performant, but may increase build times on large sites. ## Prerequisites @@ -33,17 +30,14 @@ Alternatively, use the command line flag when building your site: hugo --enableGitInfo ``` -{{% note %}} -When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file. - -This is configurable. See [details]. - -[details]: /getting-started/configuration/#configure-dates -{{% /note %}} +> [!note] +> When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file. +> +> This is configurable. See [details]. ## Methods -###### AbbreviatedHash +### AbbreviatedHash (`string`) The abbreviated commit hash. @@ -53,7 +47,7 @@ This is configurable. See [details]. {{ end }} ``` -###### AuthorDate +### AuthorDate (`time.Time`) The author date. @@ -63,7 +57,7 @@ This is configurable. See [details]. {{ end }} ``` -###### AuthorEmail +### AuthorEmail (`string`) The author's email address, respecting [gitmailmap]. @@ -73,7 +67,7 @@ This is configurable. See [details]. {{ end }} ``` -###### AuthorName +### AuthorName (`string`) The author's name, respecting [gitmailmap]. @@ -83,7 +77,7 @@ This is configurable. See [details]. {{ end }} ``` -###### CommitDate +### CommitDate (`time.Time`) The commit date. @@ -93,7 +87,7 @@ This is configurable. See [details]. {{ end }} ``` -###### Hash +### Hash (`string`) The commit hash. @@ -103,7 +97,7 @@ This is configurable. See [details]. {{ end }} ``` -###### Subject +### Subject (`string`) The commit message subject. @@ -113,7 +107,7 @@ This is configurable. See [details]. {{ end }} ``` -###### Body +### Body (`string`) The commit message body. @@ -129,29 +123,29 @@ By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` obj You can change this behavior in your [site configuration]. -[git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git -[gitmailmap]: https://git-scm.com/docs/gitmailmap -[site configuration]: /getting-started/configuration/#configure-front-matter - ## Hosting considerations -When hosting your site in a CI/CD environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file. +When hosting your site in a [CI/CD](g) environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file. -Some providers perform deep clones by default, others allow you to configure the clone depth, and some providers only perform shallow clones. +Some providers perform deep clones by default, others allow you to configure the clone depth, and some only perform shallow clones. Hosting service | Default clone depth | Configurable :-- | :-- | :-- AWS Amplify | Deep | N/A -Cloudflare Pages | Shallow | Yes [^CFP] +Cloudflare Pages | Shallow | Yes [^1] DigitalOcean App Platform | Deep | N/A -GitHub Pages | Shallow | Yes [^GHP] -GitLab Pages | Shallow | Yes [^GLP] +GitHub Pages | Shallow | Yes [^2] +GitLab Pages | Shallow | Yes [^3] Netlify | Deep | N/A Render | Shallow | No Vercel | Shallow | No -[^CFP]: To configure a Cloudflare Pages site for deep cloning, preface the site's normal Hugo build command with `git fetch --unshallow &&` (*e.g.*, `git fetch --unshallow && hugo`). +[^1]: To configure a Cloudflare Pages site for deep cloning, run `git fetch --unshallow` before building the site. + +[^2]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/host-and-deploy/host-on-github-pages/#procedure). -[^GHP]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/hosting-and-deployment/hosting-on-github/#procedure). +[^3]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd). -[^GLP]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](/hosting-and-deployment/hosting-on-gitlab/#configure-gitlab-cicd). +[details]: /configuration/front-matter/#dates +[gitmailmap]: https://git-scm.com/docs/gitmailmap +[site configuration]: /configuration/front-matter/ diff --git a/docs/content/en/methods/page/HasMenuCurrent.md b/docs/content/en/methods/page/HasMenuCurrent.md index 24ce462c9..207882167 100644 --- a/docs/content/en/methods/page/HasMenuCurrent.md +++ b/docs/content/en/methods/page/HasMenuCurrent.md @@ -3,11 +3,10 @@ title: HasMenuCurrent description: Reports whether the given Page object matches the Page object associated with one of the child menu entries under the given menu entry in the given menu. categories: [] keywords: [] -action: - related: - - methods/page/IsMenuCurrent - returnType: bool - signatures: [PAGE.HasMenuCurrent MENU MENUENTRY] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.HasMenuCurrent MENU MENUENTRY] aliases: [/functions/hasmenucurrent] --- @@ -28,8 +27,7 @@ If the `Page` object associated with the menu entry is a section, this method al See [menu templates] for a complete example. -{{% note %}} -When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration. -{{% /note %}} +> [!note] +> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration. [menu templates]: /templates/menu/#example diff --git a/docs/content/en/methods/page/HasShortcode.md b/docs/content/en/methods/page/HasShortcode.md index 2846e9535..616b6de09 100644 --- a/docs/content/en/methods/page/HasShortcode.md +++ b/docs/content/en/methods/page/HasShortcode.md @@ -3,17 +3,17 @@ title: HasShortcode description: Reports whether the given shortcode is called by the given page. categories: [] keywords: [] -action: - related: [] - returnType: bool - signatures: [PAGE.HasShortcode NAME] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.HasShortcode NAME] --- By example, let's use [Plotly] to render a chart: [Plotly]: https://plotly.com/javascript/ -{{< code file=contents/example.md lang=markdown >}} +```text {file="content/example.md"} {{</* plotly */>}} { "data": [ @@ -25,21 +25,21 @@ By example, let's use [Plotly] to render a chart: ], } {{</* /plotly */>}} -{{< /code >}} +``` The shortcode is simple: -{{< code file=layouts/shortcodes/plotly.html >}} +```go-html-template {file="layouts/shortcodes/plotly.html"} {{ $id := printf "plotly-%02d" .Ordinal }} <div id="{{ $id }}"></div> <script> Plotly.newPlot(document.getElementById({{ $id }}), {{ .Inner | safeJS }}); </script> -{{< /code >}} +``` Now we can selectively load the required JavaScript on pages that call the "plotly" shortcode: -{{< code file=layouts/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} <head> ... {{ if .HasShortcode "plotly" }} @@ -47,4 +47,4 @@ Now we can selectively load the required JavaScript on pages that call the "plot {{ end }} ... </head> -{{< /code >}} +``` diff --git a/docs/content/en/methods/page/HeadingsFiltered.md b/docs/content/en/methods/page/HeadingsFiltered.md index d741b57ce..86c989d43 100644 --- a/docs/content/en/methods/page/HeadingsFiltered.md +++ b/docs/content/en/methods/page/HeadingsFiltered.md @@ -3,16 +3,14 @@ title: HeadingsFiltered description: Returns a slice of headings for each page related to the given page. categories: [] keywords: [] -action: - related: - - methods/pages/Related - - methods/page/Fragments - returnType: tableofcontents.Headings - signatures: [PAGE.HeadingsFiltered] +params: + functions_and_methods: + returnType: tableofcontents.Headings + signatures: [PAGE.HeadingsFiltered] --- Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details]. [`Pages`]: /methods/pages/ [`Related`]: /methods/pages/related/ -[details]: /content-management/related/#index-content-headings-in-related-content +[details]: /content-management/related-content/#index-content-headings diff --git a/docs/content/en/methods/page/InSection.md b/docs/content/en/methods/page/InSection.md index 904f6ce75..adca82d86 100644 --- a/docs/content/en/methods/page/InSection.md +++ b/docs/content/en/methods/page/InSection.md @@ -3,24 +3,16 @@ title: InSection description: Reports whether the given page is in the given section. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: bool - signatures: [PAGE.InSection SECTION] -toc: true +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.InSection SECTION] --- -The `InSection` method on a `Page` object reports whether the given page is in the given section. Note that the method returns `true` when comparing a page to a sibling. - {{% glossary-term section %}} +The `InSection` method on a `Page` object reports whether the given page is in the given section. Note that the method returns `true` when comparing a page to a sibling. + With this content structure: ```text @@ -83,9 +75,8 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. ```go-html-template {{ with .Site.GetPage "/auctions" }} @@ -93,9 +84,8 @@ Use the `$` to get the context passed into the template. {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. -[`with`]: /functions/go-template/with/ [`else`]: /functions/go-template/else/ +[`with`]: /functions/go-template/with/ diff --git a/docs/content/en/methods/page/IsAncestor.md b/docs/content/en/methods/page/IsAncestor.md index 2613a2875..fe1b78454 100644 --- a/docs/content/en/methods/page/IsAncestor.md +++ b/docs/content/en/methods/page/IsAncestor.md @@ -3,22 +3,12 @@ title: IsAncestor description: Reports whether PAGE1 is an ancestor of PAGE2. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsDescendant - - methods/page/Parent - - methods/page/Sections - returnType: bool - signatures: [PAGE1.IsAncestor PAGE2] -toc: true +params: + functions_and_methods: + returnType: bool + signatures: [PAGE1.IsAncestor PAGE2] --- -{{% glossary-term section %}} - With this content structure: ```text @@ -81,9 +71,8 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. ```go-html-template {{ with .Site.GetPage "/auctions" }} @@ -91,9 +80,8 @@ Use the `$` to get the context passed into the template. {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. -[`with`]: /functions/go-template/with/ [`else`]: /functions/go-template/else/ +[`with`]: /functions/go-template/with/ diff --git a/docs/content/en/methods/page/IsDescendant.md b/docs/content/en/methods/page/IsDescendant.md index 4ef7c6598..6ee8d3c4f 100644 --- a/docs/content/en/methods/page/IsDescendant.md +++ b/docs/content/en/methods/page/IsDescendant.md @@ -3,21 +3,12 @@ title: IsDescendant description: Reports whether PAGE1 is a descendant of PAGE2. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/Parent - - methods/page/Sections - returnType: bool - signatures: [PAGE1.IsDescendant PAGE2] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE1.IsDescendant PAGE2] --- -{{% glossary-term section %}} - With this content structure: ```text @@ -80,9 +71,8 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. ```go-html-template {{ with .Site.GetPage "/auctions" }} @@ -90,9 +80,8 @@ Use the `$` to get the context passed into the template. {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. -[`with`]: /functions/go-template/with/ [`else`]: /functions/go-template/else/ +[`with`]: /functions/go-template/with/ diff --git a/docs/content/en/methods/page/IsHome.md b/docs/content/en/methods/page/IsHome.md index 16b04034f..66d8180b0 100644 --- a/docs/content/en/methods/page/IsHome.md +++ b/docs/content/en/methods/page/IsHome.md @@ -3,13 +3,10 @@ title: IsHome description: Reports whether the given page is the home page. categories: [] keywords: [] -action: - related: - - methods/page/IsNode - - methods/page/IsPage - - methods/page/IsSection - returnType: bool - signatures: [PAGE.IsHome] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsHome] --- The `IsHome` method on a `Page` object returns `true` if the [page kind](g) is `home`. diff --git a/docs/content/en/methods/page/IsMenuCurrent.md b/docs/content/en/methods/page/IsMenuCurrent.md index a16be51ee..9bbacd018 100644 --- a/docs/content/en/methods/page/IsMenuCurrent.md +++ b/docs/content/en/methods/page/IsMenuCurrent.md @@ -3,11 +3,10 @@ title: IsMenuCurrent description: Reports whether the given Page object matches the Page object associated with the given menu entry in the given menu. categories: [] keywords: [] -action: - related: - - methods/page/HasMenuCurrent - returnType: bool - signatures: [PAGE.IsMenuCurrent MENU MENUENTRY] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsMenuCurrent MENU MENUENTRY] aliases: [/functions/ismenucurrent] --- @@ -26,8 +25,7 @@ aliases: [/functions/ismenucurrent] See [menu templates] for a complete example. -{{% note %}} -When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration. -{{% /note %}} +> [!note] +> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration. [menu templates]: /templates/menu/#example diff --git a/docs/content/en/methods/page/IsNode.md b/docs/content/en/methods/page/IsNode.md index 5335ef376..194a2cac8 100644 --- a/docs/content/en/methods/page/IsNode.md +++ b/docs/content/en/methods/page/IsNode.md @@ -3,13 +3,10 @@ title: IsNode description: Reports whether the given page is a node. categories: [] keywords: [] -action: - related: - - methods/page/IsHome - - methods/page/IsPage - - methods/page/IsSection - returnType: bool - signatures: [PAGE.IsNode] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsNode] --- The `IsNode` method on a `Page` object returns `true` if the [page kind](g) is `home`, `section`, `taxonomy`, or `term`. diff --git a/docs/content/en/methods/page/IsPage.md b/docs/content/en/methods/page/IsPage.md index 92e6101d9..910a3a7e1 100644 --- a/docs/content/en/methods/page/IsPage.md +++ b/docs/content/en/methods/page/IsPage.md @@ -3,13 +3,10 @@ title: IsPage description: Reports whether the given page is a regular page. categories: [] keywords: [] -action: - related: - - methods/page/IsHome - - methods/page/IsNode - - methods/page/IsSection - returnType: bool - signatures: [PAGE.IsPage] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsPage] --- The `IsPage` method on a `Page` object returns `true` if the [page kind](g) is `page`. diff --git a/docs/content/en/methods/page/IsSection.md b/docs/content/en/methods/page/IsSection.md index 965e466cd..7a04fbd8f 100644 --- a/docs/content/en/methods/page/IsSection.md +++ b/docs/content/en/methods/page/IsSection.md @@ -3,13 +3,10 @@ title: IsSection description: Reports whether the given page is a section page. categories: [] keywords: [] -action: - related: - - methods/page/IsHome - - methods/page/IsNode - - methods/page/IsPage - returnType: bool - signatures: [PAGE.IsSection] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsSection] --- The `IsSection` method on a `Page` object returns `true` if the [page kind](g) is `section`. diff --git a/docs/content/en/methods/page/IsTranslated.md b/docs/content/en/methods/page/IsTranslated.md index 47019a52c..2cdf911ac 100644 --- a/docs/content/en/methods/page/IsTranslated.md +++ b/docs/content/en/methods/page/IsTranslated.md @@ -3,13 +3,10 @@ title: IsTranslated description: Reports whether the given page has one or more translations. categories: [] keywords: [] -action: - related: - - methods/page/Translations - - methods/page/AllTranslations - - methods/page/TranslationKey - returnType: bool - signatures: [PAGE.IsTranslated] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.IsTranslated] --- With this site configuration: diff --git a/docs/content/en/methods/page/Keywords.md b/docs/content/en/methods/page/Keywords.md index ef68c27f5..7c940984e 100644 --- a/docs/content/en/methods/page/Keywords.md +++ b/docs/content/en/methods/page/Keywords.md @@ -3,15 +3,15 @@ title: Keywords description: Returns a slice of keywords as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: '[]string' - signatures: [PAGE.Keywords] +params: + functions_and_methods: + returnType: '[]string' + signatures: [PAGE.Keywords] --- By default, Hugo evaluates the keywords when creating collections of [related content]. -[related content]: /content-management/related/ +[related content]: /content-management/related-content/ {{< code-toggle file=content/recipes/sushi.md fm=true >}} title = 'How to make spicy tuna hand rolls' diff --git a/docs/content/en/methods/page/Kind.md b/docs/content/en/methods/page/Kind.md index c5b0c6b9d..a01877e8c 100644 --- a/docs/content/en/methods/page/Kind.md +++ b/docs/content/en/methods/page/Kind.md @@ -3,11 +3,10 @@ title: Kind description: Returns the kind of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Type - returnType: string - signatures: [PAGE.Kind] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Kind] --- The [page kind](g) is one of `home`, `page`, `section`, `taxonomy`, or `term`. diff --git a/docs/content/en/methods/page/Language.md b/docs/content/en/methods/page/Language.md index e12fc2e62..9fd604df3 100644 --- a/docs/content/en/methods/page/Language.md +++ b/docs/content/en/methods/page/Language.md @@ -3,11 +3,10 @@ title: Language description: Returns the language object for the given page. categories: [] keywords: [] -action: - related: - - methods/site/Language - returnType: langs.Language - signatures: [PAGE.Language] +params: + functions_and_methods: + returnType: langs.Language + signatures: [PAGE.Language] --- The `Language` method on a `Page` object returns the language object for the given page. The language object points to the language definition in the site configuration. @@ -26,7 +25,7 @@ languageName = 'Deutsch' weight = 2 {{< /code-toggle >}} -###### Lang +### Lang (`string`) The language tag as defined by [RFC 5646]. @@ -34,7 +33,7 @@ weight = 2 {{ .Language.Lang }} → de ``` -###### LanguageCode +### LanguageCode (`string`) The language code from the site configuration. Falls back to `Lang` if not defined. @@ -42,7 +41,7 @@ weight = 2 {{ .Language.LanguageCode }} → de-DE ``` -###### LanguageDirection +### LanguageDirection (`string`) The language direction from the site configuration, either `ltr` or `rtl`. @@ -50,7 +49,7 @@ weight = 2 {{ .Language.LanguageDirection }} → ltr ``` -###### LanguageName +### LanguageName (`string`) The language name from the site configuration. @@ -58,7 +57,7 @@ weight = 2 {{ .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. diff --git a/docs/content/en/methods/page/Lastmod.md b/docs/content/en/methods/page/Lastmod.md index 78760d556..643eddc5e 100644 --- a/docs/content/en/methods/page/Lastmod.md +++ b/docs/content/en/methods/page/Lastmod.md @@ -1,16 +1,12 @@ --- title: Lastmod -description: Returns the last modification date of the given page. +description: Returns the last modification date of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Date - - methods/page/ExpiryDate - - methods/page/PublishDate - - methods/page/GitInfo - returnType: time.Time - signatures: [PAGE.Lastmod] +params: + functions_and_methods: + returnType: time.Time + signatures: [PAGE.Lastmod] --- Set the last modification date in front matter: @@ -35,6 +31,6 @@ Learn more about [date configuration]. [`gitinfo`]: /methods/page/gitinfo/ [`time.format`]: /functions/time/format/ -[date configuration]: /getting-started/configuration/#configure-dates +[date configuration]: /configuration/front-matter/#dates [time methods]: /methods/time/ -[time.time]: https://pkg.go.dev/time#time +[time.time]: https://pkg.go.dev/time#Time diff --git a/docs/content/en/methods/page/Layout.md b/docs/content/en/methods/page/Layout.md index 3d0cdc437..f9aa5b6ab 100644 --- a/docs/content/en/methods/page/Layout.md +++ b/docs/content/en/methods/page/Layout.md @@ -3,18 +3,17 @@ title: Layout description: Returns the layout for the given page as defined in front matter. categories: [] keywords: [] -action: - related: - - methods/page/Type - returnType: string - signatures: [PAGE.Layout] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Layout] --- Specify the `layout` field in front matter to target a particular template. See [details]. [details]: /templates/lookup-order/#target-a-template -{{< code-toggle file=content/contact.md >}} +{{< code-toggle file=content/contact.md fm=true >}} title = 'Contact' layout = 'contact' {{< /code-toggle >}} diff --git a/docs/content/en/methods/page/Len.md b/docs/content/en/methods/page/Len.md index d4270bda3..010da88d1 100644 --- a/docs/content/en/methods/page/Len.md +++ b/docs/content/en/methods/page/Len.md @@ -3,11 +3,10 @@ title: Len description: Returns the length, in bytes, of the rendered content of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Content - returnType: int - signatures: [PAGE.Len] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.Len] --- ```go-html-template diff --git a/docs/content/en/methods/page/LinkTitle.md b/docs/content/en/methods/page/LinkTitle.md index 0ce32e641..fcfd5318d 100644 --- a/docs/content/en/methods/page/LinkTitle.md +++ b/docs/content/en/methods/page/LinkTitle.md @@ -3,11 +3,10 @@ title: LinkTitle description: Returns the link title of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Title - returnType: string - signatures: [PAGE.LinkTitle] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.LinkTitle] --- The `LinkTitle` method returns the `linkTitle` field as defined in front matter, falling back to the value returned by the [`Title`] method. diff --git a/docs/content/en/methods/page/Next.md b/docs/content/en/methods/page/Next.md index ff0525700..996603083 100644 --- a/docs/content/en/methods/page/Next.md +++ b/docs/content/en/methods/page/Next.md @@ -3,15 +3,10 @@ title: Next description: Returns the next page in a site's collection of regular pages, relative to the current page. categories: [] keywords: [] -action: - related: - - methods/page/Prev - - methods/page/NextInSection - - methods/page/PrevInSection - - methods/pages/Next - - methods/pages/Prev - returnType: page.Page - signatures: [PAGE.Next] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.Next] --- -{{% include "methods/page/_common/next-and-prev.md" %}} +{{% include "/_common/methods/page/next-and-prev.md" %}} diff --git a/docs/content/en/methods/page/NextInSection.md b/docs/content/en/methods/page/NextInSection.md index 640e9b44a..eb02c9492 100644 --- a/docs/content/en/methods/page/NextInSection.md +++ b/docs/content/en/methods/page/NextInSection.md @@ -1,15 +1,12 @@ --- title: NextInSection -description: Returns the next regular page in a section, relative to the given page. +description: Returns the next regular page in a section, relative to the given page. categories: [] keywords: [] -action: - related: - - methods/page/PrevInSection - - methods/pages/Next - - methods/pages/Prev - returnType: page.Page - signatures: [PAGE.NextInSection] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.NextInSection] --- -{{% include "methods/page/_common/nextinsection-and-previnsection.md" %}} +{{% include "/_common/methods/page/nextinsection-and-previnsection.md" %}} diff --git a/docs/content/en/methods/page/OutputFormats.md b/docs/content/en/methods/page/OutputFormats.md index a6d014a93..0e648efaa 100644 --- a/docs/content/en/methods/page/OutputFormats.md +++ b/docs/content/en/methods/page/OutputFormats.md @@ -3,28 +3,26 @@ title: OutputFormats description: Returns a slice of OutputFormat objects, each representing one of the output formats enabled for the given page. categories: [] keywords: [] -action: - related: - - methods/page/AlternativeOutputFormats - returnType: '[]OutputFormat' - signatures: [PAGE.OutputFormats] -toc: true +params: + functions_and_methods: + returnType: '[]OutputFormat' + signatures: [PAGE.OutputFormats] --- {{% glossary-term "output format" %}} -The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See [details](/templates/output-formats/). +The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/). ## Methods -{{% include "methods/page/_common/output-format-methods.md" %}} +{{% include "/_common/methods/page/output-format-methods.md" %}} ## Example To link to the RSS feed for the current page: ```go-html-template -{{ with .OutputFormats.Get "rss" -}} +{{ with .OutputFormats.Get "rss" }} <a href="{{ .RelPermalink }}">RSS Feed</a> {{ end }} ``` @@ -37,4 +35,4 @@ On the site's home page, Hugo renders this to: Please see the [link to output formats] section to understand the importance of the construct above. -[link to output formats]: /templates/output-formats/#link-to-output-formats +[link to output formats]: /configuration/output-formats/#link-to-output-formats diff --git a/docs/content/en/methods/page/Page.md b/docs/content/en/methods/page/Page.md index 1d6867792..7c7728b2f 100644 --- a/docs/content/en/methods/page/Page.md +++ b/docs/content/en/methods/page/Page.md @@ -3,34 +3,33 @@ title: Page description: Returns the Page object of the given page. categories: [] keywords: [] -action: - related: [] - returnType: page.Page - signatures: [PAGE.Page] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.Page] --- This is a convenience method, useful within partial templates that are called from both [shortcodes](g) and page templates. -{{< code file=layouts/shortcodes/foo.html >}} +```go-html-template {file="layouts/shortcodes/foo.html"} {{ partial "my-partial.html" . }} -{{< /code >}} +``` When the shortcode calls the partial, it passes the current [context](g) (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`. -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ partial "my-partial.html" . }} -{{< /code >}} +``` When the page template calls the partial, it also passes the current context (the dot). But in this case, the dot _is_ the `Page` object. -{{< code file=layouts/partials/my-partial.html >}} +```go-html-template {file="layouts/partials/my-partial.html"} The page title is: {{ .Page.Title }} -{{< /code >}} +``` To handle both scenarios, the partial template must be able to access the `Page` object with `Page.Page`. -{{% note %}} -And yes, that means you can do `.Page.Page.Page.Page.Title` too. - -But don't. -{{% /note %}} +> [!note] +> And yes, that means you can do `.Page.Page.Page.Page.Title` too. +> +> But don't. diff --git a/docs/content/en/methods/page/Pages.md b/docs/content/en/methods/page/Pages.md index 8efcde287..ba43c36a8 100644 --- a/docs/content/en/methods/page/Pages.md +++ b/docs/content/en/methods/page/Pages.md @@ -3,15 +3,13 @@ title: Pages description: Returns a collection of regular pages within the current section, and section pages of immediate descendant sections. categories: [] keywords: [] -action: - related: - - methods/page/RegularPages - - methods/page/RegularPagesRecursive - returnType: page.Pages - signatures: [PAGE.Pages] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.Pages] --- -The `Pages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g). +The `Pages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g). Range through the page collection in your template: @@ -72,14 +70,13 @@ When rendering lesson-2, the `Pages` method returns: In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section. -{{% note %}} -When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details]. - -[details]: /methods/site/pages/ -{{% /note %}} +> [!note] +> When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details]. ```go-html-template {{ range .Site.Pages.ByTitle }} <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> {{ end }} ``` + +[details]: /methods/site/pages/ diff --git a/docs/content/en/methods/page/Paginate.md b/docs/content/en/methods/page/Paginate.md index 9d98fbb2f..0b699d6b2 100644 --- a/docs/content/en/methods/page/Paginate.md +++ b/docs/content/en/methods/page/Paginate.md @@ -3,40 +3,31 @@ title: Paginate description: Paginates a collection of pages. categories: [] keywords: [] -action: - related: - - methods/page/Paginator - returnType: page.Pager - signatures: ['PAGE.Paginate COLLECTION [N]'] +params: + functions_and_methods: + returnType: page.Pager + signatures: ['PAGE.Paginate COLLECTION [N]'] --- Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. By default, the number of elements on each pager is determined by your [site configuration]. The default is `10`. Override that value by providing a second argument, an integer, when calling the `Paginate` method. -[site configuration]: /getting-started/configuration/#pagination - -{{% note %}} -There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection. - -The `Paginate` method is more flexible. -{{% /note %}} +> [!note] +> There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection. +> +> The `Paginate` method is more flexible. You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates]. -[home template]: /templates/types/#home -[section templates]: /templates/types/#section -[taxonomy templates]: /templates/types/#taxonomy -[term templates]: /templates/types/#term - -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ $pages := where .Site.RegularPages "Section" "articles" }} {{ $pages = $pages.ByTitle }} {{ range (.Paginate $pages 7).Pages }} <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> {{ end }} {{ template "_internal/pagination.html" . }} -{{< /code >}} +``` In the example above, we: @@ -46,6 +37,11 @@ In the example above, we: 1. Range over the paginated page collection, rendering a link to each page 1. Call the embedded pagination template to create navigation links between pagers -{{% note %}} -Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. -{{% /note %}} +> [!note] +> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. + +[home template]: /templates/types/#home +[section templates]: /templates/types/#section +[site configuration]: /configuration/pagination/ +[taxonomy templates]: /templates/types/#taxonomy +[term templates]: /templates/types/#term diff --git a/docs/content/en/methods/page/Paginator.md b/docs/content/en/methods/page/Paginator.md index c3161da6c..bff7ea90c 100644 --- a/docs/content/en/methods/page/Paginator.md +++ b/docs/content/en/methods/page/Paginator.md @@ -1,45 +1,40 @@ --- title: Paginator -description: Paginates the collection of regular pages received in context. +description: Paginates the collection of regular pages received in context. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGE.Paginator] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGE.Paginator] --- Pagination is the process of splitting a list page into two or more pagers, where each pager contains a subset of the page collection and navigation links to other pagers. The number of elements on each pager is determined by your [site configuration]. The default is `10`. -[site configuration]: /getting-started/configuration/#pagination - You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates]. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context. -[home template]: /templates/types/#home -[section templates]: /templates/types/#section -[taxonomy templates]: /templates/types/#taxonomy -[term templates]: /templates/types/#term - -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ range .Paginator.Pages }} <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} {{ template "_internal/pagination.html" . }} -{{< /code >}} +``` In the example above, the embedded pagination template creates navigation links between pagers. -{{% note %}} -Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context. +> [!note] +> Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context. +> +> The [`Paginate`] method is more flexible, and strongly recommended. -The [`Paginate`] method is more flexible, and strongly recommended. +> [!note] +> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. -[`paginate`]: /methods/page/paginate/ -{{% /note %}} - -{{% note %}} -Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect. -{{% /note %}} +[home template]: /templates/types/#home +[section templates]: /templates/types/#section +[site configuration]: /configuration/pagination/ +[taxonomy templates]: /templates/types/#taxonomy +[term templates]: /templates/types/#term +[`Paginate`]: /methods/page/paginate/ diff --git a/docs/content/en/methods/page/Param.md b/docs/content/en/methods/page/Param.md index daf09a5b4..b07c1cd92 100644 --- a/docs/content/en/methods/page/Param.md +++ b/docs/content/en/methods/page/Param.md @@ -3,10 +3,10 @@ title: Param description: Returns a page parameter with the given key, falling back to a site parameter if present. categories: [] keywords: [] -action: - related: [] - returnType: any - signatures: [PAGE.Param KEY] +params: + functions_and_methods: + returnType: any + signatures: [PAGE.Param KEY] aliases: [/functions/param] --- diff --git a/docs/content/en/methods/page/Params.md b/docs/content/en/methods/page/Params.md index faeda4504..eeb253437 100644 --- a/docs/content/en/methods/page/Params.md +++ b/docs/content/en/methods/page/Params.md @@ -3,40 +3,40 @@ title: Params description: Returns a map of custom parameters as defined in the front matter of the given page. categories: [] keywords: [] -action: - related: - - functions/collections/IndexFunction - - methods/site/Params - - methods/page/Param - returnType: maps.Params - signatures: [PAGE.Params] +params: + functions_and_methods: + returnType: maps.Params + signatures: [PAGE.Params] --- -With this front matter: +By way of example, consider this front matter: -{{< code-toggle file=content/news/annual-conference.md >}} +{{< code-toggle file=content/annual-conference.md fm=true >}} title = 'Annual conference' date = 2023-10-17T15:11:37-07:00 [params] display_related = true +key-with-hyphens = 'must use index function' [params.author] email = 'jsmith@example.org' name = 'John Smith' {{< /code-toggle >}} -The `title` and `date` fields are standard parameters---the other fields are user-defined. +The `title` and `date` fields are standard [front matter fields], while the other fields are user-defined. -Access the custom parameters by [chaining](g) the [identifiers](g): +Access the custom fields by [chaining](g) the [identifiers](g) when needed: ```go-html-template {{ .Params.display_related }} → true +{{ .Params.author.email }} → jsmith@example.org {{ .Params.author.name }} → John Smith ``` In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function: ```go-html-template -{{ index .Params "key-with-hyphens" }} → 2023 +{{ index .Params "key-with-hyphens" }} → must use index function ``` [`index`]: /functions/collections/indexfunction/ +[front matter fields]: /content-management/front-matter/#fields diff --git a/docs/content/en/methods/page/Parent.md b/docs/content/en/methods/page/Parent.md index 4c182f8e1..0946a7993 100644 --- a/docs/content/en/methods/page/Parent.md +++ b/docs/content/en/methods/page/Parent.md @@ -3,26 +3,16 @@ title: Parent description: Returns the Page object of the parent section of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Sections - returnType: page.Page - signatures: [PAGE.Parent] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.Parent] --- {{% glossary-term section %}} -{{% note %}} -The parent section of a regular page is the [current section]. - -[current section]: /methods/page/currentsection/ -{{% /note %}} +> [!note] +> The parent section of a regular page is the [current section]. Consider this content structure: @@ -58,3 +48,5 @@ In the example above, note the parent section of the home page is nil. Code defe <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> {{ end }} ``` + +[current section]: /methods/page/currentsection/ diff --git a/docs/content/en/methods/page/Path.md b/docs/content/en/methods/page/Path.md index 83ad01b94..db4e7d629 100644 --- a/docs/content/en/methods/page/Path.md +++ b/docs/content/en/methods/page/Path.md @@ -3,40 +3,26 @@ title: Path description: Returns the logical path of the given page. categories: [] keywords: [] -action: - related: - - methods/page/File - - methods/page/RelPermalink - returnType: string - signatures: [PAGE.Path] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Path] --- {{< new-in 0.123.0 />}} -The `Path` method on a `Page` object returns the [logical path](g) of the given page, regardless of whether the page is backed by a file. +The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file. + +{{% glossary-term "logical path" %}} ```go-html-template {{ .Path }} → /posts/post-1 ``` -This value is neither a file path nor a relative URL. It is a logical identifier for each page, independent of content format, language, and URL modifiers. - -{{% note %}} -Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release. - -The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024. - -[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0 -[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0 -{{% /note %}} - -To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the `content` directory, and then: - -1. Strips the file extension -1. Strips the language identifier -1. Converts the result to lower case -1. Replaces spaces with hyphens +> [!note] +> Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release. +> +> The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024. The value returned by the `Path` method on a `Page` object is independent of content format, language, and URL modifiers such as the `slug` and `url` front matter fields. @@ -101,25 +87,13 @@ Methods|Functions|Shortcodes :--|:--|:-- [`Site.GetPage`]|[`urls.Ref`]|[`ref`] [`Page.GetPage`]|[`urls.RelRef`]|[`relref`] -[`Page.Ref`]|| -[`Page.RelRef`]|| -[`Shortcode.Ref`]|| -[`Shortcode.RelRef`]|| - -[`urls.Ref`]: /functions/urls/ref/ -[`urls.RelRef`]: /functions/urls/relref/ -[`Page.GetPage`]: /methods/page/getpage/ -[`Site.GetPage`]: /methods/site/getpage/ -[`ref`]: /shortcodes/ref/ -[`relref`]: /shortcodes/relref/ -[`Page.Ref`]: /methods/page/ref/ -[`Page.RelRef`]: /methods/page/relref/ -[`Shortcode.Ref`]: /methods/shortcode/ref -[`Shortcode.RelRef`]: /methods/shortcode/relref +[`Page.Ref`]||| +[`Page.RelRef`]||| +[`Shortcode.Ref`]||| +[`Shortcode.RelRef`]||| -{{% note %}} -Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. -{{% /note %}} +> [!note] +> Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. ## Logical tree @@ -149,6 +123,18 @@ A key difference between these trees is the relative path from p1 to p2: - In the file tree, the relative path from p1 to p2 is `../p2.md` - In the logical tree, the relative path is `p2` -{{% note %}} -Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. -{{% /note %}} +> [!note] +> Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree. + +[`Page.GetPage`]: /methods/page/getpage/ +[`Page.Ref`]: /methods/page/ref/ +[`Page.RelRef`]: /methods/page/relref/ +[`ref`]: /shortcodes/ref/ +[`relref`]: /shortcodes/relref/ +[`Shortcode.Ref`]: /methods/shortcode/ref +[`Shortcode.RelRef`]: /methods/shortcode/relref +[`Site.GetPage`]: /methods/site/getpage/ +[`urls.Ref`]: /functions/urls/ref/ +[`urls.RelRef`]: /functions/urls/relref/ +[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0 +[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0 diff --git a/docs/content/en/methods/page/Permalink.md b/docs/content/en/methods/page/Permalink.md index d8416df86..cc74f3342 100644 --- a/docs/content/en/methods/page/Permalink.md +++ b/docs/content/en/methods/page/Permalink.md @@ -3,11 +3,10 @@ title: Permalink description: Returns the permalink of the given page. categories: [] keywords: [] -action: - related: - - methods/page/RelPermalink - returnType: string - signatures: [PAGE.Permalink] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Permalink] --- Site configuration: diff --git a/docs/content/en/methods/page/Plain.md b/docs/content/en/methods/page/Plain.md index e26c33529..65d11166e 100644 --- a/docs/content/en/methods/page/Plain.md +++ b/docs/content/en/methods/page/Plain.md @@ -3,16 +3,10 @@ title: Plain description: Returns the rendered content of the given page, removing all HTML tags. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/RawContent - - methods/page/PlainWords - - methods/page/RenderShortcodes - returnType: string - signatures: [PAGE.Plain] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Plain] --- The `Plain` method on a `Page` object renders Markdown and [shortcodes](g) to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. diff --git a/docs/content/en/methods/page/PlainWords.md b/docs/content/en/methods/page/PlainWords.md index 221fd741b..5749a21f9 100644 --- a/docs/content/en/methods/page/PlainWords.md +++ b/docs/content/en/methods/page/PlainWords.md @@ -3,25 +3,16 @@ title: PlainWords description: Calls the Plain method, splits the result into a slice of words, and returns the slice. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/RawContent - - methods/page/Plain - - methods/page/RenderShortcodes - returnType: '[]string' - signatures: [PAGE.PlainWords] +params: + functions_and_methods: + returnType: '[]string' + signatures: [PAGE.PlainWords] --- The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words. -{{% note %}} -_Fields splits the string s around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only whitespace._ - -[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace -{{% /note %}} +> [!note] +> `Fields` splits the string `s` around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of `s` or an empty slice if `s` contains only whitespace. As a result, elements within the slice may contain leading or trailing punctuation. @@ -37,3 +28,4 @@ To determine the approximate number of unique words on a page: [`Plain`]: /methods/page/plain/ [`strings.Fields`]: https://pkg.go.dev/strings#Fields +[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace diff --git a/docs/content/en/methods/page/Prev.md b/docs/content/en/methods/page/Prev.md index d28b50265..5a6e2162d 100644 --- a/docs/content/en/methods/page/Prev.md +++ b/docs/content/en/methods/page/Prev.md @@ -3,15 +3,10 @@ title: Prev description: Returns the previous page in a site's collection of regular pages, relative to the current page. categories: [] keywords: [] -action: - related: - - methods/page/Next - - methods/page/NextInSection - - methods/page/PrevInSection - - methods/pages/Next - - methods/pages/Prev - returnType: page.Page - signatures: [PAGE.Prev] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.Prev] --- -{{% include "methods/page/_common/next-and-prev.md" %}} +{{% include "/_common/methods/page/next-and-prev.md" %}} diff --git a/docs/content/en/methods/page/PrevInSection.md b/docs/content/en/methods/page/PrevInSection.md index aaafb367e..14d3ca082 100644 --- a/docs/content/en/methods/page/PrevInSection.md +++ b/docs/content/en/methods/page/PrevInSection.md @@ -1,15 +1,12 @@ --- title: PrevInSection -description: Returns the previous regular page in a section, relative to the given page. +description: Returns the previous regular page in a section, relative to the given page. categories: [] keywords: [] -action: - related: - - methods/page/NextInSection - - methods/pages/Next - - methods/pages/Prev - returnType: page.Page - signatures: [PAGE.PrevInSection] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGE.PrevInSection] --- -{{% include "methods/page/_common/nextinsection-and-previnsection.md" %}} +{{% include "/_common/methods/page/nextinsection-and-previnsection.md" %}} diff --git a/docs/content/en/methods/page/PublishDate.md b/docs/content/en/methods/page/PublishDate.md index d1f2eb2a1..7500a08aa 100644 --- a/docs/content/en/methods/page/PublishDate.md +++ b/docs/content/en/methods/page/PublishDate.md @@ -3,13 +3,10 @@ title: PublishDate description: Returns the publish date of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Date - - methods/page/ExpiryDate - - methods/page/LastMod - returnType: time.Time - signatures: [PAGE.PublishDate] +params: + functions_and_methods: + returnType: time.Time + signatures: [PAGE.PublishDate] --- By default, Hugo excludes pages with future publish dates when building your site. To include future pages, use the `--buildFuture` command line flag. @@ -30,6 +27,6 @@ The publish date is a [time.Time] value. Format and localize the value with the In the example above we explicitly set the publish date in front matter. With Hugo's default configuration, the `PublishDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the publish date is not defined in front matter. See [details]. [`time.Format`]: /functions/time/format/ -[details]: /getting-started/configuration/#configure-dates +[details]: /configuration/front-matter/#dates [time methods]: /methods/time/ [time.Time]: https://pkg.go.dev/time#Time diff --git a/docs/content/en/methods/page/RawContent.md b/docs/content/en/methods/page/RawContent.md index 9dab9693e..41215ef53 100644 --- a/docs/content/en/methods/page/RawContent.md +++ b/docs/content/en/methods/page/RawContent.md @@ -3,16 +3,10 @@ title: RawContent description: Returns the raw content of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/Plain - - methods/page/PlainWords - - methods/page/RenderShortcodes - returnType: string - signatures: [PAGE.RawContent] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.RawContent] --- The `RawContent` method on a `Page` object returns the raw content. The raw content does not include front matter. @@ -21,12 +15,9 @@ The `RawContent` method on a `Page` object returns the raw content. The raw cont {{ .RawContent }} ``` -This is useful when rendering a page in a plain text [output format]. +This is useful when rendering a page in a plain text [output format](g). -{{% note %}} -[Shortcodes](g) within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object. +> [!note] +> [Shortcodes](g) within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object. [`RenderShortcodes`]: /methods/page/rendershortcodes/ -{{% /note %}} - -[output format]: /templates/output-formats/ diff --git a/docs/content/en/methods/page/ReadingTime.md b/docs/content/en/methods/page/ReadingTime.md index 531824b9b..1bd7dea31 100644 --- a/docs/content/en/methods/page/ReadingTime.md +++ b/docs/content/en/methods/page/ReadingTime.md @@ -3,12 +3,10 @@ title: ReadingTime description: Returns the estimated reading time, in minutes, for the given page. categories: [] keywords: [] -action: - related: - - methods/page/WordCount - - methods/page/FuzzyWordCount - returnType: int - signatures: [PAGE.ReadingTime] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.ReadingTime] --- The estimated reading time is calculated by dividing the number of words in the content by the reading speed. diff --git a/docs/content/en/methods/page/Ref.md b/docs/content/en/methods/page/Ref.md index e0d42424d..35f9460ba 100644 --- a/docs/content/en/methods/page/Ref.md +++ b/docs/content/en/methods/page/Ref.md @@ -3,27 +3,23 @@ title: Ref description: Returns the absolute URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - related: - - methods/page/RelRef - - functions/urls/RelRef - - functions/urls/Ref - returnType: string - signatures: [PAGE.Ref OPTIONS] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Ref OPTIONS] --- -The map of option contains: +## Usage -path -: (`string`) The path to the page, relative to the `content` directory. Required. +The `Ref` method accepts a single argument: an options map. -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +## Options -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. +{{% include "_common/ref-and-relref-options.md" %}} -The examples below show the rendered output when visiting a page on the English language version of the site: +## Examples + +The following examples show the rendered output for a page on the English version of the site: ```go-html-template {{ $opts := dict "path" "/books/book-1" }} @@ -36,9 +32,6 @@ The examples below show the rendered output when visiting a page on the English {{ .Ref $opts }} → https://example.org/de/books/book-1/index.json ``` -By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/docs/content/en/methods/page/RegularPages.md b/docs/content/en/methods/page/RegularPages.md index 08198fca4..761de3af5 100644 --- a/docs/content/en/methods/page/RegularPages.md +++ b/docs/content/en/methods/page/RegularPages.md @@ -3,15 +3,13 @@ title: RegularPages description: Returns a collection of regular pages within the current section. categories: [] keywords: [] -action: - related: - - methods/page/Pages - - methods/page/RegularPagesRecursive - returnType: page.Pages - signatures: [PAGE.RegularPages] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.RegularPages] --- -The `RegularPages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g). +The `RegularPages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g). Range through the page collection in your template: @@ -69,14 +67,13 @@ When rendering lesson-2, the `RegularPages` method returns: In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section. -{{% note %}} -When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details]. - -[details]: /methods/site/regularpages/ -{{% /note %}} +> [!note] +> When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details]. ```go-html-template {{ range .Site.RegularPages.ByTitle }} <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2> {{ end }} ``` + +[details]: /methods/site/regularpages/ diff --git a/docs/content/en/methods/page/RegularPagesRecursive.md b/docs/content/en/methods/page/RegularPagesRecursive.md index 8e1c5f9a4..d85cd0b48 100644 --- a/docs/content/en/methods/page/RegularPagesRecursive.md +++ b/docs/content/en/methods/page/RegularPagesRecursive.md @@ -3,15 +3,13 @@ title: RegularPagesRecursive description: Returns a collection of regular pages within the current section, and regular pages within all descendant sections. categories: [] keywords: [] -action: - related: - - methods/page/Pages - - methods/page/RegularPages - returnType: page.Pages - signatures: [PAGE.RegularPagesRecursive] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.RegularPagesRecursive] --- -The `RegularPagesRecursive` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g). +The `RegularPagesRecursive` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g). Range through the page collection in your template: @@ -81,6 +79,5 @@ When rendering lesson-2, the `RegularPagesRecursive` method returns: lessons/lesson-2/resources/task-list.md lessons/lesson-2/resources/worksheet.md -{{% note %}} -The `RegularPagesRecursive` method in not available on a `Site` object. -{{% /note %}} +> [!note] +> The `RegularPagesRecursive` method is not available on a `Site` object. diff --git a/docs/content/en/methods/page/RelPermalink.md b/docs/content/en/methods/page/RelPermalink.md index 817e3c862..a3c610d50 100644 --- a/docs/content/en/methods/page/RelPermalink.md +++ b/docs/content/en/methods/page/RelPermalink.md @@ -3,11 +3,10 @@ title: RelPermalink description: Returns the relative permalink of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Permalink - returnType: string - signatures: [PAGE.RelPermalink] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.RelPermalink] --- Site configuration: diff --git a/docs/content/en/methods/page/RelRef.md b/docs/content/en/methods/page/RelRef.md index 83ab08610..7edab5740 100644 --- a/docs/content/en/methods/page/RelRef.md +++ b/docs/content/en/methods/page/RelRef.md @@ -3,27 +3,23 @@ title: RelRef description: Returns the relative URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - related: - - methods/page/Ref - - functions/urls/Ref - - functions/urls/RelRef - returnType: string - signatures: [PAGE.RelRef OPTIONS] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.RelRef OPTIONS] --- -The map of option contains: +## Usage -path -: (`string`) The path to the page, relative to the `content` directory. Required. +The `RelRef` method accepts a single argument: an options map. -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +## Options -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. +{{% include "_common/ref-and-relref-options.md" %}} -The examples below show the rendered output when visiting a page on the English language version of the site: +## Examples + +The following examples show the rendered output for a page on the English version of the site: ```go-html-template {{ $opts := dict "path" "/books/book-1" }} @@ -36,9 +32,6 @@ The examples below show the rendered output when visiting a page on the English {{ .RelRef $opts }} → /de/books/book-1/index.json ``` -By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/docs/content/en/methods/page/Render.md b/docs/content/en/methods/page/Render.md index 1adc71c6d..10f7f9ca5 100644 --- a/docs/content/en/methods/page/Render.md +++ b/docs/content/en/methods/page/Render.md @@ -3,12 +3,10 @@ title: Render description: Renders the given template with the given page as context. categories: [] keywords: [] -action: - related: - - functions/partials/Include - - functions/partials/IncludeCached - returnType: template.HTML - signatures: [PAGE.Render NAME] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.Render NAME] aliases: [/functions/render] --- diff --git a/docs/content/en/methods/page/RenderShortcodes.md b/docs/content/en/methods/page/RenderShortcodes.md index 3346f0ba1..d124606f0 100644 --- a/docs/content/en/methods/page/RenderShortcodes.md +++ b/docs/content/en/methods/page/RenderShortcodes.md @@ -3,18 +3,10 @@ title: RenderShortcodes description: Renders all shortcodes in the content of the given page, preserving the surrounding markup. categories: [] keywords: [] -action: - related: - - methods/page/Content - - methods/page/Summary - - methods/page/ContentWithoutSummary - - methods/page/RawContent - - methods/page/Plain - - methods/page/PlainWords - - methods/page/RenderString - returnType: template.HTML - signatures: [PAGE.RenderShortcodes] -toc: true +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.RenderShortcodes] --- {{< new-in 0.117.0 />}} @@ -23,7 +15,7 @@ Use this method in shortcode templates to compose a page from multiple content f For example: -{{< code file=layouts/shortcodes/include.html >}} +```go-html-template {file="layouts/shortcodes/include.html" copy=true} {{ with .Get 0 }} {{ with $.Page.GetPage . }} {{- .RenderShortcodes }} @@ -33,15 +25,15 @@ For example: {{ else }} {{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` Then call the shortcode in your Markdown: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{%/* include "/snippets/services" */%}} {{%/* include "/snippets/values" */%}} {{%/* include "/snippets/leadership" */%}} -{{< /code >}} +``` Each of the included Markdown files can contain calls to other shortcodes. @@ -58,7 +50,7 @@ Use the latter for the "include" shortcode described above. To understand what is returned by the `RenderShortcodes` method, consider this content file -{{< code file=content/about.md lang=text >}} +```text {file="content/about.md"} +++ title = 'About' date = 2023-10-07T12:28:33-07:00 @@ -67,7 +59,7 @@ date = 2023-10-07T12:28:33-07:00 {{</* ref "privacy" */>}} An *emphasized* word. -{{< /code >}} +``` With this template code: @@ -90,7 +82,7 @@ Note that the shortcode within the content file was rendered, but the surroundin The primary use case for `.RenderShortcodes` is inclusion of Markdown content. If you try to use `.RenderShortcodes` inside `HTML` blocks when inside Markdown, you will get a warning similar to this: -``` +```text WARN .RenderShortcodes detected inside HTML block in "/content/mypost.md"; this may not be what you intended ... ``` diff --git a/docs/content/en/methods/page/RenderString.md b/docs/content/en/methods/page/RenderString.md index 1a92c78c6..c7774774c 100644 --- a/docs/content/en/methods/page/RenderString.md +++ b/docs/content/en/methods/page/RenderString.md @@ -3,12 +3,10 @@ title: RenderString description: Renders markup to HTML. categories: [] keywords: [] -action: - related: - - methods/page/RenderShortcodes - - functions/transform/Markdownify - returnType: template.HTML - signatures: ['PAGE.RenderString [OPTIONS] MARKUP'] +params: + functions_and_methods: + returnType: template.HTML + signatures: ['PAGE.RenderString [OPTIONS] MARKUP'] aliases: [/functions/renderstring] --- diff --git a/docs/content/en/methods/page/Resources.md b/docs/content/en/methods/page/Resources.md index 6c79f58ee..dd472de88 100644 --- a/docs/content/en/methods/page/Resources.md +++ b/docs/content/en/methods/page/Resources.md @@ -3,16 +3,10 @@ title: Resources description: Returns a collection of page resources. categories: [] keywords: [] -action: - related: - - functions/resources/ByType - - functions/resources/Get - - functions/resources/GetMatch - - functions/resources/GetRemote - - functions/resources/Match - returnType: resource.Resources - signatures: [PAGE.Resources] -toc: true +params: + functions_and_methods: + returnType: resource.Resources + signatures: [PAGE.Resources] --- The `Resources` method on a `Page` object returns a collection of page resources. A page resource is a file within a [page bundle](g). @@ -21,7 +15,7 @@ To work with global or remote resources, see the [`resources`] functions. ## Methods -###### ByType +### ByType (`resource.Resources`) Returns a collection of page resources of the given [media type], or nil if none found. The media type is typically one of `image`, `text`, `audio`, `video`, or `application`. @@ -33,7 +27,7 @@ To work with global or remote resources, see the [`resources`] functions. When working with global resources instead of page resources, use the [`resources.ByType`] function. -###### Get +### Get (`resource.Resource`) Returns a page resource from the given path, or nil if none found. @@ -45,9 +39,9 @@ When working with global resources instead of page resources, use the [`resource When working with global resources instead of page resources, use the [`resources.Get`] function. -###### GetMatch +### GetMatch -(`resource.Resource`) Returns the first page resource from paths matching the given [glob pattern], or nil if none found. +(`resource.Resource`) Returns the first page resource from paths matching the given [glob](g) pattern, or nil if none found. ```go-html-template {{ with .Resources.GetMatch "images/*.jpg" }} @@ -57,9 +51,9 @@ When working with global resources instead of page resources, use the [`resource When working with global resources instead of page resources, use the [`resources.GetMatch`] function. -###### Match +### Match -(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob pattern], or nil if none found. +(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob](g) pattern, or nil if none found. ```go-html-template {{ range .Resources.Match "images/*.jpg" }} @@ -69,7 +63,7 @@ When working with global resources instead of page resources, use the [`resource When working with global resources instead of page resources, use the [`resources.Match`] function. -###### Mount +### Mount {{< new-in 0.140.0 />}} @@ -84,14 +78,13 @@ This method is currently only useful in [js.Batch](/functions/js/batch/#import-c ## Pattern matching -With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob pattern]. +With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob](g) pattern. -{{% include "functions/_common/glob-patterns.md" %}} +{{% include "/_common/glob-patterns.md" %}} [`resources.ByType`]: /functions/resources/ByType/ [`resources.GetMatch`]: /functions/resources/ByType/ [`resources.Get`]: /functions/resources/ByType/ [`resources.Match`]: /functions/resources/ByType/ [`resources`]: /functions/resources/ -[glob pattern]: https://github.com/gobwas/glob#example [media type]: https://en.wikipedia.org/wiki/Media_type diff --git a/docs/content/en/methods/page/Scratch.md b/docs/content/en/methods/page/Scratch.md index 436005a94..61c5dc19e 100644 --- a/docs/content/en/methods/page/Scratch.md +++ b/docs/content/en/methods/page/Scratch.md @@ -3,14 +3,14 @@ title: Scratch description: Returns a "scratch pad" to store and manipulate data, scoped to the current page. categories: [] keywords: [] -action: - related: [] - returnType: maps.Scratch - signatures: [PAGE.Scratch] +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [PAGE.Scratch] expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft) --- -{{% deprecated-in 0.138.0 %}} +{{< deprecated-in 0.138.0 >}} Use the [`PAGE.Store`] method instead. This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `PAGE.Store` as soon as possible. @@ -18,4 +18,4 @@ This is a soft deprecation. This method will be removed in a future release, but Beginning with v0.138.0 the `PAGE.Scratch` method is aliased to `PAGE.Store`. [`PAGE.Store`]: /methods/page/store/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/docs/content/en/methods/page/Section.md b/docs/content/en/methods/page/Section.md index 31cfb1e6f..04c6a8a24 100644 --- a/docs/content/en/methods/page/Section.md +++ b/docs/content/en/methods/page/Section.md @@ -1,15 +1,16 @@ --- title: Section -description: Returns the name of the top level section in which the given page resides. +description: Returns the name of the top-level section in which the given page resides. categories: [] keywords: [] -action: - related: - - methods/page/Type - returnType: string - signatures: [PAGE.Section] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Section] --- +{{% glossary-term section %}} + With this content structure: ```text @@ -29,7 +30,7 @@ When rendering lesson-1.md: {{ .Section }} → lessons ``` -In the example above "lessons" is the top level section. +In the example above "lessons" is the top-level section. The `Section` method is often used with the [`where`] function to build a page collection. diff --git a/docs/content/en/methods/page/Sections.md b/docs/content/en/methods/page/Sections.md index 921e4eb4e..12f0a8c24 100644 --- a/docs/content/en/methods/page/Sections.md +++ b/docs/content/en/methods/page/Sections.md @@ -3,20 +3,13 @@ title: Sections description: Returns a collection of section pages, one for each immediate descendant section of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Ancestors - - methods/page/CurrentSection - - methods/page/FirstSection - - methods/page/InSection - - methods/page/IsAncestor - - methods/page/IsDescendant - - methods/page/Parent - returnType: page.Pages - signatures: [PAGE.Sections] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.Sections] --- -{{% glossary-term section %}} +The `Sections` method on a `Page` object is available to these [page kinds](g): `home`, `section`, and `taxonomy`. The templates for these page kinds receive a page [collection](g) in [context](g), in the [default sort order](g). With this content structure: diff --git a/docs/content/en/methods/page/Site.md b/docs/content/en/methods/page/Site.md index d83c45e0a..4649e5e00 100644 --- a/docs/content/en/methods/page/Site.md +++ b/docs/content/en/methods/page/Site.md @@ -3,11 +3,10 @@ title: Site description: Returns the Site object. categories: [] keywords: [] -action: - related: - - methods/page/Sites - returnType: page.siteWrapper - signatures: [PAGE.Site] +params: + functions_and_methods: + returnType: page.siteWrapper + signatures: [PAGE.Site] --- See [Site methods]. diff --git a/docs/content/en/methods/page/Sitemap.md b/docs/content/en/methods/page/Sitemap.md index 065c07c35..bb1360493 100644 --- a/docs/content/en/methods/page/Sitemap.md +++ b/docs/content/en/methods/page/Sitemap.md @@ -3,33 +3,37 @@ title: Sitemap description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in the site configuration. categories: [] keywords: [] -action: - related: [] - returnType: config.SitemapConfig - signatures: [PAGE.Sitemap] -toc: true +params: + functions_and_methods: + returnType: config.SitemapConfig + signatures: [PAGE.Sitemap] --- Access to the `Sitemap` method on a `Page` object is restricted to [sitemap templates]. ## Methods -changefreq -: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef). +### ChangeFreq + +(`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef). ```go-html-template {{ .Sitemap.ChangeFreq }} ``` -disable {{< new-in 0.125.0 />}} -: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. +### Disable + +{{< new-in 0.125.0 />}} + +(`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page. ```go-html-template {{ .Sitemap.Disable }} ``` -priority -: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#priority). +### Priority + +(`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef). ```go-html-template {{ .Sitemap.Priority }} @@ -54,7 +58,7 @@ changeFreq = 'hourly' And this simplistic sitemap template: -{{< code file=layouts/_default/sitemap.xml >}} +```xml {file="layouts/_default/sitemap.xml"} {{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }} <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml"> @@ -70,7 +74,7 @@ And this simplistic sitemap template: </url> {{ end }} </urlset> -{{< /code >}} +``` The change frequency will be `hourly` for the news page, and `monthly` for other pages. diff --git a/docs/content/en/methods/page/Sites.md b/docs/content/en/methods/page/Sites.md index cd240655e..8677226d7 100644 --- a/docs/content/en/methods/page/Sites.md +++ b/docs/content/en/methods/page/Sites.md @@ -3,11 +3,10 @@ title: Sites description: Returns a collection of all Site objects, one for each language, ordered by language weight. categories: [] keywords: [] -action: - related: - - methods/page/Site - returnType: page.Sites - signatures: [PAGE.Sites] +params: + functions_and_methods: + returnType: page.Sites + signatures: [PAGE.Sites] --- This is a convenience method to access `.Site.Sites`. diff --git a/docs/content/en/methods/page/Slug.md b/docs/content/en/methods/page/Slug.md index 9fdb09b57..34000b660 100644 --- a/docs/content/en/methods/page/Slug.md +++ b/docs/content/en/methods/page/Slug.md @@ -3,10 +3,10 @@ title: Slug description: Returns the URL slug of the given page as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [PAGE.Slug] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Slug] --- {{< code-toggle file=content/recipes/spicy-tuna-hand-rolls.md fm=true >}} diff --git a/docs/content/en/methods/page/Store.md b/docs/content/en/methods/page/Store.md index 769a554f1..0b1049b0a 100644 --- a/docs/content/en/methods/page/Store.md +++ b/docs/content/en/methods/page/Store.md @@ -3,15 +3,10 @@ title: Store description: Returns a "scratch pad" to store and manipulate data, scoped to the current page. categories: [] keywords: [] -action: - related: - - methods/site/Store - - methods/shortcode/Store - - functions/hugo/Store - - functions/collections/NewScratch - returnType: maps.Scratch - signatures: [PAGE.Store] -toc: true +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [PAGE.Store] aliases: [/functions/store/,/extras/scratch/,/doc/scratch/,/functions/scratch] --- diff --git a/docs/content/en/methods/page/Summary.md b/docs/content/en/methods/page/Summary.md index a875d62f0..9158e571d 100644 --- a/docs/content/en/methods/page/Summary.md +++ b/docs/content/en/methods/page/Summary.md @@ -3,14 +3,10 @@ title: Summary description: Returns the summary of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Truncated - - methods/page/Content - - methods/page/ContentWithoutSummary - - methods/page/Description - returnType: template.HTML - signatures: [PAGE.Summary] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.Summary] --- <!-- Do not remove the manual summary divider below. --> @@ -20,8 +16,6 @@ action: You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary. -[summary]: /content-management/summaries/ - To list the pages in a section with a summary beneath each link: ```go-html-template @@ -33,8 +27,6 @@ To list the pages in a section with a summary beneath each link: Depending on content length and how you define the summary, the summary may be equivalent to the content itself. To determine whether the content length exceeds the summary length, use the [`Truncated`] method on a `Page` object. This is useful for conditionally rendering a “read more” link: -[`Truncated`]: /methods/page/truncated - ```go-html-template {{ range .Pages }} <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> @@ -45,6 +37,8 @@ Depending on content length and how you define the summary, the summary may be e {{ end }} ``` -{{% note %}} -The `Truncated` method returns `false` if you define the summary in front matter. -{{% /note %}} +> [!note] +> The `Truncated` method returns `false` if you define the summary in front matter. + +[`Truncated`]: /methods/page/truncated +[summary]: /content-management/summaries/ diff --git a/docs/content/en/methods/page/TableOfContents.md b/docs/content/en/methods/page/TableOfContents.md index 38c3ff17b..7ec9fe614 100644 --- a/docs/content/en/methods/page/TableOfContents.md +++ b/docs/content/en/methods/page/TableOfContents.md @@ -3,11 +3,10 @@ title: TableOfContents description: Returns a table of contents for the given page. categories: [] keywords: [] -action: - related: - - methods/page/Fragments - returnType: template.HTML - signatures: [PAGE.TableOfContents] +params: + functions_and_methods: + returnType: template.HTML + signatures: [PAGE.TableOfContents] aliases: [/content-management/toc/] --- diff --git a/docs/content/en/methods/page/Title.md b/docs/content/en/methods/page/Title.md index 08fc9f9eb..dae4ba6dd 100644 --- a/docs/content/en/methods/page/Title.md +++ b/docs/content/en/methods/page/Title.md @@ -3,11 +3,10 @@ title: Title description: Returns the title of the given page. categories: [] keywords: [] -action: - related: - - methods/page/LinkTitle - returnType: string - signatures: [PAGE.Title] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Title] --- With pages backed by a file, the `Title` method returns the `title` field as defined in front matter: @@ -35,6 +34,6 @@ titleCaseStyle = "firstupper" See [details]. -[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles -[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles -[details]: /getting-started/configuration/#configure-title-case +[`capitalizeListTitles`]: /configuration/all/#capitalizelisttitles +[`pluralizeListTitles`]: /configuration/all/#pluralizelisttitles +[details]: /configuration/all/#title-case-style diff --git a/docs/content/en/methods/page/TranslationKey.md b/docs/content/en/methods/page/TranslationKey.md index a9e4b97e9..1e930687e 100644 --- a/docs/content/en/methods/page/TranslationKey.md +++ b/docs/content/en/methods/page/TranslationKey.md @@ -3,13 +3,10 @@ title: TranslationKey description: Returns the translation key of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Translations - - methods/page/AllTranslations - - methods/page/IsTranslated - returnType: string - signatures: [PAGE.TranslationKey] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.TranslationKey] --- The translation key creates a relationship between all translations of a given page. The translation key is derived from the file path, or from the `translationKey` parameter if defined in front matter. diff --git a/docs/content/en/methods/page/Translations.md b/docs/content/en/methods/page/Translations.md index 597a9aeb6..4bab9fe11 100644 --- a/docs/content/en/methods/page/Translations.md +++ b/docs/content/en/methods/page/Translations.md @@ -1,15 +1,12 @@ --- title: Translations -description: Returns all translations of the given page, excluding the current language. +description: Returns all translations of the given page, excluding the current language. categories: [] keywords: [] -action: - related: - - methods/page/AllTranslations - - methods/page/IsTranslated - - methods/page/TranslationKey - returnType: page.Pages - signatures: [PAGE.Translations] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGE.Translations] --- With this site configuration: diff --git a/docs/content/en/methods/page/Truncated.md b/docs/content/en/methods/page/Truncated.md index b4ec7ce16..8c2573069 100644 --- a/docs/content/en/methods/page/Truncated.md +++ b/docs/content/en/methods/page/Truncated.md @@ -3,11 +3,10 @@ title: Truncated description: Reports whether the content length exceeds the summary length. categories: [] keywords: [] -action: - related: - - methods/page/Summary - returnType: bool - signatures: [PAGE.Truncated] +params: + functions_and_methods: + returnType: bool + signatures: [PAGE.Truncated] --- You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary. @@ -26,6 +25,5 @@ The `Truncated` method returns `true` if the content length exceeds the summary {{ end }} ``` -{{% note %}} -The `Truncated` method returns `false` if you define the summary in front matter. -{{% /note %}} +> [!note] +> The `Truncated` method returns `false` if you define the summary in front matter. diff --git a/docs/content/en/methods/page/Type.md b/docs/content/en/methods/page/Type.md index 2a2a5c731..6f855fbe3 100644 --- a/docs/content/en/methods/page/Type.md +++ b/docs/content/en/methods/page/Type.md @@ -3,15 +3,13 @@ title: Type description: Returns the content type of the given page. categories: [] keywords: [] -action: - related: - - methods/page/Kind - - methods/page/Layout - returnType: string - signatures: [PAGE.Type] +params: + functions_and_methods: + returnType: string + signatures: [PAGE.Type] --- -The `Type` method on a `Page` object returns the [content type](g) of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined. +The `Type` method on a `Page` object returns the [content type](g) of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined. With this content structure: diff --git a/docs/content/en/methods/page/Weight.md b/docs/content/en/methods/page/Weight.md index 10f481baf..c14af0257 100644 --- a/docs/content/en/methods/page/Weight.md +++ b/docs/content/en/methods/page/Weight.md @@ -3,10 +3,10 @@ title: Weight description: Returns the weight of the given page as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [PAGE.Weight] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.Weight] --- The `Weight` method on a `Page` object returns the [weight](g) of the given page as defined in front matter. diff --git a/docs/content/en/methods/page/WordCount.md b/docs/content/en/methods/page/WordCount.md index 70fe407ab..3950244ca 100644 --- a/docs/content/en/methods/page/WordCount.md +++ b/docs/content/en/methods/page/WordCount.md @@ -3,12 +3,10 @@ title: WordCount description: Returns the number of words in the content of the given page. categories: [] keywords: [] -action: - related: - - methods/page/FuzzyWordCount - - methods/page/ReadingTime - returnType: int - signatures: [PAGE.WordCount] +params: + functions_and_methods: + returnType: int + signatures: [PAGE.WordCount] --- ```go-html-template diff --git a/docs/content/en/methods/page/_common/_index.md b/docs/content/en/methods/page/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/methods/page/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/methods/page/_common/next-and-prev.md b/docs/content/en/methods/page/_common/next-and-prev.md deleted file mode 100644 index 0a3022265..000000000 --- a/docs/content/en/methods/page/_common/next-and-prev.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Hugo determines the _next_ and _previous_ page by sorting the site's collection of regular pages according to this sorting hierarchy: - -Field|Precedence|Sort direction -:--|:--|:-- -[`weight`]|1|descending -[`date`]|2|descending -[`linkTitle`]|3|descending -[`path`]|4|descending - -[`date`]: /methods/page/date/ -[`weight`]: /methods/page/weight/ -[`linkTitle`]: /methods/page/linktitle/ -[`path`]: /methods/page/path/ - -The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior. - -For example, with this content structure: - -```text -content/ -├── pages/ -│ ├── _index.md -│ ├── page-1.md <-- front matter: weight = 10 -│ ├── page-2.md <-- front matter: weight = 20 -│ └── page-3.md <-- front matter: weight = 30 -└── _index.md -``` - -And these templates: - -{{< code file=layouts/_default/list.html >}} -{{ range .Pages.ByWeight }} - <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> -{{ end }} -{{< /code >}} - -{{< code file=layouts/_default/single.html >}} -{{ with .Prev }} - <a href="{{ .RelPermalink }}">Previous</a> -{{ end }} - -{{ with .Next }} - <a href="{{ .RelPermalink }}">Next</a> -{{ end }} -{{< /code >}} - -When you visit page-2: - -- The `Prev` method points to page-3 -- The `Next` method points to page-1 - -To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. - -[site configuration]: /getting-started/configuration/#configure-page -[`Next`]: /methods/pages/prev -[`Prev`]: /methods/pages/prev diff --git a/docs/content/en/methods/page/_common/nextinsection-and-previnsection.md b/docs/content/en/methods/page/_common/nextinsection-and-previnsection.md deleted file mode 100644 index 1d1f5438a..000000000 --- a/docs/content/en/methods/page/_common/nextinsection-and-previnsection.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Hugo determines the _next_ and _previous_ page by sorting the current section's regular pages according to this sorting hierarchy: - -Field|Precedence|Sort direction -:--|:--|:-- -[`weight`]|1|descending -[`date`]|2|descending -[`linkTitle`]|3|descending -[`path`]|4|descending - -[`date`]: /methods/page/date/ -[`weight`]: /methods/page/weight/ -[`linkTitle`]: /methods/page/linktitle/ -[`path`]: /methods/page/path/ - -The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior. - -For example, with this content structure: - -```text -content/ -├── pages/ -│ ├── _index.md -│ ├── page-1.md <-- front matter: weight = 10 -│ ├── page-2.md <-- front matter: weight = 20 -│ └── page-3.md <-- front matter: weight = 30 -└── _index.md -``` - -And these templates: - -{{< code file=layouts/_default/list.html >}} -{{ range .Pages.ByWeight }} - <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> -{{ end }} -{{< /code >}} - -{{< code file=layouts/_default/single.html >}} -{{ with .PrevInSection }} - <a href="{{ .RelPermalink }}">Previous</a> -{{ end }} - -{{ with .NextInSection }} - <a href="{{ .RelPermalink }}">Next</a> -{{ end }} -{{< /code >}} - -When you visit page-2: - -- The `PrevInSection` method points to page-3 -- The `NextInSection` method points to page-1 - -To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. - -[site configuration]: /getting-started/configuration/#configure-page -[`Next`]: /methods/pages/prev -[`Prev`]: /methods/pages/prev - -## Example - -Code defensively by checking for page existence: - -```go-html-template -{{ with .PrevInSection }} - <a href="{{ .RelPermalink }}">Previous</a> -{{ end }} - -{{ with .NextInSection }} - <a href="{{ .RelPermalink }}">Next</a> -{{ end }} -``` - -## Alternative - -Use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. diff --git a/docs/content/en/methods/page/_common/output-format-methods.md b/docs/content/en/methods/page/_common/output-format-methods.md deleted file mode 100644 index 5390e7b46..000000000 --- a/docs/content/en/methods/page/_common/output-format-methods.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Get IDENTIFIER -: (`any`) Returns the `OutputFormat` object with the given identifier. - -MediaType -: (`media.Type`) Returns the media type of the output format. - -MediaType.MainType -: (`string`) Returns the main type of the output format's media type. - -MediaType.SubType -: (`string`) Returns the subtype of the current format's media type. - -Name -: (`string`) Returns the output identifier of the output format. - -Permalink -: (`string`) Returns the permalink of the page generated by the current output format. - -Rel -: (`string`) Returns the `rel` value of the output format, either the default or as defined in the site configuration. - -RelPermalink -: (`string`) Returns the relative permalink of the page generated by the current output format. diff --git a/docs/content/en/methods/page/_index.md b/docs/content/en/methods/page/_index.md index 6dfaad9ae..c7ae7ad5d 100644 --- a/docs/content/en/methods/page/_index.md +++ b/docs/content/en/methods/page/_index.md @@ -4,10 +4,5 @@ linkTitle: Page description: Use these methods with a Page object. categories: [] keywords: [] -menu: - docs: - parent: methods aliases: [/variables/page/] --- - -Use these methods with a Page object. diff --git a/docs/content/en/methods/pager/First.md b/docs/content/en/methods/pager/First.md index 85e2e0dd3..9cd58989b 100644 --- a/docs/content/en/methods/pager/First.md +++ b/docs/content/en/methods/pager/First.md @@ -3,16 +3,10 @@ title: First description: Returns the first pager in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/Last - - methods/pager/Prev - - methods/pager/Next - - methods/pager/HasPrev - - methods/pager/HasNext - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGER.First] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGER.First] --- Use the `First` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/HasNext.md b/docs/content/en/methods/pager/HasNext.md index e7550d788..cf3688efd 100644 --- a/docs/content/en/methods/pager/HasNext.md +++ b/docs/content/en/methods/pager/HasNext.md @@ -3,16 +3,10 @@ title: HasNext description: Reports whether there is a pager after the current pager. categories: [] keywords: [] -action: - related: - - methods/pager/HasPrev - - methods/pager/Prev - - methods/pager/Next - - methods/pager/First - - methods/pager/Last - - methods/page/Paginate - returnType: bool - signatures: [PAGER.HasNext] +params: + functions_and_methods: + returnType: bool + signatures: [PAGER.HasNext] --- Use the `HasNext` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/HasPrev.md b/docs/content/en/methods/pager/HasPrev.md index 00d5c1dea..4b486b7c5 100644 --- a/docs/content/en/methods/pager/HasPrev.md +++ b/docs/content/en/methods/pager/HasPrev.md @@ -3,16 +3,10 @@ title: HasPrev description: Reports whether there is a pager before the current pager. categories: [] keywords: [] -action: - related: - - methods/pager/HasNext - - methods/pager/Prev - - methods/pager/Next - - methods/pager/First - - methods/pager/Last - - methods/page/Paginate - returnType: bool - signatures: [PAGER.HasPrev] +params: + functions_and_methods: + returnType: bool + signatures: [PAGER.HasPrev] --- Use the `HasPrev` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/Last.md b/docs/content/en/methods/pager/Last.md index 074a46943..71dea183d 100644 --- a/docs/content/en/methods/pager/Last.md +++ b/docs/content/en/methods/pager/Last.md @@ -3,16 +3,10 @@ title: Last description: Returns the last pager in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/First - - methods/pager/Prev - - methods/pager/Next - - methods/pager/HasPrev - - methods/pager/HasNext - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGER.Last] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGER.Last] --- Use the `Last` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/Next.md b/docs/content/en/methods/pager/Next.md index 099ac198e..d7ea9caa4 100644 --- a/docs/content/en/methods/pager/Next.md +++ b/docs/content/en/methods/pager/Next.md @@ -3,16 +3,10 @@ title: Next description: Returns the next pager in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/Prev - - methods/pager/HasPrev - - methods/pager/HasNext - - methods/pager/First - - methods/pager/Last - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGER.Next] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGER.Next] --- Use the `Next` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/NumberOfElements.md b/docs/content/en/methods/pager/NumberOfElements.md index 3980cdfe2..9f88126fc 100644 --- a/docs/content/en/methods/pager/NumberOfElements.md +++ b/docs/content/en/methods/pager/NumberOfElements.md @@ -3,12 +3,10 @@ title: NumberOfElements description: Returns the number of pages in the current pager. categories: [] keywords: [] -action: - related: - - methods/pager/TotalNumberOfElements - - methods/page/Paginate - returnType: int - signatures: [PAGER.NumberOfElements] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.NumberOfElements] --- ```go-html-template diff --git a/docs/content/en/methods/pager/PageGroups.md b/docs/content/en/methods/pager/PageGroups.md index 9dee18c0d..46f6d81cb 100644 --- a/docs/content/en/methods/pager/PageGroups.md +++ b/docs/content/en/methods/pager/PageGroups.md @@ -3,11 +3,10 @@ title: PageGroups description: Returns the page groups in the current pager. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: page.PagesGroup - signatures: [PAGER.PageGroups] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: [PAGER.PageGroups] --- Use the `PageGroups` method with any of the [grouping methods]. diff --git a/docs/content/en/methods/pager/PageNumber.md b/docs/content/en/methods/pager/PageNumber.md index 0d99c5a15..6d0b8e35d 100644 --- a/docs/content/en/methods/pager/PageNumber.md +++ b/docs/content/en/methods/pager/PageNumber.md @@ -3,12 +3,10 @@ title: PageNumber description: Returns the current pager's number within the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/TotalPages - - methods/page/Paginate - returnType: int - signatures: [PAGER.PageNumber] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.PageNumber] --- Use the `PageNumber` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/PageSize.md b/docs/content/en/methods/pager/PageSize.md index d69c31207..5aad88682 100644 --- a/docs/content/en/methods/pager/PageSize.md +++ b/docs/content/en/methods/pager/PageSize.md @@ -3,15 +3,15 @@ title: PageSize description: Returns the number of pages per pager. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [PAGER.PageSize] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.PageSize] expiryDate: 2026-06-09 # deprecated 2024-06-09 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`PAGER.PagerSize`] instead. [`PAGER.PagerSize`]: /methods/pager/pagersize/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/docs/content/en/methods/pager/PagerSize.md b/docs/content/en/methods/pager/PagerSize.md index 5f5f7d3a8..b2397a3e8 100644 --- a/docs/content/en/methods/pager/PagerSize.md +++ b/docs/content/en/methods/pager/PagerSize.md @@ -3,11 +3,10 @@ title: PagerSize description: Returns the number of pages per pager. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: int - signatures: [PAGER.PagerSize] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.PagerSize] --- {{< new-in 0.128.0 />}} diff --git a/docs/content/en/methods/pager/Pagers.md b/docs/content/en/methods/pager/Pagers.md index 5f167c13e..e431069f4 100644 --- a/docs/content/en/methods/pager/Pagers.md +++ b/docs/content/en/methods/pager/Pagers.md @@ -3,11 +3,10 @@ title: Pagers description: Returns the pagers collection. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: page.pagers - signatures: [PAGER.Pagers] +params: + functions_and_methods: + returnType: page.pagers + signatures: [PAGER.Pagers] --- Use the `Pagers` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/Pages.md b/docs/content/en/methods/pager/Pages.md index 1c049d53b..6e5772a48 100644 --- a/docs/content/en/methods/pager/Pages.md +++ b/docs/content/en/methods/pager/Pages.md @@ -3,11 +3,10 @@ title: Pages description: Returns the pages in the current pager. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: page.Pages - signatures: [PAGER.Pages] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGER.Pages] --- ```go-html-template diff --git a/docs/content/en/methods/pager/Prev.md b/docs/content/en/methods/pager/Prev.md index c129c6a5a..eb79f96e9 100644 --- a/docs/content/en/methods/pager/Prev.md +++ b/docs/content/en/methods/pager/Prev.md @@ -3,16 +3,10 @@ title: Prev description: Returns the previous pager in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/Next - - methods/pager/HasPrev - - methods/pager/HasNext - - methods/pager/First - - methods/pager/Last - - methods/page/Paginate - returnType: page.Pager - signatures: [PAGER.Prev] +params: + functions_and_methods: + returnType: page.Pager + signatures: [PAGER.Prev] --- Use the `Prev` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/TotalNumberOfElements.md b/docs/content/en/methods/pager/TotalNumberOfElements.md index 3cd1c8dad..ad29a01f3 100644 --- a/docs/content/en/methods/pager/TotalNumberOfElements.md +++ b/docs/content/en/methods/pager/TotalNumberOfElements.md @@ -3,12 +3,10 @@ title: TotalNumberOfElements description: Returns the number of pages in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/NumberOfElements - - methods/page/Paginate - returnType: int - signatures: [PAGER.TotalNumberOfElements] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.TotalNumberOfElements] --- ```go-html-template diff --git a/docs/content/en/methods/pager/TotalPages.md b/docs/content/en/methods/pager/TotalPages.md index e305beeff..63da5d786 100644 --- a/docs/content/en/methods/pager/TotalPages.md +++ b/docs/content/en/methods/pager/TotalPages.md @@ -3,12 +3,10 @@ title: TotalPages description: Returns the number of pagers in the pager collection. categories: [] keywords: [] -action: - related: - - methods/pager/PageNumber - - methods/page/Paginate - returnType: int - signatures: [PAGER.TotalPages] +params: + functions_and_methods: + returnType: int + signatures: [PAGER.TotalPages] --- Use the `TotalPages` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/URL.md b/docs/content/en/methods/pager/URL.md index 3daddbbd5..a3558ba7c 100644 --- a/docs/content/en/methods/pager/URL.md +++ b/docs/content/en/methods/pager/URL.md @@ -3,11 +3,10 @@ title: URL description: Returns the URL of the current pager relative to the site root. categories: [] keywords: [] -action: - related: - - methods/page/Paginate - returnType: string - signatures: [PAGER.URL] +params: + functions_and_methods: + returnType: string + signatures: [PAGER.URL] --- Use the `URL` method to build navigation between pagers. diff --git a/docs/content/en/methods/pager/_index.md b/docs/content/en/methods/pager/_index.md index 58a1def7b..7a79bf42f 100644 --- a/docs/content/en/methods/pager/_index.md +++ b/docs/content/en/methods/pager/_index.md @@ -1,14 +1,6 @@ --- title: Pager methods linkTitle: Pager -description: Use these methods with Pager objects when paginating a list page. +description: Use these methods with Pager objects when building navigation for a paginated list page. keywords: [] -menu: - docs: - identifier: - parent: methods --- - -Use these methods with Pager objects when building navigation for a [paginated] list page. - -[paginated]: /templates/pagination/ diff --git a/docs/content/en/methods/pages/ByDate.md b/docs/content/en/methods/pages/ByDate.md index eb4e86535..18f1b985e 100644 --- a/docs/content/en/methods/pages/ByDate.md +++ b/docs/content/en/methods/pages/ByDate.md @@ -3,18 +3,15 @@ title: ByDate description: Returns the given page collection sorted by date in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByExpiryDate - - methods/pages/ByLastMod - - methods/pages/ByPublishDate - returnType: page.Pages - signatures: [PAGES.ByDate] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByDate] --- When sorting by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter. -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByDate }} diff --git a/docs/content/en/methods/pages/ByExpiryDate.md b/docs/content/en/methods/pages/ByExpiryDate.md index 41753c340..703988c4e 100644 --- a/docs/content/en/methods/pages/ByExpiryDate.md +++ b/docs/content/en/methods/pages/ByExpiryDate.md @@ -3,18 +3,15 @@ title: ByExpiryDate description: Returns the given page collection sorted by expiration date in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByDate - - methods/pages/ByLastMod - - methods/pages/ByPublishDate - returnType: page.Pages - signatures: [PAGES.ByExpiryDate] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByExpiryDate] --- When sorting by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter. -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByExpiryDate }} diff --git a/docs/content/en/methods/pages/ByLanguage.md b/docs/content/en/methods/pages/ByLanguage.md index 30d87f954..36244eb4d 100644 --- a/docs/content/en/methods/pages/ByLanguage.md +++ b/docs/content/en/methods/pages/ByLanguage.md @@ -3,10 +3,10 @@ title: ByLanguage description: Returns the given page collection sorted by language in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.ByLanguage] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByLanguage] --- ```go-html-template diff --git a/docs/content/en/methods/pages/ByLastmod.md b/docs/content/en/methods/pages/ByLastmod.md index 385093134..3c03d2a6e 100644 --- a/docs/content/en/methods/pages/ByLastmod.md +++ b/docs/content/en/methods/pages/ByLastmod.md @@ -3,18 +3,15 @@ title: ByLastmod description: Returns the given page collection sorted by last modification date in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByDate - - methods/pages/ByExpiryDate - - methods/pages/ByPublishDate - returnType: page.Pages - signatures: [PAGES.ByLastmod] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByLastmod] --- When sorting by last modification date, the value is determined by your [site configuration], defaulting to the `lastmod` field in front matter. -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByLastmod }} diff --git a/docs/content/en/methods/pages/ByLength.md b/docs/content/en/methods/pages/ByLength.md index 602b548c2..c47bf98ba 100644 --- a/docs/content/en/methods/pages/ByLength.md +++ b/docs/content/en/methods/pages/ByLength.md @@ -3,10 +3,10 @@ title: ByLength description: Returns the given page collection sorted by content length in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.ByLength] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByLength] --- ```go-html-template diff --git a/docs/content/en/methods/pages/ByLinkTitle.md b/docs/content/en/methods/pages/ByLinkTitle.md index 073b1e1ba..4a024d25a 100644 --- a/docs/content/en/methods/pages/ByLinkTitle.md +++ b/docs/content/en/methods/pages/ByLinkTitle.md @@ -3,12 +3,10 @@ title: ByLinkTitle description: Returns the given page collection sorted by link title in ascending order, falling back to title if link title is not defined. categories: [] keywords: [] -action: - related: - - methods/pages/ByTitle - - methods/pages/ByParam - returnType: page.Pages - signatures: [PAGES.ByLinkTitle] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByLinkTitle] --- ```go-html-template diff --git a/docs/content/en/methods/pages/ByParam.md b/docs/content/en/methods/pages/ByParam.md index 9a919cc88..9544122a6 100644 --- a/docs/content/en/methods/pages/ByParam.md +++ b/docs/content/en/methods/pages/ByParam.md @@ -3,12 +3,10 @@ title: ByParam description: Returns the given page collection sorted by the given parameter in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByTitle - - methods/pages/ByLinkTitle - returnType: page.Pages - signatures: [PAGES.ByParam PARAM] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByParam PARAM] --- If the given parameter is not present in front matter, Hugo will use the matching parameter in your site configuration if present. diff --git a/docs/content/en/methods/pages/ByPublishDate.md b/docs/content/en/methods/pages/ByPublishDate.md index e622636a2..3dde6fd95 100644 --- a/docs/content/en/methods/pages/ByPublishDate.md +++ b/docs/content/en/methods/pages/ByPublishDate.md @@ -3,18 +3,15 @@ title: ByPublishDate description: Returns the given page collection sorted by publish date in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByDate - - methods/pages/ByExpiryDate - - methods/pages/ByLastMod - returnType: page.Pages - signatures: [PAGES.ByPublishDate] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByPublishDate] --- When sorting by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter. -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates ```go-html-template {{ range .Pages.ByPublishDate }} diff --git a/docs/content/en/methods/pages/ByTitle.md b/docs/content/en/methods/pages/ByTitle.md index ee54d5cda..e10c41714 100644 --- a/docs/content/en/methods/pages/ByTitle.md +++ b/docs/content/en/methods/pages/ByTitle.md @@ -3,12 +3,10 @@ title: ByTitle description: Returns the given page collection sorted by title in ascending order. categories: [] keywords: [] -action: - related: - - methods/pages/ByLinkTitle - - methods/pages/ByParam - returnType: page.Pages - signatures: [PAGES.ByTitle] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByTitle] --- ```go-html-template diff --git a/docs/content/en/methods/pages/ByWeight.md b/docs/content/en/methods/pages/ByWeight.md index 76d12e196..ba255d3c3 100644 --- a/docs/content/en/methods/pages/ByWeight.md +++ b/docs/content/en/methods/pages/ByWeight.md @@ -3,10 +3,10 @@ title: ByWeight description: Returns the given page collection sorted by weight in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.ByWeight] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.ByWeight] --- Assign a [weight](g) to a page using the `weight` field in front matter. The weight must be a non-zero integer. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted pages are placed at the end of the collection. diff --git a/docs/content/en/methods/pages/GroupBy.md b/docs/content/en/methods/pages/GroupBy.md index b46a39bdf..aff0800e9 100644 --- a/docs/content/en/methods/pages/GroupBy.md +++ b/docs/content/en/methods/pages/GroupBy.md @@ -3,13 +3,13 @@ title: GroupBy description: Returns the given page collection grouped by the given field in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.PagesGroup - signatures: ['PAGES.GroupBy FIELD [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupBy FIELD [SORT]'] --- -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} ```go-html-template {{ range .Pages.GroupBy "Section" }} diff --git a/docs/content/en/methods/pages/GroupByDate.md b/docs/content/en/methods/pages/GroupByDate.md index b29b90843..7ef4843a4 100644 --- a/docs/content/en/methods/pages/GroupByDate.md +++ b/docs/content/en/methods/pages/GroupByDate.md @@ -3,14 +3,10 @@ title: GroupByDate description: Returns the given page collection grouped by date in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByExpiryDate - - methods/pages/GroupByLastMod - - methods/pages/GroupByParamDate - - methods/pages/GroupByPublishDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByDate LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupByDate LAYOUT [SORT]'] --- When grouping by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter. @@ -19,9 +15,9 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -64,4 +60,4 @@ The pages within each group will also be sorted by date, either ascending or des ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/docs/content/en/methods/pages/GroupByExpiryDate.md b/docs/content/en/methods/pages/GroupByExpiryDate.md index 261d15fb5..d209e6c2b 100644 --- a/docs/content/en/methods/pages/GroupByExpiryDate.md +++ b/docs/content/en/methods/pages/GroupByExpiryDate.md @@ -3,14 +3,10 @@ title: GroupByExpiryDate description: Returns the given page collection grouped by expiration date in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByDate - - methods/pages/GroupByLastMod - - methods/pages/GroupByParamDate - - methods/pages/GroupByPublishDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByExpiryDate LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupByExpiryDate LAYOUT [SORT]'] --- When grouping by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter. @@ -19,9 +15,9 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -64,4 +60,4 @@ The pages within each group will also be sorted by expiration date, either ascen ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/docs/content/en/methods/pages/GroupByLastmod.md b/docs/content/en/methods/pages/GroupByLastmod.md index 4f9afdded..8729cd3c9 100644 --- a/docs/content/en/methods/pages/GroupByLastmod.md +++ b/docs/content/en/methods/pages/GroupByLastmod.md @@ -3,14 +3,10 @@ title: GroupByLastmod description: Returns the given page collection grouped by last modification date in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByDate - - methods/pages/GroupByExpiryDate - - methods/pages/GroupByParamDate - - methods/pages/GroupByPublishDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByLastmod LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupByLastmod LAYOUT [SORT]'] --- When grouping by last modification date, the value is determined by your [site configuration], defaulting to the `lastmod` field in front matter. @@ -19,9 +15,9 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -64,4 +60,4 @@ The pages within each group will also be sorted by last modification date, eithe ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/docs/content/en/methods/pages/GroupByParam.md b/docs/content/en/methods/pages/GroupByParam.md index 9c63ab902..6764144d6 100644 --- a/docs/content/en/methods/pages/GroupByParam.md +++ b/docs/content/en/methods/pages/GroupByParam.md @@ -3,13 +3,13 @@ title: GroupByParam description: Returns the given page collection grouped by the given parameter in ascending order. categories: [] keywords: [] -action: - related: [] - returnType: page.PagesGroup - signatures: ['PAGES.GroupByParam PARAM [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupByParam PARAM [SORT]'] --- -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} ```go-html-template {{ range .Pages.GroupByParam "color" }} diff --git a/docs/content/en/methods/pages/GroupByParamDate.md b/docs/content/en/methods/pages/GroupByParamDate.md index 826d3c83e..b05a096d2 100644 --- a/docs/content/en/methods/pages/GroupByParamDate.md +++ b/docs/content/en/methods/pages/GroupByParamDate.md @@ -3,14 +3,10 @@ title: GroupByParamDate description: Returns the given page collection grouped by the given date parameter in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByDate - - methods/pages/GroupByExpiryDate - - methods/pages/GroupByLastMod - - methods/pages/GroupByPublishDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByParamDate PARAM LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupByParamDate PARAM LAYOUT [SORT]'] --- The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region. @@ -18,7 +14,7 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -61,4 +57,4 @@ The pages within each group will also be sorted by the parameter date, either as ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/docs/content/en/methods/pages/GroupByPublishDate.md b/docs/content/en/methods/pages/GroupByPublishDate.md index 40e43c3b8..50e12f085 100644 --- a/docs/content/en/methods/pages/GroupByPublishDate.md +++ b/docs/content/en/methods/pages/GroupByPublishDate.md @@ -3,14 +3,10 @@ title: GroupByPublishDate description: Returns the given page collection grouped by publish date in descending order. categories: [] keywords: [] -action: - related: - - methods/pages/GroupByDate - - methods/pages/GroupByExpiryDate - - methods/pages/GroupByLastMod - - methods/pages/GroupByParamDate - returnType: page.PagesGroup - signatures: ['PAGES.GroupByPublishDate LAYOUT [SORT]'] +params: + functions_and_methods: + returnType: page.PagesGroup + signatures: ['PAGES.GroupByPublishDate LAYOUT [SORT]'] --- When grouping by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter. @@ -19,9 +15,9 @@ The [layout string] has the same format as the layout string for the [`time.Form [`time.Format`]: /functions/time/format/ [layout string]: #layout-string -[site configuration]: /getting-started/configuration/#configure-dates +[site configuration]: /configuration/front-matter/#dates -{{% include "methods/pages/_common/group-sort-order.md" %}} +{{% include "/_common/methods/pages/group-sort-order.md" %}} To group content by year and month: @@ -64,4 +60,4 @@ The pages within each group will also be sorted by publish date, either ascendin ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} diff --git a/docs/content/en/methods/pages/Len.md b/docs/content/en/methods/pages/Len.md index 0a5989a1a..85b3267cd 100644 --- a/docs/content/en/methods/pages/Len.md +++ b/docs/content/en/methods/pages/Len.md @@ -3,10 +3,10 @@ title: Len description: Returns the number of pages in the given page collection. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [PAGES.Len] +params: + functions_and_methods: + returnType: int + signatures: [PAGES.Len] --- ```go-html-template diff --git a/docs/content/en/methods/pages/Limit.md b/docs/content/en/methods/pages/Limit.md index bf889fd7e..6ee3de24d 100644 --- a/docs/content/en/methods/pages/Limit.md +++ b/docs/content/en/methods/pages/Limit.md @@ -3,10 +3,10 @@ title: Limit description: Returns the first N pages from the given page collection. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.Limit NUMBER] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.Limit NUMBER] --- ```go-html-template diff --git a/docs/content/en/methods/pages/Next.md b/docs/content/en/methods/pages/Next.md index dcf1231ac..ce091c1ab 100644 --- a/docs/content/en/methods/pages/Next.md +++ b/docs/content/en/methods/pages/Next.md @@ -3,15 +3,10 @@ title: Next description: Returns the next page in a page collection, relative to the given page. categories: [] keywords: [] -action: - related: - - methods/pages/Prev - - methods/page/Next - - methods/page/Prev - - methods/page/NextInSection - - methods/page/PrevInSection - returnType: page.Page - signatures: [PAGES.Next PAGE] +params: + functions_and_methods: + returnType: page.Page + signatures: [PAGES.Next PAGE] --- -{{% include "methods/pages/_common/next-and-prev.md" %}} +{{% include "/_common/methods/pages/next-and-prev.md" %}} diff --git a/docs/content/en/methods/pages/Prev.md b/docs/content/en/methods/pages/Prev.md index 2d8738521..004b9496d 100644 --- a/docs/content/en/methods/pages/Prev.md +++ b/docs/content/en/methods/pages/Prev.md @@ -3,15 +3,10 @@ title: Prev description: Returns the previous page in a page collection, relative to the given page. categories: [] keywords: [] -action: - related: - - methods/pages/Next - - methods/page/Next - - methods/page/Prev - - methods/page/NextInSection - - methods/page/PrevInSection - returnType: page.Pages - signatures: [PAGES.Prev PAGE] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.Prev PAGE] --- -{{% include "methods/pages/_common/next-and-prev.md" %}} +{{% include "/_common/methods/pages/next-and-prev.md" %}} diff --git a/docs/content/en/methods/pages/Related.md b/docs/content/en/methods/pages/Related.md index a80722a0e..22eeb4dfa 100644 --- a/docs/content/en/methods/pages/Related.md +++ b/docs/content/en/methods/pages/Related.md @@ -3,21 +3,19 @@ title: Related description: Returns a collection of pages related to the given page. categories: [] keywords: [] -action: - related: - - methods/page/HeadingsFiltered - - functions/collections/KeyVals - returnType: page.Pages - signatures: - - PAGES.Related PAGE - - PAGES.Related OPTIONS +params: + functions_and_methods: + returnType: page.Pages + signatures: + - PAGES.Related PAGE + - PAGES.Related OPTIONS --- Based on front matter, Hugo uses several factors to identify content related to the given page. Use the default [related content configuration], or tune the results to the desired indices and parameters. See [details]. The argument passed to the `Related` method may be a `Page` or an options map. For example, to pass the current page: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with .Site.RegularPages.Related . | first 5 }} <p>Related pages:</p> <ul> @@ -26,11 +24,11 @@ The argument passed to the `Related` method may be a `Page` or an options map. F {{ end }} </ul> {{ end }} -{{< /code >}} +``` To pass an options map: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ $opts := dict "document" . "indices" (slice "tags" "keywords") @@ -43,7 +41,7 @@ To pass an options map: {{ end }} </ul> {{ end }} -{{< /code >}} +``` ## Options @@ -73,5 +71,5 @@ A contrived example using all of the above: }} ``` -[details]: /content-management/related/ -[related content configuration]: /content-management/related/ +[details]: /content-management/related-content/ +[related content configuration]: /configuration/related-content/ diff --git a/docs/content/en/methods/pages/Reverse.md b/docs/content/en/methods/pages/Reverse.md index e03e0ea47..23c4b0324 100644 --- a/docs/content/en/methods/pages/Reverse.md +++ b/docs/content/en/methods/pages/Reverse.md @@ -3,10 +3,10 @@ title: Reverse description: Returns the given page collection in reverse order. categories: [] keywords: [] -action: - related: [] - returnType: page.Pages - signatures: [PAGES.Reverse] +params: + functions_and_methods: + returnType: page.Pages + signatures: [PAGES.Reverse] --- ```go-html-template diff --git a/docs/content/en/methods/pages/_common/_index.md b/docs/content/en/methods/pages/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/methods/pages/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/methods/pages/_common/group-sort-order.md b/docs/content/en/methods/pages/_common/group-sort-order.md deleted file mode 100644 index e2997a1bd..000000000 --- a/docs/content/en/methods/pages/_common/group-sort-order.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -For the optional sort order, specify either `asc` for ascending order, or `desc` for descending order. diff --git a/docs/content/en/methods/pages/_common/next-and-prev.md b/docs/content/en/methods/pages/_common/next-and-prev.md deleted file mode 100644 index 540783992..000000000 --- a/docs/content/en/methods/pages/_common/next-and-prev.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Hugo determines the _next_ and _previous_ page by sorting the page collection according to this sorting hierarchy: - -Field|Precedence|Sort direction -:--|:--|:-- -[`weight`]|1|descending -[`date`]|2|descending -[`linkTitle`]|3|descending -[`path`]|4|descending - -[`date`]: /methods/page/date/ -[`weight`]: /methods/page/weight/ -[`linkTitle`]: /methods/page/linktitle/ -[`path`]: /methods/page/path/ - -The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior. - -For example, with this content structure: - -```text -content/ -├── pages/ -│ ├── _index.md -│ ├── page-1.md <-- front matter: weight = 10 -│ ├── page-2.md <-- front matter: weight = 20 -│ └── page-3.md <-- front matter: weight = 30 -└── _index.md -``` - -And these templates: - -{{< code file=layouts/_default/list.html >}} -{{ range .Pages.ByWeight}} - <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> -{{ end }} -{{< /code >}} - -{{< code file=layouts/_default/single.html >}} -{{ $pages := .CurrentSection.Pages.ByWeight }} - -{{ with $pages.Prev . }} - <a href="{{ .RelPermalink }}">Previous</a> -{{ end }} - -{{ with $pages.Next . }} - <a href="{{ .RelPermalink }}">Next</a> -{{ end }} -{{< /code >}} - -When you visit page-2: - -- The `Prev` method points to page-3 -- The `Next` method points to page-1 - -To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] method to the page collection definition: - -{{< code file=layouts/_default/single.html >}} -{{ $pages := .CurrentSection.Pages.ByWeight.Reverse }} - -{{ with $pages.Prev . }} - <a href="{{ .RelPermalink }}">Previous</a> -{{ end }} - -{{ with $pages.Next . }} - <a href="{{ .RelPermalink }}">Next</a> -{{ end }} -{{< /code >}} - -[`Reverse`]: /methods/pages/reverse/ diff --git a/docs/content/en/methods/pages/_index.md b/docs/content/en/methods/pages/_index.md index d8a64f5d5..f2495ae49 100644 --- a/docs/content/en/methods/pages/_index.md +++ b/docs/content/en/methods/pages/_index.md @@ -4,10 +4,5 @@ linkTitle: Pages description: Use these methods with a collection of Page objects. categories: [] keywords: [] -menu: - docs: - parent: methods aliases: [/variables/pages] --- - -Use these methods with a collection of Page objects. diff --git a/docs/content/en/methods/resource/Colors.md b/docs/content/en/methods/resource/Colors.md index 08f63ae3f..14d0a40d8 100644 --- a/docs/content/en/methods/resource/Colors.md +++ b/docs/content/en/methods/resource/Colors.md @@ -3,42 +3,36 @@ title: Colors description: Applicable to images, returns a slice of the most dominant colors using a simple histogram method. categories: [] keywords: [] -action: - related: [] - returnType: '[]images.Color' - signatures: [RESOURCE.Colors] -toc: true -math: true +params: + functions_and_methods: + returnType: '[]images.Color' + signatures: [RESOURCE.Colors] --- -The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image. +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} +The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image. ## Methods Each color is an object with the following methods: -ColorHex -{{< new-in 0.125.0 />}} -: (`string`) Returns the [hexadecimal color] value, prefixed with a hash sign. +### ColorHex -Luminance {{< new-in 0.125.0 />}} -: (`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white. -{{% note %}} -Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments. +(`string`) Returns the [hexadecimal color] value, prefixed with a hash sign. -Hugo renders an `images.Color` object as a hexadecimal color value. +### Luminance -[`images.Dither`]: /functions/images/dither/ -[`images.Padding`]: /functions/images/padding/ -[`images.Text`]: /functions/images/text/ -{{% /note %}} +{{< new-in 0.125.0 />}} -[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color -[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance +(`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white. + +> [!note] +> Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments. +> +> Hugo renders an `images.Color` object as a hexadecimal color value. ## Sorting @@ -169,7 +163,12 @@ Calculate the contrast ratio to determine WCAG conformance: {{ end }} ``` -[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines +[`images.Dither`]: /functions/images/dither/ +[`images.Padding`]: /functions/images/padding/ +[`images.Text`]: /functions/images/text/ [contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio [enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color [minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum +[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance +[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines diff --git a/docs/content/en/methods/resource/Content.md b/docs/content/en/methods/resource/Content.md index 4135113e9..2c2c12d3a 100644 --- a/docs/content/en/methods/resource/Content.md +++ b/docs/content/en/methods/resource/Content.md @@ -3,20 +3,21 @@ title: Content description: Returns the content of the given resource. categories: [] keywords: [] -action: - related: [] - returnType: any - signatures: [RESOURCE.Content] -toc: +params: + functions_and_methods: + returnType: any + signatures: [RESOURCE.Content] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `Content` method on a `Resource` object returns `template.HTML` when the resource type is `page`, otherwise it returns a `string`. [resource type]: /methods/resource/resourcetype/ -{{< code file=assets/quotations/kipling.txt >}} +```text {file="assets/quotations/kipling.txt"} He travels the fastest who travels alone. -{{< /code >}} +``` To get the content: @@ -57,5 +58,3 @@ To create inline JavaScript: <script>{{ .Content | safeJS }}</script> {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/docs/content/en/methods/resource/Crop.md b/docs/content/en/methods/resource/Crop.md index 711fc07b0..97b3b95d3 100644 --- a/docs/content/en/methods/resource/Crop.md +++ b/docs/content/en/methods/resource/Crop.md @@ -3,18 +3,14 @@ title: Crop description: Applicable to images, returns an image resource cropped to the given dimensions without resizing. categories: [] keywords: [] -action: - related: - - methods/resource/Fit - - methods/resource/Fill - - methods/resource/Resize - - methods/resource/Process - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Crop SPEC] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Crop SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Crop an image to match the given dimensions without resizing. You must provide both width and height. ```go-html-template @@ -25,9 +21,7 @@ Crop an image to match the given dimensions without resizing. You must provide b {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/docs/content/en/methods/resource/Data.md b/docs/content/en/methods/resource/Data.md index b6744d1be..0709ca50a 100644 --- a/docs/content/en/methods/resource/Data.md +++ b/docs/content/en/methods/resource/Data.md @@ -3,18 +3,18 @@ title: Data description: Applicable to resources returned by the resources.GetRemote function, returns information from the HTTP response. categories: [] keywords: [] -action: - related: - - functions/resources/GetRemote - - methods/resource/Err - returnType: map - signatures: [RESOURCE.Data] +params: + functions_and_methods: + returnType: map + signatures: [RESOURCE.Data] --- The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response. [`resources.GetRemote`]: /functions/resources/getremote/ +## Example + ```go-html-template {{ $url := "https://example.org/images/a.jpg" }} {{ $opts := dict "responseHeaders" (slice "Server") }} @@ -36,30 +36,31 @@ The `Data` method on a resource returned by the [`resources.GetRemote`] function {{ end }} ``` -###### ContentLength +## Methods + +### ContentLength (`int`) The content length in bytes. -###### ContentType +### ContentType (`string`) The content type. -###### Headers +### Headers (`map[string][]string`) A map of response headers matching those requested in the [`responseHeaders`] option passed to the `resources.GetRemote` function. The header name matching is case-insensitive. In most cases there will be one value per header key. -[`responseHeaders`]: /functions/resources/getremote/#responseheaders - -###### Status +### Status (`string`) The HTTP status text. -###### StatusCode +### StatusCode (`int`) The HTTP status code. -###### TransferEncoding +### TransferEncoding (`string`) The transfer encoding. [`resources.GetRemote`]: /functions/resources/getremote/ +[`responseHeaders`]: /functions/resources/getremote/#responseheaders diff --git a/docs/content/en/methods/resource/Err.md b/docs/content/en/methods/resource/Err.md index 34ba6f9bc..591af8266 100644 --- a/docs/content/en/methods/resource/Err.md +++ b/docs/content/en/methods/resource/Err.md @@ -1,22 +1,20 @@ --- title: Err -description: Applicable to resources returned by the resources.GetRemote function, returns an error message if the HTTP request fails, else nil. +description: Applicable to resources returned by the resources.GetRemote function, returns an error message if the HTTP request fails, else nil. categories: [] keywords: [] -action: - related: - - functions/resources/GetRemote - - methods/resource/Data - returnType: resource.resourceError - signatures: [RESOURCE.Err] +params: + functions_and_methods: + returnType: resource.resourceError + signatures: [RESOURCE.Err] expiryDate: 2027-01-16 # deprecated 2025-01-16 in v0.141.0 --- -{{% deprecated-in 0.141.0 %}} +{{< deprecated-in 0.141.0 >}} Use the `try` statement instead. See [example]. [example]: /functions/go-template/try/#example -{{% /deprecated-in %}} +{{< /deprecated-in >}} The `Err` method on a resource returned by the [`resources.GetRemote`] function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build. @@ -58,6 +56,5 @@ To log an error as a warning instead of an error: {{ end }} ``` -{{% note %}} -An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above. -{{% /note %}} +> [!note] +> An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above. diff --git a/docs/content/en/methods/resource/Exif.md b/docs/content/en/methods/resource/Exif.md index a8e5a42aa..443a0ee1a 100644 --- a/docs/content/en/methods/resource/Exif.md +++ b/docs/content/en/methods/resource/Exif.md @@ -3,28 +3,35 @@ title: Exif description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an EXIF object containing image metadata. categories: [] keywords: [] -action: - related: [] - returnType: exif.ExifInfo - signatures: [RESOURCE.Exif] -toc: true +params: + functions_and_methods: + returnType: exif.ExifInfo + signatures: [RESOURCE.Exif] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Applicable to JPEG, PNG, TIFF, and WebP images, the `Exif` method on an image `Resource` object returns an [EXIF] object containing image metadata. ## Methods -Date -: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function. +### Date + +(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function. + +### Lat + +(`float64`) Returns the GPS latitude in degrees. -Lat -: (`float64`) Returns the GPS latitude in degrees. +### Long -Long -: (`float64`) Returns the GPS longitude in degrees. +(`float64`) Returns the GPS longitude in degrees. -Tags -: (`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration]. +### Tags + +(`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection. See [configure imaging]. + +[configure imaging]: /configuration/imaging/#exif-data ## Examples @@ -71,8 +78,5 @@ To list specific values: {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - [exif]: https://en.wikipedia.org/wiki/Exif -[site configuration]: /content-management/image-processing/#exif-data [`time.Format`]: /functions/time/format/ diff --git a/docs/content/en/methods/resource/Fill.md b/docs/content/en/methods/resource/Fill.md index 8bbaf93ee..82c696c91 100644 --- a/docs/content/en/methods/resource/Fill.md +++ b/docs/content/en/methods/resource/Fill.md @@ -1,20 +1,16 @@ --- title: Fill -description: Applicable to images, returns an image resource cropped and resized to the given dimensions. +description: Applicable to images, returns an image resource cropped and resized to the given dimensions. categories: [] keywords: [] -action: - related: - - methods/resource/Crop - - methods/resource/Fit - - methods/resource/Resize - - methods/resource/Process - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Fill SPEC] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Fill SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Crop and resize an image to match the given dimensions. You must provide both width and height. ```go-html-template @@ -25,9 +21,7 @@ Crop and resize an image to match the given dimensions. You must provide both wi {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/docs/content/en/methods/resource/Filter.md b/docs/content/en/methods/resource/Filter.md index 2b059c993..b83c3d8cb 100644 --- a/docs/content/en/methods/resource/Filter.md +++ b/docs/content/en/methods/resource/Filter.md @@ -3,14 +3,14 @@ title: Filter description: Applicable to images, applies one or more image filters to the given image resource. categories: [] keywords: [] -action: - related: - - functions/images/Filter - returnType: images.ImageResource - signatures: [RESOURCE.Filter FILTER...] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Filter FILTER...] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Apply one or more [image filters](#image-filters) to the given image. To apply a single filter: @@ -41,8 +41,6 @@ You can also apply image filters using the [`images.Filter`] function. [`images.Filter`]: /functions/images/filter/ -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - ## Example ```go-html-template @@ -65,4 +63,4 @@ You can also apply image filters using the [`images.Filter`] function. Use any of these filters with the `Filter` method. -{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}} +{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}} diff --git a/docs/content/en/methods/resource/Fit.md b/docs/content/en/methods/resource/Fit.md index 13354fe5a..7b416c4a1 100644 --- a/docs/content/en/methods/resource/Fit.md +++ b/docs/content/en/methods/resource/Fit.md @@ -1,20 +1,16 @@ --- title: Fit -description: Applicable to images, returns an image resource downscaled to fit the given dimensions while maintaining aspect ratio. +description: Applicable to images, returns an image resource downscaled to fit the given dimensions while maintaining aspect ratio. categories: [] keywords: [] -action: - related: - - methods/resource/Crop - - methods/resource/Fill - - methods/resource/Resize - - methods/resource/Process - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Fit SPEC] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Fit SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height. ```go-html-template @@ -25,9 +21,7 @@ Downscale an image to fit the given dimensions while maintaining aspect ratio. Y {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/docs/content/en/methods/resource/Height.md b/docs/content/en/methods/resource/Height.md index dcaf6c514..cc131378a 100644 --- a/docs/content/en/methods/resource/Height.md +++ b/docs/content/en/methods/resource/Height.md @@ -3,13 +3,14 @@ title: Height description: Applicable to images, returns the height of the given resource. categories: [] keywords: [] -action: - related: - - methods/resource/Width - returnType: int - signatures: [RESOURCE.Height] +params: + functions_and_methods: + returnType: int + signatures: [RESOURCE.Height] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + ```go-html-template {{ with resources.Get "images/a.jpg" }} {{ .Height }} → 400 @@ -23,5 +24,3 @@ Use the `Width` and `Height` methods together when rendering an `img` element: <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}"> {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/docs/content/en/methods/resource/Key.md b/docs/content/en/methods/resource/Key.md deleted file mode 100644 index 2dbd371be..000000000 --- a/docs/content/en/methods/resource/Key.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Key -description: Returns the unique key for the given resource, equivalent to its publishing path. -draft: true -categories: [] -keywords: [] -action: - related: - - methods/resource/Permalink - - methods/resource/RelPermalink - - methods/resource/Publish - returnType: string - signatures: [RESOURCE.Key] ---- - -By way of example, consider this site configuration: - -{{< code-toggle file=hugo >}} -baseURL = 'https://example.org/docs/' -{{< /code-toggle >}} - -And this template: - -```go-html-template - {{ with resources.Get "images/a.jpg" }} - {{ with resources.Copy "foo/bar/b.jpg" . }} - {{ .Key }} → foo/bar/b.jpg - - {{ .Name }} → images/a.jpg - {{ .Title }} → images/a.jpg - - {{ .RelPermalink }} → /docs/foo/bar/b.jpg - {{ end }} - {{ end }} -``` - -We used the [`resources.Copy`] function to change the publishing path. The `Key` method returns the updated path, but note that it is different than the value returned by [`RelPermalink`]. The `RelPermalink` value includes the subdirectory segment of the `baseURL` in the site configuration. - -The `Key` method is useful if you need to get the resource's publishing path without publishing the resource. Unlike the `Permalink`, `RelPermalink`, or `Publish` methods, calling `Key` will not publish the resource. - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -[`Permalink`]: /methods/resource/permalink/ -[`RelPermalink`]: /methods/resource/relpermalink/ -[`resources.Copy`]: /functions/resources/copy/ diff --git a/docs/content/en/methods/resource/MediaType.md b/docs/content/en/methods/resource/MediaType.md index 6dea8706c..7721f69ba 100644 --- a/docs/content/en/methods/resource/MediaType.md +++ b/docs/content/en/methods/resource/MediaType.md @@ -3,18 +3,21 @@ title: MediaType description: Returns a media type object for the given resource. categories: [] keywords: [] -action: - related: [] - returnType: media.Type - signatures: [RESOURCE.MediaType] +params: + functions_and_methods: + returnType: media.Type + signatures: [RESOURCE.MediaType] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `MediaType` method on a `Resource` object returns an object with additional methods. ## Methods -Type -: (`string`) The resource's media type. +### Type + +(`string`) The resource's media type. ```go-html-template {{ with resources.Get "images/a.jpg" }} @@ -22,8 +25,9 @@ Type {{ end }} ``` -MainType -: (`string`) The main type of the resource’s media type. +### MainType + +(`string`) The main type of the resource's media type. ```go-html-template {{ with resources.Get "images/a.jpg" }} @@ -31,8 +35,9 @@ MainType {{ end }} ``` -SubType -: (`string`) The subtype of the resource’s media type. This may or may not correspond to the file suffix. +### SubType + +(`string`) The subtype of the resource's media type. This may or may not correspond to the file suffix. ```go-html-template {{ with resources.Get "images/a.jpg" }} @@ -40,8 +45,9 @@ SubType {{ end }} ``` -Suffixes -: (`slice`) A slice of possible file suffixes for the resource’s media type. +### Suffixes + +(`slice`) A slice of possible file suffixes for the resource's media type. ```go-html-template {{ with resources.Get "images/a.jpg" }} @@ -49,4 +55,12 @@ Suffixes {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} +### FirstSuffix.Suffix + +(`string`) The first of the possible file suffixes for the resource's media type. + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ .MediaType.FirstSuffix.Suffix }} → jpg +{{ end }} +``` diff --git a/docs/content/en/methods/resource/Name.md b/docs/content/en/methods/resource/Name.md index 28ccf3abf..c678c96c9 100644 --- a/docs/content/en/methods/resource/Name.md +++ b/docs/content/en/methods/resource/Name.md @@ -3,12 +3,10 @@ title: Name description: Returns the name of the given resource as optionally defined in front matter, falling back to its file path. categories: [] keywords: [] -action: - related: - - methods/resource/Title - returnType: string - signatures: [RESOURCE.Name] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.Name] --- The value returned by the `Name` method on a `Resource` object depends on the resource type. diff --git a/docs/content/en/methods/resource/Params.md b/docs/content/en/methods/resource/Params.md index a171b3ddf..38f2ef6c2 100644 --- a/docs/content/en/methods/resource/Params.md +++ b/docs/content/en/methods/resource/Params.md @@ -3,10 +3,10 @@ title: Params description: Returns a map of resource parameters as defined in front matter. categories: [] keywords: [] -action: - related: [] - returnType: map - signatures: [RESOURCE.Params] +params: + functions_and_methods: + returnType: map + signatures: [RESOURCE.Params] --- Use the `Params` method with [page resources](g). It is not applicable to either [global resources](g) or [remote resources](g). diff --git a/docs/content/en/methods/resource/Permalink.md b/docs/content/en/methods/resource/Permalink.md index 4c87b4b46..a8ec2d323 100644 --- a/docs/content/en/methods/resource/Permalink.md +++ b/docs/content/en/methods/resource/Permalink.md @@ -1,16 +1,16 @@ --- title: Permalink -description: Publishes the given resource and returns its permalink. +description: Publishes the given resource and returns its permalink. categories: [] keywords: [] -action: - related: - - methods/resource/RelPermalink - - methods/resource/Publish - returnType: string - signatures: [RESOURCE.Permalink] +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.Permalink] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [permalink](g). ```go-html-template @@ -18,5 +18,3 @@ The `Permalink` method on a `Resource` object writes the resource to the publish {{ .Permalink }} → https://example.org/images/a.jpg {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/docs/content/en/methods/resource/Process.md b/docs/content/en/methods/resource/Process.md index 550b06401..fb27da54e 100644 --- a/docs/content/en/methods/resource/Process.md +++ b/docs/content/en/methods/resource/Process.md @@ -3,18 +3,14 @@ title: Process description: Applicable to images, returns an image resource processed with the given specification. categories: [] keywords: [] -action: - related: - - methods/resource/Crop - - methods/resource/Fit - - methods/resource/Fill - - methods/resource/Resize - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Process SPEC] -toc: true +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Process SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Process an image with the given specification. The specification can contain an optional action, one of `crop`, `fill`, `fit`, or `resize`. This means that you can use this method instead of [`Crop`], [`Fill`], [`Fit`], or [`Resize`]. ```go-html-template @@ -37,9 +33,7 @@ You can also use this method to apply simple transformations such as rotation an The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [`images.Process`]. -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/docs/content/en/methods/resource/Publish.md b/docs/content/en/methods/resource/Publish.md index 05344c658..0ecdf7e74 100644 --- a/docs/content/en/methods/resource/Publish.md +++ b/docs/content/en/methods/resource/Publish.md @@ -3,14 +3,14 @@ title: Publish description: Publishes the given resource. categories: [] keywords: [] -action: - related: - - methods/resource/Permalink - - methods/resource/RelPermalink - returnType: nil - signatures: [RESOURCE.Publish] +params: + functions_and_methods: + returnType: nil + signatures: [RESOURCE.Publish] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `Publish` method on a `Resource` object writes the resource to the publish directory, typically `public`. ```go-html-template @@ -30,5 +30,3 @@ Instead of this: ```go-html-template {{ $noop := $resource.Permalink }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/docs/content/en/methods/resource/RelPermalink.md b/docs/content/en/methods/resource/RelPermalink.md index a7226b057..d4c907bff 100644 --- a/docs/content/en/methods/resource/RelPermalink.md +++ b/docs/content/en/methods/resource/RelPermalink.md @@ -3,14 +3,14 @@ title: RelPermalink description: Publishes the given resource and returns its relative permalink. categories: [] keywords: [] -action: - related: - - methods/resource/Permalink - - methods/resource/Publish - returnType: string - signatures: [RESOURCE.RelPermalink] +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.RelPermalink] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [relative permalink](g). ```go-html-template @@ -18,5 +18,3 @@ The `Permalink` method on a `Resource` object writes the resource to the publish {{ .RelPermalink }} → /images/a.jpg {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/docs/content/en/methods/resource/Resize.md b/docs/content/en/methods/resource/Resize.md index 4ba054bb5..93c029ba6 100644 --- a/docs/content/en/methods/resource/Resize.md +++ b/docs/content/en/methods/resource/Resize.md @@ -3,17 +3,14 @@ title: Resize description: Applicable to images, returns an image resource resized to the given width and/or height. categories: [] keywords: [] -action: - related: - - methods/resource/Crop - - methods/resource/Fit - - methods/resource/Fill - - methods/resource/Process - - functions/images/Process - returnType: images.ImageResource - signatures: [RESOURCE.Resize SPEC] +params: + functions_and_methods: + returnType: images.ImageResource + signatures: [RESOURCE.Resize SPEC] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Resize an image to the given width and/or height. If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio. @@ -26,9 +23,7 @@ If you specify both width and height, the resulting image will be disproportiona {{ end }} ``` -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} - -{{% include "/methods/resource/_common/processing-spec.md" %}} +{{% include "/_common/methods/resource/processing-spec.md" %}} ## Example diff --git a/docs/content/en/methods/resource/ResourceType.md b/docs/content/en/methods/resource/ResourceType.md index db52e7b10..0ea9c0cf9 100644 --- a/docs/content/en/methods/resource/ResourceType.md +++ b/docs/content/en/methods/resource/ResourceType.md @@ -3,12 +3,14 @@ title: ResourceType description: Returns the main type of the given resource's media type. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [RESOURCE.ResourceType] +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.ResourceType] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + Common resource types include `audio`, `image`, `text`, and `video`. ```go-html-template @@ -34,10 +36,8 @@ content/ With the structure above, we can range through page resources of type `page` to build content: -{{< code file=layouts/lessons/single.html >}} +```go-html-template {file="layouts/lessons/single.html"} {{ range .Resources.ByType "page" }} {{ .Content }} {{ end }} -{{< /code >}} - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} +``` diff --git a/docs/content/en/methods/resource/Title.md b/docs/content/en/methods/resource/Title.md index 1a984f902..c02d29ff8 100644 --- a/docs/content/en/methods/resource/Title.md +++ b/docs/content/en/methods/resource/Title.md @@ -3,12 +3,10 @@ title: Title description: Returns the title of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type. categories: [] keywords: [] -action: - related: - - methods/resource/Name - returnType: string - signatures: [RESOURCE.Title] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [RESOURCE.Title] --- The value returned by the `Title` method on a `Resource` object depends on the resource type. diff --git a/docs/content/en/methods/resource/Width.md b/docs/content/en/methods/resource/Width.md index 8b96c95e8..e1b43f44c 100644 --- a/docs/content/en/methods/resource/Width.md +++ b/docs/content/en/methods/resource/Width.md @@ -3,13 +3,14 @@ title: Width description: Applicable to images, returns the width of the given resource. categories: [] keywords: [] -action: - related: - - methods/resource/Height - returnType: int - signatures: [RESOURCE.Width] +params: + functions_and_methods: + returnType: int + signatures: [RESOURCE.Width] --- +{{% include "/_common/methods/resource/global-page-remote-resources.md" %}} + ```go-html-template {{ with resources.Get "images/a.jpg" }} {{ .Width }} → 600 @@ -23,5 +24,3 @@ Use the `Width` and `Height` methods together when rendering an `img` element: <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}"> {{ end }} ``` - -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} diff --git a/docs/content/en/methods/resource/_common/_index.md b/docs/content/en/methods/resource/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/methods/resource/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/methods/resource/_common/global-page-remote-resources.md b/docs/content/en/methods/resource/_common/global-page-remote-resources.md deleted file mode 100644 index e410df038..000000000 --- a/docs/content/en/methods/resource/_common/global-page-remote-resources.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -{{% note %}} -Use this method with [global resources](g), [page resources](g), or [remote resources](g). -{{% /note %}} diff --git a/docs/content/en/methods/resource/_common/processing-spec.md b/docs/content/en/methods/resource/_common/processing-spec.md deleted file mode 100644 index 395217328..000000000 --- a/docs/content/en/methods/resource/_common/processing-spec.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -## Process specification - -The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence: - -action -: Applicable to the [`Process`](/methods/resource/process) method only. Specify zero or one of `crop`, `fill`, `fit`, or `resize`. If you specify an action you must also provide dimensions. - -dimensions -: Provide width _or_ height when using the [`Resize`](/methods/resource/resize) method, else provide both width _and_ height. See [details](/content-management/image-processing/#dimensions). - -anchor -: Use with the [`Crop`](/methods/resource/crop) and [`Fill`](/methods/resource/fill) methods. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See [details](/content-management/image-processing/#anchor). - -rotation -: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation). - -target format -: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format). - -quality -: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See [details](/content-management/image-processing/#quality). - -hint -: Applicable to WebP images and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint). - -[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp - -background color -: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See [details](/content-management/image-processing/#background-color). - -resampling filter -: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See [details](/content-management/image-processing/#resampling-filter). diff --git a/docs/content/en/methods/resource/_index.md b/docs/content/en/methods/resource/_index.md index e9426e1a5..edfbc5b14 100644 --- a/docs/content/en/methods/resource/_index.md +++ b/docs/content/en/methods/resource/_index.md @@ -4,9 +4,4 @@ linkTitle: Resource description: Use these methods with global, page, and remote Resource objects. categories: [] keywords: [] -menu: - docs: - parent: methods --- - -Use these methods with global, page, and remote Resource objects. diff --git a/docs/content/en/methods/shortcode/Get.md b/docs/content/en/methods/shortcode/Get.md index 8874c7649..b9c01cfc4 100644 --- a/docs/content/en/methods/shortcode/Get.md +++ b/docs/content/en/methods/shortcode/Get.md @@ -3,49 +3,44 @@ title: Get description: Returns the value of the given argument. categories: [] keywords: [] -action: - related: - - methods/shortcode/IsNamedParams - - methods/shortcode/Params - returnType: any - signatures: [SHORTCODE.Get ARG] -toc: true +params: + functions_and_methods: + returnType: any + signatures: [SHORTCODE.Get ARG] --- Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both. -{{% note %}} -Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details. -{{% /note %}} +> [!note] +> Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details. ## Positional arguments This shortcode call uses positional arguments: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{</* myshortcode "Hello" "world" */>}} -{{< /code >}} +``` To retrieve arguments by position: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world. -{{< /code >}} +``` ## Named arguments This shortcode call uses named arguments: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{</* myshortcode greeting="Hello" firstName="world" */>}} -{{< /code >}} +``` To retrieve arguments by name: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world. -{{< /code >}} +``` -{{% note %}} -Argument names are case-sensitive. -{{% /note %}} +> [!note] +> Argument names are case-sensitive. diff --git a/docs/content/en/methods/shortcode/Inner.md b/docs/content/en/methods/shortcode/Inner.md index ef8d05ecb..cdce4c1c3 100644 --- a/docs/content/en/methods/shortcode/Inner.md +++ b/docs/content/en/methods/shortcode/Inner.md @@ -3,28 +3,23 @@ title: Inner description: Returns the content between opening and closing shortcode tags, applicable when the shortcode call includes a closing tag. categories: [] keywords: [] -action: - related: - - functions/strings/Trim - - methods/page/RenderString - - functions/transform/Markdownify - - methods/shortcode/InnerDeindent - returnType: template.HTML - signatures: [SHORTCODE.Inner] -toc: true +params: + functions_and_methods: + returnType: template.HTML + signatures: [SHORTCODE.Inner] --- This content: -{{< code file=content/services.md lang=md >}} +```text {file="content/services.md"} {{</* card title="Product Design" */>}} We design the **best** widgets in the world. {{</* /card */>}} -{{< /code >}} +``` With this shortcode: -{{< code file=layouts/shortcodes/card.html >}} +```go-html-template {file="layouts/shortcodes/card.html"} <div class="card"> {{ with .Get "title" }} <div class="card-title">{{ . }}</div> @@ -33,7 +28,7 @@ With this shortcode: {{ .Inner | strings.TrimSpace }} </div> </div> -{{< /code >}} +``` Is rendered to: @@ -46,23 +41,17 @@ Is rendered to: </div> ``` -{{% note %}} -Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove both carriage returns and newlines. - -[`strings.TrimSpace`]: /functions/strings/trimspace/ -{{% /note %}} +> [!note] +> Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`] function as shown above to remove carriage returns and newlines. -{{% note %}} -In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML. -{{% /note %}} +> [!note] +> In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML. ## Use RenderString Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object: -[`RenderString`]: /methods/page/renderstring/ - -{{< code file=layouts/shortcodes/card.html >}} +```go-html-template {file="layouts/shortcodes/card.html"} <div class="card"> {{ with .Get "title" }} <div class="card-title">{{ . }}</div> @@ -71,7 +60,7 @@ Let's modify the example above to pass the value returned by `Inner` through the {{ .Inner | strings.TrimSpace | .Page.RenderString }} </div> </div> -{{< /code >}} +``` Hugo renders this to: @@ -86,18 +75,15 @@ Hugo renders this to: You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See [details]. -[details]: /methods/page/renderstring/ -[`markdownify`]: /functions/transform/markdownify/ - ## Alternative notation Instead of calling the shortcode with the `{{</* */>}}` notation, use the `{{%/* */%}}` notation: -{{< code file=content/services.md lang=md >}} +```text {file="content/services.md"} {{%/* card title="Product Design" */%}} We design the **best** widgets in the world. {{%/* /card */%}} -{{< /code >}} +``` When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as Markdown, requiring the following changes. @@ -112,7 +98,7 @@ This configuration is not unsafe if _you_ control the content. Read more about H Second, because we are rendering the entire shortcode as Markdown, we must adhere to the rules governing [indentation] and inclusion of [raw HTML blocks] as provided in the [CommonMark] specification. -{{< code file=layouts/shortcodes/card.html >}} +```go-html-template {file="layouts/shortcodes/card.html"} <div class="card"> {{ with .Get "title" }} <div class="card-title">{{ . }}</div> @@ -122,7 +108,7 @@ Second, because we are rendering the entire shortcode as Markdown, we must adher {{ .Inner | strings.TrimSpace }} </div> </div> -{{< /code >}} +``` The difference between this and the previous example is subtle but required. Note the change in indentation, the addition of a blank line, and removal of the `RenderString` method. @@ -143,11 +129,15 @@ The difference between this and the previous example is subtle but required. Not </div> ``` -{{% note %}} -When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner` through the `RenderString` method or the `markdownify` function. -{{% /note %}} +> [!note] +> Don't process the `Inner` value with `RenderString` or `markdownify` when using [Markdown notation] to call the shortcode. -[commonmark]: https://commonmark.org/ +[`markdownify`]: /functions/transform/markdownify/ +[`RenderString`]: /methods/page/renderstring/ +[`strings.TrimSpace`]: /functions/strings/trimspace/ +[CommonMark]: https://spec.commonmark.org/current/ +[details]: /methods/page/renderstring/ [indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks -[raw html blocks]: https://spec.commonmark.org/0.30/#html-blocks +[Markdown notation]: /content-management/shortcodes/#notation +[raw HTML blocks]: https://spec.commonmark.org/0.31.2/#html-blocks [security model]: /about/security/ diff --git a/docs/content/en/methods/shortcode/InnerDeindent.md b/docs/content/en/methods/shortcode/InnerDeindent.md index ab4263709..0b8c8e2d8 100644 --- a/docs/content/en/methods/shortcode/InnerDeindent.md +++ b/docs/content/en/methods/shortcode/InnerDeindent.md @@ -1,13 +1,12 @@ --- title: InnerDeindent -description: Returns the content between opening and closing shortcode tags, with indentation removed, applicable when the shortcode call includes a closing tag. +description: Returns the content between opening and closing shortcode tags, with indentation removed, applicable when the shortcode call includes a closing tag. categories: [] keywords: [] -action: - related: - - methods/shortcode/Inner - returnType: template.HTML - signatures: [SHORTCODE.InnerDeindent] +params: + functions_and_methods: + returnType: template.HTML + signatures: [SHORTCODE.InnerDeindent] --- Similar to the [`Inner`] method, `InnerDeindent` returns the content between opening and closing shortcode tags. However, with `InnerDeindent`, indentation before the content is removed. @@ -16,7 +15,7 @@ This allows us to effectively bypass the rules governing [indentation] as provid Consider this Markdown, an unordered list with a small gallery of thumbnail images within each list item: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} - Gallery one {{</* gallery */>}} @@ -30,17 +29,17 @@ Consider this Markdown, an unordered list with a small gallery of thumbnail imag   {{</* /gallery */>}} -{{< /code >}} +``` In the example above, notice that the content between the opening and closing shortcode tags is indented by four spaces. Per the CommonMark specification, this is treated as an indented code block. With this shortcode, calling `Inner` instead of `InnerDeindent`: -{{< code file=layouts/shortcodes/gallery.html >}} +```go-html-template {file="layouts/shortcodes/gallery.html"} <div class="gallery"> {{ .Inner | strings.TrimSpace | .Page.RenderString }} </div> -{{< /code >}} +``` Hugo renders the Markdown to: @@ -67,11 +66,11 @@ Hugo renders the Markdown to: Although technically correct per the CommonMark specification, this is not what we want. If we remove the indentation using the `InnerDeindent` method: -{{< code file=layouts/shortcodes/gallery.html >}} +```go-html-template {file="layouts/shortcodes/gallery.html"} <div class="gallery"> {{ .InnerDeindent | strings.TrimSpace | .Page.RenderString }} </div> -{{< /code >}} +``` Hugo renders the Markdown to: diff --git a/docs/content/en/methods/shortcode/IsNamedParams.md b/docs/content/en/methods/shortcode/IsNamedParams.md index a1d93ddac..1e0a7f00e 100644 --- a/docs/content/en/methods/shortcode/IsNamedParams.md +++ b/docs/content/en/methods/shortcode/IsNamedParams.md @@ -3,28 +3,27 @@ title: IsNamedParams description: Reports whether the shortcode call uses named arguments. categories: [] keywords: [] -action: - related: - - methods/shortcode/Get - returnType: bool - signatures: [SHORTCODE.IsNamedParams] +params: + functions_and_methods: + returnType: bool + signatures: [SHORTCODE.IsNamedParams] --- To support both positional and named arguments when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called. With this shortcode template: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ if .IsNamedParams }} {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} {{ else }} {{ printf "%s %s." (.Get 0) (.Get 1) }} {{ end }} -{{< /code >}} +``` Both of these calls return the same value: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{</* myshortcode greeting="Hello" firstName="world" */>}} {{</* myshortcode "Hello" "world" */>}} -{{< /code >}} +``` diff --git a/docs/content/en/methods/shortcode/Name.md b/docs/content/en/methods/shortcode/Name.md index fcf92718f..b5f9b6c17 100644 --- a/docs/content/en/methods/shortcode/Name.md +++ b/docs/content/en/methods/shortcode/Name.md @@ -3,24 +3,22 @@ title: Name description: Returns the shortcode file name, excluding the file extension. categories: [] keywords: [] -action: - related: - - methods/shortcode/Position - - functions/fmt/Errorf - returnType: string - signatures: [SHORTCODE.Name] +params: + functions_and_methods: + returnType: string + signatures: [SHORTCODE.Name] --- The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ $greeting := "" }} {{ with .Get "greeting" }} {{ $greeting = . }} {{ else }} {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` In the absence of a "greeting" argument, Hugo will throw an error message and fail the build: diff --git a/docs/content/en/methods/shortcode/Ordinal.md b/docs/content/en/methods/shortcode/Ordinal.md index 41393fa22..def0c016f 100644 --- a/docs/content/en/methods/shortcode/Ordinal.md +++ b/docs/content/en/methods/shortcode/Ordinal.md @@ -3,29 +3,28 @@ title: Ordinal description: Returns the zero-based ordinal of the shortcode in relation to its parent. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [SHORTCODE.Ordinal] +params: + functions_and_methods: + returnType: int + signatures: [SHORTCODE.Ordinal] --- The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content. -{{% note %}} -Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page. -{{% /note %}} +> [!note] +> Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page. This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example: -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{</* img src="images/a.jpg" */>}} {{</* img src="images/b.jpg" */>}} -{{< /code >}} +``` This shortcode performs error checking, then renders an HTML `img` element with a unique `id` attribute: -{{< code file=layouts/shortcodes/img.html >}} +```go-html-template {file="layouts/shortcodes/img.html"} {{ $src := "" }} {{ with .Get "src" }} {{ $src = . }} @@ -38,7 +37,7 @@ This shortcode performs error checking, then renders an HTML `img` element with {{ else }} {{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` Hugo renders the page to: @@ -47,8 +46,7 @@ Hugo renders the page to: <img id="img-001" src="/images/b.jpg" width="600" height="400" alt=""> ``` -{{% note %}} -In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top level context passed into the template. +> [!note] +> In the shortcode template above, the [`with`] statement is used to create conditional blocks. Remember that the `with` statement binds context (the dot) to its expression. Inside of a `with` block, preface shortcode method calls with a `$` to access the top-level context passed into the template. [`with`]: /functions/go-template/with/ -{{% /note %}} diff --git a/docs/content/en/methods/shortcode/Page.md b/docs/content/en/methods/shortcode/Page.md index 8bb58fa18..774caf9fc 100644 --- a/docs/content/en/methods/shortcode/Page.md +++ b/docs/content/en/methods/shortcode/Page.md @@ -3,10 +3,10 @@ title: Page description: Returns the Page object from which the shortcode was called. categories: [] keywords: [] -action: - related: [] - returnType: hugolib.pageForShortcode - signatures: [SHORTCODE.Page] +params: + functions_and_methods: + returnType: hugolib.pageForShortcode + signatures: [SHORTCODE.Page] --- With this content: @@ -26,11 +26,11 @@ Calling this shortcode: We can access the front matter values using the `Page` method: -{{< code file=layouts/shortcodes/book-details.html >}} +```go-html-template {file="layouts/shortcodes/book-details.html"} <ul> <li>Title: {{ .Page.Title }}</li> <li>Author: {{ .Page.Params.author }}</li> <li>Published: {{ .Page.Params.publication_year }}</li> <li>ISBN: {{ .Page.Params.isbn }}</li> </ul> -{{< /code >}} +``` diff --git a/docs/content/en/methods/shortcode/Params.md b/docs/content/en/methods/shortcode/Params.md index c0772e36a..f001e737f 100644 --- a/docs/content/en/methods/shortcode/Params.md +++ b/docs/content/en/methods/shortcode/Params.md @@ -3,31 +3,30 @@ title: Params description: Returns a collection of the shortcode arguments. categories: [] keywords: [] -action: - related: - - methods/shortcode/Get - returnType: any - signatures: [SHORTCODE.Params] +params: + functions_and_methods: + returnType: any + signatures: [SHORTCODE.Params] --- When you call a shortcode using positional arguments, the `Params` method returns a slice. -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{</* myshortcode "Hello" "world" */>}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ index .Params 0 }} → Hello {{ index .Params 1 }} → world -{{< /code >}} +``` When you call a shortcode using named arguments, the `Params` method returns a map. -{{< code file=content/about.md lang=md >}} +```text {file="content/about.md"} {{</* myshortcode greeting="Hello" name="world" */>}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ .Params.greeting }} → Hello {{ .Params.name }} → world -{{< /code >}} +``` diff --git a/docs/content/en/methods/shortcode/Parent.md b/docs/content/en/methods/shortcode/Parent.md index 740b1ad7e..91c445d2a 100644 --- a/docs/content/en/methods/shortcode/Parent.md +++ b/docs/content/en/methods/shortcode/Parent.md @@ -1,31 +1,31 @@ --- title: Parent -description: Returns the parent shortcode context in nested shortcodes. +description: Returns the parent shortcode context in nested shortcodes. categories: [] keywords: [] -action: - related: [] - returnType: hugolib.ShortcodeWithPage - signatures: [SHORTCODE.Parent] +params: + functions_and_methods: + returnType: hugolib.ShortcodeWithPage + signatures: [SHORTCODE.Parent] --- This is useful for inheritance of common shortcode arguments from the root. In this contrived example, the "greeting" shortcode is the parent, and the "now" shortcode is child. -{{< code file=content/welcome.md lang=md >}} +```text {file="content/welcome.md"} {{</* greeting dateFormat="Jan 2, 2006" */>}} Welcome. Today is {{</* now */>}}. {{</* /greeting */>}} -{{< /code >}} +``` -{{< code file=layouts/shortcodes/greeting.html >}} +```go-html-template {file="layouts/shortcodes/greeting.html"} <div class="greeting"> {{ .Inner | strings.TrimSpace | .Page.RenderString }} </div> -{{< /code >}} +``` -{{< code file=layouts/shortcodes/now.html >}} +```go-html-template {file="layouts/shortcodes/now.html"} {{- $dateFormat := "January 2, 2006 15:04:05" }} {{- with .Params }} @@ -41,7 +41,7 @@ Welcome. Today is {{</* now */>}}. {{- end }} {{- now | time.Format $dateFormat -}} -{{< /code >}} +``` The "now" shortcode formats the current time using: diff --git a/docs/content/en/methods/shortcode/Position.md b/docs/content/en/methods/shortcode/Position.md index 6f047c01b..24810e825 100644 --- a/docs/content/en/methods/shortcode/Position.md +++ b/docs/content/en/methods/shortcode/Position.md @@ -1,26 +1,24 @@ --- title: Position -description: Returns the filename and position from which the shortcode was called. +description: Returns the file name and position from which the shortcode was called. categories: [] keywords: [] -action: - related: - - methods/shortcode/Name - - functions/fmt/Errorf - returnType: text.Position - signatures: [SHORTCODE.Position] +params: + functions_and_methods: + returnType: text.Position + signatures: [SHORTCODE.Position] --- The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument: -{{< code file=layouts/shortcodes/myshortcode.html >}} +```go-html-template {file="layouts/shortcodes/myshortcode.html"} {{ $greeting := "" }} {{ with .Get "greeting" }} {{ $greeting = . }} {{ else }} {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }} {{ end }} -{{< /code >}} +``` In the absence of a "greeting" argument, Hugo will throw an error message and fail the build: @@ -28,6 +26,5 @@ In the absence of a "greeting" argument, Hugo will throw an error message and fa ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1" ``` -{{% note %}} -The position can be expensive to calculate. Limit its use to error reporting. -{{% /note %}} +> [!note] +> The position can be expensive to calculate. Limit its use to error reporting. diff --git a/docs/content/en/methods/shortcode/Ref.md b/docs/content/en/methods/shortcode/Ref.md index 305e1e7d8..3a877d568 100644 --- a/docs/content/en/methods/shortcode/Ref.md +++ b/docs/content/en/methods/shortcode/Ref.md @@ -3,27 +3,23 @@ title: Ref description: Returns the absolute URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - related: - - methods/shortcode/RelRef - - functions/urls/RelRef - - functions/urls/Ref - returnType: string - signatures: [SHORTCODE.Ref OPTIONS] +params: + functions_and_methods: + returnType: string + signatures: [SHORTCODE.Ref OPTIONS] --- -The map of option contains: +## Usage -path -: (`string`) The path to the page, relative to the `content` directory. Required. +The `Ref` method accepts a single argument: an options map. -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +## Options -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. +{{% include "_common/ref-and-relref-options.md" %}} -The examples below show the rendered output when visiting a page on the English language version of the site: +## Examples + +The following examples show the rendered output for a page on the English version of the site: ```go-html-template {{ $opts := dict "path" "/books/book-1" }} @@ -36,9 +32,6 @@ The examples below show the rendered output when visiting a page on the English {{ .Ref $opts }} → https://example.org/de/books/book-1/index.json ``` -By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/docs/content/en/methods/shortcode/RelRef.md b/docs/content/en/methods/shortcode/RelRef.md index 4e367312b..273705a95 100644 --- a/docs/content/en/methods/shortcode/RelRef.md +++ b/docs/content/en/methods/shortcode/RelRef.md @@ -3,27 +3,23 @@ title: RelRef description: Returns the relative URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - related: - - methods/shortcode/Ref - - functions/urls/Ref - - functions/urls/RelRef - returnType: string - signatures: [SHORTCODE.RelRef OPTIONS] +params: + functions_and_methods: + returnType: string + signatures: [SHORTCODE.RelRef OPTIONS] --- -The map of option contains: +## Usage -path -: (`string`) The path to the page, relative to the `content` directory. Required. +The `RelRef` method accepts a single argument: an options map. -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +## Options -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. +{{% include "_common/ref-and-relref-options.md" %}} -The examples below show the rendered output when visiting a page on the English language version of the site: +## Examples + +The following examples show the rendered output for a page on the English version of the site: ```go-html-template {{ $opts := dict "path" "/books/book-1" }} @@ -36,9 +32,6 @@ The examples below show the rendered output when visiting a page on the English {{ .RelRef $opts }} → /de/books/book-1/index.json ``` -By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/docs/content/en/methods/shortcode/Scratch.md b/docs/content/en/methods/shortcode/Scratch.md index 6dd882e24..6efec2097 100644 --- a/docs/content/en/methods/shortcode/Scratch.md +++ b/docs/content/en/methods/shortcode/Scratch.md @@ -3,14 +3,14 @@ title: Scratch description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode. categories: [] keywords: [] -action: - related: [] - returnType: maps.Scratch - signatures: [SHORTCODE.Scratch] +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [SHORTCODE.Scratch] expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft) --- -{{% deprecated-in 0.139.0 %}} +{{< deprecated-in 0.139.0 >}} Use the [`SHORTCODE.Store`] method instead. This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `SHORTCODE.Store` as soon as possible. @@ -18,4 +18,4 @@ This is a soft deprecation. This method will be removed in a future release, but Beginning with v0.139.0 the `SHORTCODE.Scratch` method is aliased to `SHORTCODE.Store`. [`SHORTCODE.Store`]: /methods/shortcode/store/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/docs/content/en/methods/shortcode/Site.md b/docs/content/en/methods/shortcode/Site.md index af2a755ee..4c5a9a9b5 100644 --- a/docs/content/en/methods/shortcode/Site.md +++ b/docs/content/en/methods/shortcode/Site.md @@ -3,11 +3,10 @@ title: Site description: Returns the Site object. categories: [] keywords: [] -action: - related: - - methods/page/Sites - returnType: page.siteWrapper - signatures: [SHORTCODE.Site] +params: + functions_and_methods: + returnType: page.siteWrapper + signatures: [SHORTCODE.Site] --- See [Site methods]. diff --git a/docs/content/en/methods/shortcode/Store.md b/docs/content/en/methods/shortcode/Store.md index 8d9a8596b..76cb9237d 100644 --- a/docs/content/en/methods/shortcode/Store.md +++ b/docs/content/en/methods/shortcode/Store.md @@ -3,28 +3,22 @@ title: Store description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode. categories: [] keywords: [] -action: - related: - - methods/page/Store - - methods/site/Store - - functions/hugo/Store - - functions/collections/NewScratch - returnType: maps.Scratch - signatures: [SHORTCODE.Store] -toc: true +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [SHORTCODE.Store] --- {{< new-in 0.139.0 />}} Use the `Store` method to create a [scratch pad](g) to store and manipulate data, scoped to the current shortcode. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below. -{{% note %}} -With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete. - -[assign values to template variables]: https://go.dev/doc/go1.11#text/template -[`newScratch`]: /functions/collections/newScratch/ -{{% /note %}} +> [!note] +> With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete. {{% include "_common/store-methods.md" %}} {{% include "_common/scratch-pad-scope.md" %}} + +[`newScratch`]: /functions/collections/newScratch/ +[assign values to template variables]: https://go.dev/doc/go1.11#texttemplatepkgtexttemplate diff --git a/docs/content/en/methods/shortcode/_index.md b/docs/content/en/methods/shortcode/_index.md index 1c99adba7..0064f42aa 100644 --- a/docs/content/en/methods/shortcode/_index.md +++ b/docs/content/en/methods/shortcode/_index.md @@ -4,10 +4,5 @@ linkTitle: Shortcode description: Use these methods in your shortcode templates. categories: [] keywords: [] -menu: - docs: - parent: methods aliases: [/variables/shortcodes] --- - -Use these methods in your shortcode templates. diff --git a/docs/content/en/methods/site/AllPages.md b/docs/content/en/methods/site/AllPages.md index 7c6c21b57..90cceee8c 100644 --- a/docs/content/en/methods/site/AllPages.md +++ b/docs/content/en/methods/site/AllPages.md @@ -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. diff --git a/docs/content/en/methods/site/BaseURL.md b/docs/content/en/methods/site/BaseURL.md index ea965a568..3644443cb 100644 --- a/docs/content/en/methods/site/BaseURL.md +++ b/docs/content/en/methods/site/BaseURL.md @@ -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/ diff --git a/docs/content/en/methods/site/BuildDrafts.md b/docs/content/en/methods/site/BuildDrafts.md index 0d85c78fd..4beceeb6b 100644 --- a/docs/content/en/methods/site/BuildDrafts.md +++ b/docs/content/en/methods/site/BuildDrafts.md @@ -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: diff --git a/docs/content/en/methods/site/Config.md b/docs/content/en/methods/site/Config.md index 0ff4cddec..d1b4d1f42 100644 --- a/docs/content/en/methods/site/Config.md +++ b/docs/content/en/methods/site/Config.md @@ -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: diff --git a/docs/content/en/methods/site/Copyright.md b/docs/content/en/methods/site/Copyright.md index e2ae7d2a5..dd8bdb4a3 100644 --- a/docs/content/en/methods/site/Copyright.md +++ b/docs/content/en/methods/site/Copyright.md @@ -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: diff --git a/docs/content/en/methods/site/Data.md b/docs/content/en/methods/site/Data.md index 1021aad7d..296851874 100644 --- a/docs/content/en/methods/site/Data.md +++ b/docs/content/en/methods/site/Data.md @@ -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 diff --git a/docs/content/en/methods/site/DisqusShortname.md b/docs/content/en/methods/site/DisqusShortname.md index f6fedf4e9..de679fd7e 100644 --- a/docs/content/en/methods/site/DisqusShortname.md +++ b/docs/content/en/methods/site/DisqusShortname.md @@ -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 >}} diff --git a/docs/content/en/methods/site/GetPage.md b/docs/content/en/methods/site/GetPage.md index a439a578b..2a3bd7d59 100644 --- a/docs/content/en/methods/site/GetPage.md +++ b/docs/content/en/methods/site/GetPage.md @@ -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 [details]. diff --git a/docs/content/en/methods/site/GoogleAnalytics.md b/docs/content/en/methods/site/GoogleAnalytics.md index f87e1787e..e4d28bcce 100644 --- a/docs/content/en/methods/site/GoogleAnalytics.md +++ b/docs/content/en/methods/site/GoogleAnalytics.md @@ -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 >}} diff --git a/docs/content/en/methods/site/Home.md b/docs/content/en/methods/site/Home.md index a25491a8e..19ab61747 100644 --- a/docs/content/en/methods/site/Home.md +++ b/docs/content/en/methods/site/Home.md @@ -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. diff --git a/docs/content/en/methods/site/IsDevelopment.md b/docs/content/en/methods/site/IsDevelopment.md index 51783efb9..cddd18818 100644 --- a/docs/content/en/methods/site/IsDevelopment.md +++ b/docs/content/en/methods/site/IsDevelopment.md @@ -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 >}} diff --git a/docs/content/en/methods/site/IsMultiLingual.md b/docs/content/en/methods/site/IsMultiLingual.md index 10968f14d..3f9723f1c 100644 --- a/docs/content/en/methods/site/IsMultiLingual.md +++ b/docs/content/en/methods/site/IsMultiLingual.md @@ -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 >}} diff --git a/docs/content/en/methods/site/IsServer.md b/docs/content/en/methods/site/IsServer.md index 8fb5b7bf6..8b09c8492 100644 --- a/docs/content/en/methods/site/IsServer.md +++ b/docs/content/en/methods/site/IsServer.md @@ -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 >}} diff --git a/docs/content/en/methods/site/Language.md b/docs/content/en/methods/site/Language.md index 2400c225a..31f15b8cb 100644 --- a/docs/content/en/methods/site/Language.md +++ b/docs/content/en/methods/site/Language.md @@ -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. diff --git a/docs/content/en/methods/site/LanguagePrefix.md b/docs/content/en/methods/site/LanguagePrefix.md index 88808eda0..81a5e8607 100644 --- a/docs/content/en/methods/site/LanguagePrefix.md +++ b/docs/content/en/methods/site/LanguagePrefix.md @@ -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: diff --git a/docs/content/en/methods/site/Languages.md b/docs/content/en/methods/site/Languages.md index cfa1ade6b..056d6193a 100644 --- a/docs/content/en/methods/site/Languages.md +++ b/docs/content/en/methods/site/Languages.md @@ -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. diff --git a/docs/content/en/methods/site/LastChange.md b/docs/content/en/methods/site/LastChange.md index f6017df04..e02937bf1 100644 --- a/docs/content/en/methods/site/LastChange.md +++ b/docs/content/en/methods/site/LastChange.md @@ -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 >}} diff --git a/docs/content/en/methods/site/Lastmod.md b/docs/content/en/methods/site/Lastmod.md index f1663db49..38f6da2fa 100644 --- a/docs/content/en/methods/site/Lastmod.md +++ b/docs/content/en/methods/site/Lastmod.md @@ -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 />}} diff --git a/docs/content/en/methods/site/MainSections.md b/docs/content/en/methods/site/MainSections.md index aa6e84bda..bee4f2d57 100644 --- a/docs/content/en/methods/site/MainSections.md +++ b/docs/content/en/methods/site/MainSections.md @@ -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: diff --git a/docs/content/en/methods/site/Menus.md b/docs/content/en/methods/site/Menus.md index e51980c2e..398a9b022 100644 --- a/docs/content/en/methods/site/Menus.md +++ b/docs/content/en/methods/site/Menus.md @@ -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/ diff --git a/docs/content/en/methods/site/Pages.md b/docs/content/en/methods/site/Pages.md index bb684a96d..a6ba5e029 100644 --- a/docs/content/en/methods/site/Pages.md +++ b/docs/content/en/methods/site/Pages.md @@ -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. diff --git a/docs/content/en/methods/site/Param.md b/docs/content/en/methods/site/Param.md index 0c2f621c8..929e30e98 100644 --- a/docs/content/en/methods/site/Param.md +++ b/docs/content/en/methods/site/Param.md @@ -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. diff --git a/docs/content/en/methods/site/Params.md b/docs/content/en/methods/site/Params.md index 418118ee3..8467be41d 100644 --- a/docs/content/en/methods/site/Params.md +++ b/docs/content/en/methods/site/Params.md @@ -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: diff --git a/docs/content/en/methods/site/RegularPages.md b/docs/content/en/methods/site/RegularPages.md index 65bafef6c..69a460529 100644 --- a/docs/content/en/methods/site/RegularPages.md +++ b/docs/content/en/methods/site/RegularPages.md @@ -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: diff --git a/docs/content/en/methods/site/Sections.md b/docs/content/en/methods/site/Sections.md index a397c5926..0ddaf0626 100644 --- a/docs/content/en/methods/site/Sections.md +++ b/docs/content/en/methods/site/Sections.md @@ -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 diff --git a/docs/content/en/methods/site/Sites.md b/docs/content/en/methods/site/Sites.md index ac287d3b4..cca71a40a 100644 --- a/docs/content/en/methods/site/Sites.md +++ b/docs/content/en/methods/site/Sites.md @@ -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: diff --git a/docs/content/en/methods/site/Store.md b/docs/content/en/methods/site/Store.md index dcc3a0bed..7dcf7d095 100644 --- a/docs/content/en/methods/site/Store.md +++ b/docs/content/en/methods/site/Store.md @@ -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. diff --git a/docs/content/en/methods/site/Taxonomies.md b/docs/content/en/methods/site/Taxonomies.md index ee98d2ac5..92dc41a9b 100644 --- a/docs/content/en/methods/site/Taxonomies.md +++ b/docs/content/en/methods/site/Taxonomies.md @@ -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 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/ diff --git a/docs/content/en/methods/site/Title.md b/docs/content/en/methods/site/Title.md index a357286c1..935edda0c 100644 --- a/docs/content/en/methods/site/Title.md +++ b/docs/content/en/methods/site/Title.md @@ -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: diff --git a/docs/content/en/methods/site/_index.md b/docs/content/en/methods/site/_index.md index bf322ee07..f395a3693 100644 --- a/docs/content/en/methods/site/_index.md +++ b/docs/content/en/methods/site/_index.md @@ -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. diff --git a/docs/content/en/methods/taxonomy/Alphabetical.md b/docs/content/en/methods/taxonomy/Alphabetical.md index 72cd1c355..af4af596c 100644 --- a/docs/content/en/methods/taxonomy/Alphabetical.md +++ b/docs/content/en/methods/taxonomy/Alphabetical.md @@ -3,23 +3,21 @@ title: Alphabetical description: Returns an ordered taxonomy, sorted alphabetically by term. categories: [] keywords: [] -action: - related: - - methods/taxonomy/ByCount - returnType: page.OrderedTaxonomy - signatures: [TAXONOMY.Alphabetical] -toc: true +params: + functions_and_methods: + returnType: page.OrderedTaxonomy + signatures: [TAXONOMY.Alphabetical] --- The `Alphabetical` method on a `Taxonomy` object returns an [ordered taxonomy](g), sorted alphabetically by [term](g). While a `Taxonomy` object is a [map](g), an ordered taxonomy is a [slice](g), where each element is an object that contains the term and a slice of its [weighted pages](g). -{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} +{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}} ## Get the ordered taxonomy -Now that we have captured the “genres” Taxonomy object, let’s get the ordered taxonomy sorted alphabetically by term: +Now that we have captured the “genres” Taxonomy object, let's get the ordered taxonomy sorted alphabetically by term: ```go-html-template {{ $taxonomyObject.Alphabetical }} @@ -37,7 +35,7 @@ To inspect the data structure: <pre>{{ debug.Dump $taxonomyObject.Alphabetical }}</pre> ``` -{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} +{{% include "/_common/methods/taxonomy/ordered-taxonomy-element-methods.md" %}} ## Example diff --git a/docs/content/en/methods/taxonomy/ByCount.md b/docs/content/en/methods/taxonomy/ByCount.md index 930f8953b..fbf9bb4a1 100644 --- a/docs/content/en/methods/taxonomy/ByCount.md +++ b/docs/content/en/methods/taxonomy/ByCount.md @@ -3,23 +3,21 @@ title: ByCount description: Returns an ordered taxonomy, sorted by the number of pages associated with each term. categories: [] keywords: [] -action: - related: - - methods/taxonomy/Alphabetical - returnType: page.OrderedTaxonomy - signatures: [TAXONOMY.ByCount] -toc: true +params: + functions_and_methods: + returnType: page.OrderedTaxonomy + signatures: [TAXONOMY.ByCount] --- The `ByCount` method on a `Taxonomy` object returns an [ordered taxonomy](g), sorted by the number of pages associated with each [term](g). While a `Taxonomy` object is a [map](g), an ordered taxonomy is a [slice](g), where each element is an object that contains the term and a slice of its [weighted pages](g). -{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} +{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}} ## Get the ordered taxonomy -Now that we have captured the “genres” Taxonomy object, let’s get the ordered taxonomy sorted by the number of pages associated with each term: +Now that we have captured the “genres” Taxonomy object, let's get the ordered taxonomy sorted by the number of pages associated with each term: ```go-html-template {{ $taxonomyObject.ByCount }} @@ -37,7 +35,7 @@ To inspect the data structure: <pre>{{ debug.Dump $taxonomyObject.ByCount }}</pre> ``` -{{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} +{{% include "/_common/methods/taxonomy/ordered-taxonomy-element-methods.md" %}} ## Example diff --git a/docs/content/en/methods/taxonomy/Count.md b/docs/content/en/methods/taxonomy/Count.md index 4b756f254..76af8ee04 100644 --- a/docs/content/en/methods/taxonomy/Count.md +++ b/docs/content/en/methods/taxonomy/Count.md @@ -3,16 +3,15 @@ title: Count description: Returns the number of number of weighted pages to which the given term has been assigned. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [TAXONOMY.Count TERM] -toc: true +params: + functions_and_methods: + returnType: int + signatures: [TAXONOMY.Count TERM] --- The `Count` method on a `Taxonomy` object returns the number of number of [weighted pages](g) to which the given [term](g) has been assigned. -{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} +{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}} ## Count the weighted pages diff --git a/docs/content/en/methods/taxonomy/Get.md b/docs/content/en/methods/taxonomy/Get.md index 107912493..03c184868 100644 --- a/docs/content/en/methods/taxonomy/Get.md +++ b/docs/content/en/methods/taxonomy/Get.md @@ -3,16 +3,15 @@ title: Get description: Returns a slice of weighted pages to which the given term has been assigned. categories: [] keywords: [] -action: - related: [] - returnType: page.WeightedPages - signatures: [TAXONOMY.Get TERM] -toc: true +params: + functions_and_methods: + returnType: page.WeightedPages + signatures: [TAXONOMY.Get TERM] --- The `Get` method on a `Taxonomy` object returns a slice of [weighted pages](g) to which the given [term](g) has been assigned. -{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}} +{{% include "/_common/methods/taxonomy/get-a-taxonomy-object.md" %}} ## Get the weighted pages diff --git a/docs/content/en/methods/taxonomy/Page.md b/docs/content/en/methods/taxonomy/Page.md index 039719b93..b0b5d3aff 100644 --- a/docs/content/en/methods/taxonomy/Page.md +++ b/docs/content/en/methods/taxonomy/Page.md @@ -3,10 +3,10 @@ title: Page description: Returns the taxonomy page or nil if the taxonomy has no terms. categories: [] keywords: [] -action: - related: [] - returnType: page.Page - signatures: [TAXONOMY.Page] +params: + functions_and_methods: + returnType: page.Page + signatures: [TAXONOMY.Page] --- {{< new-in 0.125.0 />}} diff --git a/docs/content/en/methods/taxonomy/_common/_index.md b/docs/content/en/methods/taxonomy/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/methods/taxonomy/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md b/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md deleted file mode 100644 index 9ef2585e1..000000000 --- a/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Before we can use a `Taxonomy` method, we need to capture a `Taxonomy` object. - -## Capture a Taxonomy object - -Consider this site configuration: - -{{< code-toggle file=hugo >}} -[taxonomies] -genre = 'genres' -author = 'authors' -{{< /code-toggle >}} - -And this content structure: - -```text -content/ -├── books/ -│ ├── and-then-there-were-none.md --> genres: suspense -│ ├── death-on-the-nile.md --> genres: suspense -│ └── jamaica-inn.md --> genres: suspense, romance -│ └── pride-and-prejudice.md --> genres: romance -└── _index.md -``` - -To capture the "genres" `Taxonomy` object from within any template, use the [`Taxonomies`] method on a `Site` object. - -```go-html-template -{{ $taxonomyObject := .Site.Taxonomies.genres }} -``` - -To capture the "genres" `Taxonomy` object when rendering its page with a taxonomy template, use the [`Terms`] method on the page's [`Data`] object: - -{{< code file=layouts/_default/taxonomy.html >}} -{{ $taxonomyObject := .Data.Terms }} -{{< /code >}} - -To inspect the data structure: - -```go-html-template -<pre>{{ debug.Dump $taxonomyObject }}</pre> -``` - -Although the [`Alphabetical`] and [`ByCount`] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object: - -```go-html-template -{{ range $term, $weightedPages := $taxonomyObject }} - <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2> - <ul> - {{ range $weightedPages }} - <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> - {{ end }} - </ul> -{{ end }} -``` - -In the example above, the first anchor element is a link to the term page. - -[`Alphabetical`]: /methods/taxonomy/alphabetical/ -[`ByCount`]: /methods/taxonomy/bycount/ - -[`data`]: /methods/page/data/ -[`terms`]: /methods/page/data/#in-a-taxonomy-template -[`taxonomies`]: /methods/site/taxonomies/ diff --git a/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md b/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md deleted file mode 100644 index ec5f8e406..000000000 --- a/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -An ordered taxonomy is a slice, where each element is an object that contains the term and a slice of its weighted pages. - -Each element of the slice provides these methods: - -Count -: (`int`) Returns the number of pages to which the term is assigned. - -Page -: (`page.Page`) Returns the term's `Page` object, useful for linking to the term page. - -Pages -: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight](g). To sort or group, use any of the [methods] available to the `Pages` object. For example, sort by the last modification date. - -Term -: (`string`) Returns the term name. - -WeightedPages -: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by taxonomic weight. The `Pages` method above is more flexible, allowing you to sort and group. - -[methods]: /methods/pages/ diff --git a/docs/content/en/methods/taxonomy/_index.md b/docs/content/en/methods/taxonomy/_index.md index 18c7f12c9..13acdb10c 100644 --- a/docs/content/en/methods/taxonomy/_index.md +++ b/docs/content/en/methods/taxonomy/_index.md @@ -3,11 +3,5 @@ title: Taxonomy methods linkTitle: Taxonomy description: Use these methods with Taxonomy objects. keywords: [] -menu: - docs: - identifier: - parent: methods aliases: [/variables/taxonomy/] --- - -Use these methods with Taxonomy objects. diff --git a/docs/content/en/methods/time/Add.md b/docs/content/en/methods/time/Add.md index 8fd755244..e518a1633 100644 --- a/docs/content/en/methods/time/Add.md +++ b/docs/content/en/methods/time/Add.md @@ -3,13 +3,10 @@ title: Add description: Returns the given time plus the given duration. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - - functions/time/Duration - - functions/time/ParseDuration - returnType: time.Time - signatures: [TIME.Add DURATION] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.Add DURATION] --- ```go-html-template diff --git a/docs/content/en/methods/time/AddDate.md b/docs/content/en/methods/time/AddDate.md index 8537d6e25..ffc93c712 100644 --- a/docs/content/en/methods/time/AddDate.md +++ b/docs/content/en/methods/time/AddDate.md @@ -3,11 +3,10 @@ title: AddDate description: Returns the time corresponding to adding the given number of years, months, and days to the given time.Time value. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: time.Time - signatures: [TIME.AddDate YEARS MONTHS DAYS] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.AddDate YEARS MONTHS DAYS] aliases: [/functions/adddate] --- @@ -21,11 +20,10 @@ aliases: [/functions/adddate] {{ $d.AddDate -1 -1 -1 | time.Format "2006-01-02" }} → 2020-11-30 ``` -{{% note %}} -When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year. - -See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team. -{{% /note %}} +> [!note] +> When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year. +> +> See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team. ```go-html-template {{ $d := "2023-01-31" | time.AsTime }} diff --git a/docs/content/en/methods/time/After.md b/docs/content/en/methods/time/After.md index 64c6cfe67..1c8d41f64 100644 --- a/docs/content/en/methods/time/After.md +++ b/docs/content/en/methods/time/After.md @@ -3,13 +3,10 @@ title: After description: Reports whether TIME1 is after TIME2. categories: [] keywords: [] -action: - related: - - methods/time/Before - - methods/time/Equal - - functions/time/AsTime - returnType: bool - signatures: [TIME1.After TIME2] +params: + functions_and_methods: + returnType: bool + signatures: [TIME1.After TIME2] --- ```go-html-template diff --git a/docs/content/en/methods/time/Before.md b/docs/content/en/methods/time/Before.md index c3d582860..f6dc3a8e7 100644 --- a/docs/content/en/methods/time/Before.md +++ b/docs/content/en/methods/time/Before.md @@ -3,13 +3,10 @@ title: Before description: Reports whether TIME1 is before TIME2. categories: [] keywords: [] -action: - related: - - methods/time/After - - methods/time/Equal - - functions/time/AsTime - returnType: bool - signatures: [TIME1.Before TIME2] +params: + functions_and_methods: + returnType: bool + signatures: [TIME1.Before TIME2] --- ```go-html-template diff --git a/docs/content/en/methods/time/Day.md b/docs/content/en/methods/time/Day.md index 1173b8489..e9e67873c 100644 --- a/docs/content/en/methods/time/Day.md +++ b/docs/content/en/methods/time/Day.md @@ -3,16 +3,10 @@ title: Day description: Returns the day of the month of the given time.Time value. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Month - - methods/time/Hour - - methods/time/Minute - - methods/time/Second - - functions/time/AsTime - returnType: int - signatures: [TIME.Day] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Day] --- ```go-html-template diff --git a/docs/content/en/methods/time/Equal.md b/docs/content/en/methods/time/Equal.md index 4d45a3ada..6db10423c 100644 --- a/docs/content/en/methods/time/Equal.md +++ b/docs/content/en/methods/time/Equal.md @@ -3,13 +3,10 @@ title: Equal description: Reports whether TIME1 is equal to TIME2. categories: [] keywords: [] -action: - related: - - methods/time/After - - methods/time/Before - - functions/time/AsTime - returnType: bool - signatures: [TIME1.Equal TIME2] +params: + functions_and_methods: + returnType: bool + signatures: [TIME1.Equal TIME2] --- ```go-html-template diff --git a/docs/content/en/methods/time/Format.md b/docs/content/en/methods/time/Format.md index 9a718b53b..8a484b74e 100644 --- a/docs/content/en/methods/time/Format.md +++ b/docs/content/en/methods/time/Format.md @@ -3,15 +3,10 @@ title: Format description: Returns a textual representation of the time.Time value formatted according to the layout string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/time/AsTime - - methods/time/UTC - - methods/time/Local - returnType: string - signatures: [TIME.Format LAYOUT] -toc: true +params: + functions_and_methods: + returnType: string + signatures: [TIME.Format LAYOUT] aliases: [/methods/time/format] --- @@ -23,11 +18,8 @@ aliases: [/methods/time/format] {{ $t.Format $format }} → 27 Jan 2023 ``` -{{% note %}} -To [localize](g) the return value, use the [`time.Format`] function instead. - -[`time.Format`]: /functions/time/format/ -{{% /note %}} +> [!note] +> To [localize](g) the return value, use the [`time.Format`] function instead. Use the `Format` method with any `time.Time` value, including the four predefined front matter dates: @@ -40,15 +32,12 @@ Use the `Format` method with any `time.Time` value, including the four predefine {{ .Lastmod.Format $format }} ``` -{{% note %}} -Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset. - -[`time.Format`]: /functions/time/format/ -{{% /note %}} +> [!note] +> Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset. ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} ## Examples @@ -95,3 +84,5 @@ Use the [`humanize`](/functions/inflect/humanize) function to render the day of {{ humanize $t.Day }} of {{ $t.Format "January 2006" }} → 27th of January 2023 ``` + +[`time.Format`]: /functions/time/format/ diff --git a/docs/content/en/methods/time/Hour.md b/docs/content/en/methods/time/Hour.md index 58ed00260..28ecf62ac 100644 --- a/docs/content/en/methods/time/Hour.md +++ b/docs/content/en/methods/time/Hour.md @@ -3,16 +3,10 @@ title: Hour description: Returns the hour within the day of the given time.Time value, in the range [0, 23]. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Month - - methods/time/Day - - methods/time/Minute - - methods/time/Second - - functions/time/AsTime - returnType: int - signatures: [TIME.Hour] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Hour] --- ```go-html-template diff --git a/docs/content/en/methods/time/IsDST.md b/docs/content/en/methods/time/IsDST.md index df2b84cae..28177b105 100644 --- a/docs/content/en/methods/time/IsDST.md +++ b/docs/content/en/methods/time/IsDST.md @@ -3,11 +3,10 @@ title: IsDST description: Reports whether the given time.Time value is in Daylight Savings Time. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: bool - signatures: [TIME.IsDST] +params: + functions_and_methods: + returnType: bool + signatures: [TIME.IsDST] --- ```go-html-template diff --git a/docs/content/en/methods/time/IsZero.md b/docs/content/en/methods/time/IsZero.md index 2026f3b2e..400172794 100644 --- a/docs/content/en/methods/time/IsZero.md +++ b/docs/content/en/methods/time/IsZero.md @@ -3,11 +3,10 @@ title: IsZero description: Reports whether the given time.Time value represents the zero time instant, January 1, year 1, 00:00:00 UTC. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: bool - signatures: [TIME.IsZero] +params: + functions_and_methods: + returnType: bool + signatures: [TIME.IsZero] --- ````go-html-template diff --git a/docs/content/en/methods/time/Local.md b/docs/content/en/methods/time/Local.md index bd40e3a44..74fe889e0 100644 --- a/docs/content/en/methods/time/Local.md +++ b/docs/content/en/methods/time/Local.md @@ -3,12 +3,10 @@ title: Local description: Returns the given time.Time value with the location set to local time. categories: [] keywords: [] -action: - related: - - methods/time/UTC - - functions/time/AsTime - returnType: time.Time - signatures: [TIME.Local] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.Local] --- ```go-html-template diff --git a/docs/content/en/methods/time/Minute.md b/docs/content/en/methods/time/Minute.md index d482fab5d..b53db6d83 100644 --- a/docs/content/en/methods/time/Minute.md +++ b/docs/content/en/methods/time/Minute.md @@ -3,16 +3,10 @@ title: Minute description: Returns the minute offset within the hour of the given time.Time value, in the range [0, 59]. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Month - - methods/time/Day - - methods/time/Hour - - methods/time/Second - - functions/time/AsTime - returnType: int - signatures: [TIME.Minute] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Minute] --- ```go-html-template diff --git a/docs/content/en/methods/time/Month.md b/docs/content/en/methods/time/Month.md index 0a01d1a70..b0ccea9c3 100644 --- a/docs/content/en/methods/time/Month.md +++ b/docs/content/en/methods/time/Month.md @@ -3,16 +3,10 @@ title: Month description: Returns the month of the year of the given time.Time value. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Day - - methods/time/Hour - - methods/time/Minute - - methods/time/Second - - functions/time/AsTime - returnType: time.Month - signatures: [TIME.Month] +params: + functions_and_methods: + returnType: time.Month + signatures: [TIME.Month] --- To convert the `time.Month` value to a string: diff --git a/docs/content/en/methods/time/Nanosecond.md b/docs/content/en/methods/time/Nanosecond.md index 606143139..d895f9622 100644 --- a/docs/content/en/methods/time/Nanosecond.md +++ b/docs/content/en/methods/time/Nanosecond.md @@ -3,11 +3,10 @@ title: Nanosecond description: Returns the nanosecond offset within the second of the given time.Time value, in the range [0, 999999999]. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: int - signatures: [TIME.Nanosecond] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Nanosecond] --- ```go-html-template diff --git a/docs/content/en/methods/time/Round.md b/docs/content/en/methods/time/Round.md index 16bd2009f..816d41b44 100644 --- a/docs/content/en/methods/time/Round.md +++ b/docs/content/en/methods/time/Round.md @@ -3,13 +3,10 @@ title: Round description: Returns the result of rounding TIME to the nearest multiple of DURATION since January 1, 0001, 00:00:00 UTC. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - - functions/time/ParseDuration - - methods/time/Truncate - returnType: time.Time - signatures: [TIME.Round DURATION] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.Round DURATION] --- The rounding behavior for halfway values is to round up. diff --git a/docs/content/en/methods/time/Second.md b/docs/content/en/methods/time/Second.md index e326c64bc..3af086fd3 100644 --- a/docs/content/en/methods/time/Second.md +++ b/docs/content/en/methods/time/Second.md @@ -3,16 +3,10 @@ title: Second description: Returns the second offset within the minute of the given time.Time value, in the range [0, 59]. categories: [] keywords: [] -action: - related: - - methods/time/Year - - methods/time/Month - - methods/time/Day - - methods/time/Hour - - methods/time/Minute - - functions/time/AsTime - returnType: int - signatures: [TIME.Second] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Second] --- ```go-html-template diff --git a/docs/content/en/methods/time/Sub.md b/docs/content/en/methods/time/Sub.md index 9678365eb..d48bf3467 100644 --- a/docs/content/en/methods/time/Sub.md +++ b/docs/content/en/methods/time/Sub.md @@ -3,11 +3,10 @@ title: Sub description: Returns the duration computed by subtracting TIME2 from TIME1. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: time.Duration - signatures: [TIME1.Sub TIME2] +params: + functions_and_methods: + returnType: time.Duration + signatures: [TIME1.Sub TIME2] --- ```go-html-template diff --git a/docs/content/en/methods/time/Truncate.md b/docs/content/en/methods/time/Truncate.md index 64751f2c1..b797afec0 100644 --- a/docs/content/en/methods/time/Truncate.md +++ b/docs/content/en/methods/time/Truncate.md @@ -3,13 +3,10 @@ title: Truncate description: Returns the result of rounding TIME down to a multiple of DURATION since January 1, 0001, 00:00:00 UTC. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - - functions/time/ParseDuration - - methods/time/Round - returnType: time.Time - signatures: [TIME.Truncate DURATION] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.Truncate DURATION] --- The `Truncate` method operates on TIME as an absolute duration since the [zero time](g); it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Truncate` may return a time with a non-zero minute, depending on the time zone. diff --git a/docs/content/en/methods/time/UTC.md b/docs/content/en/methods/time/UTC.md index 6fd7b526d..e131a003e 100644 --- a/docs/content/en/methods/time/UTC.md +++ b/docs/content/en/methods/time/UTC.md @@ -3,12 +3,10 @@ title: UTC description: Returns the given time.Time value with the location set to UTC. categories: [] keywords: [] -action: - related: - - methods/time/Local - - functions/time/AsTime - returnType: time.Time - signatures: [TIME.UTC] +params: + functions_and_methods: + returnType: time.Time + signatures: [TIME.UTC] --- ```go-html-template diff --git a/docs/content/en/methods/time/Unix.md b/docs/content/en/methods/time/Unix.md index fcfc661fe..73deb524e 100644 --- a/docs/content/en/methods/time/Unix.md +++ b/docs/content/en/methods/time/Unix.md @@ -1,15 +1,11 @@ --- title: Unix -description: Returns the given time.Time value expressed as the number of seconds elapsed since January 1, 1970 UTC. +description: Returns the given time.Time value expressed as the number of seconds elapsed since January 1, 1970 UTC. categories: [] -action: - related: - - methods/time/UnixMilli - - methods/time/UnixMicro - - methods/time/UnixNano - - functions/time/AsTime - returnType: int64 - signatures: [TIME.Unix] +params: + functions_and_methods: + returnType: int64 + signatures: [TIME.Unix] aliases: [/functions/unix] --- diff --git a/docs/content/en/methods/time/UnixMicro.md b/docs/content/en/methods/time/UnixMicro.md index 150497cd3..fadb0916c 100644 --- a/docs/content/en/methods/time/UnixMicro.md +++ b/docs/content/en/methods/time/UnixMicro.md @@ -1,16 +1,12 @@ --- title: UnixMicro -description: Returns the given time.Time value expressed as the number of microseconds elapsed since January 1, 1970 UTC. +description: Returns the given time.Time value expressed as the number of microseconds elapsed since January 1, 1970 UTC. categories: [] keywords: [] -action: - related: - - methods/time/Unix - - methods/time/UnixMilli - - methods/time/UnixNano - - functions/time/AsTime - returnType: int64 - signatures: [TIME.UnixMicro] +params: + functions_and_methods: + returnType: int64 + signatures: [TIME.UnixMicro] --- See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). diff --git a/docs/content/en/methods/time/UnixMilli.md b/docs/content/en/methods/time/UnixMilli.md index e5e90ba25..9d2261d91 100644 --- a/docs/content/en/methods/time/UnixMilli.md +++ b/docs/content/en/methods/time/UnixMilli.md @@ -1,16 +1,12 @@ --- title: UnixMilli -description: Returns the given time.Time value expressed as the number of milliseconds elapsed since January 1, 1970 UTC. +description: Returns the given time.Time value expressed as the number of milliseconds elapsed since January 1, 1970 UTC. categories: [] keywords: [] -action: - related: - - methods/time/Unix - - methods/time/UnixMicro - - methods/time/UnixNano - - functions/time/AsTime - returnType: int64 - signatures: [TIME.UnixMilli] +params: + functions_and_methods: + returnType: int64 + signatures: [TIME.UnixMilli] --- See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). diff --git a/docs/content/en/methods/time/UnixNano.md b/docs/content/en/methods/time/UnixNano.md index 63db320a3..4159ddee2 100644 --- a/docs/content/en/methods/time/UnixNano.md +++ b/docs/content/en/methods/time/UnixNano.md @@ -1,16 +1,12 @@ --- title: UnixNano -description: Returns the given time.Time value expressed as the number of nanoseconds elapsed since January 1, 1970 UTC. +description: Returns the given time.Time value expressed as the number of nanoseconds elapsed since January 1, 1970 UTC. categories: [] keywords: [] -action: - related: - - methods/time/Unix - - methods/time/UnixMilli - - methods/time/UnixMicro - - functions/time/AsTime - returnType: int64 - signatures: [TIME.UnixNano] +params: + functions_and_methods: + returnType: int64 + signatures: [TIME.UnixNano] --- See [Unix epoch](https://en.wikipedia.org/wiki/Unix_time). diff --git a/docs/content/en/methods/time/Weekday.md b/docs/content/en/methods/time/Weekday.md index b2a95fe9c..da939ff87 100644 --- a/docs/content/en/methods/time/Weekday.md +++ b/docs/content/en/methods/time/Weekday.md @@ -1,13 +1,12 @@ --- title: Weekday -description: Returns the day of the week of the given time.Time value. +description: Returns the day of the week of the given time.Time value. categories: [] keywords: [] -action: - related: - - functions/time/AsTime - returnType: time.Weekday - signatures: [TIME.Weekday] +params: + functions_and_methods: + returnType: time.Weekday + signatures: [TIME.Weekday] --- To convert the `time.Weekday` value to a string: diff --git a/docs/content/en/methods/time/Year.md b/docs/content/en/methods/time/Year.md index b046896f4..3f647ea34 100644 --- a/docs/content/en/methods/time/Year.md +++ b/docs/content/en/methods/time/Year.md @@ -3,16 +3,10 @@ title: Year description: Returns the year of the given time.Time value. categories: [] keywords: [] -action: - related: - - methods/time/Month - - methods/time/Day - - methods/time/Hour - - methods/time/Minute - - methods/time/Second - - functions/time/AsTime - returnType: int - signatures: [TIME.Year] +params: + functions_and_methods: + returnType: int + signatures: [TIME.Year] --- ```go-html-template diff --git a/docs/content/en/methods/time/YearDay.md b/docs/content/en/methods/time/YearDay.md index f380cdffe..a93158b45 100644 --- a/docs/content/en/methods/time/YearDay.md +++ b/docs/content/en/methods/time/YearDay.md @@ -3,10 +3,10 @@ title: YearDay description: Returns the day of the year of the given time.Time value, in the range [1, 365] for non-leap years, and [1, 366] in leap years. categories: [] keywords: [] -action: - related: [] - returnType: int - signatures: [TIME.YearDay] +params: + functions_and_methods: + returnType: int + signatures: [TIME.YearDay] --- ```go-html-template diff --git a/docs/content/en/methods/time/_index.md b/docs/content/en/methods/time/_index.md index 81d4690e0..8114664d3 100644 --- a/docs/content/en/methods/time/_index.md +++ b/docs/content/en/methods/time/_index.md @@ -4,10 +4,4 @@ linkTitle: Time description: Use these methods with time.Time values. categories: [] keywords: [] -menu: - docs: - identifier: time-methods - parent: methods --- - -Use these methods with time.Time values. |