diff options
Diffstat (limited to 'docs/content/en/methods')
137 files changed, 1432 insertions, 334 deletions
diff --git a/docs/content/en/methods/_common/_index.md b/docs/content/en/methods/_common/_index.md index 47d5812fb..4328d4d14 100644 --- a/docs/content/en/methods/_common/_index.md +++ b/docs/content/en/methods/_common/_index.md @@ -7,7 +7,7 @@ cascade: --- <!-- -Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. +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/_common/next-prev-on-page-vs-next-prev-on-pages.md b/docs/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md index 4ae3a0f39..f65037878 100644 --- a/docs/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md +++ b/docs/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md @@ -9,10 +9,10 @@ The `Next` and `Prev` methods on a `Pages` object are more flexible than the `Ne [`PAGES.Next`] and [`PAGES.Prev`]|locally defined|✔️ [`PAGE.Next`] and [`PAGE.Prev`]|globally defined|❌ -[`PAGES.Next`]: /methods/pages/next -[`PAGES.Prev`]: /methods/pages/prev -[`PAGE.Next`]: /methods/page/next -[`PAGE.Prev`]: /methods/page/prev +[`PAGES.Next`]: /methods/pages/next/ +[`PAGES.Prev`]: /methods/pages/prev/ +[`PAGE.Next`]: /methods/page/next/ +[`PAGE.Prev`]: /methods/page/prev/ locally defined : Build the page collection every time you call `PAGES.Next` and `PAGES.Prev`. Navigation between pages is relative to the current page's position within the local collection, independent of the global collection. @@ -31,7 +31,7 @@ With a global collection, the navigation sort order is fixed, using Hugo's defau For example, with a global collection sorted by title, the navigation sort order will use Hugo's default sort order. This is probably not what you want or expect. For this reason, the `Next` and `Prev` methods on a `Pages` object are generally a better choice. -[date]: /methods/page/date -[weight]: /methods/page/weight -[linkTitle]: /methods/page/linktitle -[title]: /methods/page/title +[date]: /methods/page/date/ +[weight]: /methods/page/weight/ +[linkTitle]: /methods/page/linktitle/ +[title]: /methods/page/title/ diff --git a/docs/content/en/methods/_index.md b/docs/content/en/methods/_index.md index c12bd9d4d..bab637ddb 100644 --- a/docs/content/en/methods/_index.md +++ b/docs/content/en/methods/_index.md @@ -1,16 +1,17 @@ --- title: Methods -linkTitle: Overview +linkTitle: In this section description: A list of Hugo template methods including examples. categories: [] keywords: [] menu: docs: - identifier: methods-overview + 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/menu-entry/KeyName.md b/docs/content/en/methods/menu-entry/KeyName.md index 4b43596b0..409cb31d6 100644 --- a/docs/content/en/methods/menu-entry/KeyName.md +++ b/docs/content/en/methods/menu-entry/KeyName.md @@ -36,4 +36,4 @@ This example uses the `KeyName` method when querying the translation table on a In the example above, we need to pass the value returned by `.KeyName` through the [`lower`] function because the keys in the translation table are lowercase. -[`lower`]: functions/strings/tolower +[`lower`]: /functions/strings/tolower/ diff --git a/docs/content/en/methods/menu-entry/Menu.md b/docs/content/en/methods/menu-entry/Menu.md index 6827519bd..63f148c1a 100644 --- a/docs/content/en/methods/menu-entry/Menu.md +++ b/docs/content/en/methods/menu-entry/Menu.md @@ -19,6 +19,6 @@ action: Use this method with the [`IsMenuCurrent`] and [`HasMenuCurrent`] methods on a `Page` object to set "active" and "ancestor" classes on a rendered entry. See [this example]. -[`HasMenuCurrent`]: /methods/page/hasmenucurrent -[`IsMenuCurrent`]: /methods/page/ismenucurrent +[`HasMenuCurrent`]: /methods/page/hasmenucurrent/ +[`IsMenuCurrent`]: /methods/page/ismenucurrent/ [this example]: /templates/menu-templates/#example diff --git a/docs/content/en/methods/menu-entry/Name.md b/docs/content/en/methods/menu-entry/Name.md index d722da07c..d77c65cb5 100644 --- a/docs/content/en/methods/menu-entry/Name.md +++ b/docs/content/en/methods/menu-entry/Name.md @@ -13,8 +13,8 @@ If you define the menu entry [automatically], the `Name` method returns the page If you define the menu entry [in front matter] or [in site configuration], the `Name` method returns the `name` property, falling back to the page’s `LinkTitle`, then to its `Title`. -[`LinkTitle`]: /methods/page/linktitle -[`Title`]: /methods/page/title +[`LinkTitle`]: /methods/page/linktitle/ +[`Title`]: /methods/page/title/ [automatically]: /content-management/menus/#define-automatically [in front matter]: /content-management/menus/#define-in-front-matter [in site configuration]: /content-management/menus/#define-in-site-configuration diff --git a/docs/content/en/methods/menu-entry/Page.md b/docs/content/en/methods/menu-entry/Page.md index b75e4af55..bd8c1625e 100644 --- a/docs/content/en/methods/menu-entry/Page.md +++ b/docs/content/en/methods/menu-entry/Page.md @@ -46,8 +46,8 @@ If the entry is not associated with a page, we use its `url` and `name` properti See the [menu templates] section for more information. -[`LinkTitle`]: /methods/page/linktitle -[`RelPermalink`]: /methods/page/relpermalink +[`LinkTitle`]: /methods/page/linktitle/ +[`RelPermalink`]: /methods/page/relpermalink/ [define menu entries]: /content-management/menus/ [menu templates]: /templates/menu-templates/#page-references -[methods]: /methods/page +[methods]: /methods/page/ diff --git a/docs/content/en/methods/menu-entry/Title.md b/docs/content/en/methods/menu-entry/Title.md index c1eec2cc0..4082e4e93 100644 --- a/docs/content/en/methods/menu-entry/Title.md +++ b/docs/content/en/methods/menu-entry/Title.md @@ -11,10 +11,10 @@ action: If you define the menu entry [automatically], the `Title` 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 `title` property, falling back to the page’s `LinkTitle`, then to its `Title`. +If you define the menu entry [in front matter] or [in site configuration], the `Title` method returns the `title` property, falling back to the page’s `LinkTitle`, then to its `Title`. -[`LinkTitle`]: /methods/page/linktitle -[`Title`]: /methods/page/title +[`LinkTitle`]: /methods/page/linktitle/ +[`Title`]: /methods/page/title/ [automatically]: /content-management/menus/#define-automatically [in front matter]: /content-management/menus/#define-in-front-matter [in site configuration]: /content-management/menus/#define-in-site-configuration diff --git a/docs/content/en/methods/menu-entry/URL.md b/docs/content/en/methods/menu-entry/URL.md index c2b314b58..bf3ec044a 100644 --- a/docs/content/en/methods/menu-entry/URL.md +++ b/docs/content/en/methods/menu-entry/URL.md @@ -20,4 +20,4 @@ For menu entries associated with a page, the `URL` method returns the page's [`R </ul> ``` -[`RelPermalink`]: /methods/page/relpermalink +[`RelPermalink`]: /methods/page/relpermalink/ diff --git a/docs/content/en/methods/menu-entry/Weight.md b/docs/content/en/methods/menu-entry/Weight.md index 7b0c24ae8..eab935736 100644 --- a/docs/content/en/methods/menu-entry/Weight.md +++ b/docs/content/en/methods/menu-entry/Weight.md @@ -13,7 +13,7 @@ If you define the menu entry [automatically], the `Weight` method returns the pa 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 +[`Weight`]: /methods/page/weight/ [automatically]: /content-management/menus/#define-automatically [in front matter]: /content-management/menus/#define-in-front-matter [in site configuration]: /content-management/menus/#define-in-site-configuration diff --git a/docs/content/en/methods/menu-entry/_common/_index.md b/docs/content/en/methods/menu-entry/_common/_index.md index 47d5812fb..4328d4d14 100644 --- a/docs/content/en/methods/menu-entry/_common/_index.md +++ b/docs/content/en/methods/menu-entry/_common/_index.md @@ -7,7 +7,7 @@ cascade: --- <!-- -Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. +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/ByName.md b/docs/content/en/methods/menu/ByName.md index 04f25c22d..2e28016b6 100644 --- a/docs/content/en/methods/menu/ByName.md +++ b/docs/content/en/methods/menu/ByName.md @@ -62,4 +62,4 @@ You can also sort menu entries using the [`sort`] function. For example, to sort When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`. -[`sort`]: /functions/collections/sort +[`sort`]: /functions/collections/sort/ diff --git a/docs/content/en/methods/menu/ByWeight.md b/docs/content/en/methods/menu/ByWeight.md index d5cb0444b..3774619be 100644 --- a/docs/content/en/methods/menu/ByWeight.md +++ b/docs/content/en/methods/menu/ByWeight.md @@ -73,4 +73,4 @@ You can also sort menu entries using the [`sort`] function. For example, to sort When using the sort function with menu entries, specify any of the following keys: `Identifier`, `Name`, `Parent`, `Post`, `Pre`, `Title`, `URL`, or `Weight`. -[`sort`]: /functions/collections/sort +[`sort`]: /functions/collections/sort/ diff --git a/docs/content/en/methods/page/AllTranslations.md b/docs/content/en/methods/page/AllTranslations.md index b8cc65179..51d82d4f9 100644 --- a/docs/content/en/methods/page/AllTranslations.md +++ b/docs/content/en/methods/page/AllTranslations.md @@ -1,6 +1,6 @@ --- title: AllTranslations -description: Returns all translation of the given page, including the given page. +description: Returns all translations of the given page, including the current language. categories: [] keywords: [] action: @@ -63,9 +63,9 @@ And this template: {{ with .AllTranslations }} <ul> {{ range . }} - {{ $langName := or .Language.LanguageName .Language.Lang }} - {{ $langCode := or .Language.LanguageCode .Language.Lang }} - <li><a href="{{ .RelPermalink }}" hreflang="{{ $langCode }}">{{ .LinkTitle }} ({{ $langName }})</a></li> + <li> + <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a> + </li> {{ end }} </ul> {{ end }} diff --git a/docs/content/en/methods/page/BundleType.md b/docs/content/en/methods/page/BundleType.md index 77d1d72eb..5254757ee 100644 --- a/docs/content/en/methods/page/BundleType.md +++ b/docs/content/en/methods/page/BundleType.md @@ -5,7 +5,7 @@ categories: [] keywords: [] action: related: [] - returnType: files.ContentClass + returnType: string signatures: [PAGE.BundleType] --- diff --git a/docs/content/en/methods/page/CodeOwners.md b/docs/content/en/methods/page/CodeOwners.md index 068c4591f..c0baf26ad 100644 --- a/docs/content/en/methods/page/CodeOwners.md +++ b/docs/content/en/methods/page/CodeOwners.md @@ -63,4 +63,4 @@ Render the code owners for each content page: Combine this method with [`resources.GetRemote`] to retrieve names and avatars from your Git provider by querying their API. -[`resources.GetRemote`]: functions/resources/getremote +[`resources.GetRemote`]: /functions/resources/getremote/ diff --git a/docs/content/en/methods/page/Content.md b/docs/content/en/methods/page/Content.md index 40a057f02..a9d38367c 100644 --- a/docs/content/en/methods/page/Content.md +++ b/docs/content/en/methods/page/Content.md @@ -13,7 +13,7 @@ action: signatures: [PAGE.Content] --- -The `Content` method on a `Page` object renders markdown and shortcodes to HTML. The content does not include front matter. +The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. The content does not include front matter. [shortcodes]: /getting-started/glossary/#shortcode diff --git a/docs/content/en/methods/page/Data.md b/docs/content/en/methods/page/Data.md index 4eccde6ff..aea1042d4 100644 --- a/docs/content/en/methods/page/Data.md +++ b/docs/content/en/methods/page/Data.md @@ -74,7 +74,7 @@ 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 +[taxonomy methods]: /methods/taxonomy/ {{% /note %}} Learn more about [taxonomy templates]. diff --git a/docs/content/en/methods/page/Date.md b/docs/content/en/methods/page/Date.md index 83192f94c..113d6ca09 100644 --- a/docs/content/en/methods/page/Date.md +++ b/docs/content/en/methods/page/Date.md @@ -33,7 +33,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 +[`time.Format`]: /functions/time/format/ [details]: /getting-started/configuration/#configure-dates -[time methods]: /methods/time +[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 fbb43b8b5..67171fe01 100644 --- a/docs/content/en/methods/page/Description.md +++ b/docs/content/en/methods/page/Description.md @@ -10,7 +10,7 @@ action: signatures: [PAGE.Description] --- -Conceptually different that a [content summary], a page description is typically used in metadata about the page. +Conceptually different from a [content summary], a page description is typically used in metadata about the page. {{< code-toggle file=content/recipes/sushi.md fm=true >}} title = 'How to make spicy tuna hand rolls' @@ -25,4 +25,4 @@ description = 'Instructions for making spicy tuna hand rolls.' </head> {{< /code >}} -[content summary]: /content-management/summaries +[content summary]: /content-management/summaries/ diff --git a/docs/content/en/methods/page/ExpiryDate.md b/docs/content/en/methods/page/ExpiryDate.md index 353546449..9b95ebc65 100644 --- a/docs/content/en/methods/page/ExpiryDate.md +++ b/docs/content/en/methods/page/ExpiryDate.md @@ -29,7 +29,7 @@ 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 +[`time.Format`]: /functions/time/format/ [details]: /getting-started/configuration/#configure-dates -[time methods]: /methods/time +[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 44b752215..d59171577 100644 --- a/docs/content/en/methods/page/File.md +++ b/docs/content/en/methods/page/File.md @@ -22,7 +22,9 @@ content/ └── book-2.md ``` -Code defensively by verifying file existence as shown in each of the examples below. +{{% note %}} +Code defensively by verifying file existence as shown in the examples below. +{{% /note %}} ## Methods @@ -80,13 +82,17 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` -###### Lang +###### IsContentAdapter + +{{< new-in 0.126.0 >}} + +(`bool`) Reports whether the file is a [content adapter]. -(`string`) The language associated with the given file. +[content adapter]: /content-management/content-adapters/ ```go-html-template {{ with .File }} - {{ .Lang }} + {{ .IsContentAdapter }} {{ end }} ``` @@ -110,6 +116,16 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend {{ end }} ``` +###### Section + +(`string`) The name of the top level section in which the file resides. + +```go-html-template +{{ with .File }} + {{ .Section }} +{{ end }} +``` + ###### TranslationBaseName (`string`) The file name, excluding the extension and language identifier. @@ -157,9 +173,10 @@ ContentBaseName|a|b|news Dir|news/|news/b/|news/ Ext|md|md|md Filename|/home/user/...|/home/user/...|/home/user/... -Lang|en|en|en +IsContentAdapter|false|false|false LogicalName|a.en.md|index.en.md|_index.en.md Path|news/a.en.md|news/b/index.en.md|news/_index.en.md +Section|news|news|news TranslationBaseName|a|index|_index UniqueID|15be14b...|186868f...|7d9159d... @@ -171,13 +188,7 @@ Some of the pages on a site may not be backed by a file. For example: - Taxonomy pages - Term pages -Without a backing file, Hugo will throw a warning if you attempt to access a `.File` property. For example: - -```text -WARN .File.ContentBaseName on zero object. Wrap it in if or with... -``` - -To code defensively, first check for file existence: +Without a backing file, Hugo will throw an error if you attempt to access a `.File` property. To code defensively, first check for file existence: ```go-html-template {{ with .File }} diff --git a/docs/content/en/methods/page/Fragments.md b/docs/content/en/methods/page/Fragments.md index 89f82d2ce..7bcad1ef9 100644 --- a/docs/content/en/methods/page/Fragments.md +++ b/docs/content/en/methods/page/Fragments.md @@ -21,7 +21,7 @@ In a URL, whether absolute or relative, the [fragment] links to an `id` attribut path fragment ``` -Hugo assigns an `id` attribute to each markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page. +Hugo assigns an `id` attribute to each Markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [Markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page. Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking] the `Fragments.Map` data structure. @@ -31,21 +31,21 @@ Headings : (`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>{{ .Fragments.Headings | jsonify (dict "indent" " ") }}</pre> +<pre>{{ debug.Dump .Fragments.Headings }}</pre> ``` HeadingsMap : (`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>{{ .Fragments.HeadingsMap | jsonify (dict "indent" " ") }}</pre> +<pre>{{ debug.Dump .Fragments.HeadingsMap }}</pre> ``` Identifiers : (`slice`) A slice containing the `id` of each heading on the page. To inspect the data structure: ```go-html-template -<pre>{{ .Fragments.Identifiers | jsonify (dict "indent" " ") }}</pre> +<pre>{{ debug.Dump .Fragments.Identifiers }}</pre> ``` Identifiers.Contains ID @@ -100,7 +100,7 @@ When using the `Fragments` methods within a shortcode, call the shortcode using [fragment]: /getting-started/glossary/#fragment [markdown attribute]: /getting-started/glossary/#markdown-attribute [setext]: https://spec.commonmark.org/0.30/#setext-headings -[table of contents]: /methods/page/tableofcontents +[table of contents]: /methods/page/tableofcontents/ [walking]: /getting-started/glossary/#walk -[`tableofcontents`]: /methods/page/tableofcontents +[`tableofcontents`]: /methods/page/tableofcontents/ [render hook]: /getting-started/glossary/#render-hook diff --git a/docs/content/en/methods/page/FuzzyWordCount.md b/docs/content/en/methods/page/FuzzyWordCount.md index 600ad48d5..8523edf8c 100644 --- a/docs/content/en/methods/page/FuzzyWordCount.md +++ b/docs/content/en/methods/page/FuzzyWordCount.md @@ -17,4 +17,4 @@ action: To get the exact word count, use the [`WordCount`] method. -[`WordCount`]: /methods/page/wordcount +[`WordCount`]: /methods/page/wordcount/ diff --git a/docs/content/en/methods/page/GetPage.md b/docs/content/en/methods/page/GetPage.md index b1f192d58..9b4ced345 100644 --- a/docs/content/en/methods/page/GetPage.md +++ b/docs/content/en/methods/page/GetPage.md @@ -13,7 +13,7 @@ aliases: [/functions/getpage] The `GetPage` method is also available on a `Site` object. See [details]. -[details]: /methods/site/getpage +[details]: /methods/site/getpage/ When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the content directory. @@ -36,7 +36,7 @@ content/ └── _index.md ``` -The examples below depict the result of rendering works/paintings/the-mona-list.md with a single page template: +The examples below depict the result of rendering works/paintings/the-mona-lisa.md with a single page template: ```go-html-template {{ with .GetPage "starry-night" }} diff --git a/docs/content/en/methods/page/HeadingsFiltered.md b/docs/content/en/methods/page/HeadingsFiltered.md index a39c48da1..d741b57ce 100644 --- a/docs/content/en/methods/page/HeadingsFiltered.md +++ b/docs/content/en/methods/page/HeadingsFiltered.md @@ -14,5 +14,5 @@ action: Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details]. [`Pages`]: /methods/pages/ -[`Related`]: /methods/pages/related +[`Related`]: /methods/pages/related/ [details]: /content-management/related/#index-content-headings-in-related-content diff --git a/docs/content/en/methods/page/InSection.md b/docs/content/en/methods/page/InSection.md index b98fbc808..41ce918f3 100644 --- a/docs/content/en/methods/page/InSection.md +++ b/docs/content/en/methods/page/InSection.md @@ -98,5 +98,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ {{% /note %}} [context]: /getting-started/glossary/#context -[`with`]: /functions/go-template/with -[`else`]: /functions/go-template/else +[`with`]: /functions/go-template/with/ +[`else`]: /functions/go-template/else/ diff --git a/docs/content/en/methods/page/IsAncestor.md b/docs/content/en/methods/page/IsAncestor.md index ca23c0868..8ace8463c 100644 --- a/docs/content/en/methods/page/IsAncestor.md +++ b/docs/content/en/methods/page/IsAncestor.md @@ -1,6 +1,6 @@ --- title: IsAncestor -description: Reports whether PAGE1 in an ancestor of PAGE2. +description: Reports whether PAGE1 is an ancestor of PAGE2. categories: [] keywords: [] action: @@ -96,5 +96,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ {{% /note %}} [context]: /getting-started/glossary/#context -[`with`]: /functions/go-template/with -[`else`]: /functions/go-template/else +[`with`]: /functions/go-template/with/ +[`else`]: /functions/go-template/else/ diff --git a/docs/content/en/methods/page/IsDescendant.md b/docs/content/en/methods/page/IsDescendant.md index f1042564e..2c0599d91 100644 --- a/docs/content/en/methods/page/IsDescendant.md +++ b/docs/content/en/methods/page/IsDescendant.md @@ -1,6 +1,6 @@ --- title: IsDescendant -description: Reports whether PAGE1 in a descendant of PAGE2. +description: Reports whether PAGE1 is a descendant of PAGE2. categories: [] keywords: [] action: @@ -95,5 +95,5 @@ Gaining a thorough understanding of context is critical for anyone writing templ {{% /note %}} [context]: /getting-started/glossary/#context -[`with`]: /functions/go-template/with -[`else`]: /functions/go-template/else +[`with`]: /functions/go-template/with/ +[`else`]: /functions/go-template/else/ diff --git a/docs/content/en/methods/page/Keywords.md b/docs/content/en/methods/page/Keywords.md index 5ad37ce51..ef68c27f5 100644 --- a/docs/content/en/methods/page/Keywords.md +++ b/docs/content/en/methods/page/Keywords.md @@ -11,7 +11,7 @@ action: By default, Hugo evaluates the keywords when creating collections of [related content]. -[related content]: /content-management/related +[related content]: /content-management/related/ {{< code-toggle file=content/recipes/sushi.md fm=true >}} title = 'How to make spicy tuna hand rolls' @@ -32,7 +32,7 @@ Or use the [delimit] function: {{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice ``` -[delimit]: /functions/collections/delimit +[delimit]: /functions/collections/delimit/ Keywords are also a useful [taxonomy]: @@ -43,4 +43,4 @@ keyword = 'keywords' category = 'categories' {{< /code-toggle >}} -[taxonomy]: /content-management/taxonomies +[taxonomy]: /content-management/taxonomies/ diff --git a/docs/content/en/methods/page/Language.md b/docs/content/en/methods/page/Language.md index 4e65107da..321b44e56 100644 --- a/docs/content/en/methods/page/Language.md +++ b/docs/content/en/methods/page/Language.md @@ -34,7 +34,7 @@ Lang ``` LanguageCode -: (`string`) The language code from the site configuration. +: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined. ```go-html-template {{ .Language.LanguageCode }} → de-DE @@ -61,5 +61,5 @@ Weight {{ .Language.Weight }} → 2 ``` -[details]: /methods/site/language +[details]: /methods/site/language/ [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 diff --git a/docs/content/en/methods/page/Lastmod.md b/docs/content/en/methods/page/Lastmod.md index c1692233d..78760d556 100644 --- a/docs/content/en/methods/page/Lastmod.md +++ b/docs/content/en/methods/page/Lastmod.md @@ -33,8 +33,8 @@ In the example above we explicitly set the last modification date in front matte Learn more about [date configuration]. -[`gitinfo`]: /methods/page/gitinfo -[`time.format`]: /functions/time/format +[`gitinfo`]: /methods/page/gitinfo/ +[`time.format`]: /functions/time/format/ [date configuration]: /getting-started/configuration/#configure-dates -[time methods]: /methods/time +[time methods]: /methods/time/ [time.time]: https://pkg.go.dev/time#time diff --git a/docs/content/en/methods/page/LinkTitle.md b/docs/content/en/methods/page/LinkTitle.md index 746e433bb..0ce32e641 100644 --- a/docs/content/en/methods/page/LinkTitle.md +++ b/docs/content/en/methods/page/LinkTitle.md @@ -12,7 +12,7 @@ action: The `LinkTitle` method returns the `linkTitle` field as defined in front matter, falling back to the value returned by the [`Title`] method. -[`Title`]: /methods/page/title +[`Title`]: /methods/page/title/ {{< code-toggle file=content/articles/healthy-desserts.md fm=true >}} title = 'Seventeen delightful recipes for healthy desserts' diff --git a/docs/content/en/methods/page/NextInSection.md b/docs/content/en/methods/page/NextInSection.md index 73f82d754..59a35d03d 100644 --- a/docs/content/en/methods/page/NextInSection.md +++ b/docs/content/en/methods/page/NextInSection.md @@ -65,7 +65,7 @@ With the `PrevInSection` and `NextInSection` methods, the navigation sort order For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice. -[date]: /methods/page/date -[weight]: /methods/page/weight -[linkTitle]: /methods/page/linktitle -[title]: /methods/page/title +[date]: /methods/page/date/ +[weight]: /methods/page/weight/ +[linkTitle]: /methods/page/linktitle/ +[title]: /methods/page/title/ diff --git a/docs/content/en/methods/page/Pages.md b/docs/content/en/methods/page/Pages.md index 2f329eeec..d446292e2 100644 --- a/docs/content/en/methods/page/Pages.md +++ b/docs/content/en/methods/page/Pages.md @@ -75,7 +75,7 @@ In the last example, the collection includes pages in the resources subdirectory {{% note %}} When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details]. -[details]: /methods/site/pages +[details]: /methods/site/pages/ {{% /note %}} ```go-html-template diff --git a/docs/content/en/methods/page/Paginator.md b/docs/content/en/methods/page/Paginator.md index b1540286a..b411e6ec0 100644 --- a/docs/content/en/methods/page/Paginator.md +++ b/docs/content/en/methods/page/Paginator.md @@ -28,7 +28,7 @@ Although simple to invoke, with the `Paginator` method you can neither filter no The [`Paginate`] method is more flexible, and strongly recommended. -[`paginate`]: /methods/page/paginate +[`paginate`]: /methods/page/paginate/ {{% /note %}} {{% note %}} diff --git a/docs/content/en/methods/page/Param.md b/docs/content/en/methods/page/Param.md index b2932d981..daf09a5b4 100644 --- a/docs/content/en/methods/page/Param.md +++ b/docs/content/en/methods/page/Param.md @@ -29,6 +29,7 @@ Content: title = 'Example' date = 2023-01-01 draft = false +[params] display_toc = false {{< /code-toggle >}} diff --git a/docs/content/en/methods/page/Params.md b/docs/content/en/methods/page/Params.md index 13416ada7..219b5de9d 100644 --- a/docs/content/en/methods/page/Params.md +++ b/docs/content/en/methods/page/Params.md @@ -17,8 +17,9 @@ With this front matter: {{< code-toggle file=content/news/annual-conference.md >}} title = 'Annual conference' date = 2023-10-17T15:11:37-07:00 +[params] display_related = true -[author] +[params.author] email = 'jsmith@example.org' name = 'John Smith' {{< /code-toggle >}} @@ -38,6 +39,6 @@ In the template example above, each of the keys is a valid identifier. For examp {{ index .Params "key-with-hyphens" }} → 2023 ``` -[`index`]: /functions/collections/indexfunction +[`index`]: /functions/collections/indexfunction/ [chaining]: /getting-started/glossary/#chain [identifiers]: /getting-started/glossary/#identifier diff --git a/docs/content/en/methods/page/Parent.md b/docs/content/en/methods/page/Parent.md index 9d9ed7ea3..db01eb589 100644 --- a/docs/content/en/methods/page/Parent.md +++ b/docs/content/en/methods/page/Parent.md @@ -21,7 +21,7 @@ action: {{% note %}} The parent section of a regular page is the [current section]. -[current section]: /methods/page/currentsection +[current section]: /methods/page/currentsection/ {{% /note %}} Consider this content structure: diff --git a/docs/content/en/methods/page/Path.md b/docs/content/en/methods/page/Path.md new file mode 100644 index 000000000..b65120d4d --- /dev/null +++ b/docs/content/en/methods/page/Path.md @@ -0,0 +1,157 @@ +--- +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 +--- + +{{< new-in 0.123.0 >}} + +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. + +[logical path]: /getting-started/glossary#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 +2. Strips the language identifier +3. Converts the result to lower case +4. Replaces spaces with hyphens + +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. + +## Examples + +### Monolingual site + +Note that the logical path is independent of content format and URL modifiers. + +File path|Front matter slug|Logical path +:--|:--|:-- +`content/_index.md`||`/` +`content/posts/_index.md`||`/posts` +`content/posts/post-1.md`|`foo`|`/posts/post-1` +`content/posts/post-2.html`|`bar`|`/posts/post-2` + +### Multilingual site + +Note that the logical path is independent of content format, language identifiers, and URL modifiers. + +File path|Front matter slug|Logical path +:--|:--|:-- +`content/_index.en.md`||`/` +`content/_index.de.md`||`/` +`content/posts/_index.en.md`||`/posts` +`content/posts/_index.de.md`||`/posts` +`content/posts/posts-1.en.md`|`foo`|`/posts/post-1` +`content/posts/posts-1.de.md`|`foo`|`/posts/post-1` +`content/posts/posts-2.en.html`|`bar`|`/posts/post-2` +`content/posts/posts-2.de.html`|`bar`|`/posts/post-2` + +### Pages not backed by a file + +The `Path` method on a `Page` object returns a value regardless of whether the page is backed by a file. + +```text +content/ +└── posts/ + └── post-1.md <-- front matter: tags = ['hugo'] +``` + +When you build the site: + +```text +public/ +├── posts/ +│ ├── post-1/ +│ │ └── index.html .Page.Path = /posts/post-1 +│ └── index.html .Page.Path = /posts +├── tags/ +│ ├── hugo/ +│ │ └── index.html .Page.Path = /tags/hugo +│ └── index.html .Page.Path = /tags +└── index.html .Page.Path = / +``` + +## Finding pages + +These methods, functions, and shortcodes use the logical path to find the given page: + +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`]: /content-management/shortcodes/#ref +[`relref`]: /content-management/shortcodes/#relref +[`Page.Ref`]: /methods/page/ref/ +[`Page.RelRef`]: /methods/page/relref/ +[`Shortcode.Ref`]: /methods/shortcode/ref +[`Shortcode.RelRef`]: /methods/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 %}} + + +## Logical tree + +Just as file paths form a file tree, logical paths form a logical tree. + +A file tree: + +```text +content/ +└── s1/ + ├── p1/ + │ └── index.md + └── p2.md +``` + +The same content represented as a logical tree: + +```text +content/ +└── s1/ + ├── p1 + └── p2 +``` + +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 %}} diff --git a/docs/content/en/methods/page/Plain.md b/docs/content/en/methods/page/Plain.md index 6fdf60b62..3aae1ed61 100644 --- a/docs/content/en/methods/page/Plain.md +++ b/docs/content/en/methods/page/Plain.md @@ -13,7 +13,7 @@ action: signatures: [PAGE.Plain] --- -The `Plain` method on a `Page` object renders markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter. +The `Plain` method on a `Page` object renders Markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter. To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function. @@ -25,4 +25,4 @@ To prevent Go's [html/template] package from escaping HTML entities, pass the re [html/template]: https://pkg.go.dev/html/template [entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity [tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag -[`htmlUnescape`]: /functions/ +[`htmlUnescape`]: /functions/transform/htmlunescape/ diff --git a/docs/content/en/methods/page/PlainWords.md b/docs/content/en/methods/page/PlainWords.md index 4bc79d241..4f70193fe 100644 --- a/docs/content/en/methods/page/PlainWords.md +++ b/docs/content/en/methods/page/PlainWords.md @@ -15,7 +15,7 @@ action: 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 white space characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only white space._ +_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 %}} @@ -32,5 +32,5 @@ To determine the approximate number of unique words on a page: {{ .PlainWords | uniq }} → 42 ``` -[`Plain`]: /methods/page/plain +[`Plain`]: /methods/page/plain/ [`strings.Fields`]: https://pkg.go.dev/strings#Fields diff --git a/docs/content/en/methods/page/PrevInSection.md b/docs/content/en/methods/page/PrevInSection.md index c09e4580f..e6daf66c4 100644 --- a/docs/content/en/methods/page/PrevInSection.md +++ b/docs/content/en/methods/page/PrevInSection.md @@ -66,7 +66,7 @@ With the `PrevInSection` and `NextInSection` methods, the navigation sort order For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice. -[date]: /methods/page/date -[weight]: /methods/page/weight -[linkTitle]: /methods/page/linktitle -[title]: /methods/page/title +[date]: /methods/page/date/ +[weight]: /methods/page/weight/ +[linkTitle]: /methods/page/linktitle/ +[title]: /methods/page/title/ diff --git a/docs/content/en/methods/page/PublishDate.md b/docs/content/en/methods/page/PublishDate.md index b1c0717a9..d1f2eb2a1 100644 --- a/docs/content/en/methods/page/PublishDate.md +++ b/docs/content/en/methods/page/PublishDate.md @@ -29,7 +29,7 @@ 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 +[`time.Format`]: /functions/time/format/ [details]: /getting-started/configuration/#configure-dates -[time methods]: /methods/time +[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 258a294d0..12686c695 100644 --- a/docs/content/en/methods/page/RawContent.md +++ b/docs/content/en/methods/page/RawContent.md @@ -25,7 +25,7 @@ This is useful when rendering a page in a plain text [output format]. [Shortcodes] within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object. [shortcodes]: /getting-started/glossary/#shortcode -[`RenderShortcodes`]: /methods/page/rendershortcodes +[`RenderShortcodes`]: /methods/page/rendershortcodes/ {{% /note %}} -[output format]: /templates/output-formats +[output format]: /templates/output-formats/ diff --git a/docs/content/en/methods/page/RegularPages.md b/docs/content/en/methods/page/RegularPages.md index b0ca7b1e1..d3327702e 100644 --- a/docs/content/en/methods/page/RegularPages.md +++ b/docs/content/en/methods/page/RegularPages.md @@ -72,7 +72,7 @@ In the last example, the collection includes pages in the resources subdirectory {{% note %}} When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details]. -[details]: /methods/site/regularpages +[details]: /methods/site/regularpages/ {{% /note %}} ```go-html-template diff --git a/docs/content/en/methods/page/Render.md b/docs/content/en/methods/page/Render.md index bc3f58352..9a70d2bed 100644 --- a/docs/content/en/methods/page/Render.md +++ b/docs/content/en/methods/page/Render.md @@ -70,6 +70,6 @@ layouts/_default/li.html See [content views] for more examples. -[content views]: /templates/views -[`partial`]: /functions/partials/include +[content views]: /templates/views/ +[`partial`]: /functions/partials/include/ [content type]: /getting-started/glossary/#content-type diff --git a/docs/content/en/methods/page/RenderShortcodes.md b/docs/content/en/methods/page/RenderShortcodes.md index 4636bf8f5..a4120f69a 100644 --- a/docs/content/en/methods/page/RenderShortcodes.md +++ b/docs/content/en/methods/page/RenderShortcodes.md @@ -22,11 +22,12 @@ Use this method in shortcode templates to compose a page from multiple content f For example: {{< code file=layouts/shortcodes/include.html >}} -{{ $p := site.GetPage (.Get 0) }} -{{ $p.RenderShortcodes }} +{{ with site.GetPage (.Get 0) }} + {{ .RenderShortcodes }} +{{ end }} {{< /code >}} -Then in your markdown: +Then call the shortcode in your Markdown: {{< code file=content/about.md lang=md >}} {{%/* include "/snippets/services.md" */%}} @@ -34,14 +35,14 @@ Then in your markdown: {{%/* include "/snippets/leadership.md" */%}} {{< /code >}} -Each of the included markdown files can contain calls to other shortcodes. +Each of the included Markdown files can contain calls to other shortcodes. ## Shortcode notation In the example above it's important to understand the difference between the two delimiters used when calling a shortcode: - `{{</* myshortcode */>}}` tells Hugo that the rendered shortcode does not need further processing. For example, the shortcode content is HTML. -- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is markdown. +- `{{%/* myshortcode */%}}` tells Hugo that the rendered shortcode needs further processing. For example, the shortcode content is Markdown. Use the latter for the "include" shortcode described above. @@ -75,4 +76,4 @@ https://example.org/privacy/ An *emphasized* word. ``` -Note that the shortcode within the content file was rendered, but the surrounding markdown was preserved. +Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved. diff --git a/docs/content/en/methods/page/RenderString.md b/docs/content/en/methods/page/RenderString.md index 5782cd2b1..1a92c78c6 100644 --- a/docs/content/en/methods/page/RenderString.md +++ b/docs/content/en/methods/page/RenderString.md @@ -47,5 +47,5 @@ Render with [Pandoc]: {{ .RenderString $opts $s }} → <p>H<sub>2</sub>O</p> ``` -[markup identifier]: /content-management/formats/#list-of-content-formats +[markup identifier]: /content-management/formats/#classification [pandoc]: https://www.pandoc.org/ diff --git a/docs/content/en/methods/page/Resources.md b/docs/content/en/methods/page/Resources.md index 140b50020..54a61a2e4 100644 --- a/docs/content/en/methods/page/Resources.md +++ b/docs/content/en/methods/page/Resources.md @@ -75,11 +75,11 @@ With the `GetMatch` and `Match` methods, Hugo determines a match using a case-in {{% include "functions/_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 +[`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 [page bundle]: /getting-started/glossary/#page-bundle diff --git a/docs/content/en/methods/page/Scratch.md b/docs/content/en/methods/page/Scratch.md index f9ce7f7fb..8fef31893 100644 --- a/docs/content/en/methods/page/Scratch.md +++ b/docs/content/en/methods/page/Scratch.md @@ -1,6 +1,6 @@ --- title: Scratch -description: Creates a "scratch pad" on the given page to store and manipulate data. +description: Returns a "scratch pad" on the given page to store and manipulate data. categories: [] keywords: [] action: @@ -9,6 +9,7 @@ action: - functions/collections/NewScratch returnType: maps.Scratch signatures: [PAGE.Scratch] +toc: true aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch] --- @@ -16,8 +17,28 @@ The `Scratch` method on a `Page` object creates a [scratch pad] to store and man To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function. -[`Store`]: /methods/page/store -[`newScratch`]: functions/collections/newscratch +[`Store`]: /methods/page/store/ +[`newScratch`]: /functions/collections/newscratch/ [scratch pad]: /getting-started/glossary/#scratch-pad {{% include "methods/page/_common/scratch-methods.md" %}} + +## Determinate values + +The `Scratch` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content. + +If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable: + +[noop]: /getting-started/glossary/#noop + +```go-html-template +{{ $noop := .Content }} +{{ .Store.Get "mykey" }} +``` + +You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: + +```go-html-template +{{ $noop := .WordCount }} +{{ .Store.Get "mykey" }} +``` diff --git a/docs/content/en/methods/page/Section.md b/docs/content/en/methods/page/Section.md index 30c8a9837..8e027a5a1 100644 --- a/docs/content/en/methods/page/Section.md +++ b/docs/content/en/methods/page/Section.md @@ -50,5 +50,5 @@ This is similar to using the [`Type`] method with the `where` function However, if the `type` field in front matter has been defined on one or more pages, the page collection based on `Type` will be different than the page collection based on `Section`. -[`where`]: /functions/collections/where -[`Type`]: /methods/page/type +[`where`]: /functions/collections/where/ +[`Type`]: /methods/page/type/ diff --git a/docs/content/en/methods/page/Sections.md b/docs/content/en/methods/page/Sections.md index d64440038..4cce1a4fb 100644 --- a/docs/content/en/methods/page/Sections.md +++ b/docs/content/en/methods/page/Sections.md @@ -35,11 +35,11 @@ content/ │ ├── bidding.md │ └── payment.md ├── books/ -│ ├── _index.md <-- front matter: weight = 10 +│ ├── _index.md <-- front matter: weight = 20 │ ├── book-1.md │ └── book-2.md ├── films/ -│ ├── _index.md <-- front matter: weight = 20 +│ ├── _index.md <-- front matter: weight = 10 │ ├── film-1.md │ └── film-2.md └── _index.md diff --git a/docs/content/en/methods/page/Site.md b/docs/content/en/methods/page/Site.md index 34748facd..d83c45e0a 100644 --- a/docs/content/en/methods/page/Site.md +++ b/docs/content/en/methods/page/Site.md @@ -12,7 +12,7 @@ action: See [Site methods]. -[Site methods]: /methods/site +[Site methods]: /methods/site/ ```go-html-template {{ .Site.Title }} diff --git a/docs/content/en/methods/page/Sitemap.md b/docs/content/en/methods/page/Sitemap.md index 08ff3f5d0..d6159267d 100644 --- a/docs/content/en/methods/page/Sitemap.md +++ b/docs/content/en/methods/page/Sitemap.md @@ -14,15 +14,22 @@ Access to the `Sitemap` method on a `Page` object is restricted to [sitemap temp ## Methods -ChangeFreq -: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is "" (change frequency omitted from rendered sitemap). +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 }} ``` -Priority -: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is -1 (priority omitted from rendered sitemap). +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). ```go-html-template {{ .Sitemap.Priority }} diff --git a/docs/content/en/methods/page/Sites.md b/docs/content/en/methods/page/Sites.md index 1fbdfcdcd..cd240655e 100644 --- a/docs/content/en/methods/page/Sites.md +++ b/docs/content/en/methods/page/Sites.md @@ -52,10 +52,10 @@ Produces a list of links to each home page: </ul> ``` -To render a link to home page of the primary (first) language: +To render a link to the home page of the site corresponding to the default content language: ```go-html-template -{{ with .Sites.First }} +{{ with .Sites.Default }} <a href="{{ .Home.Permalink }}">{{ .Title }}</a> {{ end }} ``` diff --git a/docs/content/en/methods/page/Store.md b/docs/content/en/methods/page/Store.md index 8bc16034b..e7090fe79 100644 --- a/docs/content/en/methods/page/Store.md +++ b/docs/content/en/methods/page/Store.md @@ -1,6 +1,6 @@ --- title: Store -description: Creates a persistent "scratch pad" on the given page to store and manipulate data. +description: Returns a persistent "scratch pad" on the given page to store and manipulate data. categories: [] keywords: [] action: @@ -9,6 +9,7 @@ action: - functions/collections/NewScratch returnType: maps.Scratch signatures: [PAGE.Store] +toc: true aliases: [/functions/store] --- @@ -16,8 +17,8 @@ The `Store` method on a `Page` object creates a persistent [scratch pad] to stor To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function. -[`Scratch`]: /methods/page/scratch -[`newScratch`]: functions/collections/newscratch +[`Scratch`]: /methods/page/scratch/ +[`newScratch`]: /functions/collections/newscratch/ [scratch pad]: /getting-started/glossary/#scratch-pad ## Methods @@ -102,3 +103,23 @@ Removes the given key. {{ .Store.Set "greeting" "Hello" }} {{ .Store.Delete "greeting" }} ``` + +## Determinate values + +The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content. + +If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable: + +[noop]: /getting-started/glossary/#noop + +```go-html-template +{{ $noop := .Content }} +{{ .Store.Get "mykey" }} +``` + +You can also trigger content rendering with the `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount` methods. For example: + +```go-html-template +{{ $noop := .WordCount }} +{{ .Store.Get "mykey" }} +``` diff --git a/docs/content/en/methods/page/Summary.md b/docs/content/en/methods/page/Summary.md index 37ce86589..e4542d258 100644 --- a/docs/content/en/methods/page/Summary.md +++ b/docs/content/en/methods/page/Summary.md @@ -11,10 +11,14 @@ action: signatures: [PAGE.Summary] --- +<!-- Do not remove the manual summary divider below. --> +<!-- If you do, you will break its first literal usage on this page. --> +<!--more--> + There are three ways to define the [content summary]: 1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration. -2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary. +2. Manually split the content with a `<!--more-->` tag in Markdown. Everything before the tag is included in the summary. 3. Create a `summary` field in front matter. To list the pages in a section with a summary beneath each link: @@ -26,4 +30,4 @@ To list the pages in a section with a summary beneath each link: {{ end }} ``` -[content summary]: /content-management/summaries +[content summary]: /content-management/summaries/ diff --git a/docs/content/en/methods/page/TableOfContents.md b/docs/content/en/methods/page/TableOfContents.md index 2ab182e8c..38c3ff17b 100644 --- a/docs/content/en/methods/page/TableOfContents.md +++ b/docs/content/en/methods/page/TableOfContents.md @@ -8,9 +8,10 @@ action: - methods/page/Fragments returnType: template.HTML signatures: [PAGE.TableOfContents] +aliases: [/content-management/toc/] --- -The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the markdown [ATX] and [setext] headings within the page content. +The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the Markdown [ATX] and [setext] headings within the page content. [atx]: https://spec.commonmark.org/0.30/#atx-headings [setext]: https://spec.commonmark.org/0.30/#setext-headings diff --git a/docs/content/en/methods/page/Title.md b/docs/content/en/methods/page/Title.md index 52e46ff44..5c2c98d6b 100644 --- a/docs/content/en/methods/page/Title.md +++ b/docs/content/en/methods/page/Title.md @@ -20,19 +20,21 @@ title = 'About us' {{ .Title }} → About us ``` -With section pages not backed by a file, the `Title` method returns the section name, pluralized and converted to title case. - -To disable [pluralization]: +With section, taxonomy, and term pages not backed by a file, the `Title` method returns the section name, capitalized and pluralized. You can disable these transformations by setting [`capitalizeListTitles`] and [`pluralizeListTitles`] in your site configuration. For example: {{< code-toggle file=hugo >}} +capitalizeListTitles = false pluralizeListTitles = false {{< /code-toggle >}} -To change the [title case style], specify one of `ap`, `chicago`, `go`, `firstupper`, or `none`: +You can change the capitalization style in your site configuration to one of `ap`, `chicago`, `go`, `firstupper`, or `none`. For example: {{< code-toggle file=hugo >}} -titleCaseStyle = "ap" +titleCaseStyle = "firstupper" {{< /code-toggle >}} -[pluralization]: /functions/inflect/pluralize -[title case style]: /getting-started/configuration/#configure-title-case + See [details]. + +[`capitalizeListTitles`]: /getting-started/configuration/#capitalizelisttitles +[`pluralizeListTitles`]: /getting-started/configuration/#pluralizelisttitles +[details]: /getting-started/configuration/#configure-title-case diff --git a/docs/content/en/methods/page/Translations.md b/docs/content/en/methods/page/Translations.md index 1ed256630..597a9aeb6 100644 --- a/docs/content/en/methods/page/Translations.md +++ b/docs/content/en/methods/page/Translations.md @@ -1,6 +1,6 @@ --- title: Translations -description: Returns all translation of the given page, excluding the current language. +description: Returns all translations of the given page, excluding the current language. categories: [] keywords: [] action: @@ -63,9 +63,9 @@ And this template: {{ with .Translations }} <ul> {{ range . }} - {{ $langName := or .Language.LanguageName .Language.Lang }} - {{ $langCode := or .Language.LanguageCode .Language.Lang }} - <li><a href="{{ .RelPermalink }}" hreflang="{{ $langCode }}">{{ .LinkTitle }} ({{ $langName }})</a></li> + <li> + <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a> + </li> {{ end }} </ul> {{ end }} diff --git a/docs/content/en/methods/page/Truncated.md b/docs/content/en/methods/page/Truncated.md index e6051f0cd..0785f40cb 100644 --- a/docs/content/en/methods/page/Truncated.md +++ b/docs/content/en/methods/page/Truncated.md @@ -13,7 +13,7 @@ action: There are three ways to define the [content summary]: 1. Let Hugo create the summary based on the first 70 words. You can change the number of words by setting the `summaryLength` in your site configuration. -2. Manually split the content with a `<--more-->` tag in markdown. Everything before the tag is included in the summary. +2. Manually split the content with a `<--more-->` tag in Markdown. Everything before the tag is included in the summary. 3. Create a `summary` field in front matter. {{% note %}} @@ -32,4 +32,4 @@ The `Truncated` method returns `true` if the content length exceeds the summary {{ end }} ``` -[content summary]: /content-management/summaries +[content summary]: /content-management/summaries/ diff --git a/docs/content/en/methods/page/WordCount.md b/docs/content/en/methods/page/WordCount.md index bb1fdcf94..70fe407ab 100644 --- a/docs/content/en/methods/page/WordCount.md +++ b/docs/content/en/methods/page/WordCount.md @@ -17,4 +17,4 @@ action: To round up to nearest multiple of 100, use the [`FuzzyWordCount`] method. -[`FuzzyWordCount`]: /methods/page/fuzzywordcount +[`FuzzyWordCount`]: /methods/page/fuzzywordcount/ diff --git a/docs/content/en/methods/page/_common/_index.md b/docs/content/en/methods/page/_common/_index.md index 47d5812fb..4328d4d14 100644 --- a/docs/content/en/methods/page/_common/_index.md +++ b/docs/content/en/methods/page/_common/_index.md @@ -7,7 +7,7 @@ cascade: --- <!-- -Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. +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/output-format-definition.md b/docs/content/en/methods/page/_common/output-format-definition.md index 25944464a..412c5cee6 100644 --- a/docs/content/en/methods/page/_common/output-format-definition.md +++ b/docs/content/en/methods/page/_common/output-format-definition.md @@ -8,4 +8,4 @@ Hugo generates one or more files per page when building a site. For example, whe [taxonomy]: /getting-started/glossary/#taxonomy [term]: /getting-started/glossary/#term [page kind]: /getting-started/glossary/#page-kind -[details]: /templates/output-formats +[details]: /templates/output-formats/ diff --git a/docs/content/en/methods/pager/First.md b/docs/content/en/methods/pager/First.md new file mode 100644 index 000000000..85e2e0dd3 --- /dev/null +++ b/docs/content/en/methods/pager/First.md @@ -0,0 +1,44 @@ +--- +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] +--- + +Use the `First` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ with .Prev }} + <li><a href="{{ .URL }}">Previous</a></li> + {{ end }} + {{ with .Next }} + <li><a href="{{ .URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/HasNext.md b/docs/content/en/methods/pager/HasNext.md new file mode 100644 index 000000000..e7550d788 --- /dev/null +++ b/docs/content/en/methods/pager/HasNext.md @@ -0,0 +1,72 @@ +--- +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] +--- + +Use the `HasNext` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ if .HasPrev }} + <li><a href="{{ .Prev.URL }}">Previous</a></li> + {{ end }} + {{ if .HasNext }} + <li><a href="{{ .Next.URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` + +You can also write the above without using the `HasNext` method: + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ with .Prev }} + <li><a href="{{ .URL }}">Previous</a></li> + {{ end }} + {{ with .Next }} + <li><a href="{{ .URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/HasPrev.md b/docs/content/en/methods/pager/HasPrev.md new file mode 100644 index 000000000..00d5c1dea --- /dev/null +++ b/docs/content/en/methods/pager/HasPrev.md @@ -0,0 +1,72 @@ +--- +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] +--- + +Use the `HasPrev` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ if .HasPrev }} + <li><a href="{{ .Prev.URL }}">Previous</a></li> + {{ end }} + {{ if .HasNext }} + <li><a href="{{ .Next.URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` + +You can also write the above without using the `HasPrev` method: + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ with .Prev }} + <li><a href="{{ .URL }}">Previous</a></li> + {{ end }} + {{ with .Next }} + <li><a href="{{ .URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/Last.md b/docs/content/en/methods/pager/Last.md new file mode 100644 index 000000000..074a46943 --- /dev/null +++ b/docs/content/en/methods/pager/Last.md @@ -0,0 +1,44 @@ +--- +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] +--- + +Use the `Last` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ with .Prev }} + <li><a href="{{ .URL }}">Previous</a></li> + {{ end }} + {{ with .Next }} + <li><a href="{{ .URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/Next.md b/docs/content/en/methods/pager/Next.md new file mode 100644 index 000000000..099ac198e --- /dev/null +++ b/docs/content/en/methods/pager/Next.md @@ -0,0 +1,44 @@ +--- +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] +--- + +Use the `Next` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ with .Prev }} + <li><a href="{{ .URL }}">Previous</a></li> + {{ end }} + {{ with .Next }} + <li><a href="{{ .URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/NumberOfElements.md b/docs/content/en/methods/pager/NumberOfElements.md new file mode 100644 index 000000000..3980cdfe2 --- /dev/null +++ b/docs/content/en/methods/pager/NumberOfElements.md @@ -0,0 +1,25 @@ +--- +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] +--- + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + {{ .NumberOfElements }} +{{ end }} +``` diff --git a/docs/content/en/methods/pager/PageGroups.md b/docs/content/en/methods/pager/PageGroups.md new file mode 100644 index 000000000..9dee18c0d --- /dev/null +++ b/docs/content/en/methods/pager/PageGroups.md @@ -0,0 +1,29 @@ +--- +title: PageGroups +description: Returns the page groups in the current pager. +categories: [] +keywords: [] +action: + related: + - methods/page/Paginate + returnType: page.PagesGroup + signatures: [PAGER.PageGroups] +--- + +Use the `PageGroups` method with any of the [grouping methods]. + +[grouping methods]: /quick-reference/page-collections/#group + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }} + +{{ range $paginator.PageGroups }} + <h2>{{ .Key }}</h2> + {{ range .Pages }} + <h3><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h3> + {{ end }} +{{ end }} + +{{ template "_internal/pagination.html" . }} +``` diff --git a/docs/content/en/methods/pager/PageNumber.md b/docs/content/en/methods/pager/PageNumber.md new file mode 100644 index 000000000..0d99c5a15 --- /dev/null +++ b/docs/content/en/methods/pager/PageNumber.md @@ -0,0 +1,31 @@ +--- +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] +--- + +Use the `PageNumber` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ range .Pagers }} + <li><a href="{{ .URL }}">{{ .PageNumber }}</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/PageSize.md b/docs/content/en/methods/pager/PageSize.md new file mode 100644 index 000000000..a400f929a --- /dev/null +++ b/docs/content/en/methods/pager/PageSize.md @@ -0,0 +1,24 @@ +--- +title: PageSize +description: Returns the maximum number of pages per pager. +categories: [] +keywords: [] +action: + related: + - methods/page/Paginate + returnType: int + signatures: [PAGER.PageSize] +--- + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + {{ .PageSize }} +{{ end }} +``` diff --git a/docs/content/en/methods/pager/Pagers.md b/docs/content/en/methods/pager/Pagers.md new file mode 100644 index 000000000..5f167c13e --- /dev/null +++ b/docs/content/en/methods/pager/Pagers.md @@ -0,0 +1,30 @@ +--- +title: Pagers +description: Returns the pagers collection. +categories: [] +keywords: [] +action: + related: + - methods/page/Paginate + returnType: page.pagers + signatures: [PAGER.Pagers] +--- + +Use the `Pagers` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ range .Pagers }} + <li><a href="{{ .URL }}">{{ .PageNumber }}</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/Pages.md b/docs/content/en/methods/pager/Pages.md new file mode 100644 index 000000000..1c049d53b --- /dev/null +++ b/docs/content/en/methods/pager/Pages.md @@ -0,0 +1,22 @@ +--- +title: Pages +description: Returns the pages in the current pager. +categories: [] +keywords: [] +action: + related: + - methods/page/Paginate + returnType: page.Pages + signatures: [PAGER.Pages] +--- + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ template "_internal/pagination.html" . }} +``` diff --git a/docs/content/en/methods/pager/Prev.md b/docs/content/en/methods/pager/Prev.md new file mode 100644 index 000000000..c129c6a5a --- /dev/null +++ b/docs/content/en/methods/pager/Prev.md @@ -0,0 +1,44 @@ +--- +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] +--- + +Use the `Prev` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ with .Prev }} + <li><a href="{{ .URL }}">Previous</a></li> + {{ end }} + {{ with .Next }} + <li><a href="{{ .URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/TotalNumberOfElements.md b/docs/content/en/methods/pager/TotalNumberOfElements.md new file mode 100644 index 000000000..3cd1c8dad --- /dev/null +++ b/docs/content/en/methods/pager/TotalNumberOfElements.md @@ -0,0 +1,25 @@ +--- +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] +--- + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + {{ .TotalNumberOfElements }} +{{ end }} +``` diff --git a/docs/content/en/methods/pager/TotalPages.md b/docs/content/en/methods/pager/TotalPages.md new file mode 100644 index 000000000..e305beeff --- /dev/null +++ b/docs/content/en/methods/pager/TotalPages.md @@ -0,0 +1,41 @@ +--- +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] +--- + +Use the `TotalPages` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <p>Pager {{ .PageNumber }} of {{ .TotalPages }}</p> + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ with .Prev }} + <li><a href="{{ .URL }}">Previous</a></li> + {{ end }} + {{ with .Next }} + <li><a href="{{ .URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/URL.md b/docs/content/en/methods/pager/URL.md new file mode 100644 index 000000000..3daddbbd5 --- /dev/null +++ b/docs/content/en/methods/pager/URL.md @@ -0,0 +1,39 @@ +--- +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] +--- + +Use the `URL` method to build navigation between pagers. + +```go-html-template +{{ $pages := where site.RegularPages "Type" "posts" }} +{{ $paginator := .Paginate $pages }} + +{{ range $paginator.Pages }} + <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> +{{ end }} + +{{ with $paginator }} + <ul> + {{ with .First }} + <li><a href="{{ .URL }}">First</a></li> + {{ end }} + {{ with .Prev }} + <li><a href="{{ .URL }}">Previous</a></li> + {{ end }} + {{ with .Next }} + <li><a href="{{ .URL }}">Next</a></li> + {{ end }} + {{ with .Last }} + <li><a href="{{ .URL }}">Last</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/methods/pager/_index.md b/docs/content/en/methods/pager/_index.md new file mode 100644 index 000000000..58a1def7b --- /dev/null +++ b/docs/content/en/methods/pager/_index.md @@ -0,0 +1,14 @@ +--- +title: Pager methods +linkTitle: Pager +description: Use these methods with Pager objects when paginating a 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/_common/_index.md b/docs/content/en/methods/pages/_common/_index.md index 47d5812fb..4328d4d14 100644 --- a/docs/content/en/methods/pages/_common/_index.md +++ b/docs/content/en/methods/pages/_common/_index.md @@ -7,7 +7,7 @@ cascade: --- <!-- -Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. +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/Colors.md b/docs/content/en/methods/resource/Colors.md index 1452d558f..b062210ba 100644 --- a/docs/content/en/methods/resource/Colors.md +++ b/docs/content/en/methods/resource/Colors.md @@ -5,18 +5,174 @@ categories: [] keywords: [] action: related: [] - returnType: '[]string' + returnType: '[]images.Color' signatures: [RESOURCE.Colors] +toc: true +math: true --- {{< new-in 0.104.0 >}} +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 "methods/resource/_common/global-page-remote-resources.md" %}} + +## 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. + +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. + +Hugo renders an `images.Color` object as a hexadecimal color value. + +[`images.Dither`]: /functions/images/dither/ +[`images.Padding`]: /functions/images/padding/ +[`images.Text`]: /functions/images/text/ +{{% /note %}} + +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color +[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance + +## Sorting + +As a contrived example, create a table of an image's dominant colors with the most dominant color first, and display the relative luminance of each dominant color: + ```go-html-template {{ with resources.Get "images/a.jpg" }} - {{ .Colors }} → [#bebebd #514947 #768a9a #647789 #90725e #a48974] + <table> + <thead> + <tr> + <th>Color</th> + <th>Relative luminance</th> + </tr> + </thead> + <tbody> + {{ range .Colors }} + <tr> + <td>{{ .ColorHex }}</td> + <td>{{ .Luminance | lang.FormatNumber 4 }}</td> + </tr> + {{ end }} + </tbody> + </table> {{ end }} ``` -This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled image. +Hugo renders this to: -{{% include "methods/resource/_common/global-page-remote-resources.md" %}} +ColorHex|Relative luminance +:--|:-- +`#bebebd`|`0.5145` +`#514947`|`0.0697` +`#768a9a`|`0.2436` +`#647789`|`0.1771` +`#90725e`|`0.1877` +`#a48974`|`0.2704` + +To sort by dominance with the least dominant color first: + +```go-html-template +{{ range .Colors | collections.Reverse }} +``` + +To sort by relative luminance with the darkest color first: + +```go-html-template +{{ range sort .Colors "Luminance" }} +``` + +To sort by relative luminance with the lightest color first, use either of these constructs: + +```go-html-template +{{ range sort .Colors "Luminance" | collections.Reverse }} +{{ range sort .Colors "Luminance" "desc" }} +``` + +## Examples + +### Image borders + +To add a 5 pixel border to an image using the most dominant color: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ $mostDominant := index .Colors 0 }} + {{ $filter := images.Padding 5 $mostDominant }} + {{ with .Filter $filter }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +To add a 5 pixel border to an image using the darkest dominant color: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ $darkest := index (sort .Colors "Luminance") 0 }} + {{ $filter := images.Padding 5 $darkest }} + {{ with .Filter $filter }} + <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> + {{ end }} +{{ end }} +``` + +### Light text on dark background + +To create a text box where the foreground and background colors are derived from an image's lightest and darkest dominant colors: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ $darkest := index (sort .Colors "Luminance") 0 }} + {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }} + <div style="background: {{ $darkest }};"> + <div style="color: {{ $lightest }};"> + <p>This is light text on a dark background.</p> + </div> + </div> +{{ end }} +``` + +### WCAG contrast ratio + +In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG] guidelines for either the [minimum] or the [enhanced] contrast ratio? + +The WCAG defines the [contrast ratio] as: + +$$contrast\ ratio = { L_1 + 0.05 \over L_2 + 0.05 }$$ + +where $L_1$ is the relative luminance of the lightest color and $L_2$ is the relative luminance of the darkest color. + +Calculate the contrast ratio to determine WCAG conformance: + +```go-html-template +{{ with resources.Get "images/a.jpg" }} + {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }} + {{ $darkest := index (sort .Colors "Luminance") 0 }} + {{ $cr := div + (add $lightest.Luminance 0.05) + (add $darkest.Luminance 0.05) + }} + {{ if ge $cr 7.5 }} + {{ printf "The %.2f contrast ratio conforms to WCAG Level AAA." $cr }} + {{ else if ge $cr 4.5 }} + {{ printf "The %.2f contrast ratio conforms to WCAG Level AA." $cr }} + {{ else }} + {{ printf "The %.2f contrast ratio does not conform to WCAG guidelines." $cr }} + {{ end }} +{{ end }} +``` + + +[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines +[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio +[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced +[minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum diff --git a/docs/content/en/methods/resource/Content.md b/docs/content/en/methods/resource/Content.md index a5945ff65..4135113e9 100644 --- a/docs/content/en/methods/resource/Content.md +++ b/docs/content/en/methods/resource/Content.md @@ -12,7 +12,7 @@ toc: 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 +[resource type]: /methods/resource/resourcetype/ {{< code file=assets/quotations/kipling.txt >}} He travels the fastest who travels alone. diff --git a/docs/content/en/methods/resource/Data.md b/docs/content/en/methods/resource/Data.md index 0fbaf6199..43108fce8 100644 --- a/docs/content/en/methods/resource/Data.md +++ b/docs/content/en/methods/resource/Data.md @@ -13,7 +13,7 @@ action: The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response. -[`resources.GetRemote`]: functions/resources/getremote +[`resources.GetRemote`]: /functions/resources/getremote/ ```go-html-template {{ $url := "https://example.org/images/a.jpg" }} @@ -50,4 +50,4 @@ TransferEncoding : (`string`) The transfer encoding. -[`resources.GetRemote`]: functions/resources/getremote +[`resources.GetRemote`]: /functions/resources/getremote/ diff --git a/docs/content/en/methods/resource/Err.md b/docs/content/en/methods/resource/Err.md index f4b410aa7..6baa30e47 100644 --- a/docs/content/en/methods/resource/Err.md +++ b/docs/content/en/methods/resource/Err.md @@ -13,7 +13,7 @@ action: 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. -[`resources.GetRemote`]: functions/resources/getremote +[`resources.GetRemote`]: /functions/resources/getremote/ In this example we send an HTTP request to a nonexistent domain: diff --git a/docs/content/en/methods/resource/Exif.md b/docs/content/en/methods/resource/Exif.md index 765b4c92f..1d00ef3bc 100644 --- a/docs/content/en/methods/resource/Exif.md +++ b/docs/content/en/methods/resource/Exif.md @@ -15,7 +15,7 @@ Applicable to JPEG and TIFF images, the `Exif` method on an image `Resource` obj ## Methods Date -: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function. +: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function. Lat : (`float64`) Returns the GPS latitude in degrees. @@ -75,4 +75,4 @@ To list specific values: [exif]: https://en.wikipedia.org/wiki/Exif [site configuration]: /content-management/image-processing/#exif-data -[`time.Format`]: /functions/time/format +[`time.Format`]: /functions/time/format/ diff --git a/docs/content/en/methods/resource/Filter.md b/docs/content/en/methods/resource/Filter.md index 329168da7..9db6bbe17 100644 --- a/docs/content/en/methods/resource/Filter.md +++ b/docs/content/en/methods/resource/Filter.md @@ -39,7 +39,7 @@ To apply two or more filters, executing from left to right: You can also apply image filters using the [`images.Filter`] function. -[`images.Filter`]: /functions/images/filter +[`images.Filter`]: /functions/images/filter/ {{% 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 index 15927aea9..deeba9ab3 100644 --- a/docs/content/en/methods/resource/Key.md +++ b/docs/content/en/methods/resource/Key.md @@ -1,6 +1,7 @@ --- title: Key description: Returns the unique key for the given resource, equivalent to its publishing path. +draft: true categories: [] keywords: [] action: @@ -40,6 +41,6 @@ The `Key` method is useful if you need to get the resource's publishing path wit {{% include "methods/resource/_common/global-page-remote-resources.md" %}} -[`Permalink`]: /methods/resource/permalink -[`RelPermalink`]: /methods/resource/relpermalink -[`resources.Copy`]: /functions/resources/copy +[`Permalink`]: /methods/resource/permalink/ +[`RelPermalink`]: /methods/resource/relpermalink/ +[`resources.Copy`]: /functions/resources/copy/ diff --git a/docs/content/en/methods/resource/Name.md b/docs/content/en/methods/resource/Name.md index 01b75e5b2..694b67baa 100644 --- a/docs/content/en/methods/resource/Name.md +++ b/docs/content/en/methods/resource/Name.md @@ -1,6 +1,6 @@ --- title: Name -description: Returns the name of the given resource as optionally defined in front matter, falling back to a relative path or hashed file name depending on resource type. +description: Returns the name of the given resource as optionally defined in front matter, falling back to its file path. categories: [] keywords: [] action: @@ -20,51 +20,63 @@ With a [global resource], the `Name` method returns the path to the resource, re ```text assets/ └── images/ - └── a.jpg + └── Sunrise in Bryce Canyon.jpg ``` ```go-html-template -{{ with resources.Get "images/a.jpg" }} - {{ .Name }} → images/a.jpg +{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }} + {{ .Name }} → /images/Sunrise in Bryce Canyon.jpg {{ end }} ``` ## Page resource -With a [page resource], the `Name` method returns the path to the resource, relative to the page bundle. +With a [page resource], if you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter. ```text content/ -├── posts/ -│ ├── post-1/ -│ │ ├── images/ -│ │ │ └── a.jpg -│ │ └── index.md -│ └── _index.md +├── example/ +│ ├── images/ +│ │ └── a.jpg +│ └── index.md └── _index.md ``` +{{< code-toggle file=content/example/index.md fm=true >}} +title = 'Example' +[[resources]] +src = 'images/a.jpg' +name = 'Sunrise in Bryce Canyon' +{{< /code-toggle >}} + ```go-html-template {{ with .Resources.Get "images/a.jpg" }} - {{ .Name }} → images/a.jpg + {{ .Name }} → Sunrise in Bryce Canyon {{ end }} ``` -If you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter: +You can also capture the image by specifying its `name` instead of its path: -{{< code-toggle file=content/posts/post-1.md fm=true >}} -title = 'Post 1' -[[resources]] -src = 'images/a.jpg' -name = 'cat' -title = 'Felix the cat' -[resources.params] -temperament = 'malicious' -{{< /code-toggle >}} +```go-html-template +{{ with .Resources.Get "Sunrise in Bryce Canyon" }} + {{ .Name }} → Sunrise in Bryce Canyon +{{ end }} +``` + +If you do not create an element in the `resources` array in front matter, the `Name` method returns the file path, relative to the page bundle. + +```text +content/ +├── example/ +│ ├── images/ +│ │ └── Sunrise in Bryce Canyon.jpg +│ └── index.md +└── _index.md +``` ```go-html-template -{{ with .Resources.Get "cat" }} - {{ .Name }} → cat +{{ with .Resources.Get "images/Sunrise in Bryce Canyon.jpg" }} + {{ .Name }} → images/Sunrise in Bryce Canyon.jpg {{ end }} ``` ## Remote resource @@ -73,10 +85,11 @@ With a [remote resource], the `Name` method returns a hashed file name. ```go-html-template {{ with resources.GetRemote "https://example.org/images/a.jpg" }} - {{ .Name }} → a_18432433023265451104.jpg + {{ .Name }} → /a_18432433023265451104.jpg {{ end }} ``` [global resource]: /getting-started/glossary/#global-resource +[logical path]: /getting-started/glossary/#logical-path [page resource]: /getting-started/glossary/#page-resource [remote resource]: /getting-started/glossary/#remote-resource diff --git a/docs/content/en/methods/resource/Params.md b/docs/content/en/methods/resource/Params.md index 275182c46..ff6707f0b 100644 --- a/docs/content/en/methods/resource/Params.md +++ b/docs/content/en/methods/resource/Params.md @@ -62,4 +62,4 @@ Hugo renders: See the [page resources] section for more information. -[page resources]: /content-management/page-resources +[page resources]: /content-management/page-resources/ diff --git a/docs/content/en/methods/resource/Permalink.md b/docs/content/en/methods/resource/Permalink.md index ab0ad41b0..e0fa9aa87 100644 --- a/docs/content/en/methods/resource/Permalink.md +++ b/docs/content/en/methods/resource/Permalink.md @@ -7,7 +7,6 @@ action: related: - methods/resource/RelPermalink - methods/resource/Publish - - methods/resource/Key returnType: string signatures: [RESOURCE.Permalink] --- diff --git a/docs/content/en/methods/resource/Process.md b/docs/content/en/methods/resource/Process.md index 3c88492df..550b06401 100644 --- a/docs/content/en/methods/resource/Process.md +++ b/docs/content/en/methods/resource/Process.md @@ -59,8 +59,8 @@ The `Process` method is also available as a filter, which is more effective if y example=true >}} -[`Crop`]: /methods/resource/crop -[`Fill`]: /methods/resource/fill -[`Fit`]: /methods/resource/fit -[`Resize`]: /methods/resource/resize -[`images.Process`]: /functions/images/process +[`Crop`]: /methods/resource/crop/ +[`Fill`]: /methods/resource/fill/ +[`Fit`]: /methods/resource/fit/ +[`Resize`]: /methods/resource/resize/ +[`images.Process`]: /functions/images/process/ diff --git a/docs/content/en/methods/resource/Publish.md b/docs/content/en/methods/resource/Publish.md index b090bfe5a..05344c658 100644 --- a/docs/content/en/methods/resource/Publish.md +++ b/docs/content/en/methods/resource/Publish.md @@ -7,7 +7,6 @@ action: related: - methods/resource/Permalink - methods/resource/RelPermalink - - methods/resource/Key returnType: nil signatures: [RESOURCE.Publish] --- diff --git a/docs/content/en/methods/resource/RelPermalink.md b/docs/content/en/methods/resource/RelPermalink.md index 2b96c35d7..190cdf64a 100644 --- a/docs/content/en/methods/resource/RelPermalink.md +++ b/docs/content/en/methods/resource/RelPermalink.md @@ -7,7 +7,6 @@ action: related: - methods/resource/Permalink - methods/resource/Publish - - methods/resource/Key returnType: string signatures: [RESOURCE.RelPermalink] --- diff --git a/docs/content/en/methods/resource/Title.md b/docs/content/en/methods/resource/Title.md index e30f86d2e..c620c2448 100644 --- a/docs/content/en/methods/resource/Title.md +++ b/docs/content/en/methods/resource/Title.md @@ -20,73 +20,65 @@ With a [global resource], the `Title` method returns the path to the resource, r ```text assets/ └── images/ - └── a.jpg + └── Sunrise in Bryce Canyon.jpg ``` ```go-html-template -{{ with resources.Get "images/a.jpg" }} - {{ .Title }} → images/a.jpg +{{ with resources.Get "images/Sunrise in Bryce Canyon.jpg" }} + {{ .Title }} → /images/Sunrise in Bryce Canyon.jpg {{ end }} ``` ## Page resource -With a [page resource], the `Title` method returns the path to the resource, relative to the page bundle. +With a [page resource], if you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter. ```text content/ -├── posts/ -│ ├── post-1/ -│ │ ├── images/ -│ │ │ └── a.jpg -│ │ └── index.md -│ └── _index.md +├── example/ +│ ├── images/ +│ │ └── a.jpg +│ └── index.md └── _index.md ``` -```go-html-template -{{ with .Resources.Get "images/a.jpg" }} - {{ .Title }} → images/a.jpg -{{ end }} -``` - -If you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter: - -{{< code-toggle file=content/posts/post-1.md fm=true >}} -title = 'Post 1' +{{< code-toggle file=content/example/index.md fm=true >}} +title = 'Example' [[resources]] src = 'images/a.jpg' -name = 'cat' -title = 'Felix the cat' -[resources.params] -temperament = 'malicious' +title = 'A beautiful sunrise in Bryce Canyon' {{< /code-toggle >}} ```go-html-template -{{ with .Resources.Get "cat" }} - {{ .Title }} → Felix the cat +{{ with .Resources.Get "images/a.jpg" }} + {{ .Title }} → A beautiful sunrise in Bryce Canyon {{ end }} ``` -If the page resource is a content file, the `Title` methods return the `title` field as defined in front matter. +If you do not create an element in the `resources` array in front matter, the `Title` method returns the file path, relative to the page bundle. ```text content/ -├── lessons/ -│ ├── lesson-1/ -│ │ ├── _objectives.md <-- resource type = page -│ │ └── index.md -│ └── _index.md +├── example/ +│ ├── images/ +│ │ └── Sunrise in Bryce Canyon.jpg +│ └── index.md └── _index.md ``` +```go-html-template +{{ with .Resources.Get "Sunrise in Bryce Canyon.jpg" }} + {{ .Title }} → images/Sunrise in Bryce Canyon.jpg +{{ end }} +``` + ## Remote resource With a [remote resource], the `Title` method returns a hashed file name. ```go-html-template {{ with resources.GetRemote "https://example.org/images/a.jpg" }} - {{ .Title }} → a_18432433023265451104.jpg + {{ .Title }} → /a_18432433023265451104.jpg {{ end }} ``` diff --git a/docs/content/en/methods/resource/_common/_index.md b/docs/content/en/methods/resource/_common/_index.md index 47d5812fb..4328d4d14 100644 --- a/docs/content/en/methods/resource/_common/_index.md +++ b/docs/content/en/methods/resource/_common/_index.md @@ -7,7 +7,7 @@ cascade: --- <!-- -Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. +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/shortcode/Get.md b/docs/content/en/methods/shortcode/Get.md index cd674614f..8874c7649 100644 --- a/docs/content/en/methods/shortcode/Get.md +++ b/docs/content/en/methods/shortcode/Get.md @@ -1,6 +1,6 @@ --- title: Get -description: Returns the value of the given parameter. +description: Returns the value of the given argument. categories: [] keywords: [] action: @@ -8,44 +8,44 @@ action: - methods/shortcode/IsNamedParams - methods/shortcode/Params returnType: any - signatures: [SHORTCODE.Get PARAM] + signatures: [SHORTCODE.Get ARG] toc: true --- -Specify the parameter by position or by name. When calling a shortcode within markdown, use either positional or named parameters, but not both. +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 parameters, some support named parameters, and others support both. Refer to the shortcode's documentation for usage details. +Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details. {{% /note %}} -## Positional parameters +## Positional arguments -This shortcode call uses positional parameters: +This shortcode call uses positional arguments: {{< code file=content/about.md lang=md >}} {{</* myshortcode "Hello" "world" */>}} {{< /code >}} -To retrieve parameters by position: +To retrieve arguments by position: {{< code file=layouts/shortcodes/myshortcode.html >}} {{ printf "%s %s." (.Get 0) (.Get 1) }} → Hello world. {{< /code >}} -## Named parameters +## Named arguments -This shortcode call uses named parameters: +This shortcode call uses named arguments: {{< code file=content/about.md lang=md >}} {{</* myshortcode greeting="Hello" firstName="world" */>}} {{< /code >}} -To retrieve parameters by name: +To retrieve arguments by name: {{< code file=layouts/shortcodes/myshortcode.html >}} {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world. {{< /code >}} {{% note %}} -Parameter names are case-sensitive. +Argument names are case-sensitive. {{% /note %}} diff --git a/docs/content/en/methods/shortcode/Inner.md b/docs/content/en/methods/shortcode/Inner.md index de7c284cb..9271adb34 100644 --- a/docs/content/en/methods/shortcode/Inner.md +++ b/docs/content/en/methods/shortcode/Inner.md @@ -46,13 +46,13 @@ Is rendered to: ``` {{% note %}} -Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines. +Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`trim`] function as shown above to remove both carriage returns and newlines. -[`trim`]: /functions/strings/trim +[`trim`]: /functions/strings/trim/ {{% /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. +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 %}} @@ -60,7 +60,7 @@ In the example above, the value returned by `Inner` is markdown, but it was rend 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 +[`RenderString`]: /methods/page/renderstring/ {{< code file=layouts/shortcodes/card.html >}} <div class="card"> @@ -86,8 +86,8 @@ 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 +[details]: /methods/page/renderstring/ +[`markdownify`]: /functions/transform/markdownify/ ## Use alternate notation @@ -99,9 +99,9 @@ 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. +When you use the `{{%/* */%}}` notation, Hugo renders the entire shortcode as Markdown, requiring the following changes. -First, configure the renderer to allow raw HTML within markdown: +First, configure the renderer to allow raw HTML within Markdown: {{< code-toggle file=hugo >}} [markup.goldmark.renderer] @@ -110,7 +110,7 @@ unsafe = true This configuration is not unsafe if _you_ control the content. Read more about Hugo's [security model]. -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. +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 >}} <div class="card"> @@ -150,4 +150,4 @@ When using the `{{%/* */%}}` notation, do not pass the value returned by `Inner` [commonmark]: https://commonmark.org/ [indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks [raw html blocks]: https://spec.commonmark.org/0.30/#html-blocks -[security model]: /about/security-model/ +[security model]: /about/security/ diff --git a/docs/content/en/methods/shortcode/InnerDeindent.md b/docs/content/en/methods/shortcode/InnerDeindent.md index 136412bc7..b5f5cf206 100644 --- a/docs/content/en/methods/shortcode/InnerDeindent.md +++ b/docs/content/en/methods/shortcode/InnerDeindent.md @@ -14,7 +14,7 @@ Similar to the [`Inner`] method, `InnerDeindent` returns the content between ope This allows us to effectively bypass the rules governing [indentation] as provided in the [CommonMark] specification. -Consider this markdown, an unordered list with a small gallery of thumbnail images within each list item: +Consider this Markdown, an unordered list with a small gallery of thumbnail images within each list item: {{< code file=content/about.md lang=md >}} - Gallery one @@ -42,7 +42,7 @@ With this shortcode, calling `Inner` instead of `InnerDeindent`: </div> {{< /code >}} -Hugo renders the markdown to: +Hugo renders the Markdown to: ```html <ul> @@ -73,7 +73,7 @@ Although technically correct per the CommonMark specification, this is not what </div> {{< /code >}} -Hugo renders the markdown to: +Hugo renders the Markdown to: ```html <ul> @@ -96,4 +96,4 @@ Hugo renders the markdown to: [commonmark]: https://commonmark.org/ [indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks -[`Inner`]: /methods/shortcode/inner +[`Inner`]: /methods/shortcode/inner/ diff --git a/docs/content/en/methods/shortcode/IsNamedParams.md b/docs/content/en/methods/shortcode/IsNamedParams.md index 83eeb2f74..a1d93ddac 100644 --- a/docs/content/en/methods/shortcode/IsNamedParams.md +++ b/docs/content/en/methods/shortcode/IsNamedParams.md @@ -1,6 +1,6 @@ --- title: IsNamedParams -description: Reports whether the shortcode call uses named parameters. +description: Reports whether the shortcode call uses named arguments. categories: [] keywords: [] action: @@ -10,7 +10,7 @@ action: signatures: [SHORTCODE.IsNamedParams] --- -To support both positional and named parameters when calling a shortcode, use the `IsNamedParams` method to determine how the shortcode was called. +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: diff --git a/docs/content/en/methods/shortcode/Name.md b/docs/content/en/methods/shortcode/Name.md index 18bddfe1f..fcf92718f 100644 --- a/docs/content/en/methods/shortcode/Name.md +++ b/docs/content/en/methods/shortcode/Name.md @@ -11,19 +11,19 @@ action: signatures: [SHORTCODE.Name] --- -The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter: +The `Name` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument: {{< code file=layouts/shortcodes/myshortcode.html >}} {{ $greeting := "" }} {{ with .Get "greeting" }} {{ $greeting = . }} {{ else }} - {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }} + {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }} {{ end }} {{< /code >}} -In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build: +In the absence of a "greeting" argument, Hugo will throw an error message and fail the build: ```text -ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1" +ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1" ``` diff --git a/docs/content/en/methods/shortcode/Ordinal.md b/docs/content/en/methods/shortcode/Ordinal.md index 954940258..6f3580d0f 100644 --- a/docs/content/en/methods/shortcode/Ordinal.md +++ b/docs/content/en/methods/shortcode/Ordinal.md @@ -32,7 +32,7 @@ This shortcode performs error checking, then renders an HTML `img` element with {{ errorf "The %q shortcode was unable to find %s. See %s" $.Name $src $.Position }} {{ end }} {{ else }} - {{ errorf "The %q shortcode requires a 'src' parameter. See %s" .Name .Position }} + {{ errorf "The %q shortcode requires a 'src' argument. See %s" .Name .Position }} {{ end }} {{< /code >}} @@ -46,5 +46,5 @@ Hugo renders the page to: {{% 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 +[`with`]: /functions/go-template/with/ {{% /note %}} diff --git a/docs/content/en/methods/shortcode/Params.md b/docs/content/en/methods/shortcode/Params.md index 63df768a6..c0772e36a 100644 --- a/docs/content/en/methods/shortcode/Params.md +++ b/docs/content/en/methods/shortcode/Params.md @@ -1,6 +1,6 @@ --- title: Params -description: Returns a collection of the shortcode parameters. +description: Returns a collection of the shortcode arguments. categories: [] keywords: [] action: @@ -10,7 +10,7 @@ action: signatures: [SHORTCODE.Params] --- -When you call a shortcode using positional parameters, the `Params` method returns a slice. +When you call a shortcode using positional arguments, the `Params` method returns a slice. {{< code file=content/about.md lang=md >}} {{</* myshortcode "Hello" "world" */>}} @@ -21,7 +21,7 @@ When you call a shortcode using positional parameters, the `Params` method retur {{ index .Params 1 }} → world {{< /code >}} -When you call a shortcode using named parameters, the `Params` method returns a map. +When you call a shortcode using named arguments, the `Params` method returns a map. {{< code file=content/about.md lang=md >}} {{</* myshortcode greeting="Hello" name="world" */>}} diff --git a/docs/content/en/methods/shortcode/Parent.md b/docs/content/en/methods/shortcode/Parent.md index 50ae521da..c500af375 100644 --- a/docs/content/en/methods/shortcode/Parent.md +++ b/docs/content/en/methods/shortcode/Parent.md @@ -9,7 +9,7 @@ action: signatures: [SHORTCODE.Parent] --- -This is useful for inheritance of common shortcode parameters from the root. +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. @@ -45,6 +45,6 @@ Welcome. Today is {{</* now */>}}. The "now" shortcode formats the current time using: -1. The `dateFormat` parameter passed to the "now" shortcode, if present -2. The `dateFormat` parameter passed to the "greeting" shortcode, if present +1. The `dateFormat` argument passed to the "now" shortcode, if present +2. The `dateFormat` argument passed to the "greeting" shortcode, if present 3. The default layout string defined at the top of the shortcode diff --git a/docs/content/en/methods/shortcode/Position.md b/docs/content/en/methods/shortcode/Position.md index 565a158bf..6f047c01b 100644 --- a/docs/content/en/methods/shortcode/Position.md +++ b/docs/content/en/methods/shortcode/Position.md @@ -11,21 +11,21 @@ action: signatures: [SHORTCODE.Position] --- -The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" parameter: +The `Position` method is useful for error reporting. For example, if your shortcode requires a "greeting" argument: {{< code file=layouts/shortcodes/myshortcode.html >}} {{ $greeting := "" }} {{ with .Get "greeting" }} {{ $greeting = . }} {{ else }} - {{ errorf "The %q shortcode requires a 'greeting' parameter. See %s" .Name .Position }} + {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }} {{ end }} {{< /code >}} -In the absence of a "greeting" parameter, Hugo will throw an error message and fail the build: +In the absence of a "greeting" argument, Hugo will throw an error message and fail the build: ```text -ERROR The "myshortcode" shortcode requires a 'greeting' parameter. See "/home/user/project/content/about.md:11:1" +ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1" ``` {{% note %}} diff --git a/docs/content/en/methods/shortcode/Scratch.md b/docs/content/en/methods/shortcode/Scratch.md index 3ab195a3f..fcfc99d53 100644 --- a/docs/content/en/methods/shortcode/Scratch.md +++ b/docs/content/en/methods/shortcode/Scratch.md @@ -1,6 +1,6 @@ --- title: Scratch -description: Creates a "scratch pad" scoped to the shortcode to store and manipulate data. +description: Returns a "scratch pad" scoped to the shortcode to store and manipulate data. categories: [] keywords: [] action: @@ -16,7 +16,7 @@ The `Scratch` method within a shortcode creates a [scratch pad] to store and man With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Scratch` method within a shortcode is obsolete. [assign values to template variables]: https://go.dev/doc/go1.11#text/template -[`newScratch`]: functions/collections/newscratch +[`newScratch`]: /functions/collections/newscratch/ {{% /note %}} [scratch pad]: /getting-started/glossary/#scratch-pad diff --git a/docs/content/en/methods/shortcode/Site.md b/docs/content/en/methods/shortcode/Site.md index fa2d274de..af2a755ee 100644 --- a/docs/content/en/methods/shortcode/Site.md +++ b/docs/content/en/methods/shortcode/Site.md @@ -12,7 +12,7 @@ action: See [Site methods]. -[Site methods]: /methods/site +[Site methods]: /methods/site/ ```go-html-template {{ .Site.Title }} diff --git a/docs/content/en/methods/site/AllPages.md b/docs/content/en/methods/site/AllPages.md index 8df6348f9..e02c2cbbc 100644 --- a/docs/content/en/methods/site/AllPages.md +++ b/docs/content/en/methods/site/AllPages.md @@ -16,7 +16,7 @@ This method returns all page [kinds] in all languages. That includes the home pa In most cases you should use the [`RegularPages`] method instead. -[`RegularPages`]: methods/site/regularpages +[`RegularPages`]: /methods/site/regularpages/ [kinds]: /getting-started/glossary/#page-kind ```go-html-template diff --git a/docs/content/en/methods/site/BaseURL.md b/docs/content/en/methods/site/BaseURL.md index f9c43bca3..ea965a568 100644 --- a/docs/content/en/methods/site/BaseURL.md +++ b/docs/content/en/methods/site/BaseURL.md @@ -30,8 +30,8 @@ There is almost never a good reason to use this method in your templates. Its us Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead. -[`absURL`]: /functions/urls/absURL -[`absLangURL`]: /functions/urls/absLangURL -[`relURL`]: /functions/urls/relURL -[`relLangURL`]: /functions/urls/relLangURL +[`absURL`]: /functions/urls/absURL/ +[`absLangURL`]: /functions/urls/absLangURL/ +[`relURL`]: /functions/urls/relURL/ +[`relLangURL`]: /functions/urls/relLangURL/ {{% /note %}} diff --git a/docs/content/en/methods/site/Data.md b/docs/content/en/methods/site/Data.md index b78caddec..65cdadd01 100644 --- a/docs/content/en/methods/site/Data.md +++ b/docs/content/en/methods/site/Data.md @@ -20,7 +20,7 @@ Use the `Data` method on a `Site` object to access data within the data director {{% 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 +[`transform.Unmarshal`]: /functions/transform/unmarshal/ {{% /note %}} Consider this data directory: @@ -101,8 +101,14 @@ To find a fiction book by ISBN: {{ end }} ``` -In the template examples 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: +In the template examples 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. For example: -[`index`]: /functions/collections/indexfunction +[identifier]: /getting-started/glossary/#identifier + +```go-html-template +{{ index .Site.Data.books "historical-fiction" }} +``` + +[`index`]: /functions/collections/indexfunction/ [chaining]: /getting-started/glossary/#chain [identifiers]: /getting-started/glossary/#identifier diff --git a/docs/content/en/methods/site/DisqusShortname.md b/docs/content/en/methods/site/DisqusShortname.md index 2d4447485..0e900ac4e 100644 --- a/docs/content/en/methods/site/DisqusShortname.md +++ b/docs/content/en/methods/site/DisqusShortname.md @@ -13,5 +13,5 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30 {{% deprecated-in 0.120.0 %}} Use [`Site.Config.Services.Disqus.Shortname`] instead. -[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config +[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config/ {{% /deprecated-in %}} diff --git a/docs/content/en/methods/site/GetPage.md b/docs/content/en/methods/site/GetPage.md index b7d4b8f32..3505e582a 100644 --- a/docs/content/en/methods/site/GetPage.md +++ b/docs/content/en/methods/site/GetPage.md @@ -13,7 +13,7 @@ toc: true The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See [details]. -[details]: /methods/page/getpage +[details]: /methods/page/getpage/ When using the `GetPage` method on a `Site` object, specify a path relative to the content directory. diff --git a/docs/content/en/methods/site/GoogleAnalytics.md b/docs/content/en/methods/site/GoogleAnalytics.md index 50f479b49..c58974452 100644 --- a/docs/content/en/methods/site/GoogleAnalytics.md +++ b/docs/content/en/methods/site/GoogleAnalytics.md @@ -13,5 +13,5 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30 {{% deprecated-in 0.120.0 %}} Use [`Site.Config.Services.GoogleAnalytics.ID`] instead. -[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config +[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config/ {{% /deprecated-in %}} diff --git a/docs/content/en/methods/site/IsDevelopment.md b/docs/content/en/methods/site/IsDevelopment.md index c009ba0de..6f443316b 100644 --- a/docs/content/en/methods/site/IsDevelopment.md +++ b/docs/content/en/methods/site/IsDevelopment.md @@ -13,7 +13,7 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30 {{% deprecated-in 0.120.0 %}} Use [`hugo.IsDevelopment`] instead. -[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment +[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment/ {{% /deprecated-in %}} ```go-html-template diff --git a/docs/content/en/methods/site/IsMultiLingual.md b/docs/content/en/methods/site/IsMultiLingual.md index 61cc5e462..a14283787 100644 --- a/docs/content/en/methods/site/IsMultiLingual.md +++ b/docs/content/en/methods/site/IsMultiLingual.md @@ -1,6 +1,6 @@ --- title: IsMultiLingual -description: Reports whether the site is multilingual. +description: Reports whether there are two or more configured languages. categories: [] keywords: [] action: @@ -9,6 +9,12 @@ action: signatures: [SITE.IsMultiLingual] --- +{{% deprecated-in 0.124.0 %}} +Use [`hugo.IsMultilingual`] instead. + +[`hugo.IsMultilingual`]: /functions/hugo/ismultilingual/ +{{% /deprecated-in %}} + Site configuration: {{< code-toggle file=hugo >}} diff --git a/docs/content/en/methods/site/IsServer.md b/docs/content/en/methods/site/IsServer.md index 3d5ce41b5..a688c553a 100644 --- a/docs/content/en/methods/site/IsServer.md +++ b/docs/content/en/methods/site/IsServer.md @@ -13,7 +13,7 @@ expiryDate: 2024-10-30 # deprecated 2023-10-30 {{% deprecated-in 0.120.0 %}} Use [`hugo.IsServer`] instead. -[`hugo.IsServer`]: /functions/hugo/isserver +[`hugo.IsServer`]: /functions/hugo/isserver/ {{% /deprecated-in %}} ```go-html-template diff --git a/docs/content/en/methods/site/Language.md b/docs/content/en/methods/site/Language.md index 1babc099b..7179038e4 100644 --- a/docs/content/en/methods/site/Language.md +++ b/docs/content/en/methods/site/Language.md @@ -35,7 +35,7 @@ Lang ``` LanguageCode -: (`string`) The language code from the site configuration. +: (`string`) The language code from the site configuration. Falls back to `Lang` if not defined. ```go-html-template {{ .Site.Language.LanguageCode }} → de-DE @@ -68,16 +68,10 @@ Some of the methods above are commonly used in a base template as attributes for ```go-html-template <html - lang="{{ or site.Language.LanguageCode site.Language.Lang }}" - dir="{{ or site.Language.LanguageDirection `ltr` }} + lang="{{ .Site.Language.LanguageCode }}" + dir="{{ or .Site.Language.LanguageDirection `ltr` }} > ``` -The example above uses the global [`site`] function instead of accessing the `Site` object via the `.Site` notation. - -Also note that each attribute has a fallback value assigned via the [`or`] operator. - -[details]: /methods/page/language +[details]: /methods/page/language/ [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 -[`or`]: /functions/go-template/or -[`site`]: /functions/global/site diff --git a/docs/content/en/methods/site/Languages.md b/docs/content/en/methods/site/Languages.md index 26bdefc21..cfa1ade6b 100644 --- a/docs/content/en/methods/site/Languages.md +++ b/docs/content/en/methods/site/Languages.md @@ -12,10 +12,10 @@ action: 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. -To view the data structure: +To inspect the data structure: ```go-html-template -<pre>{{ jsonify (dict "indent" " ") .Site.Languages }}</pre> +<pre>{{ debug.Dump .Site.Languages }}</pre> ``` With this site configuration: diff --git a/docs/content/en/methods/site/LastChange.md b/docs/content/en/methods/site/LastChange.md index aceee691d..2a8c3e491 100644 --- a/docs/content/en/methods/site/LastChange.md +++ b/docs/content/en/methods/site/LastChange.md @@ -9,13 +9,19 @@ action: signatures: [SITE.LastChange] --- +{{% deprecated-in 0.123.0 %}} +Use [`.Site.Lastmod`] instead. + +[`.Site.Lastmod`]: /methods/site/lastmod/ +{{% /deprecated-in %}} + The `LastChange` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example: ```go-html-template -{{ .Site.LastChange | time.Format ":date_long" }} → October 16, 2023 +{{ .Site.LastChange | time.Format ":date_long" }} → January 31, 2024 ``` [`time.Time`]: https://pkg.go.dev/time#Time -[functions]: /functions/time -[methods]: /methods/time +[functions]: /functions/time/ +[methods]: /methods/time/ diff --git a/docs/content/en/methods/site/Lastmod.md b/docs/content/en/methods/site/Lastmod.md new file mode 100644 index 000000000..081481956 --- /dev/null +++ b/docs/content/en/methods/site/Lastmod.md @@ -0,0 +1,23 @@ +--- +title: Lastmod +description: Returns the last modification date of site content. +categories: [] +keywords: [] +action: + related: [] + returnType: time.Time + signatures: [SITE.Lastmod] +--- + +{{< new-in 0.123.0 >}} + +The `Lastmod` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example: + +```go-html-template +{{ .Site.Lastmod | time.Format ":date_long" }} → January 31, 2024 + +``` + +[`time.Time`]: https://pkg.go.dev/time#Time +[functions]: /functions/time/ +[methods]: /methods/time/ diff --git a/docs/content/en/methods/site/Menus.md b/docs/content/en/methods/site/Menus.md index c204fe97b..98ce4e879 100644 --- a/docs/content/en/methods/site/Menus.md +++ b/docs/content/en/methods/site/Menus.md @@ -88,7 +88,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-templates +[menu templates]: /templates/menu-templates/ -[`partial`]: /functions/partials/include -[`partialCached`]: /functions/partials/includecached +[`partial`]: /functions/partials/include/ +[`partialCached`]: /functions/partials/includecached/ diff --git a/docs/content/en/methods/site/Pages.md b/docs/content/en/methods/site/Pages.md index 583e98c11..ac6e13c4a 100644 --- a/docs/content/en/methods/site/Pages.md +++ b/docs/content/en/methods/site/Pages.md @@ -16,7 +16,7 @@ This method returns all page [kinds] in the current language. That includes the In most cases you should use the [`RegularPages`] method instead. -[`RegularPages`]: methods/site/regularpages +[`RegularPages`]: /methods/site/regularpages/ [kinds]: /getting-started/glossary/#page-kind ```go-html-template diff --git a/docs/content/en/methods/site/Params.md b/docs/content/en/methods/site/Params.md index 518d93bf3..95e016b81 100644 --- a/docs/content/en/methods/site/Params.md +++ b/docs/content/en/methods/site/Params.md @@ -33,7 +33,7 @@ Access the custom parameters by [chaining] the [identifiers]: {{ .Site.Params.author.name }} → John Smith {{ $layout := .Site.Params.layouts.rfc_1123 }} -{{ .Site.LastChange.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT +{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT ``` 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: @@ -42,6 +42,6 @@ In the template example above, each of the keys is a valid identifier. For examp {{ index .Site.Params "copyright-year" }} → 2023 ``` -[`index`]: /functions/collections/indexfunction +[`index`]: /functions/collections/indexfunction/ [chaining]: /getting-started/glossary/#chain [identifiers]: /getting-started/glossary/#identifier diff --git a/docs/content/en/methods/site/Sites.md b/docs/content/en/methods/site/Sites.md index f7bafd3ed..ac287d3b4 100644 --- a/docs/content/en/methods/site/Sites.md +++ b/docs/content/en/methods/site/Sites.md @@ -1,6 +1,6 @@ --- title: Sites -description: Returns a collection of all Site objects, one for each language, ordered by language weight. +description: Returns a collection of all Site objects, one for each language, ordered by default content language then by language weight. categories: [] keywords: [] action: @@ -49,10 +49,10 @@ Produces a list of links to each home page: </ul> ``` -To render a link to home page of the primary (first) language: +To render a link to the home page of the site corresponding to the default content language: ```go-html-template -{{ with .Site.Sites.First }} +{{ with .Site.Sites.Default }} <a href="{{ .Home.Permalink }}">{{ .Title }}</a> {{ end }} ``` diff --git a/docs/content/en/methods/site/Taxonomies.md b/docs/content/en/methods/site/Taxonomies.md index 72bfc75d5..219fe188b 100644 --- a/docs/content/en/methods/site/Taxonomies.md +++ b/docs/content/en/methods/site/Taxonomies.md @@ -95,5 +95,5 @@ Hugo's taxonomy system is powerful, allowing you to classify content and create Please see the [taxonomies] section for a complete explanation and examples. -[taxonomies]: content-management/taxonomies/ +[taxonomies]: /content-management/taxonomies/ {{% /note %}} diff --git a/docs/content/en/methods/taxonomy/Alphabetical.md b/docs/content/en/methods/taxonomy/Alphabetical.md index 7845dbf3d..ea90cfdf9 100644 --- a/docs/content/en/methods/taxonomy/Alphabetical.md +++ b/docs/content/en/methods/taxonomy/Alphabetical.md @@ -34,7 +34,7 @@ To reverse the sort order: To inspect the data structure: ```go-html-template -<pre>{{ jsonify (dict "indent" " ") $taxonomyObject.Alphabetical }}</pre> +<pre>{{ debug.Dump $taxonomyObject.Alphabetical }}</pre> ``` {{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} diff --git a/docs/content/en/methods/taxonomy/ByCount.md b/docs/content/en/methods/taxonomy/ByCount.md index 40f58420a..68143ccff 100644 --- a/docs/content/en/methods/taxonomy/ByCount.md +++ b/docs/content/en/methods/taxonomy/ByCount.md @@ -34,7 +34,7 @@ To reverse the sort order: To inspect the data structure: ```go-html-template -<pre>{{ jsonify (dict "indent" " ") $taxonomyObject.ByCount }}</pre> +<pre>{{ debug.Dump $taxonomyObject.ByCount }}</pre> ``` {{% include "methods/taxonomy/_common/ordered-taxonomy-element-methods.md" %}} diff --git a/docs/content/en/methods/taxonomy/Get.md b/docs/content/en/methods/taxonomy/Get.md index 3bac86f08..79d25b704 100644 --- a/docs/content/en/methods/taxonomy/Get.md +++ b/docs/content/en/methods/taxonomy/Get.md @@ -43,7 +43,7 @@ You could also use the [`index`] function, but the syntax is more verbose: To inspect the data structure: ```go-html-template -<pre>{{ jsonify (dict "indent" " ") $weightedPages }}</pre> +<pre>{{ debug.Dump $weightedPages }}</pre> ``` ## Example @@ -66,7 +66,7 @@ Hugo renders: ``` [chaining]: /getting-started/glossary/#chain -[`index`]: /functions/collections/indexfunction +[`index`]: /functions/collections/indexfunction/ [identifier]: /getting-started/glossary/#identifier [term]: /getting-started/glossary/#term [weighted pages]: /getting-started/glossary/#weighted-page diff --git a/docs/content/en/methods/taxonomy/Page.md b/docs/content/en/methods/taxonomy/Page.md new file mode 100644 index 000000000..e148ac5c7 --- /dev/null +++ b/docs/content/en/methods/taxonomy/Page.md @@ -0,0 +1,26 @@ +--- +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] +--- + +{{< new-in 0.125.0 >}} + +This `TAXONOMY` method returns nil if the taxonomy has no terms, so you must code defensively: + +```go-html-template +{{ with .Site.Taxonomies.tags.Page }} + <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> +{{ end }} +``` + +This is rendered to: + +```html +<a href="/tags/">Tags</a> +``` diff --git a/docs/content/en/methods/taxonomy/_common/_index.md b/docs/content/en/methods/taxonomy/_common/_index.md index 47d5812fb..4328d4d14 100644 --- a/docs/content/en/methods/taxonomy/_common/_index.md +++ b/docs/content/en/methods/taxonomy/_common/_index.md @@ -7,7 +7,7 @@ cascade: --- <!-- -Files within this headless branch bundle are markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. +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 index 4c4fc42c9..6bf86cd85 100644 --- a/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md +++ b/docs/content/en/methods/taxonomy/_common/get-a-taxonomy-object.md @@ -41,7 +41,7 @@ To capture the "genres" taxonomy object when rendering its page with a taxonomy To inspect the data structure: ```go-html-template -<pre>{{ jsonify (dict "indent" " ") $taxonomyObject }}</pre> +<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: @@ -60,9 +60,9 @@ Although the [`Alphabetical`] and [`ByCount`] methods provide a better data stru In the example above, the first anchor element is a link to the term page. -[`Alphabetical`]: /methods/taxonomy/alphabetical -[`ByCount`]: /methods/taxonomy/bycount +[`Alphabetical`]: /methods/taxonomy/alphabetical/ +[`ByCount`]: /methods/taxonomy/bycount/ -[`data`]: /methods/page/data +[`data`]: /methods/page/data/ [`terms`]: /methods/page/data/#in-a-taxonomy-template -[`taxonomies`]: /methods/site/taxonomies +[`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 index 9c94729ba..7201ad318 100644 --- a/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md +++ b/docs/content/en/methods/taxonomy/_common/ordered-taxonomy-element-methods.md @@ -21,5 +21,5 @@ Term 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 +[methods]: /methods/pages/ [taxonomic weight]: /getting-started/glossary/#taxonomic-weight diff --git a/docs/content/en/methods/time/Format.md b/docs/content/en/methods/time/Format.md index fc3e2635c..d526b7b64 100644 --- a/docs/content/en/methods/time/Format.md +++ b/docs/content/en/methods/time/Format.md @@ -27,7 +27,7 @@ aliases: [/methods/time/format] To [localize] the return value, use the [`time.Format`] function instead. [localize]: /getting-started/glossary/#localization -[`time.Format`]: /functions/time/format +[`time.Format`]: /functions/time/format/ {{% /note %}} Use the `Format` method with any `time.Time` value, including the four predefined front matter dates: @@ -44,7 +44,7 @@ Use the `Format` method with any `time.Time` value, including the four predefine {{% 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 +[`time.Format`]: /functions/time/format/ {{% /note %}} ## Layout string diff --git a/docs/content/en/methods/time/Round.md b/docs/content/en/methods/time/Round.md new file mode 100644 index 000000000..988c56ba9 --- /dev/null +++ b/docs/content/en/methods/time/Round.md @@ -0,0 +1,26 @@ +--- +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] +--- + +The rounding behavior for halfway values is to round up. + +The `Round` method operates on TIME as an absolute duration since the [zero time]; it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Round` may return a time with a non-zero minute, depending on the time zone. + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $d := time.ParseDuration "1h"}} + +{{ ($t.Round $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-28T00:00:00-00:00 +``` + +[zero time]: /getting-started/glossary/#zero-time diff --git a/docs/content/en/methods/time/Truncate.md b/docs/content/en/methods/time/Truncate.md new file mode 100644 index 000000000..da6e0b26b --- /dev/null +++ b/docs/content/en/methods/time/Truncate.md @@ -0,0 +1,24 @@ +--- +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] +--- + +The `Truncate` method operates on TIME as an absolute duration since the [zero time]; 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. + +```go-html-template +{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }} +{{ $d := time.ParseDuration "1h"}} + +{{ ($t.Truncate $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-27T23:00:00-00:00 +``` + +[zero time]: /getting-started/glossary/#zero-time diff --git a/docs/content/en/methods/time/YearDay.md b/docs/content/en/methods/time/YearDay.md index 40d7d6aab..f380cdffe 100644 --- a/docs/content/en/methods/time/YearDay.md +++ b/docs/content/en/methods/time/YearDay.md @@ -1,6 +1,6 @@ --- 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. +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: |