{{ debug.Dump $taxonomyObject }}
```
-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:
+Although the [`Alphabetical`][] and [`ByCount`][] methods provide a better data structure for ranging through the taxonomy, you can render the weighted pages by term directly from the `Taxonomy` object:
```go-html-template
{{ range $term, $weightedPages := $taxonomyObject }}
@@ -61,7 +61,6 @@ In the example above, the first anchor element is a link to the term page.
[`Alphabetical`]: /methods/taxonomy/alphabetical/
[`ByCount`]: /methods/taxonomy/bycount/
-
-[`data`]: /methods/page/data/
-[`terms`]: /methods/page/data/#in-a-taxonomy-template
-[`taxonomies`]: /methods/site/taxonomies/
+[`Data`]: /methods/page/data/
+[`Taxonomies`]: /methods/site/taxonomies/
+[`Terms`]: /methods/page/data/#in-a-taxonomy-template
diff --git a/docs/content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md b/docs/content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md
index ec5f8e406..07afadbd6 100644
--- a/docs/content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md
+++ b/docs/content/en/_common/methods/taxonomy/ordered-taxonomy-element-methods.md
@@ -6,19 +6,19 @@ An ordered taxonomy is a slice, where each element is an object that contains th
Each element of the slice provides these methods:
-Count
+`Count`
: (`int`) Returns the number of pages to which the term is assigned.
-Page
+`Page`
: (`page.Page`) Returns the term's `Page` object, useful for linking to the term page.
-Pages
-: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight](g). To sort or group, use any of the [methods] available to the `Pages` object. For example, sort by the last modification date.
+`Pages`
+: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight](g). To sort or group, use any of the [methods][] available to the `Pages` object. For example, sort by the last modification date.
-Term
+`Term`
: (`string`) Returns the term name.
-WeightedPages
+`WeightedPages`
: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by taxonomic weight. The `Pages` method above is more flexible, allowing you to sort and group.
[methods]: /methods/pages/
diff --git a/docs/content/en/_common/permalink-tokens.md b/docs/content/en/_common/permalink-tokens.md
index 70dee0bca..bf14e0942 100644
--- a/docs/content/en/_common/permalink-tokens.md
+++ b/docs/content/en/_common/permalink-tokens.md
@@ -45,27 +45,26 @@ _comment: Do not remove front matter.
`:filename`
: {{< deprecated-in v0.144.0 />}}
-: Use `:contentbasename` instead.
+: Use the [`:contentbasename`](#contentbasename) token instead.
`:slugorfilename`
: {{< deprecated-in v0.144.0 />}}
-: Use `:slugorcontentbasename` instead.
+: Use the [`:slugorcontentbasename`](#slugorcontentbasename) token instead.
`:contentbasename`
: {{< new-in 0.144.0 />}}
-: The [content base name].
-
-[content base name]: /methods/page/file/#contentbasename
+: The [content base name][].
`:slugorcontentbasename`
: {{< new-in 0.144.0 />}}
-: The `slug` as defined in front matter, else the [content base name].
+: The `slug` as defined in front matter, else the [content base name][].
-For time-related values, you can also use the layout string components defined in Go's [time package]. For example:
-
-[time package]: https://pkg.go.dev/time#pkg-constants
+For time-related values, you can also use the layout string components defined in Go's [time package][]. For example:
{{< code-toggle file=hugo >}}
permalinks:
posts: /:06/:1/:2/:title/
{{< /code-toggle >}}
+
+[content base name]: /methods/page/file/#contentbasename
+[time package]: https://pkg.go.dev/time#pkg-constants
diff --git a/docs/content/en/_common/ref-and-relref-options.md b/docs/content/en/_common/ref-and-relref-options.md
index ed0dd14c6..79808c3d4 100644
--- a/docs/content/en/_common/ref-and-relref-options.md
+++ b/docs/content/en/_common/ref-and-relref-options.md
@@ -2,11 +2,11 @@
_comment: Do not remove front matter.
---
-path
+`path`
: (`string`) The path to the target page. Paths without a leading slash (`/`) are resolved first relative to the current page, and then relative to the rest of the site.
-lang
+`lang`
: (`string`) The language of the target page. Default is the current language. Optional.
-outputFormat
+`outputFormat`
: (`string`) The output format of the target page. Default is the current output format. Optional.
diff --git a/docs/content/en/_common/render-hooks/pageinner.md b/docs/content/en/_common/render-hooks/pageinner.md
index 4cde59325..dc9e59dba 100644
--- a/docs/content/en/_common/render-hooks/pageinner.md
+++ b/docs/content/en/_common/render-hooks/pageinner.md
@@ -20,7 +20,7 @@ The primary use case for `PageInner` is to resolve links and [page resources](g)
Then call the shortcode in your Markdown:
-```text {file="content/posts/post-1.md"}
+```md {file="content/posts/post-1.md"}
{{%/* include "/posts/post-2" */%}}
```
@@ -31,15 +31,15 @@ Any render hook triggered while rendering `/posts/post-2` will get:
`PageInner` falls back to the value of `Page` if not relevant, and always returns a value.
-> [!note]
-> The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using [Markdown notation].
+> [!NOTE]
+> The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`][] method, and you must call the shortcode using [Markdown notation][].
As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each:
-- [Embedded link render hook]
-- [Embedded image render hook]
+- [Embedded link render hook][]
+- [Embedded image render hook][]
-[`RenderShortcodes`]: /methods/page/rendershortcodes/
-[Markdown notation]: /content-management/shortcodes/#notation
-[Embedded link render hook]: <{{% eturl render-link %}}>
[Embedded image render hook]: <{{% eturl render-image %}}>
+[Embedded link render hook]: <{{% eturl render-link %}}>
+[Markdown notation]: /content-management/shortcodes/#notation
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
diff --git a/docs/content/en/_common/scratch-pad-scope.md b/docs/content/en/_common/scratch-pad-scope.md
index 789b943e6..b63877c2d 100644
--- a/docs/content/en/_common/scratch-pad-scope.md
+++ b/docs/content/en/_common/scratch-pad-scope.md
@@ -4,18 +4,18 @@ _comment: Do not remove front matter.
## Scope
-The method or function used to create a scratch pad determines its scope. For example, use the `Store` method on a `Page` object to create a scratch pad scoped to the page.
+The method or function used to create the data structure determines its scope. For example, use the `Store` method on a `Page` object to create a data structure scoped to the page.
Scope|Method or function
:--|:--
-page|[`PAGE.Store`]
-site|[`SITE.Store`]
-global|[`hugo.Store`]
-local|[`collections.NewScratch`]
-shortcode|[`SHORTCODE.Store`]
+page|[`PAGE.Store`][]
+site|[`SITE.Store`][]
+global|[`hugo.Store`][]
+local|[`collections.NewScratch`][]
+shortcode|[`SHORTCODE.Store`][]
-[`page.store`]: /methods/page/store
-[`site.store`]: /methods/site/store
-[`hugo.store`]: /functions/hugo/store
-[`collections.newscratch`]: functions/collections/newscratch
-[`shortcode.store`]: /methods/shortcode/store
+[`PAGE.Store`]: /methods/page/store/
+[`SHORTCODE.Store`]: /methods/shortcode/store/
+[`SITE.Store`]: /methods/site/store/
+[`collections.NewScratch`]: /functions/collections/newscratch/
+[`hugo.Store`]: /functions/hugo/store/
diff --git a/docs/content/en/_common/store-methods.md b/docs/content/en/_common/store-methods.md
index 1dd776130..d632c107d 100644
--- a/docs/content/en/_common/store-methods.md
+++ b/docs/content/en/_common/store-methods.md
@@ -4,83 +4,78 @@
## Methods
-### Set
+Use these methods on the data structure.
-Sets the value of the given key.
+`Set`
+: Sets the value of the given key.
-```go-html-template
-{{ .Store.Set "greeting" "Hello" }}
-```
-
-### Get
-
-Gets the value of the given key.
-
-```go-html-template
-{{ .Store.Set "greeting" "Hello" }}
-{{ .Store.Get "greeting" }} → Hello
-```
-
-### Add
-
-Adds the given value to the existing value(s) of the given key.
-
-For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
-
-```go-html-template
-{{ .Store.Set "greeting" "Hello" }}
-{{ .Store.Add "greeting" "Welcome" }}
-{{ .Store.Get "greeting" }} → HelloWelcome
-```
-
-```go-html-template
-{{ .Store.Set "total" 3 }}
-{{ .Store.Add "total" 7 }}
-{{ .Store.Get "total" }} → 10
-```
-
-```go-html-template
-{{ .Store.Set "greetings" (slice "Hello") }}
-{{ .Store.Add "greetings" (slice "Welcome" "Cheers") }}
-{{ .Store.Get "greetings" }} → [Hello Welcome Cheers]
-```
-
-### SetInMap
-
-Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
-
-```go-html-template
-{{ .Store.SetInMap "greetings" "english" "Hello" }}
-{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
-{{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour]
+ ```go-html-template
+ {{ .Store.Set "greeting" "Hello" }}
```
-### DeleteInMap
+`Get`
+: (`any`) Gets the value of the given key.
-Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+ ```go-html-template
+ {{ .Store.Set "greeting" "Hello" }}
+ {{ .Store.Get "greeting" }} → Hello
+ ```
-```go-html-template
-{{ .Store.SetInMap "greetings" "english" "Hello" }}
-{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
-{{ .Store.DeleteInMap "greetings" "english" }}
-{{ .Store.Get "greetings" }} → map[french:Bonjour]
-```
+`Add`
+: Adds the given value to the existing value(s) of the given key.
-### GetSortedMapValues
+ For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
-Returns an array of values from `key` sorted by `mapKey`.
+ ```go-html-template
+ {{ .Store.Set "greeting" "Hello" }}
+ {{ .Store.Add "greeting" "Welcome" }}
+ {{ .Store.Get "greeting" }} → HelloWelcome
+ ```
-```go-html-template
-{{ .Store.SetInMap "greetings" "english" "Hello" }}
-{{ .Store.SetInMap "greetings" "french" "Bonjour" }}
-{{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
-```
+ ```go-html-template
+ {{ .Store.Set "total" 3 }}
+ {{ .Store.Add "total" 7 }}
+ {{ .Store.Get "total" }} → 10
+ ```
-### Delete
+ ```go-html-template
+ {{ .Store.Set "greetings" (slice "Hello") }}
+ {{ .Store.Add "greetings" (slice "Welcome" "Cheers") }}
+ {{ .Store.Get "greetings" }} → [Hello Welcome Cheers]
+ ```
-Removes the given key.
+`SetInMap`
+: Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
-```go-html-template
-{{ .Store.Set "greeting" "Hello" }}
-{{ .Store.Delete "greeting" }}
-```
+ ```go-html-template
+ {{ .Store.SetInMap "greetings" "english" "Hello" }}
+ {{ .Store.SetInMap "greetings" "french" "Bonjour" }}
+ {{ .Store.Get "greetings" }} → map[english:Hello french:Bonjour]
+ ```
+
+`DeleteInMap`
+: Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+
+ ```go-html-template
+ {{ .Store.SetInMap "greetings" "english" "Hello" }}
+ {{ .Store.SetInMap "greetings" "french" "Bonjour" }}
+ {{ .Store.DeleteInMap "greetings" "english" }}
+ {{ .Store.Get "greetings" }} → map[french:Bonjour]
+ ```
+
+`GetSortedMapValues`
+: (`[]any`) Returns an array of values from `key` sorted by `mapKey`.
+
+ ```go-html-template
+ {{ .Store.SetInMap "greetings" "english" "Hello" }}
+ {{ .Store.SetInMap "greetings" "french" "Bonjour" }}
+ {{ .Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+ ```
+
+`Delete`
+: Removes the given key.
+
+ ```go-html-template
+ {{ .Store.Set "greeting" "Hello" }}
+ {{ .Store.Delete "greeting" }}
+ ```
diff --git a/docs/content/en/_common/store-scope.md b/docs/content/en/_common/store-scope.md
new file mode 100644
index 000000000..b63877c2d
--- /dev/null
+++ b/docs/content/en/_common/store-scope.md
@@ -0,0 +1,21 @@
+---
+_comment: Do not remove front matter.
+---
+
+## Scope
+
+The method or function used to create the data structure determines its scope. For example, use the `Store` method on a `Page` object to create a data structure scoped to the page.
+
+Scope|Method or function
+:--|:--
+page|[`PAGE.Store`][]
+site|[`SITE.Store`][]
+global|[`hugo.Store`][]
+local|[`collections.NewScratch`][]
+shortcode|[`SHORTCODE.Store`][]
+
+[`PAGE.Store`]: /methods/page/store/
+[`SHORTCODE.Store`]: /methods/shortcode/store/
+[`SITE.Store`]: /methods/site/store/
+[`collections.NewScratch`]: /functions/collections/newscratch/
+[`hugo.Store`]: /functions/hugo/store/
diff --git a/docs/content/en/_common/syntax-highlighting-options.md b/docs/content/en/_common/syntax-highlighting-options.md
index 8c390f271..2f57cb071 100644
--- a/docs/content/en/_common/syntax-highlighting-options.md
+++ b/docs/content/en/_common/syntax-highlighting-options.md
@@ -2,31 +2,31 @@
_comment: Do not remove front matter.
---
-anchorLineNos
+`anchorLineNos`
: (`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
-codeFences
+`codeFences`
: (`bool`) Whether to highlight fenced code blocks. Default is `true`.
-guessSyntax
+`guessSyntax`
: (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer](g). Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
- > [!note]
+ > [!NOTE]
> The syntax highlighter includes lexers for approximately 300 languages, but only 5 of these have implemented automatic language detection.
-hl_Lines
+`hl_Lines`
: (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
-hl_inline
+`hl_inline`
: (`bool`) Whether to render the highlighted code without a wrapping container. Default is `false`.
-lineAnchors
+`lineAnchors`
: (`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
-lineNoStart
+`lineNoStart`
: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
-lineNos
+`lineNos`
: (`any`) Controls line number display. Default is `false`.
- `true`: Enable line numbers, controlled by `lineNumbersInTable`.
@@ -34,23 +34,23 @@ lineNos
- `inline`: Enable inline line numbers (sets `lineNumbersInTable` to `false`).
- `table`: Enable table-based line numbers (sets `lineNumbersInTable` to `true`).
-lineNumbersInTable
+`lineNumbersInTable`
: (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
-noClasses
+`noClasses`
: (`bool`) Whether to use inline CSS styles instead of an external CSS file. Default is `true`. To use an external CSS file, set this value to `false` and generate the CSS file from the command line:
- ```text
+ ```sh
hugo gen chromastyles --style=monokai > syntax.css
```
-style
+`style`
: (`string`) The CSS styles to apply to the highlighted code. This value is case-insensitive. Default is `monokai`. See [syntax highlighting styles][].
-tabWidth
+`tabWidth`
: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
-wrapperClass
+`wrapperClass`
: {{< new-in 0.140.2 />}}
: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
diff --git a/docs/content/en/_common/time-layout-string.md b/docs/content/en/_common/time-layout-string.md
index 3664eaef2..2d205c5a3 100644
--- a/docs/content/en/_common/time-layout-string.md
+++ b/docs/content/en/_common/time-layout-string.md
@@ -2,9 +2,7 @@
_comment: Do not remove front matter.
---
-Format a `time.Time` value based on [Go's reference time]:
-
-[Go's reference time]: https://pkg.go.dev/time#pkg-constants
+Format a `time.Time` value based on [Go's reference time][]:
```text
Mon Jan 2 15:04:05 MST 2006
@@ -44,3 +42,5 @@ Strings such as `PST` and `CET` are not time zones. They are time zone _abbrevia
Strings such as `-07:00` and `+01:00` are not time zones. They are time zone _offsets_.
A time zone is a geographic area with the same local time. For example, the time zone abbreviated by `PST` and `PDT` (depending on Daylight Savings Time) is `America/Los_Angeles`.
+
+[Go's reference time]: https://pkg.go.dev/time#pkg-constants
diff --git a/docs/content/en/about/features.md b/docs/content/en/about/features.md
index 2c75eddf1..cb93db9c6 100644
--- a/docs/content/en/about/features.md
+++ b/docs/content/en/about/features.md
@@ -8,137 +8,133 @@ weight: 20
## Framework
-[Multiplatform]
+[Multiplatform][]
: Install Hugo's single executable on Linux, macOS, Windows, and more.
-[Multilingual]
+[Multilingual][]
: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations.
-[Output formats]
+[Output formats][]
: Render each page of your project to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
-[Templates]
+[Templates][]
: Create templates using variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format.
-[Themes]
+[Themes][]
: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more.
-[Modules]
+[Modules][]
: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new project, or to augment an existing project.
-[Privacy]
+[Privacy][]
: Configure your project to help comply with regional privacy regulations.
-[Security]
+[Security][]
: Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more.
## Content authoring
-[Content formats]
-: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark] and [GitHub Flavored Markdown] specifications.
+[Content formats][]
+: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark][] and [GitHub Flavored Markdown][] specifications.
-[Markdown attributes]
+[Markdown attributes][]
: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
-[Markdown extensions]
+[Markdown extensions][]
: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
-[Markdown render hooks]
+[Markdown render hooks][]
: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, links, and tables. For example, render every standalone image as an HTML `figure` element.
-[Diagrams]
+[Diagrams][]
: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
-[Mathematics]
+[Mathematics][]
: Include mathematical equations and expressions in Markdown using LaTeX markup.
-[Syntax highlighting]
+[Syntax highlighting][]
: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles.
-[Shortcodes]
+[Shortcodes][]
: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more.
## Content management
-[Multidimensional content model]
+[Multidimensional content model][]
: Generate pages across any combination of language, version, and role from a single source. This allows a single piece of content to be published to multiple [sites](g) within your project, removing the need to duplicate files for different audiences or versions.
-[Content adapters]
+[Content adapters][]
: Create content adapters to dynamically add content when building your project. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
-[Taxonomies]
+[Taxonomies][]
: Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance.
-[Data]
+[Data][]
: Augment your content using local or remote data sources including CSV, JSON, TOML, YAML, and XML. For example, create a shortcode to render an HTML table from a remote CSV file.
-[Menus]
+[Menus][]
: Provide rapid access to content via Hugo's menu system, configured automatically, globally, or on a page-by-page basis. The menu system is a key component of Hugo's multilingual architecture.
-[URL management]
+[URL management][]
: Serve any page from any path via global configuration or on a page-by-page basis.
## Asset pipelines
-[CSS Processing]
+[CSS Processing][]
: Bundle, transform, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
-[Image processing]
+[Image processing][]
: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract metadata.
-[JavaScript bundling]
+[JavaScript bundling][]
: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
-[Sass processing]
+[Sass processing][]
: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
-[Tailwind CSS processing]
+[Tailwind CSS processing][]
: Compile Tailwind CSS utility classes into standard CSS, bundle, tree shake, optimize, minify, perform SRI hashing, and integrate with PostCSS.
## Performance
-[Caching]
+[Caching][]
: Reduce build time and cost by rendering a _partial_ template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
-[Segmentation]
+[Segmentation][]
: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire project once a week.
-[Minification]
+[Minification][]
: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times.
-[Multilingual]: /content-management/multilingual/
-[Multiplatform]: /installation/
-[Output formats]: /configuration/output-formats/
-[Templates]: /templates/introduction/
-[Themes]: https://themes.gohugo.io/
-[Modules]: /hugo-modules/
-[Privacy]: /configuration/privacy/
-[Security]: /about/security/
-
-[Content formats]: /content-management/formats/
+[CSS Processing]: /functions/css/build/
+[Caching]: /functions/partials/includecached/
[CommonMark]: https://spec.commonmark.org/current/
+[Content adapters]: /content-management/content-adapters/
+[Content formats]: /content-management/formats/
+[Data]: /content-management/data-sources/
+[Diagrams]: /content-management/diagrams/
[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Image processing]: /content-management/image-processing/
+[JavaScript bundling]: /functions/js/build/
[Markdown attributes]: /content-management/markdown-attributes/
[Markdown extensions]: /configuration/markup/#extensions
[Markdown render hooks]: /render-hooks/introduction/
-[Diagrams]: /content-management/diagrams/
[Mathematics]: /content-management/mathematics/
-[Syntax highlighting]: /content-management/syntax-highlighting/
-[Shortcodes]: /content-management/shortcodes/
-
-[Multidimensional content model]: /quick-reference/glossary/#sites-matrix
-[Content adapters]: /content-management/content-adapters/
-[Taxonomies]: /content-management/taxonomies/
-[Data]: /content-management/data-sources/
[Menus]: /content-management/menus/
-[URL management]: /content-management/urls/
-
-[CSS processing]: /functions/css/build/
-[Image processing]: /content-management/image-processing/
-[JavaScript bundling]: /functions/js/build/
-[Sass processing]: /functions/css/sass/
-[Tailwind CSS processing]: /functions/css/tailwindcss/
-
-[Caching]: /functions/partials/includecached/
-[Segmentation]: /configuration/segments/
[Minification]: /configuration/minify/
+[Modules]: /hugo-modules/
+[Multidimensional content model]: /quick-reference/glossary/#sites-matrix
+[Multilingual]: /content-management/multilingual/
+[Multiplatform]: /installation/
+[Output formats]: /configuration/output-formats/
+[Privacy]: /configuration/privacy/
+[Sass processing]: /functions/css/sass/
+[Security]: /about/security/
+[Segmentation]: /configuration/segments/
+[Shortcodes]: /content-management/shortcodes/
+[Syntax highlighting]: /content-management/syntax-highlighting/
+[Tailwind CSS processing]: /functions/css/tailwindcss/
+[Taxonomies]: /content-management/taxonomies/
+[Templates]: /templates/introduction/
+[Themes]: https://themes.gohugo.io/
+[URL management]: /content-management/urls/
diff --git a/docs/content/en/about/introduction.md b/docs/content/en/about/introduction.md
index 3d56b9570..2a046a7d9 100644
--- a/docs/content/en/about/introduction.md
+++ b/docs/content/en/about/introduction.md
@@ -7,7 +7,7 @@ weight: 10
aliases: [/about/what-is-hugo/,/about/benefits/]
---
-Hugo is a [static site generator] written in [Go], optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
+Hugo is a [static site generator][] written in [Go][], optimized for speed and designed for flexibility. With its advanced templating system and fast asset pipelines, Hugo renders a complete site in seconds, often less.
Due to its flexible framework, multilingual support, and powerful taxonomy system, Hugo is widely used to create:
@@ -20,15 +20,15 @@ Due to its flexible framework, multilingual support, and powerful taxonomy syste
Use Hugo's embedded web server during development to instantly see changes to content, structure, behavior, and presentation. Then deploy the site to your host, or push changes to your Git provider for automated builds and deployment.
-And with [Hugo Modules], you can share content, assets, data, translations, themes, templates, and configuration with other projects via public or private Git repositories.
+And with [modules][] you can share content, assets, data, translations, themes, templates, and configuration with other projects via public or private Git repositories.
-Learn more about Hugo's [features], [privacy protections], and [security model].
-
-[Go]: https://go.dev
-[Hugo Modules]: /hugo-modules/
-[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator
-[features]: /about/features/
-[security model]: /about/security/
-[privacy protections]: /configuration/privacy
+Learn more about Hugo's [features][], [privacy protections][], and [security model][].
{{< youtube 0RKpf3rK57I >}}
+
+[Go]: https://go.dev
+[features]: /about/features/
+[modules]: /hugo-modules/
+[privacy protections]: /configuration/privacy/
+[security model]: /about/security/
+[static site generator]: https://en.wikipedia.org/wiki/Static_site_generator
diff --git a/docs/content/en/about/security.md b/docs/content/en/about/security.md
index b242bce50..7ff12f614 100644
--- a/docs/content/en/about/security.md
+++ b/docs/content/en/about/security.md
@@ -31,32 +31,33 @@ This combination of sandboxing and strict defaults effectively minimizes potenti
## Dependency security
-Hugo utilizes [Go Modules][] to manage its dependencies, compiling as a static binary. Go Modules create a `go.sum` file, a critical security feature. This file acts as a database, storing the expected cryptographic checksums of all dependencies, including those required indirectly (transitive dependencies).
+Hugo utilizes [Go modules][] to manage its dependencies, compiling as a static binary. Go modules create a `go.sum` file, a critical security feature. This file acts as a database, storing the expected cryptographic checksums of all dependencies, including those required indirectly (transitive dependencies).
-[Hugo Modules][], which extend Go Modules' functionality, also produce a `go.sum` file. To ensure dependency integrity, commit this `go.sum` file to your version control. If Hugo detects a checksum mismatch during the build process, it will fail, indicating a possible attempt to [tamper with your project's dependencies][].
+[Hugo modules][], which extend the functionality of Go modules, also produce a `go.sum` file. To ensure dependency integrity, commit this `go.sum` file to your version control. If Hugo detects a checksum mismatch during the build process, it will fail, indicating a possible attempt to [tamper with your project's dependencies][].
## Web application security
Hugo's security philosophy is rooted in established security standards, primarily aligning with the threats defined by [OWASP][]. For HTML output, Hugo operates under a clear trust model. This model assumes that template and configuration authors, the developers, are trustworthy. However, the data supplied to these templates is inherently considered untrusted. This distinction is crucial for understanding how Hugo handles potential security risks.
-To prevent unintended escaping of data that developers know is safe, Hugo provides [`safe`][] functions, such as [`safeHTML`][]. These functions allow developers to explicitly mark data as trusted, bypassing the default escaping mechanisms. This is essential for scenarios where data is generated or sourced from reliable sources. However, an exception exists: enabling [inline shortcodes][]. By activating this feature, you are implicitly trusting the logic within the shortcodes and the data contained within your content files.
+To prevent unintended escaping of data that developers know is safe, Hugo provides [`safe`][] functions, such as [`safe.HTML`][]. These functions allow developers to explicitly mark data as trusted, bypassing the default escaping mechanisms. This is essential for scenarios where data is generated or sourced from reliable sources. However, an exception exists: enabling [inline shortcodes][]. By activating this feature, you are implicitly trusting the logic within the shortcodes and the data contained within your content files.
It's vital to remember that Hugo is a static site generator. This architectural choice significantly reduces the attack surface by eliminating the complexities and vulnerabilities associated with dynamic user input. Unlike dynamic websites, Hugo generates static HTML files, minimizing the risk of real-time attacks. Regarding content, Hugo's default Markdown renderer is [configured to sanitize][] potentially unsafe content. This default behavior ensures that potentially malicious code or scripts are removed or escaped. However, this setting can be reconfigured if you have a high degree of confidence in the safety of your content sources.
-In essence, Hugo prioritizes secure output by establishing a clear trust boundary between developers and data. By default, it errs on the side of caution, sanitizing potentially unsafe content and escaping data. Developers have the flexibility to adjust these defaults through [`safe`][] functions and [configuration options][], but they must do so with a clear understanding of the security implications. Hugo's static site generation model further strengthens its security posture by minimizing dynamic vulnerabilities.
+In essence, Hugo prioritizes secure output by establishing a clear trust boundary between developers and data. By default, it errs on the side of caution, sanitizing potentially unsafe content and escaping data. Developers have the flexibility to adjust these defaults through [`safe`][] functions and [configuration settings][], but they must do so with a clear understanding of the security implications. Hugo's static site generation model further strengthens its security posture by minimizing dynamic vulnerabilities.
## Configuration
-See [configure security](/configuration/security/).
+See [configure security][].
-[`safe`]: /functions/safe
-[`safeHTML`]: /functions/safe/html/
-[content adapters]: /content-management/content-adapters/
-[configuration options]: /configuration/security
-[configured to sanitize]: /configuration/markup/#rendererunsafe
-[Go Modules]: https://go.dev/wiki/Modules#modules
-[Hugo Modules]: /hugo-modules/
-[inline shortcodes]: /content-management/shortcodes/#inline
+[Go modules]: https://go.dev/wiki/Modules#modules
+[Hugo modules]: /hugo-modules/
[OWASP]: https://en.wikipedia.org/wiki/OWASP
+[`safe.HTML`]: /functions/safe/html/
+[`safe`]: /functions/safe/
+[configuration settings]: /configuration/security/
+[configure security]: /configuration/security/
+[configured to sanitize]: /configuration/markup/#rendererunsafe
+[content adapters]: /content-management/content-adapters/
+[inline shortcodes]: /content-management/shortcodes/#inline
[security policy]: /configuration/security/
[tamper with your project's dependencies]: https://julienrenaux.fr/2019/12/20/github-actions-security-risk/
diff --git a/docs/content/en/configuration/all.md b/docs/content/en/configuration/all.md
index 36fc4c091..5e57a251d 100644
--- a/docs/content/en/configuration/all.md
+++ b/docs/content/en/configuration/all.md
@@ -9,320 +9,317 @@ aliases: [/getting-started/configuration/]
## Settings
-archetypeDir
+`archetypeDir`
: (`string`) The designated directory for [archetypes](g). Default is `archetypes`. {{% module-mounts-note %}}
-assetDir
+`assetDir`
: (`string`) The designated directory for [global resources](g). Default is `assets`. {{% module-mounts-note %}}
-baseURL
+`baseURL`
: (`string`) The absolute URL of your published site including the protocol, host, path, and a trailing slash.
-build
+`build`
: See [configure build][].
-buildDrafts
+`buildDrafts`
: (`bool`) Whether to include draft content when building a site. Default is `false`.
-buildExpired
+`buildExpired`
: (`bool`) Whether to include expired content when building a site. Default is `false`.
-buildFuture
+`buildFuture`
: (`bool`) Whether to include future content when building a site. Default is `false`.
-cacheDir
-: (`string`) The designated cache directory. See [details](#cache-directory).
+`cacheDir`
+: (`string`) The designated cache directory. See [details](#cache-directory).
-caches
+`caches`
: See [configure file caches][].
-canonifyURLs
-: (`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
+`canonifyURLs`
+: (`bool`) See [details][canonical-urls] before enabling this feature. Default is `false`.
-capitalizeListTitles
-: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Use the [`titleCaseStyle`][] setting to configure capitalization rules. Default is `true`.
+`capitalizeListTitles`
+: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Use the [`titleCaseStyle`](#titlecasestyle) setting to configure capitalization rules. Default is `true`.
-cascade
+`cascade`
: See [configure cascade][].
-cleanDestinationDir
-: (`bool`) Whether to remove files from the [`publishDir`][] that do not exist in the [`staticDir`][] when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`.
+`cleanDestinationDir`
+: (`bool`) Whether to remove files from the [`publishDir`](#publishdir) that do not exist in the [`staticDir`](#staticdir) when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`.
-contentDir
+`contentDir`
: (`string`) The designated directory for content files. Default is `content`. {{% module-mounts-note %}}
-copyright
+`copyright`
: (`string`) The copyright notice for a site, typically displayed in the footer.
-dataDir
+`dataDir`
: (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}}
-defaultContentLanguage
+`defaultContentLanguage`
: (`string`) The projects's [default language](g), conforming to the syntax described in [RFC 5646][].
-defaultContentLanguageInSubdir
-: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`.
+`defaultContentLanguageInSubdir`
+: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`](#defaultcontentlanguage). Default is `false`.
-defaultContentRole
+`defaultContentRole`
: {{< new-in 0.153.0 />}}
: (`string`) The project's [default role](g).
-defaultContentRoleInSubdir
+`defaultContentRoleInSubdir`
: {{< new-in 0.153.0 />}}
-: (`bool`) Whether to publish the default content [role](g) to a subdirectory matching the [`defaultContentRole`][]. Default is `false`.
+: (`bool`) Whether to publish the default content [role](g) to a subdirectory matching the [`defaultContentRole`](#defaultcontentrole). Default is `false`.
-defaultContentVersion
+`defaultContentVersion`
: {{< new-in 0.153.0 />}}
: (`string`) The project's [default version](g).
-defaultContentVersionInSubdir
+`defaultContentVersionInSubdir`
: {{< new-in 0.153.0 />}}
-: (`bool`) Whether to publish the default content version to a subdirectory matching the [`defaultContentVersion`][]. Default is `false`.
+: (`bool`) Whether to publish the default content version to a subdirectory matching the [`defaultContentVersion`](#defaultcontentversion). Default is `false`.
-defaultOutputFormat
+`defaultOutputFormat`
: (`string`) The default output format for the site. If unspecified, the first available format in the defined order (by weight, then alphabetically) will be used.
-deployment
+`deployment`
: See [configure deployment][].
-disableAliases
+`disableAliases`
: (`bool`) Whether to disable the generation of HTML redirect files for each path defined in the [`aliases`][aliases_front_matter] front matter field. When `true`, Hugo will not create physical files for [client-side redirection][], but the alias data remains available via the [`Aliases`][aliases_page_method] method on a `Page` object. Default is `false`.
-disableDefaultLanguageRedirect
+`disableDefaultLanguageRedirect`
: {{< new-in 0.140.0 />}}
-: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`][] is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`.
+: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`](#defaultcontentlanguageinsubdir) is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`](#disabledefaultsiteredirect) setting. Default is `false`.
-disableDefaultSiteRedirect
+`disableDefaultSiteRedirect`
: {{< new-in 0.154.5 />}}
-: (`bool`) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`][], [`defaultContentRoleInSubdir`][], or [`defaultContentVersionInSubdir`][] is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. Default is `false`.
+: (`bool`) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`](#defaultcontentlanguageinsubdir), [`defaultContentRoleInSubdir`](#defaultcontentroleinsubdir), or [`defaultContentVersionInSubdir`](#defaultcontentversioninsubdir) is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. Default is `false`.
-disableHugoGeneratorInject
+`disableHugoGeneratorInject`
: (`bool`) Whether to disable injection of a `` tag into the home page. Default is `false`.
-disableKinds
+`disableKinds`
: (`[]string`) A slice of page [kinds](g) to disable during the build process, any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
-disableLanguages
+`disableLanguages`
: (`[]string`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`][] key under each language instead.
-disableLiveReload
+`disableLiveReload`
: (`bool`) Whether to disable automatic live reloading of the browser window. Default is `false`.
-disablePathToLower
+`disablePathToLower`
: (`bool`) Whether to disable transformation of page URLs to lower case. Default is `false`.
-enableEmoji
+`enableEmoji`
: (`bool`) Whether to allow emoji in Markdown. Default is `false`.
-enableGitInfo
+`enableGitInfo`
: (`bool`) Whether to retrieve commit metadata from the Git history of your local project and any [modules](g). This enables the [`GitInfo`][] method on a `Page` object. With the default front matter configuration, the [`Lastmod`][] method on a `Page` object returns the Git author date of the last commit for that file. Default is `false`.
-enableMissingTranslationPlaceholders
+`enableMissingTranslationPlaceholders`
: (`bool`) Whether to show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`.
-enableRobotsTXT
+`enableRobotsTXT`
: (`bool`) Whether to enable generation of a `robots.txt` file. Default is `false`.
-environment
-: (`string`) The build environment. Default is `production` when running `hugo build` and `development` when running `hugo server`.
-
-frontmatter
+`frontmatter`
: See [configure front matter][].
-hasCJKLanguage
+`hasCJKLanguage`
: (`bool`) Whether to automatically detect [CJK](g) languages in content. Affects the values returned by the [`WordCount`][] and [`FuzzyWordCount`][] methods. Default is `false`.
-HTTPCache
+`HTTPCache`
: See [configure HTTP cache][].
-i18nDir
+`i18nDir`
: (`string`) The designated directory for translation tables. Default is `i18n`. {{% module-mounts-note %}}
-ignoreCache
+`ignoreCache`
: (`bool`) Whether to ignore the configured file caches. Default is `false`.
-ignoreFiles
+`ignoreFiles`
: (`[]string`) A slice of [regular expressions](g) used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts][].
-ignoreLogs
+`ignoreLogs`
: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`][] and [`warnidf`][].
-ignoreVendorPaths
+`ignoreVendorPaths`
: (`string`) A [glob pattern](g) matching the module paths to exclude from the `_vendor` directory.
-imaging
+`imaging`
: See [configure imaging][].
-languageCode
+`languageCode`
: {{
@@ -59,7 +59,7 @@ Then include this snippet at the _bottom_ of your base template, before the clos
With that you can use the `mermaid` language in Markdown code blocks:
-````text {copy=true}
+````md {file="content/example.md" copy=true}
```mermaid
sequenceDiagram
participant Alice
@@ -255,6 +255,6 @@ Created from
└────────────────────────────────────────────────┘
```
+[GoAT]: https://github.com/bep/goat
[code block render hook]: /render-hooks/code-blocks/
[embedded code block render hook]: <{{% eturl render-codeblock-goat %}}>
-[GoAT]: https://github.com/bep/goat
diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md
index 0f9fe7f1c..86cb5adc6 100644
--- a/docs/content/en/content-management/formats.md
+++ b/docs/content/en/content-management/formats.md
@@ -10,7 +10,7 @@ aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-f
You may mix content formats throughout your site. For example:
-```text
+```tree
content/
└── posts/
├── post-1.md
@@ -21,106 +21,81 @@ content/
└── post-6.html
```
-Regardless of content format, all content must have [front matter], preferably including both `title` and `date`.
+Regardless of content format, all content must have [front matter][], preferably including both `title` and `date`.
-Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification] table below for a list of markup identifiers and recognized file extensions.
-
-[classification]: #classification
-[front matter]: /content-management/front-matter/
+Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification](#classification) table below for a list of markup identifiers and recognized file extensions.
## Formats
### Markdown
-Create your content in [Markdown] preceded by front matter.
+Create your content in [Markdown][] preceded by front matter.
-Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can configure Goldmark in your [project configuration][configure goldmark].
+Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark][]. Goldmark is fast and conforms to the [CommonMark][] and [GitHub Flavored Markdown][] specifications. You can configure Goldmark in your [project configuration][configure goldmark].
Hugo provides custom Markdown features including:
-[Attributes]
+[Attributes][]
: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
-[Extensions]
+[Extensions][]
: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
-[Mathematics]
+[Mathematics][]
: Include mathematical equations and expressions in Markdown using LaTeX markup.
-[Render hooks]
+[Render hooks][]
: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
-[Attributes]: /content-management/markdown-attributes/
-[CommonMark]: https://spec.commonmark.org/current/
-[Extensions]: /configuration/markup/#extensions
-[GitHub Flavored Markdown]: https://github.github.com/gfm/
-[Goldmark]: https://github.com/yuin/goldmark
-[Markdown]: https://daringfireball.net/projects/markdown/
-[Mathematics]: /content-management/mathematics/
-[Render hooks]: /render-hooks/introduction/
-[configure goldmark]: /configuration/markup/#goldmark
-
### HTML
-Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
+Create your content in [HTML][] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
-[HTML]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content
+> [!NOTE]
+> The HTML content format is denied by default. See [`security.allowContent`][].
### Emacs Org Mode
-Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details].
-
-[details]: /content-management/front-matter/#emacs-org-mode
-[Emacs Org Mode]: https://orgmode.org/
+Create your content in the [Emacs Org Mode][] format preceded by front matter. You can use Org Mode keywords for front matter. See [details][].
### AsciiDoc
-Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to render the AsciiDoc content format.
+Create your content in the [AsciiDoc][] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to render the AsciiDoc content format.
You can configure the AsciiDoc renderer in your [project configuration][configure asciidoc].
In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable:
-```text
+```sh
--no-header-footer
```
The CLI flags passed to the Asciidoctor executable depend on configuration. You may inspect the flags when building your project:
-```text
+```sh
hugo build --logLevel info
```
-[AsciiDoc]: https://asciidoc.org/
-[configure asciidoc]: /configuration/markup/#asciidoc
-
### Pandoc
-Create your content in the [Pandoc] format[^1] preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to render the Pandoc content format.
-
-[^1]: This is a derivation of the Markdown format as described by the CommonMark specification.
+Create your content in the [Pandoc][] format preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to render the Pandoc content format.
Hugo passes these CLI flags when calling the Pandoc executable:
-```text
+```sh
--mathjax
```
-[Pandoc]: https://pandoc.org/MANUAL.html#pandocs-markdown
-
### reStructuredText
-Create your content in the [reStructuredText] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils], specifically rst2html. You must install Docutils and its dependencies (Python) to render the reStructuredText content format.
+Create your content in the [reStructuredText][] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils][], specifically rst2html. You must install Docutils and its dependencies (Python) to render the reStructuredText content format.
Hugo passes these CLI flags when calling the rst2html executable:
-```text
+```sh
--leave-comments --initial-header-level=2
```
-[Docutils]: https://docutils.sourceforge.io/
-[reStructuredText]: https://docutils.sourceforge.io/rst.html
-
## Classification
{{% include "/_common/content-format-table.md" %}}
@@ -131,3 +106,23 @@ When converting content to HTML, Hugo uses:
- External renderers for AsciiDoc, Pandoc, and reStructuredText
Native renderers are faster than external renderers.
+
+[AsciiDoc]: https://asciidoc.org/
+[Attributes]: /content-management/markdown-attributes/
+[CommonMark]: https://spec.commonmark.org/current/
+[Docutils]: https://docutils.sourceforge.io/
+[Emacs Org Mode]: https://orgmode.org/
+[Extensions]: /configuration/markup/#extensions
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Goldmark]: https://github.com/yuin/goldmark
+[HTML]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content
+[Markdown]: https://daringfireball.net/projects/markdown/
+[Mathematics]: /content-management/mathematics/
+[Pandoc]: https://pandoc.org/MANUAL.html#pandocs-markdown
+[Render hooks]: /render-hooks/introduction/
+[`security.allowContent`]: /configuration/security/#allowcontent
+[configure asciidoc]: /configuration/markup/#asciidoc
+[configure goldmark]: /configuration/markup/#goldmark
+[details]: /content-management/front-matter/#emacs-org-mode
+[front matter]: /content-management/front-matter/
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md
index 738cc0ad7..ab73b563f 100644
--- a/docs/content/en/content-management/front-matter.md
+++ b/docs/content/en/content-management/front-matter.md
@@ -35,79 +35,79 @@ Front matter fields may be [boolean](g), [integer](g), [float](g), [string](g),
The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below.
-> [!note]
+> [!NOTE]
> The field names below are reserved. For example, you cannot create a custom field named `type`. Create custom fields under the `params` key. See the [parameters](#parameters) section for details.
-aliases
+`aliases`
: (`[]string`) An array of one or more [page-relative](g) or [site-relative](g) paths that should redirect to the current page. Hugo resolves these to [server-relative](g) URLs during the build process. Access these values from a template using the [`Aliases`][] method on a `Page` object. See the [aliases][] section for details.
-build
+`build`
: (`map`) A map of [build options][].
-cascade
-: (`map`) A map (or array of maps) of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See the [cascade][] section for details.
+`cascade`
+: (`map`) A map (or array of maps) of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See the [cascade](#cascade-1) section for details.
-date
+`date`
: (`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Date`][] method on a `Page` object.
-description
+`description`
: (`string`) Conceptually different than the page `summary`, the description is typically rendered within a `meta` element within the `head` element of the published HTML file. Access this value from a template using the [`Description`][] method on a `Page` object.
-draft
+`draft`
: (`bool`) Whether to disable rendering unless you pass the `--buildDrafts` flag to the `hugo` command. Access this value from a template using the [`Draft`][] method on a `Page` object.
-expiryDate
+`expiryDate`
: (`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`ExpiryDate`][] method on a `Page` object.
-headless
+`headless`
: (`bool`) Applicable to [leaf bundles][], whether to set the `render` and `list` [build options][] to `never`, creating a headless bundle of [page resources][].
-isCJKLanguage
+`isCJKLanguage`
: (`bool`) Whether the content language is in the [CJK](g) family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`][], [`FuzzyWordCount`][], [`ReadingTime`][], and [`Summary`][] methods on a `Page` object.
-keywords
+`keywords`
: (`[]string`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`][] method on a `Page` object.
-lastmod
+`lastmod`
: (`string`) The date that the page was last modified. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Lastmod`][] method on a `Page` object.
-layout
+`layout`
: (`string`) Provide a template name to [target a specific template][], overriding the default [template lookup order][]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`][] method on a `Page` object.
-linkTitle
+`linkTitle`
: (`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`][] method on a `Page` object.
-markup
+`markup`
: (`string`) An identifier corresponding to one of the supported [content formats][]. If not provided, Hugo determines the content renderer based on the file extension.
-menus
+`menus`
: (`string`, `[]string`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus][] page for details.
-modified
+`modified`
: Alias to [lastmod](#lastmod).
-outputs
+`outputs`
: (`[]string`) The [output formats][] to render. See [configure outputs][] for more information.
-params
-: (`map`) A map of custom [page parameters][].
+`params`
+: (`map`) A map of custom [page parameters](#parameters).
-pubdate
+`pubdate`
: Alias to [publishDate](#publishdate).
-publishDate
+`publishDate`
: (`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`PublishDate`][] method on a `Page` object.
-published
+`published`
: Alias to [publishDate](#publishdate).
-resources
-: (`map array`) An array of maps to provide metadata for [page resources]. Each element supports the `src`, `name`, `title`, and `params` keys.
+`resources`
+: (`map array`) An array of maps to provide metadata for [page resources][]. Each element supports the `src`, `name`, `title`, and `params` keys.
-sitemap
+`sitemap`
: (`map`) A map of sitemap options. See the [sitemap templates][] page for details. Access these values from a template using the [`Sitemap`][] method on a `Page` object.
-sites
+`sites`
: {{< new-in 0.153.0 />}}
: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the page.
@@ -125,28 +125,28 @@ sites
-slug
+`slug`
: (`string`) Overrides the last segment of the URL path. Not applicable to `home`, `section`, `taxonomy`, or `term` pages. See the [URL management][] page for details. Access this value from a template using the [`Slug`][] method on a `Page` object.
-summary
+`summary`
: (`string`) Conceptually different than the page `description`, the summary either summarizes the content or serves as a teaser to encourage readers to visit the page. Access this value from a template using the [`Summary`][] method on a `Page` object.
-title
+`title`
: (`string`) The page title. Access this value from a template using the [`Title`][] method on a `Page` object.
-translationKey
+`translationKey`
: (`string`) An arbitrary value used to relate two or more translations of the same page, useful when the translated pages do not share a common path. Access this value from a template using the [`TranslationKey`][] method on a `Page` object.
-type
+`type`
: (`string`) The [content type](g), overriding the value derived from the top-level section in which the page resides. Access this value from a template using the [`Type`][] method on a `Page` object.
-unpublishdate
+`unpublishdate`
: Alias to [expirydate](#expirydate).
-url
+`url`
: (`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management][] page for details.
-weight
+`weight`
: (`int`) The page [weight](g), used to order the page within a [page collection](g). Access this value from a template using the [`Weight`][] method on a `Page` object.
## Parameters
@@ -164,16 +164,6 @@ author = 'John Smith'
Access these values from a template using the [`Params`][] or [`Param`][] method on a `Page` object.
-Hugo provides [embedded templates][] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
-
-Parameter|Data type|Used by these embedded templates
-:--|:--|:--
-`audio`|`[]string`|[`opengraph.html`][]
-`images`|`[]string`|[`opengraph.html`][], [`schema.html`][], [`twitter_cards.html`][]
-`videos`|`[]string`|[`opengraph.html`][]
-
-The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
-
## Taxonomies
Classify content by adding taxonomy terms to front matter. For example, with this project configuration:
@@ -220,10 +210,10 @@ Access taxonomy terms from a template using the [`Params`][] or [`GetTerms`][] m
## Cascade
-> [!note]
-> For multilingual projects, defining cascade values in your project configuration is often more efficient. This avoids repeating the same cascade values for each language. See [details](/configuration/cascade/).
+> [!NOTE]
+ > For multilingual projects, defining cascade values in your project configuration is often more efficient. This avoids repeating the same cascade values for each language. See [details][].
-A [node](g) can cascade front matter values to its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor node has already cascaded a value for that same field.
+A [branch](g) can cascade front matter values to its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor branch has already cascaded a value for that same field.
For example, to cascade the `color` page parameter from the home page to all its descendants:
@@ -236,7 +226,8 @@ color = 'red'
### Target
The `target` key accepts a [page matcher](g) to limit cascaded values to a subset of pages.[^1] If a target is not specified, values cascade to all descendant pages.
@@ -298,7 +289,7 @@ When populating a date field, whether a [custom page parameter](#parameters) or
{{% include "/_common/parsable-date-time-strings.md" %}}
-To override the default time zone, set the [`timeZone`](/configuration/all/#timezone) in your project configuration. The order of precedence for determining the time zone is:
+To override the default time zone, set the [`timeZone`][] in your project configuration. The order of precedence for determining the time zone is:
1. The time zone offset in the date/time string
1. The time zone specified in your project configuration
@@ -306,49 +297,45 @@ To override the default time zone, set the [`timeZone`](/configuration/all/#time
[^1]: The `_target` alias for `target` is deprecated and will be removed in a future release.
+[Emacs Org Mode]: https://orgmode.org/
+[JSON]: https://www.json.org/
+[TOML]: https://toml.io/
[URL management]: /content-management/urls/#slug
+[YAML]: https://yaml.org/
+[`Aliases`]: /methods/page/aliases/
+[`Date`]: /methods/page/date/
+[`Description`]: /methods/page/description/
+[`Draft`]: /methods/page/draft/
+[`ExpiryDate`]: /methods/page/expirydate/
+[`FuzzyWordCount`]: /methods/page/wordcount/
[`GetTerms`]: /methods/page/getterms/
+[`Keywords`]: /methods/page/keywords/
+[`Lastmod`]: /methods/page/date/
+[`Layout`]: /methods/page/layout/
+[`LinkTitle`]: /methods/page/linktitle/
[`Param`]: /methods/page/param/
[`Params`]: /methods/page/params/
+[`PublishDate`]: /methods/page/publishdate/
+[`ReadingTime`]: /methods/page/readingtime/
+[`Sitemap`]: /methods/page/sitemap/
+[`Slug`]: /methods/page/slug/
[`Summary`]: /methods/page/summary/
-[`aliases`]: /methods/page/aliases/
-[`date`]: /methods/page/date/
-[`description`]: /methods/page/description/
-[`draft`]: /methods/page/draft/
-[`expirydate`]: /methods/page/expirydate/
-[`fuzzywordcount`]: /methods/page/wordcount/
-[`keywords`]: /methods/page/keywords/
-[`lastmod`]: /methods/page/date/
-[`layout`]: /methods/page/layout/
-[`linktitle`]: /methods/page/linktitle/
-[`opengraph.html`]: <{{% eturl opengraph %}}>
-[`publishdate`]: /methods/page/publishdate/
-[`readingtime`]: /methods/page/readingtime/
-[`schema.html`]: <{{% eturl schema %}}>
-[`sitemap`]: /methods/page/sitemap/
-[`slug`]: /methods/page/slug/
-[`title`]: /methods/page/title/
-[`translationkey`]: /methods/page/translationkey/
-[`twitter_cards.html`]: <{{% eturl twitter_cards %}}>
-[`type`]: /methods/page/type/
-[`weight`]: /methods/page/weight/
-[`wordcount`]: /methods/page/wordcount/
+[`Title`]: /methods/page/title/
+[`TranslationKey`]: /methods/page/translationkey/
+[`Type`]: /methods/page/type/
+[`Weight`]: /methods/page/weight/
+[`WordCount`]: /methods/page/wordcount/
+[`timeZone`]: /configuration/all/#timezone
[aliases]: /content-management/urls/#aliases
[build options]: /content-management/build-options/
-[cascade]: #cascade-1
[configure outputs]: /configuration/outputs/#outputs-per-page
[content format]: /content-management/formats/
[content formats]: /content-management/formats/#classification
-[emacs org mode]: https://orgmode.org/
-[embedded templates]: /templates/embedded/
-[json]: https://www.json.org/
+[details]: /configuration/cascade/
[leaf bundles]: /content-management/page-bundles/#leaf-bundles
[menus]: /content-management/menus/#define-in-front-matter
[output formats]: /configuration/output-formats/
-[page parameters]: #parameters
[page resources]: /content-management/page-resources/#metadata
[sitemap templates]: /templates/sitemap/
[target a specific template]: /templates/lookup-order/#target-a-template
[template lookup order]: /templates/lookup-order/
-[toml]: https://toml.io/
-[yaml]: https://yaml.org/
diff --git a/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md
index 173f3b3d3..9e8fa952e 100644
--- a/docs/content/en/content-management/image-processing/index.md
+++ b/docs/content/en/content-management/image-processing/index.md
@@ -7,7 +7,7 @@ keywords: []
Hugo provides methods to transform and analyze images during the build process. While Hugo can manage any image format as a resource, only [processable images](g) can be transformed using the methods below. The results are cached to ensure subsequent builds remain fast.
-> [!note]
+> [!NOTE]
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
## Resources
@@ -18,7 +18,7 @@ To process an image you must capture the file as a page resource, a global resou
{{% glossary-term "page resource" %}}
-```text
+```tree
content/
└── posts/
└── post-1/ <-- page bundle
@@ -36,7 +36,7 @@ To capture an image as a page resource:
{{% glossary-term "global resource" %}}
-```text
+```tree
assets/
└── images/
└── sunset.jpg <-- global resource
@@ -115,7 +115,7 @@ To transform an image, apply a processing method to the image resource. Hugo gen
{{ end }}
```
-> [!note]
+> [!NOTE]
> Metadata is not preserved during image transformation. Use the [`Meta`][] method with the original image resource to extract metadata from supported formats.
Select a method from the table below for syntax and usage examples, depending on your specific transformation or metadata requirements:
@@ -146,7 +146,7 @@ If you host your site with Netlify, include the following in your project config
If you change image processing methods, or rename/remove images, the cache will eventually contain unused files. To remove them and reclaim disk space, run Hugo's garbage collection:
-```text
+```sh
hugo build --gc
```
@@ -158,7 +158,7 @@ If your source images are much larger than the maximum size you intend to publis
## Configuration
-See [configure imaging](/configuration/imaging).
+See [configure imaging][].
[`Height`]: /methods/resource/height/
[`Meta`]: /methods/resource/meta/
@@ -166,4 +166,5 @@ See [configure imaging](/configuration/imaging).
[`RelPermalink`]: /methods/resource/relpermalink/
[`Width`]: /methods/resource/width/
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[configure imaging]: /configuration/imaging/
[file cache]: /configuration/caches/
diff --git a/docs/content/en/content-management/markdown-attributes.md b/docs/content/en/content-management/markdown-attributes.md
index 17533ebfa..c9ff8395e 100644
--- a/docs/content/en/content-management/markdown-attributes.md
+++ b/docs/content/en/content-management/markdown-attributes.md
@@ -11,14 +11,14 @@ Hugo supports Markdown attributes on images and block elements including blockqu
For example:
-```text
+```md
This is a paragraph.
{class="foo bar" id="baz"}
```
With `class` and `id` attributes you can also use short-form notation:
-```text
+```md
This is a paragraph.
{.foo .bar #baz}
```
@@ -48,7 +48,7 @@ block = true # default is false
## Standalone images
-By default, when the [Goldmark][] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification][].
+By default, when the [Goldmark][] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark][] specification.
If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image.
@@ -63,14 +63,14 @@ wrapStandAloneImageWithinParagraph = false # default is true
You may add [global HTML attributes][], or HTML attributes specific to the current element type. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`.
-> [!note]
+> [!NOTE]
> Within fenced code blocks, Hugo interprets the `style` attribute as a syntax highlighting [option][option] rather than a global HTML attribute.
The attribute list consists of one or more key-value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value.
For example:
-```text
+```md
> This is a blockquote.
{class="foo bar" hidden=hidden}
```
@@ -85,20 +85,20 @@ Hugo renders this to:
In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right.
-Element|Position of attribute list
-:--|:--
-blockquote|bottom
-fenced code block|right
-heading|right
-horizontal rule|bottom
-image|bottom
-list|bottom
-paragraph|bottom
-table|bottom
+Element | Position of attribute list
+:-----------------|:--------------------------
+blockquote | bottom
+fenced code block | right
+heading | right
+horizontal rule | bottom
+image | bottom
+list | bottom
+paragraph | bottom
+table | bottom
For example:
-````text
+````md
## Section 1 {class=foo}
```sh {class=foo linenos=inline}
@@ -112,8 +112,8 @@ This is a paragraph.
As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options][option].
-[CommonMark specification]: https://spec.commonmark.org/current/
-[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
+[CommonMark]: https://spec.commonmark.org/current/
[Goldmark]: https://github.com/yuin/goldmark
-[render hook templates]: /render-hooks/introduction/
+[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
[option]: /functions/transform/highlight/#options
+[render hook templates]: /render-hooks/introduction/
diff --git a/docs/content/en/content-management/mathematics.md b/docs/content/en/content-management/mathematics.md
index 6b86cac1c..529d6694b 100644
--- a/docs/content/en/content-management/mathematics.md
+++ b/docs/content/en/content-management/mathematics.md
@@ -12,7 +12,7 @@ Mathematical equations and expressions written in [LaTeX][] are common in academ
For example, this LaTeX markup:
-```text
+```md
\[
\begin{aligned}
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
@@ -34,7 +34,7 @@ Equations and expressions can be displayed inline with other text, or as standal
Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different.
-> [!note]
+> [!NOTE]
> You can configure Hugo to render mathematical markup on the client side using the MathJax or KaTeX display engine, or you can render the markup with the [`transform.ToMath`][] function while building your project.
>
> The first approach is described below.
@@ -58,12 +58,12 @@ Step 1
math = true
{{< /code-toggle >}}
- The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your project configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3][].
+ The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your project configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3](#step-3).
- > [!note]
+ > [!NOTE]
> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
>
- > See the [inline delimiters][] section for details.
+ > See the [inline delimiters](#inline-delimiters) section for details.
To disable passthrough of inline snippets, omit the `inline` key from the configuration:
@@ -72,7 +72,7 @@ Step 1
block = [['\[', '\]'], ['$$', '$$']]
{{< /code-toggle >}}
- You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2][].
+ You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2](#step-2).
{{< code-toggle file=hugo >}}
[markup.goldmark.extensions.passthrough.delimiters]
@@ -81,7 +81,7 @@ Step 1
{{< /code-toggle >}}
Step 2
-: Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines][] section.
+: Create a _partial_ template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
```go-html-template {file="layouts/_partials/math.html" copy=true}
@@ -129,7 +129,7 @@ Step 4
Step 5
: Include mathematical equations and expressions in Markdown using LaTeX markup.
- ```text {file="content/math-examples.md" copy=true}
+ ```md {file="content/math-examples.md" copy=true}
This is an inline \(a^*=x-b^*\) equation.
These are block equations:
@@ -159,44 +159,33 @@ The configuration, JavaScript, and examples above use the `\(...\)` delimiter pa
If you add the `$...$` delimiter pair to your configuration and JavaScript, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting. For example:
-```text
+```md
I will give you \\$2 if you can solve $y = x^2$.
```
-> [!note]
+> [!NOTE]
> If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation][].
## Engines
MathJax and KaTeX are open-source JavaScript display engines.
-> [!note]
+> [!NOTE]
> If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation][].
>
->See the [inline delimiters][] section for details.
+>See the [inline delimiters](#inline-delimiters) section for details.
-To use KaTeX instead of MathJax, replace the _partial_ template from [Step 2][] with this:
+To use KaTeX instead of MathJax, replace the _partial_ template from [Step 2](#step-2) with this:
```go-html-template {file="layouts/_partials/math.html" copy=true}
-
-
-
+
+
+
- {{ end }}
- {{ else }}
-
- {{ end }}
- {{ end }}
-{{ end }}
-```
+The `js.Babel` function transforms JavaScript using [Babel][].
## Setup
Step 1
-: Install [Node.js](https://nodejs.org/en/download)
+: Install [Node.js][].
Step 2
-: Install the required Node packages in the root of your project.
+: Install the required Node packages in the root of your project. For example, to install Babel's core compiler, its command-line interface, and the preset for transpiling modern JavaScript based on your target environments:
```sh
- npm install --save-dev @babel/core @babel/cli
+ npm install --save-dev @babel/core @babel/cli @babel/preset-env
```
Step 3
-: Add the babel executable to Hugo's `security.exec.allow` list in your project configuration:
+: Create a Babel configuration file in the root of your project. For example, to use the environment preset to target Google Chrome version 79 or later:
+
+ ```js {file="babel.config.mjs" copy=true}
+ export default {
+ presets: [
+ [
+ '@babel/preset-env',
+ {
+ targets: {
+ chrome: "79"
+ }
+ }
+ ]
+ ]
+ };
+ ```
+
+Step 4
+: Place your JS file within the `assets/js` directory.
+
+Step 5
+: Add the Babel executable to Hugo's `security.exec.allow` list in your project configuration:
{{< code-toggle file=hugo >}}
[security.exec]
- allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$']
+ allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^git$', '^node$', '^postcss$', '^tailwindcss$', '^babel$']
{{< /code-toggle >}}
-## Configuration
+Step 6
+: Create a partial template to process the JavaScript:
-We add the main project's `node_modules` to `NODE_PATH` when running Babel and similar tools. There are some known [issues](https://github.com/babel/babel/issues/5618) with Babel in this area, so if you have a `babel.config.js` living in a Hugo Module (and not in the project itself), we recommend using `require` to load the presets/plugins, e.g.:
+ ```go-html-template {file="layouts/_partials/js.html" copy=true}
+ {{ with resources.Get "js/main.js" }}
+ {{ $opts := dict
+ "minified" (cond hugo.IsDevelopment false true)
+ "noComments" (cond hugo.IsDevelopment false true)
+ "sourceMap" (cond hugo.IsDevelopment "inline" "none")
+ }}
+ {{ with . | js.Babel $opts }}
+ {{ if hugo.IsDevelopment }}
+
+ {{ else }}
+ {{ with . | fingerprint }}
+
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ ```
-```js
-module.exports = {
- presets: [
- [
- require("@babel/preset-env"),
- {
- useBuiltIns: "entry",
- corejs: 3,
- },
- ],
- ],
-};
-```
+Step 7
+: Call the partial template from your base template:
+
+ ```go-html-template {file="layouts/baseof.html" copy=true}
+
+ {{ partial "js.html" . }}
+
+ ```
## Options
-compact
-: (`bool`) Whether to remove optional newlines and whitespace. Enabled when `minified` is `true`. Default is `false`
+The `js.Babel` function accepts an options map.
-config
-: (`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` file in the root of your project. See [details](https://babeljs.io/docs/en/configuration).
+`compact`
+: (`bool`) Whether to remove optional newlines and whitespace. Enabled when `minified` is `true`. Default is `false`.
-minified
-: (`bool`) Whether to minify the compiled code. Enables the `compact` option. Default is `false`.
+`config`
+: (`string`) The path to the Babel configuration file. By default, Hugo searches the root of the project directory and any modules for `babel.config.js`, `babel.config.mjs`, and `babel.config.cjs` in that order. Use this option only to point to a configuration file with a custom name or one located in a custom subdirectory.
-noBabelrc
-: (`string`) Whether to ignore `.babelrc` and `.babelignore` files. Default is `false`.
+`minified`
+: (`bool`) Whether to minify transpiled code. Enables the `compact` option. Default is `false`.
-noComments
+`noBabelrc`
+: (`bool`) Whether to ignore `.babelrc` and `.babelignore` files. Default is `false`.
+
+`noComments`
: (`bool`) Whether to remove comments. Default is `false`.
-sourceMap
+`sourceMap`
: (`string`) Whether to generate source maps, one of `external`, `inline`, or `none`. Default is `none`.
-verbose
-: (`bool`) Whether to enable verbose logging. Default is `false`
+`verbose`
+: (`bool`) Whether to enable verbose logging. Default is `false`.
+
+[Babel]: https://babeljs.io/
+[Node.js]: https://nodejs.org/en/download
diff --git a/docs/content/en/functions/js/Batch.md b/docs/content/en/functions/js/Batch.md
index b4b85cd51..703ad47c0 100644
--- a/docs/content/en/functions/js/Batch.md
+++ b/docs/content/en/functions/js/Batch.md
@@ -10,23 +10,23 @@ params:
signatures: ['js.Batch [ID]']
---
-> [!note]
+> [!NOTE]
> The `js.Batch` function is backed by the [`evanw/esbuild`][] package, providing a mature, high-performance foundation for bundling, transformation, and minification.
-> [!note]
-> For a runnable example of this feature, see [this test and demo repo](https://github.com/bep/hugojsbatchdemo/).
+> [!NOTE]
+> For a runnable example of this feature, see [this test and demo repo][js_batch_demo].
-The Batch `ID` is used to create the base directory for this batch. Forward slashes are allowed. `js.Batch` returns an object with an API with this structure:
+The Batch `ID` is used to create the base directory for this batch. Forward slashes are allowed. The `js.Batch` function returns an object with an API with this structure:
-- [Group]
- - [Script]
- - [SetOptions]
- - [Instance]
- - [SetOptions]
- - [Runner]
- - [SetOptions]
- - [Config]
- - [SetOptions]
+- [Group](#group)
+ - [Script](#script)
+ - [SetOptions](#optionssetter)
+ - [Instance](#instance)
+ - [SetOptions](#optionssetter)
+ - [Runner](#runner)
+ - [SetOptions](#optionssetter)
+ - [Config](#config)
+ - [SetOptions](#optionssetter)
## Group
@@ -34,7 +34,7 @@ The `Group` method take an `ID` (`string`) as argument. No slashes. It returns a
### Script
-The `Script` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter] that can be used to set [script options] for this script.
+The `Script` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter](#optionssetter) that can be used to set [script options](#script-options) for this script.
```go-html-template
{{ with js.Batch "js/mybatch" }}
@@ -46,11 +46,11 @@ The `Script` method takes an `ID` (`string`) as argument. No slashes. It returns
{{ end }}
```
-`SetOptions` takes a [script options] map. Note that if you want the script to be handled by a [runner], you need to set the `export` option to match what you want to pass on to the runner (default is `*`).
+`SetOptions` takes a [script options](#script-options) map. Note that if you want the script to be handled by a [Runner](#runner), you need to set the `export` option to match what you want to pass on to the runner (default is `*`).
### Instance
-The `Instance` method takes two `string` arguments `SCRIPT_ID` and `INSTANCE_ID`. No slashes. It returns an [OptionsSetter] that can be used to set [params options] for this instance.
+The `Instance` method takes two `string` arguments `SCRIPT_ID` and `INSTANCE_ID`. No slashes. It returns an [OptionsSetter](#optionssetter) that can be used to set [params options](#params-options) for this instance.
```go-html-template
{{ with js.Batch "js/mybatch" }}
@@ -62,11 +62,11 @@ The `Instance` method takes two `string` arguments `SCRIPT_ID` and `INSTANCE_ID`
{{ end }}
```
-`SetOptions` takes a [params options] map. The instance options will be passed to any [runner] script in the same group, as JSON.
+`SetOptions` takes a [params options](#params-options) map. The instance options will be passed to any [Runner](#runner) script in the same group, as JSON.
### Runner
-The `Runner` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter] that can be used to set [script options] for this runner.
+The `Runner` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter](#optionssetter) that can be used to set [script options](#script-options) for this runner.
```go-html-template
{{ with js.Batch "js/mybatch" }}
@@ -78,9 +78,9 @@ The `Runner` method takes an `ID` (`string`) as argument. No slashes. It returns
{{ end }}
```
-`SetOptions` takes a [script options] map.
+`SetOptions` takes a [script options](#script-options) map.
-The runner will receive a data structure with all instances for that group with a live binding of the [JavaScript import] of the defined `export`.
+The runner will receive a data structure with all instances for that group with a live binding of the [JavaScript import][] of the defined `export`.
The runner script's export must be a function that takes one argument, the group data structure. An example of a group data structure as JSON is:
@@ -120,7 +120,7 @@ The runner script's export must be a function that takes one argument, the group
}
```
-Below is an example of a runner script that uses React to render elements. Note that the export (`default`) must match the `export` option in the [script options] (`default` is the default value for runner scripts) (runnable versions of examples on this page can be found at [js.Batch Demo Repo]):
+Below is an example of a runner script that uses React to render elements. Note that the export (`default`) must match the `export` option in the [script options](#script-options) (`default` is the default value for runner scripts). Runnable versions of the examples on this page can be found in this `js.Batch` [demonstration repository][js_batch_demo].
```js
import * as ReactDOM from 'react-dom/client';
@@ -148,20 +148,20 @@ export default function Run(group) {
### Config
-Returns an [OptionsSetter] that can be used to set [build options] for the batch.
+Returns an [OptionsSetter](#optionssetter) that can be used to set [build options](#build-options) for the batch.
These are mostly the same as for `js.Build`, but note that:
- `targetPath` is set automatically (there may be multiple outputs).
-- `format` must be `esm`, currently the only format supporting [code splitting].
-- `params` will be available in the `@params/config` namespace in the scripts. This way you can import both the [script] or [runner] params and the [config] params with:
+- `format` must be `esm`, currently the only format that supports [code splitting][].
+- `params` will be available in the `@params/config` namespace in the scripts. This way you can import both the [Script](#script) or [Runner](#runner) params and the [Config](#config) params with:
```js
import * as params from "@params";
import * as config from "@params/config";
```
-Setting the `Config` for a batch can be done from any template (including _shortcode_ templates), but will only be set once (the first will win):
+Setting the `Config` for a batch can be done from any template (including shortcode templates), but will only be set once (the first will win):
```go-html-template
{{ with js.Batch "js/mybatch" }}
@@ -183,23 +183,23 @@ Setting the `Config` for a batch can be done from any template (including _short
### Build options
-format
-: (`string`) Currently only `esm` is supported in ESBuild's [code splitting].
+`format`
+: (`string`) Currently, `esbuild` only supports `esm` output for [code splitting][].
{{% include "/_common/functions/js/options.md" %}}
### Script options
-resource
+`resource`
: The resource to build. This can be a file resource or a virtual resource.
-export
-: The export to bind the runner to. Set it to `*` to export the [entire namespace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#namespace_import). Default is `default` for [runner] scripts and `*` for other [scripts](#script).
+`export`
+: The export to bind the runner to. Set it to `*` to export the [entire namespace][]. Default is `default` for [Runner](#runner) scripts and `*` for other [scripts](#script).
-importContext
+`importContext`
: An additional context for resolving imports. Hugo will always check this one first before falling back to `assets` and `node_modules`. A common use of this is to resolve imports inside a page bundle. See [import context](#import-context).
-params
+`params`
: A map of parameters that will be passed to the script as JSON. These gets bound to the `@params` namespace:
```js
@@ -208,25 +208,25 @@ params
### Params options
-params
+`params`
: A map of parameters that will be passed to the script as JSON.
### Import context
-Hugo will, by default, first try to resolve any import in [assets](/hugo-pipes/introduction/#asset-directory) and, if not found, let [ESBuild] resolve it (e.g. from `node_modules`). The `importContext` option can be used to set the first context for resolving imports. A common use of this is to resolve imports inside a [page bundle](/content-management/page-bundles/).
+Hugo will, by default, first try to resolve any import in the `assets` directory and, if not found, let `esbuild` resolve it (e.g. from `node_modules`). The `importContext` option can be used to set the first context for resolving imports. A common use of this is to resolve imports inside a [page bundle][].
```go-html-template
{{ $common := resources.Match "/js/headlessui/*.*" }}
{{ $importContext := (slice $.Page ($common.Mount "/js/headlessui" ".")) }}
```
-You can pass any object that implements [Resource.Get](/methods/page/resources/#get). Pass a slice to set multiple contexts.
+You can pass any object that implements [`Resource.Get`][]. Pass a slice to set multiple contexts.
-The example above uses [`Resources.Mount`] to resolve a directory inside `assets` relative to the page bundle.
+The example above uses [`Resources.Mount`][] to resolve a directory inside `assets` relative to the page bundle.
### OptionsSetter
-An `OptionsSetter` is a special object that is returned once only. This means that you should wrap it with [with]:
+An `OptionsSetter` is a special object that is returned once only. This means that you should wrap it with [`with`][]:
```go-html-template
{{ with .Script "myscript" }}
@@ -239,16 +239,16 @@ An `OptionsSetter` is a special object that is returned once only. This means th
The `Build` method returns an object with the following structure:
- Groups (map)
- - [`Resources`]
+ - [`Resources`][]
-Each [`Resource`] will be of media type `application/javascript` or `text/css`.
+Each [`Resource`][] will be of media type `application/javascript` or `text/css`.
-In a template you would typically handle one group with a given `ID` (e.g. scripts for the current section). Because of the concurrent build, this needs to be done in a [`templates.Defer`] block:
+In a template you would typically handle one group with a given `ID` (e.g., scripts for the current section). Because of the concurrent build, this needs to be done in a [`templates.Defer`][] block:
-> [!note]
-> The [`templates.Defer`] acts as a synchronisation point to handle scripts added concurrently by different templates. If you have a setup with where the batch is created in one go (in one template), you don't need it.
+> [!NOTE]
+> The [`templates.Defer`][] acts as a synchronisation point to handle scripts added concurrently by different templates. If you have a setup with where the batch is created in one go (in one template), you don't need it.
>
-> See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global-script/53002/5?u=bep) for more.
+> See [this discussion][] for more information.
```go-html-template
{{ $group := .group }}
@@ -271,17 +271,17 @@ In a template you would typically handle one group with a given `ID` (e.g. scrip
## Known Issues
-In the official documentation for ESBuild's [code splitting], there's a warning note in the header. The two issues are:
+In the official documentation for the `esbuild` [code splitting][] feature, there's a warning note in the header. The two issues are:
-- `esm` is currently the only implemented output format. This means that it will not work for very old browsers. See [caniuse](https://caniuse.com/?search=ESM).
+- `esm` is currently the only implemented output format. This means that it will not work for legacy browsers. See [caniuse][].
- There's a known import ordering issue.
-We have not seen the ordering issue as a problem during our [extensive testing](https://github.com/bep/hugojsbatchdemo) of this new feature with different libraries. There are two main cases:
+We have not seen the ordering issue as a problem during our [extensive testing][] of this new feature with different libraries. There are two main cases:
-1. Undefined execution order of imports, see [this comment](https://github.com/evanw/esbuild/issues/399#issuecomment-1458680887)
-1. Only one execution order of imports, see [this comment](https://github.com/evanw/esbuild/issues/399#issuecomment-735355932)
+1. Undefined execution order of imports, see [this comment][comment-1]
+1. Only one execution order of imports, see [this comment][comment-2]
-Many would say that both of the above are [code smells](https://en.wikipedia.org/wiki/Code_smell). The first one has a simple workaround in Hugo. Define the import order in its own script and make sure it gets passed early to ESBuild, e.g. by putting it in a script group with a name that comes early in the alphabet.
+Many would say that both of the above are [code smells][]. The first one has a simple workaround in Hugo. Define the import order in its own script and make sure it gets passed early to `esbuild`, e.g., by putting it in a script group with a name that comes early in the alphabet.
```js
import './lib2.js';
@@ -290,23 +290,21 @@ import './lib1.js';
console.log('entrypoints-workaround.js');
```
-[ESBuild]: https://github.com/evanw/esbuild
[JavaScript import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
-[OptionsSetter]: #optionssetter
-[SetOptions]: #optionssetter
+[`Resource.Get`]: /methods/page/resources/#get
[`Resource`]: /methods/resource/
[`Resources.Mount`]: /methods/page/resources/#mount
[`Resources`]: /methods/page/resources/
[`evanw/esbuild`]: https://github.com/evanw/esbuild
[`templates.Defer`]: /functions/templates/defer/
-[build options]: #build-options
+[`with`]: /functions/go-template/with/
+[caniuse]: https://caniuse.com/?search=ESM
+[code smells]: https://en.wikipedia.org/wiki/Code_smell
[code splitting]: https://esbuild.github.io/api/#splitting
-[config]: #config
-[group]: #group
-[instance]: #instance
-[js.Batch Demo Repo]: https://github.com/bep/hugojsbatchdemo/
-[params options]: #params-options
-[runner]: #runner
-[script options]: #script-options
-[script]: #script
-[with]: /functions/go-template/with/
+[comment-1]: https://github.com/evanw/esbuild/issues/399#issuecomment-1458680887
+[comment-2]: https://github.com/evanw/esbuild/issues/399#issuecomment-735355932
+[entire namespace]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#namespace_import
+[extensive testing]: https://github.com/bep/hugojsbatchdemo
+[js_batch_demo]: https://github.com/bep/hugojsbatchdemo/
+[page bundle]: /content-management/page-bundles/
+[this discussion]: https://discourse.gohugo.io/t/js-batch-with-simple-global-script/53002/5
diff --git a/docs/content/en/functions/js/Build.md b/docs/content/en/functions/js/Build.md
index 60960a15d..56371ddfe 100644
--- a/docs/content/en/functions/js/Build.md
+++ b/docs/content/en/functions/js/Build.md
@@ -10,7 +10,7 @@ params:
signatures: ['js.Build [OPTIONS] RESOURCE']
---
-> [!note]
+> [!NOTE]
> The `js.Build` function is backed by the [`evanw/esbuild`][] package, providing a mature, high-performance foundation for bundling, transformation, and minification.
Use the `js.Build` function to:
@@ -41,17 +41,19 @@ Use the `js.Build` function to:
## Options
-targetPath
-: (`string`) If not set, the source path will be used as the base target path. Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript.
+The `js.Build` function accepts an options map.
-format
+`format`
: (`string`) The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a `
```
+[`esbuild`]: https://esbuild.github.io/
[`evanw/esbuild`]: https://github.com/evanw/esbuild
+[`hugo mod npm pack`]: /commands/hugo_mod_npm_pack/
+[test project]: https://github.com/gohugoio/hugoTestProjectJSModImports
+[turn it off]: /configuration/build/#nojsconfiginassets
diff --git a/docs/content/en/functions/lang/FormatNumberCustom.md b/docs/content/en/functions/lang/FormatNumberCustom.md
index 0a70cd938..817dc1c16 100644
--- a/docs/content/en/functions/lang/FormatNumberCustom.md
+++ b/docs/content/en/functions/lang/FormatNumberCustom.md
@@ -15,7 +15,7 @@ This function formats a number with the given precision. The first options param
Note that numbers are rounded up at 5 or greater. So, with precision set to 0, 1.5 becomes 2, and 1.4 becomes 1.
-For a simpler function that adapts to the current language, see [`lang.FormatNumber`].
+For a simpler function that adapts to the current language, see [`lang.FormatNumber`][].
```go-html-template
{{ lang.FormatNumberCustom 2 12345.6789 }} → 12,345.68
diff --git a/docs/content/en/functions/lang/Translate.md b/docs/content/en/functions/lang/Translate.md
index f8bdc069b..3787d9169 100644
--- a/docs/content/en/functions/lang/Translate.md
+++ b/docs/content/en/functions/lang/Translate.md
@@ -15,7 +15,7 @@ The `lang.Translate` function returns the value associated with the given key by
If not found, the function returns an empty string.
-> [!note]
+> [!NOTE]
> To list missing and fallback translations, set [`printI18nWarnings`][] to `true` in your project configuration, or use the `--printI18nWarnings` flag when building your project.
>
> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`][] to `true` in your project configuration.
@@ -45,14 +45,14 @@ i18n/art-x-hugolang.toml
i18n/hugolang.toml
```
-> [!note]
+> [!NOTE]
> Private use subtags must not exceed 8 alphanumeric characters.
## Simple translations
Let's say your multilingual project supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
-```text
+```tree
i18n/
├── en.toml
└── pl.toml
@@ -72,7 +72,7 @@ privacy = 'prywatność'
security = 'bezpieczeństwo'
{{< /code-toggle >}}
-> [!note]
+> [!NOTE]
> The examples below use the `T` alias for brevity.
When viewing the English language site:
@@ -93,7 +93,7 @@ When viewing the Polish language site:
Let's say your multilingual project supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
-```text
+```tree
i18n/
├── en.toml
└── pl.toml
@@ -129,7 +129,7 @@ many = '{{ . }} miesięcy'
other = '{{ . }} miesiąca'
{{< /code-toggle >}}
-> [!note]
+> [!NOTE]
> The examples below use the `T` alias for brevity.
When viewing the English language site:
@@ -177,44 +177,44 @@ Template code:
{{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old.
```
-> [!note]
+> [!NOTE]
> Translation tables may contain both simple translations and translations with pluralization.
## Reserved keys
Hugo uses the [`nicksnyder/go-i18n`][] package to look up values in translation tables. This package reserves the following keys for internal use:
-id
+`id`
: (`string`) Uniquely identifies the message.
-description
+`description`
: (`string`) Describes the message to give additional context to translators that may be relevant for translation.
-hash
+`hash`
: (`string`) Uniquely identifies the content of the message that this message was translated from.
-leftdelim
+`leftdelim`
: (`string`) The left Go template delimiter.
-rightdelim
+`rightdelim`
: (`string`) The right Go template delimiter.
-zero
+`zero`
: (`string`) The content of the message for the [CLDR][] plural form "zero".
-one
+`one`
: (`string`) The content of the message for the [CLDR][] plural form "one".
-two
+`two`
: (`string`) The content of the message for the [CLDR][] plural form "two".
-few
+`few`
: (`string`) The content of the message for the [CLDR][] plural form "few".
-many
+`many`
: (`string`) The content of the message for the [CLDR][] plural form "many".
-other
+`other`
: (`string`) The content of the message for the [CLDR][] plural form "other".
If you need to provide a translation for one of the reserved keys, you can prepend the word with an underscore. For example:
diff --git a/docs/content/en/functions/math/Counter.md b/docs/content/en/functions/math/Counter.md
index 9eb6cb785..f86dbe9e3 100644
--- a/docs/content/en/functions/math/Counter.md
+++ b/docs/content/en/functions/math/Counter.md
@@ -24,10 +24,10 @@ WARN page.html called 3 times
Use this function to:
-- Create unique warnings as shown above; the [`warnf`] function suppresses duplicate messages
+- Create unique warnings as shown above; the [`warnf`][] function suppresses duplicate messages
- Create unique target paths for the `resources.FromString` function where the target path is also the cache key
-> [!note]
+> [!NOTE]
> Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page.
[`warnf`]: /functions/fmt/warnf/
diff --git a/docs/content/en/functions/openapi3/Unmarshal.md b/docs/content/en/functions/openapi3/Unmarshal.md
index f64ee1147..139923dd0 100644
--- a/docs/content/en/functions/openapi3/Unmarshal.md
+++ b/docs/content/en/functions/openapi3/Unmarshal.md
@@ -16,9 +16,10 @@ This function automatically resolves and includes all external references, both
## Options
-{{< new-in 0.153.0 />}}
+The `openapi3.Unmarshal` function accepts an options map.
-getremote
+`getremote`
+: {{< new-in 0.153.0 />}}
: (`map`) This is a map of the options for the [`resources.GetRemote`][] function, useful when an OpenAPI Document includes remote external references.
## Examples
@@ -65,10 +66,12 @@ For global resources, local external reference paths starting with `/` are resol
## Inspection
-> [!note]
-> The unmarshaled data structure is created with [`kin-openapi`](https://github.com/getkin/kin-openapi). Many fields are structs or pointers (not maps), and therefore require accessors or other methods for indexing and iteration.
-> For example, prior to [`kin-openapi` v0.122.0](https://github.com/getkin/kin-openapi#v01220) / [Hugo v0.121.0](https://github.com/gohugoio/hugo/releases/tag/v0.121.0), `Paths` was a map (so `.Paths` was iterable) and it is now a pointer (and requires the `.Paths.Map` accessor, as in the example above).
-> See the [`kin-openapi` godoc for OpenAPI 3](https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3) for full type definitions.
+> [!NOTE]
+> The unmarshaled data structure is created with [`kin-openapi`][]. Many fields are structs or pointers (not maps), and therefore require accessors or other methods for indexing and iteration.
+>
+> For example, `Paths` is a pointer rather than a map; to iterate over the API paths, you must use the `.Paths.Map` accessor as shown in the example below.
+>
+> See the [`kin-openapi` godoc for OpenAPI 3][] for full type definitions.
To inspect the unmarshaled data structure:
@@ -111,6 +114,8 @@ Hugo renders this to:
```
-[`resources.GetRemote`]: /functions/resources/getremote/#options
-[OpenAPI Document]: https://swagger.io/specification/#openapi-document
[OpenAPI Description]: https://swagger.io/specification/#openapi-description
+[OpenAPI Document]: https://swagger.io/specification/#openapi-document
+[`kin-openapi` godoc for OpenAPI 3]: https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3
+[`kin-openapi`]: https://github.com/getkin/kin-openapi
+[`resources.GetRemote`]: /functions/resources/getremote/#options
diff --git a/docs/content/en/functions/os/FileExists.md b/docs/content/en/functions/os/FileExists.md
index b8a01a3e7..0d0a4961c 100644
--- a/docs/content/en/functions/os/FileExists.md
+++ b/docs/content/en/functions/os/FileExists.md
@@ -11,11 +11,11 @@ params:
aliases: [/functions/fileexists]
---
-The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional.
+The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`][]. A leading path separator (`/`) is optional.
With this directory structure:
-```text
+```tree
content/
├── about.md
├── contact.md
@@ -35,3 +35,5 @@ The function returns these values:
{{ fileExists "news/article-1" }} → false
{{ fileExists "news/article-1.md" }} → true
```
+
+[`contentDir`]: /configuration/all/#contentdir
diff --git a/docs/content/en/functions/os/Getenv.md b/docs/content/en/functions/os/Getenv.md
index d9e6e08fe..4276ec5ef 100644
--- a/docs/content/en/functions/os/Getenv.md
+++ b/docs/content/en/functions/os/Getenv.md
@@ -25,7 +25,7 @@ To access other environment variables, adjust your project configuration. For ex
getenv = ['^HUGO_', '^CI$', '^USER$', '^HOME$']
{{< /code-toggle >}}
-For more information see [configure security](/configuration/security).
+For more information see [configure security][].
## Examples
@@ -52,3 +52,5 @@ And then retrieve the values within a template:
{{ getenv "MY_VAR1" }} → foo
{{ getenv "MY_VAR2" }} → bar
```
+
+[configure security]: /configuration/security/
diff --git a/docs/content/en/functions/os/ReadDir.md b/docs/content/en/functions/os/ReadDir.md
index 65c398a31..915cab9f0 100644
--- a/docs/content/en/functions/os/ReadDir.md
+++ b/docs/content/en/functions/os/ReadDir.md
@@ -15,7 +15,7 @@ The `os.ReadDir` function resolves the path relative to the root of your project
With this directory structure:
-```text
+```tree
content/
├── about.md
├── contact.md
@@ -42,4 +42,6 @@ news → true
Note that `os.ReadDir` is not recursive.
-Details of the `FileInfo` structure are available in the [Go documentation](https://pkg.go.dev/io/fs#FileInfo).
+Details of the `FileInfo` structure are available in the [Go documentation][].
+
+[Go documentation]: https://pkg.go.dev/io/fs#FileInfo
diff --git a/docs/content/en/functions/os/ReadFile.md b/docs/content/en/functions/os/ReadFile.md
index 7f25327c8..f33169a2e 100644
--- a/docs/content/en/functions/os/ReadFile.md
+++ b/docs/content/en/functions/os/ReadFile.md
@@ -11,11 +11,11 @@ params:
aliases: [/functions/readfile]
---
-The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional.
+The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`][]. A leading path separator (`/`) is optional.
With a file named README.md in the root of your project directory:
-```text
+```md
This is **bold** text.
```
@@ -32,3 +32,5 @@ This is **bold** text.
```
Note that `os.ReadFile` returns raw (uninterpreted) content.
+
+[`contentDir`]: /configuration/all/#contentdir
diff --git a/docs/content/en/functions/os/Stat.md b/docs/content/en/functions/os/Stat.md
index 63cb3f26a..18f410d97 100644
--- a/docs/content/en/functions/os/Stat.md
+++ b/docs/content/en/functions/os/Stat.md
@@ -11,7 +11,7 @@ params:
aliases: [/functions/os.stat]
---
-The `os.Stat` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional.
+The `os.Stat` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`][]. A leading path separator (`/`) is optional.
```go-html-template
{{ $f := os.Stat "README.md" }}
@@ -24,4 +24,7 @@ The `os.Stat` function attempts to resolve the path relative to the root of your
{{ $d.IsDir }} → true (bool)
```
-Details of the `FileInfo` structure are available in the [Go documentation](https://pkg.go.dev/io/fs#FileInfo).
+Details of the `FileInfo` structure are available in the [Go documentation][].
+
+[Go documentation]: https://pkg.go.dev/io/fs#FileInfo
+[`contentDir`]: /configuration/all/#contentdir
diff --git a/docs/content/en/functions/partials/Include.md b/docs/content/en/functions/partials/Include.md
index dfb8873b4..5e77cdb9b 100644
--- a/docs/content/en/functions/partials/Include.md
+++ b/docs/content/en/functions/partials/Include.md
@@ -11,11 +11,11 @@ params:
aliases: [/functions/partial]
---
-Without a [`return`] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type.
+Without a [`return`][] statement, the `partial` function returns a string of type `template.HTML`. With a `return` statement, the `partial` function can return any data type.
In this example we have three _partial_ templates:
-```text
+```tree
layouts/
└── _partials/
├── average.html
@@ -30,7 +30,7 @@ The "average" partial returns the average of one or more numbers. We pass the nu
{{ $average := partial "average.html" $numbers }}
```
-The "breadcrumbs" partial renders [breadcrumb navigation], and needs to receive the current page in context:
+The "breadcrumbs" partial renders [breadcrumb navigation][], and needs to receive the current page in context:
```go-html-template
{{ partial "breadcrumbs.html" . }}
@@ -74,7 +74,5 @@ To return a value from a _partial_ template, it must contain only one `return` s
{{ return $result }}
```
-See [details][`return`].
-
[`return`]: /functions/go-template/return/
[breadcrumb navigation]: /content-management/sections/#ancestors-and-descendants
diff --git a/docs/content/en/functions/partials/IncludeCached.md b/docs/content/en/functions/partials/IncludeCached.md
index a8a715783..1c19285e0 100644
--- a/docs/content/en/functions/partials/IncludeCached.md
+++ b/docs/content/en/functions/partials/IncludeCached.md
@@ -11,11 +11,11 @@ params:
aliases: [/functions/partialcached]
---
-Without a [`return`] statement, the `partialCached` function returns a string of type `template.HTML`. With a `return` statement, the `partialCached` function can return any data type.
+Without a [`return`][] statement, the `partialCached` function returns a string of type `template.HTML`. With a `return` statement, the `partialCached` function can return any data type.
The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation.
-> [!note]
+> [!NOTE]
> Each site (or language) has its own `partialCached` cache, so each site will execute a partial once.
>
> Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result.
@@ -52,6 +52,4 @@ To return a value from a _partial_ template, it must contain only one `return` s
{{ return $result }}
```
-See [details][`return`].
-
[`return`]: /functions/go-template/return/
diff --git a/docs/content/en/functions/path/Clean.md b/docs/content/en/functions/path/Clean.md
index b9f2de038..240f40086 100644
--- a/docs/content/en/functions/path/Clean.md
+++ b/docs/content/en/functions/path/Clean.md
@@ -11,9 +11,7 @@ params:
aliases: [/functions/path.clean]
---
-See Go's [`path.Clean`] documentation for details.
-
-[`path.Clean`]: https://pkg.go.dev/path#Clean
+See Go's [`path.Clean`][] documentation for details.
```go-html-template
{{ path.Clean "foo/bar" }} → foo/bar
@@ -25,3 +23,5 @@ See Go's [`path.Clean`] documentation for details.
{{ path.Clean "/../foo/../bar/" }} → /bar
{{ path.Clean "" }} → .
```
+
+[`path.Clean`]: https://pkg.go.dev/path#Clean
diff --git a/docs/content/en/functions/path/Join.md b/docs/content/en/functions/path/Join.md
index bda46737f..18bf5f72c 100644
--- a/docs/content/en/functions/path/Join.md
+++ b/docs/content/en/functions/path/Join.md
@@ -11,10 +11,7 @@ params:
aliases: [/functions/path.join]
---
-See Go's [`path.Join`] and [`path.Clean`] documentation for details.
-
-[`path.Clean`]: https://pkg.go.dev/path#Clean
-[`path.Join`]: https://pkg.go.dev/path#Join
+See Go's [`path.Join`][] and [`path.Clean`][] documentation for details.
```go-html-template
{{ path.Join "partial" "news.html" }} → partial/news.html
@@ -26,3 +23,6 @@ See Go's [`path.Join`] and [`path.Clean`] documentation for details.
{{ path.Join "foo" ".." "baz" }} → baz
{{ path.Join "/.." "foo" ".." "baz" }} → baz
```
+
+[`path.Clean`]: https://pkg.go.dev/path#Clean
+[`path.Join`]: https://pkg.go.dev/path#Join
diff --git a/docs/content/en/functions/reflect/IsResource.md b/docs/content/en/functions/reflect/IsResource.md
index ae86b4ecd..52a2a1d7a 100644
--- a/docs/content/en/functions/reflect/IsResource.md
+++ b/docs/content/en/functions/reflect/IsResource.md
@@ -14,7 +14,7 @@ params:
With this project structure:
-```text
+```tree
project/
├── assets/
│ ├── a.json
diff --git a/docs/content/en/functions/resources/ByType.md b/docs/content/en/functions/resources/ByType.md
index 99e2b9771..ca8a8b3eb 100644
--- a/docs/content/en/functions/resources/ByType.md
+++ b/docs/content/en/functions/resources/ByType.md
@@ -10,7 +10,7 @@ params:
signatures: [resources.ByType MEDIATYPE]
---
-The [media type] is typically one of `image`, `text`, `audio`, `video`, or `application`.
+The [media type][] is typically one of `image`, `text`, `audio`, `video`, or `application`.
```go-html-template
{{ range resources.ByType "image" }}
@@ -18,10 +18,10 @@ The [media type] is typically one of `image`, `text`, `audio`, `video`, or `appl
{{ end }}
```
-> [!note]
+> [!NOTE]
> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
>
-> For page resources, use the [`Resources.ByType`] method on a `Page` object.
+> For page resources, use the [`Resources.ByType`][] method on a `Page` object.
[`Resources.ByType`]: /methods/page/resources/
[media type]: https://en.wikipedia.org/wiki/Media_type
diff --git a/docs/content/en/functions/resources/Concat.md b/docs/content/en/functions/resources/Concat.md
index fe7226e1b..03673bf79 100644
--- a/docs/content/en/functions/resources/Concat.md
+++ b/docs/content/en/functions/resources/Concat.md
@@ -10,17 +10,16 @@ params:
signatures: ['resources.Concat TARGETPATH [RESOURCE...]']
---
-The `resources.Concat` function returns a concatenated slice of resources, caching the result using the target path as its cache key. Each resource must have the same [media type].
+The `resources.Concat` function returns a concatenated slice of resources, caching the result using the target path as its cache key. Each resource must have the same [media type](g).
-Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] method.
-
-[media type]: https://en.wikipedia.org/wiki/Media_type
-[`publish`]: /methods/resource/publish/
-[`permalink`]: /methods/resource/permalink/
-[`relpermalink`]: /methods/resource/relpermalink/
+Hugo publishes the resource to the target path when you call its [`Publish`][], [`Permalink`][], or [`RelPermalink`][] method.
```go-html-template
{{ $plugins := resources.Get "js/plugins.js" }}
{{ $global := resources.Get "js/global.js" }}
{{ $js := slice $plugins $global | resources.Concat "js/bundle.js" }}
```
+
+[`Permalink`]: /methods/resource/permalink/
+[`Publish`]: /methods/resource/publish/
+[`RelPermalink`]: /methods/resource/relpermalink/
diff --git a/docs/content/en/functions/resources/Copy.md b/docs/content/en/functions/resources/Copy.md
index 220a3db4c..208f6d65f 100644
--- a/docs/content/en/functions/resources/Copy.md
+++ b/docs/content/en/functions/resources/Copy.md
@@ -17,11 +17,7 @@ params:
{{ end }}
```
-The relative URL of the new published resource will be:
+The `TARGETPATH` is relative to the server root. A leading slash is optional and has no effect.
-```text
-/img/new-image-name.jpg
-```
-
-> [!note]
+> [!NOTE]
> Use the `resources.Copy` function with global, page, and remote resources.
diff --git a/docs/content/en/functions/resources/ExecuteAsTemplate.md b/docs/content/en/functions/resources/ExecuteAsTemplate.md
index 2ffb9dff7..c449ec75d 100644
--- a/docs/content/en/functions/resources/ExecuteAsTemplate.md
+++ b/docs/content/en/functions/resources/ExecuteAsTemplate.md
@@ -12,7 +12,7 @@ params:
The `resources.ExecuteAsTemplate` function returns a resource created from a Go template, parsed and executed with the given context, caching the result using the target path as its cache key.
-Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
+Hugo publishes the resource to the target path when you call its [`Publish`][], [`Permalink`][], or [`RelPermalink`][] methods.
Let's say you have a CSS file that you wish to populate with values from your project configuration:
@@ -56,6 +56,6 @@ body {
}
```
-[`publish`]: /methods/resource/publish/
-[`permalink`]: /methods/resource/permalink/
-[`relpermalink`]: /methods/resource/relpermalink/
+[`Permalink`]: /methods/resource/permalink/
+[`Publish`]: /methods/resource/publish/
+[`RelPermalink`]: /methods/resource/relpermalink/
diff --git a/docs/content/en/functions/resources/Fingerprint.md b/docs/content/en/functions/resources/Fingerprint.md
index 6757a0b6f..c42b0259d 100644
--- a/docs/content/en/functions/resources/Fingerprint.md
+++ b/docs/content/en/functions/resources/Fingerprint.md
@@ -31,6 +31,6 @@ The hash algorithm may be one of `md5`, `sha256` (default), `sha384`, or `sha512
After cryptographically hashing the resource content:
1. The values returned by the `.Permalink` and `.RelPermalink` methods include the hash sum
-1. The resource's `.Data.Integrity` method returns a [Subresource Integrity] (SRI) value consisting of the name of the hash algorithm, one hyphen, and the base64-encoded hash sum
+1. The resource's `.Data.Integrity` method returns a [Subresource Integrity][] (SRI) value consisting of the name of the hash algorithm, one hyphen, and the base64-encoded hash sum
[Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
diff --git a/docs/content/en/functions/resources/FromString.md b/docs/content/en/functions/resources/FromString.md
index 160e85d81..15765445e 100644
--- a/docs/content/en/functions/resources/FromString.md
+++ b/docs/content/en/functions/resources/FromString.md
@@ -12,18 +12,14 @@ params:
The `resources.FromString` function returns a resource created from a string, caching the result using the target path as its cache key.
-Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
-
-[`publish`]: /methods/resource/publish/
-[`permalink`]: /methods/resource/permalink/
-[`relpermalink`]: /methods/resource/relpermalink/
+Hugo publishes the resource to the target path when you call its [`Publish`][], [`Permalink`][], or [`RelPermalink`][] methods.
Let's say you need to publish a file named "site.json" in the root of your `public` directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example:
```json
{
"build_date": "2026-04-04T10:46:21-07:00",
- "hugo_version": "0.161.1",
+ "hugo_version": "0.163.2",
"last_modified": "2026-04-04T10:46:26-07:00"
}
```
@@ -46,12 +42,12 @@ Place this in your baseof.html template:
The example above:
-1. Creates a map with the relevant key-value pairs using the [`dict`] function
-1. Encodes the map as a JSON string using the [`jsonify`] function
+1. Creates a map with the relevant key-value pairs using the [`dict`][] function
+1. Encodes the map as a JSON string using the [`jsonify`][] function
1. Creates a resource from the JSON string using the `resources.FromString` function
1. Publishes the file to the root of the `public` directory using the resource's `.Publish` method
-Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your string contains template actions. Rewriting the example above:
+Combine `resources.FromString` with [`resources.ExecuteAsTemplate`][] if your string contains template actions. Rewriting the example above:
```go-html-template
{{ if .IsHome }}
@@ -71,6 +67,9 @@ Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your stri
{{ end }}
```
+[`Permalink`]: /methods/resource/permalink/
+[`Publish`]: /methods/resource/publish/
+[`RelPermalink`]: /methods/resource/relpermalink/
[`dict`]: /functions/collections/dictionary/
[`jsonify`]: /functions/encoding/jsonify/
[`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate/
diff --git a/docs/content/en/functions/resources/Get.md b/docs/content/en/functions/resources/Get.md
index db91f0a9a..ea0819d1b 100644
--- a/docs/content/en/functions/resources/Get.md
+++ b/docs/content/en/functions/resources/Get.md
@@ -16,9 +16,9 @@ params:
{{ end }}
```
-> [!note]
+> [!NOTE]
> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
>
-> For page resources, use the [`Resources.Get`] method on a `Page` object.
+> For page resources, use the [`Resources.Get`][] method on a `Page` object.
-[`Resources.Get`]: /methods/page/resources/
+[`Resources.Get`]: /methods/page/resources/#get
diff --git a/docs/content/en/functions/resources/GetMatch.md b/docs/content/en/functions/resources/GetMatch.md
index bf6a95486..6d0cd3f2e 100644
--- a/docs/content/en/functions/resources/GetMatch.md
+++ b/docs/content/en/functions/resources/GetMatch.md
@@ -16,13 +16,13 @@ params:
{{ end }}
```
-> [!note]
+> [!NOTE]
> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
>
-> For page resources, use the [`Resources.GetMatch`] method on a `Page` object.
+> For page resources, use the [`Resources.GetMatch`][] method on a `Page` object.
Hugo determines a match using a case-insensitive [glob pattern](g).
{{% include "/_common/glob-patterns.md" %}}
-[`Resources.GetMatch`]: /methods/page/resources/
+[`Resources.GetMatch`]: /methods/page/resources/#getmatch
diff --git a/docs/content/en/functions/resources/GetRemote.md b/docs/content/en/functions/resources/GetRemote.md
index caa9cc1d3..cb13b2eeb 100644
--- a/docs/content/en/functions/resources/GetRemote.md
+++ b/docs/content/en/functions/resources/GetRemote.md
@@ -13,7 +13,7 @@ params:
{{< new-in 0.141.0 >}}
The `Err` method on the returned resource was removed in v0.141.0.
-Use the [`try`](/functions/go-template/try) statement instead, as shown in the [error handling](#error-handling) example below.
+Use the [`try`][] statement instead, as shown in the [error handling](#error-handling) example below.
{{< /new-in >}}
```go-html-template
@@ -31,32 +31,32 @@ Use the [`try`](/functions/go-template/try) statement instead, as shown in the [
## Options
-The `resources.GetRemote` function takes an optional map of options.
+The `resources.GetRemote` function accepts an options map.
-body
+`body`
: (`string`) The data you want to transmit to the server.
-headers
+`headers`
: (`map[string][]string`) The collection of key-value pairs that provide additional information about the request.
-key
+`key`
: (`string`) The cache key. Hugo derives the default value from the URL and options map. See [caching](#caching).
-method
+`method`
: (`string`) The action to perform on the requested resource, typically one of `GET`, `POST`, or `HEAD`.
-responseHeaders
+`responseHeaders`
: {{< new-in 0.143.0 />}}
: (`[]string`) The headers to extract from the server's response, accessible through the resource's [`Data.Headers`][] method. Header name matching is case-insensitive.
-timeout
+`timeout`
: {{< new-in 0.157.0 />}}
: (`string`) The duration after which the request is cancelled if it does not complete, expressed as a [duration](g). If not specified, the request will timeout after 2 minutes.
## Options examples
-> [!note]
-> For brevity, the examples below do not include [error handling][].
+> [!NOTE]
+> For brevity, the examples below do not include [error handling](#error-handling).
To include a header:
@@ -143,7 +143,7 @@ When retrieving remote data, use the [`transform.Unmarshal`][] function to [unma
{{ end }}
```
-> [!note]
+> [!NOTE]
> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type][]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
>
> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead:
@@ -154,7 +154,7 @@ When retrieving remote data, use the [`transform.Unmarshal`][] function to [unma
Use the [`try`][] statement to capture HTTP request errors. If you do not handle the error yourself, Hugo will fail the build.
-> [!note]
+> [!NOTE]
> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
```go-html-template
@@ -222,7 +222,7 @@ Although the allowlist contains entries for common media types, you may encounte
{{< code-toggle file=hugo >}}
[security.http]
-mediaTypes = ['^image/avif$','^application/vnd\.api\+json$']
+mediaTypes = ['^application/vnd\.api\+json$']
{{< /code-toggle >}}
Note that the entry above is:
@@ -230,11 +230,10 @@ Note that the entry above is:
- An _addition_ to the allowlist; it does not _replace_ the allowlist
- An array of [regular expressions](g)
+[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
[`Data.Headers`]: /methods/resource/data/#headers
[`Data`]: /methods/resource/data/
[`transform.Unmarshal`]: /functions/transform/unmarshal/
-[`try`]: /functions/go-template/try
+[`try`]: /functions/go-template/try/
[allowlist]: https://en.wikipedia.org/wiki/Whitelist
[configure file caches]: /configuration/caches/
-[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
-[error handling]: #error-handling
diff --git a/docs/content/en/functions/resources/Match.md b/docs/content/en/functions/resources/Match.md
index 6c7d83649..ebc86f856 100644
--- a/docs/content/en/functions/resources/Match.md
+++ b/docs/content/en/functions/resources/Match.md
@@ -16,14 +16,14 @@ params:
{{ end }}
```
-> [!note]
+> [!NOTE]
> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
>
-> For page resources, use the [`Resources.Match`] method on a `Page` object.
+> For page resources, use the [`Resources.Match`][] method on a `Page` object.
-Hugo determines a match using a case-insensitive [glob pattern].
+Hugo determines a match using a case-insensitive [glob pattern][].
{{% include "/_common/glob-patterns.md" %}}
-[`Resources.Match`]: /methods/page/resources/
+[`Resources.Match`]: /methods/page/resources/#match
[glob pattern]: https://github.com/gobwas/glob#example
diff --git a/docs/content/en/functions/resources/PostProcess.md b/docs/content/en/functions/resources/PostProcess.md
index f20bed7dd..63c31fac8 100644
--- a/docs/content/en/functions/resources/PostProcess.md
+++ b/docs/content/en/functions/resources/PostProcess.md
@@ -16,13 +16,13 @@ The `resources.PostProcess` function delays resource transformation steps until
In this example, after the build is complete, Hugo will:
-1. Purge unused CSS using the [PurgeCSS] plugin for [PostCSS]
-1. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS
-1. [Minify] the CSS
-1. [Fingerprint] the CSS
+1. Purge unused CSS using the [PurgeCSS][] plugin for [PostCSS][]
+1. Add vendor prefixes to CSS rules using the [Autoprefixer][] plugin for PostCSS
+1. [Minify][] the CSS
+1. [Fingerprint][] the CSS
Step 1
-: Install [Node.js].
+: Install [Node.js][].
Step 2
: Install the required Node packages in the root of your project:
@@ -32,21 +32,21 @@ Step 2
```
Step 3
-: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`].
+: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`][].
{{< code-toggle file=hugo copy=true >}}
[build.buildStats]
enable = true
{{< /code-toggle >}}
- See the [configure build] documentation for details and options.
+ See the [configure build][] documentation for details and options.
Step 4
: Create a PostCSS configuration file in the root of your project.
- ```js {file="postcss.config.js" copy=true}
- const autoprefixer = require('autoprefixer');
- const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default;
+ ```js {file="postcss.config.mjs" copy=true}
+ import autoprefixer from 'autoprefixer';
+ import purgeCSSPlugin from '@fullhuman/postcss-purgecss';
const purgecss = purgeCSSPlugin({
content: ['./hugo_stats.json'],
@@ -62,7 +62,7 @@ Step 4
safelist: []
});
- module.exports = {
+ export default {
plugins: [
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
autoprefixer,
@@ -70,9 +70,6 @@ Step 4
};
```
- > [!note]
- > If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333].
-
Step 5
: Place your CSS file within the `assets/css` directory.
@@ -99,17 +96,17 @@ Hugo passes the environment variables below to PostCSS, allowing you to do somet
process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
```
-PWD
+`PWD`
: The absolute path to the project working directory.
-HUGO_ENVIRONMENT
+`HUGO_ENVIRONMENT`
: The current Hugo environment, set with the `--environment` command line flag.
Default is `production` for `hugo build` and `development` for `hugo server`.
-HUGO_PUBLISHDIR
+`HUGO_PUBLISHDIR`
: The absolute path to the publish directory, typically `public`. This value points to a directory on disk, even when rendering to memory with the `--renderToMemory` command line flag.
-HUGO_FILE_X
+`HUGO_FILE_X`
: Hugo automatically mounts the following files from your project's root directory under `assets/_jsconfig`:
- `babel.config.js`
@@ -136,13 +133,11 @@ You cannot manipulate the values returned from the resource's methods. For examp
{{ $css.RelPermalink | strings.ToUpper }}
```
-[#7333]: https://github.com/gohugoio/hugo/issues/7333
-[`config/production`]: /configuration/introduction/#configuration-directory
[Autoprefixer]: https://github.com/postcss/autoprefixer
-[configure build]: /configuration/build/
[Fingerprint]: /functions/resources/fingerprint/
[Minify]: /functions/resources/minify/
[Node.js]: https://nodejs.org/en
[PostCSS]: https://postcss.org/
[PurgeCSS]: https://github.com/FullHuman/purgecss
-[this example]: https://github.com/postcss/postcss-load-config#packagejson
+[`config/production`]: /configuration/introduction/#configuration-directory
+[configure build]: /configuration/build/
diff --git a/docs/content/en/functions/safe/CSS.md b/docs/content/en/functions/safe/CSS.md
index 12ebbf8aa..3ee7e3aa8 100644
--- a/docs/content/en/functions/safe/CSS.md
+++ b/docs/content/en/functions/safe/CSS.md
@@ -26,7 +26,7 @@ Use the `safe.CSS` function to encapsulate known safe content that matches any o
Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
-See the [Go documentation] for details.
+See the [Go documentation][] for details.
## Example
@@ -43,7 +43,7 @@ Hugo renders the above to:
foo
```
-> [!note]
+> [!NOTE]
> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
To declare the string as safe:
diff --git a/docs/content/en/functions/safe/HTML.md b/docs/content/en/functions/safe/HTML.md
index 25ffb3318..5f1e3d973 100644
--- a/docs/content/en/functions/safe/HTML.md
+++ b/docs/content/en/functions/safe/HTML.md
@@ -21,9 +21,7 @@ Use the `safe.HTML` function to encapsulate a known safe HTML document fragment.
Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
-See the [Go documentation] for details.
-
-[Go documentation]: https://pkg.go.dev/html/template#HTML
+See the [Go documentation][] for details.
## Example
@@ -52,3 +50,5 @@ Hugo renders the above to:
```html
emphasized
```
+
+[Go documentation]: https://pkg.go.dev/html/template#HTML
diff --git a/docs/content/en/functions/safe/HTMLAttr.md b/docs/content/en/functions/safe/HTMLAttr.md
index 7cfefdfb2..35ead550b 100644
--- a/docs/content/en/functions/safe/HTMLAttr.md
+++ b/docs/content/en/functions/safe/HTMLAttr.md
@@ -21,9 +21,7 @@ Use the `safe.HTMLAttr` function to encapsulate an HTML attribute from a trusted
Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
-See the [Go documentation] for details.
-
-[Go documentation]: https://pkg.go.dev/html/template#HTMLAttr
+See the [Go documentation][] for details.
## Example
@@ -58,3 +56,5 @@ Hugo renders the above to:
```html
```
+
+[Go documentation]: https://pkg.go.dev/html/template#HTMLAttr
diff --git a/docs/content/en/functions/safe/JS.md b/docs/content/en/functions/safe/JS.md
index 0c4d9009d..65fbe073b 100644
--- a/docs/content/en/functions/safe/JS.md
+++ b/docs/content/en/functions/safe/JS.md
@@ -19,17 +19,13 @@ aliases: [/functions/safejs]
Use the `safe.JS` function to encapsulate a known safe EcmaScript5 Expression.
-Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no statement/expression ambiguity as when passing an expression like `{ foo: bar() }\n['foo']()`, which is both a valid Expression and a valid Program with a very different meaning.
+Template authors are responsible for ensuring that typed expressions do not break the intended precedence and that there is no statement/expression ambiguity as when passing an expression like `{ foo: bar() }\n['foo']()`, which is both a valid Expression and a valid Program with an entirely different meaning.
Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
-Using the `safe.JS` function to include valid but untrusted JSON is not safe. A safe alternative is to parse the JSON with the [`transform.Unmarshal`] function and then pass the resultant object into the template, where it will be converted to sanitized JSON when presented in a JavaScript context.
+Using the `safe.JS` function to include valid but untrusted JSON is not safe. A safe alternative is to parse the JSON with the [`transform.Unmarshal`][] function and then pass the resultant object into the template, where it will be converted to sanitized JSON when presented in a JavaScript context.
-[`transform.Unmarshal`]: /functions/transform/unmarshal/
-
-See the [Go documentation] for details.
-
-[Go documentation]: https://pkg.go.dev/html/template#JS
+See the [Go documentation][] for details.
## Example
@@ -58,3 +54,6 @@ Hugo renders the above to:
```html
```
+
+[Go documentation]: https://pkg.go.dev/html/template#JS
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
diff --git a/docs/content/en/functions/safe/JSStr.md b/docs/content/en/functions/safe/JSStr.md
index 81946a14c..444776a9e 100644
--- a/docs/content/en/functions/safe/JSStr.md
+++ b/docs/content/en/functions/safe/JSStr.md
@@ -21,9 +21,7 @@ Use the `safe.JSStr` function to encapsulate a sequence of characters meant to b
Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
-See the [Go documentation] for details.
-
-[Go documentation]: https://pkg.go.dev/html/template#JSStr
+See the [Go documentation][] for details.
## Example
@@ -60,3 +58,5 @@ Hugo renders the above to:
const a = "Title: " + "Lilo & Stitch";
```
+
+[Go documentation]: https://pkg.go.dev/html/template#JSStr
diff --git a/docs/content/en/functions/safe/URL.md b/docs/content/en/functions/safe/URL.md
index 44bed8064..d7d3011f1 100644
--- a/docs/content/en/functions/safe/URL.md
+++ b/docs/content/en/functions/safe/URL.md
@@ -25,7 +25,7 @@ Use the `safe.URL` function to encapsulate a known safe URL or URL substring. Sc
Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
-See the [Go documentation] for details.
+See the [Go documentation][] for details.
## Example
@@ -42,7 +42,7 @@ Hugo renders the above to:
IRC
```
-> [!note]
+> [!NOTE]
> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
To declare the string as safe:
diff --git a/docs/content/en/functions/strings/ContainsNonSpace.md b/docs/content/en/functions/strings/ContainsNonSpace.md
index 7b8dcb730..2d21a9dd2 100644
--- a/docs/content/en/functions/strings/ContainsNonSpace.md
+++ b/docs/content/en/functions/strings/ContainsNonSpace.md
@@ -11,12 +11,12 @@ params:
aliases: [/functions/strings.containsnonspace]
---
-Whitespace characters include `\t`, `\n`, `\v`, `\f`, `\r`, and characters in the [Unicode Space Separator] category.
-
-[Unicode Space Separator]: https://www.compart.com/en/unicode/category/Zs
+Whitespace characters include `\t`, `\n`, `\v`, `\f`, `\r`, and characters in the [Unicode Space Separator][] category.
```go-html-template
{{ strings.ContainsNonSpace "\n" }} → false
{{ strings.ContainsNonSpace " " }} → false
{{ strings.ContainsNonSpace "\n abc" }} → true
```
+
+[Unicode Space Separator]: https://www.compart.com/en/unicode/category/Zs
diff --git a/docs/content/en/functions/strings/CountRunes.md b/docs/content/en/functions/strings/CountRunes.md
index 3ac7baad7..1b06ec542 100644
--- a/docs/content/en/functions/strings/CountRunes.md
+++ b/docs/content/en/functions/strings/CountRunes.md
@@ -11,7 +11,7 @@ params:
aliases: [/functions/countrunes]
---
-In contrast with the [`strings.RuneCount`] function, which counts every rune in a string, `strings.CountRunes` excludes whitespace.
+In contrast with the [`strings.RuneCount`][] function, which counts every rune in a string, `strings.CountRunes` excludes whitespace.
```go-html-template
{{ "Hello, 世界" | strings.CountRunes }} → 8
diff --git a/docs/content/en/functions/strings/FindRESubmatch.md b/docs/content/en/functions/strings/FindRESubmatch.md
index d039607fb..e9cdd5ca3 100644
--- a/docs/content/en/functions/strings/FindRESubmatch.md
+++ b/docs/content/en/functions/strings/FindRESubmatch.md
@@ -29,7 +29,7 @@ By default, `findRESubmatch` finds all matches. You can limit the number of matc
This Markdown:
-```text
+```md
- [Example](https://example.org)
- [Hugo](https://gohugo.io)
```
@@ -82,5 +82,7 @@ https://example.org
https://gohugo.io
```
-> [!note]
-> You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin.
+> [!NOTE]
+> You can write and test your regular expression using [regex101.com][]. Be sure to select the Go flavor before you begin.
+
+[regex101.com]: https://regex101.com/
diff --git a/docs/content/en/functions/strings/FindRe.md b/docs/content/en/functions/strings/FindRe.md
index 45129ec91..0d6ba2456 100644
--- a/docs/content/en/functions/strings/FindRe.md
+++ b/docs/content/en/functions/strings/FindRe.md
@@ -28,5 +28,7 @@ To limit the number of matches to one:
{{ findRE `(?s).*?` .Content 1 }}
```
-> [!note]
-> You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin.
+> [!NOTE]
+> You can write and test your regular expression using [regex101.com][]. Be sure to select the Go flavor before you begin.
+
+[regex101.com]: https://regex101.com/
diff --git a/docs/content/en/functions/strings/ReplaceRE.md b/docs/content/en/functions/strings/ReplaceRE.md
index dba4bd15a..00bd5b130 100644
--- a/docs/content/en/functions/strings/ReplaceRE.md
+++ b/docs/content/en/functions/strings/ReplaceRE.md
@@ -32,7 +32,7 @@ Use `$1`, `$2`, etc. within the replacement string to insert the content of each
{{ replaceRE "^https?://([^/]+).*" "$1" $s }} → gohugo.io
```
-> [!note]
-> You can write and test your regular expression using [regex101.com]. Be sure to select the Go flavor before you begin.
+> [!NOTE]
+> You can write and test your regular expression using [regex101.com][]. Be sure to select the Go flavor before you begin.
[regex101.com]: https://regex101.com/
diff --git a/docs/content/en/functions/strings/RuneCount.md b/docs/content/en/functions/strings/RuneCount.md
index bdc1bfd2d..54d3f534b 100644
--- a/docs/content/en/functions/strings/RuneCount.md
+++ b/docs/content/en/functions/strings/RuneCount.md
@@ -11,7 +11,7 @@ params:
aliases: [/functions/strings.runecount]
---
-In contrast with the [`strings.CountRunes`] function, which excludes whitespace, `strings.RuneCount` counts every rune in a string.
+In contrast with the [`strings.CountRunes`][] function, which excludes whitespace, `strings.RuneCount` counts every rune in a string.
```go-html-template
{{ "Hello, 世界" | strings.RuneCount }} → 9
diff --git a/docs/content/en/functions/strings/SliceString.md b/docs/content/en/functions/strings/SliceString.md
index 69e4f6f33..456a3ee59 100644
--- a/docs/content/en/functions/strings/SliceString.md
+++ b/docs/content/en/functions/strings/SliceString.md
@@ -19,6 +19,6 @@ The START and END positions are zero-based, where `0` represents the first chara
{{ slicestr "BatMan" 0 3 }} → Bat
```
-The START and END arguments represent the endpoints of a half-open [interval](g), a concept that may be difficult to grasp when first encountered. You may find that the [`strings.Substr`] function is easier to understand.
+The START and END arguments represent the endpoints of a half-open [interval](g), a concept that may be difficult to grasp when first encountered. You may find that the [`strings.Substr`][] function is easier to understand.
[`strings.Substr`]: /functions/strings/substr/
diff --git a/docs/content/en/functions/strings/Split.md b/docs/content/en/functions/strings/Split.md
index bcab1b4d7..d425fd9c5 100644
--- a/docs/content/en/functions/strings/Split.md
+++ b/docs/content/en/functions/strings/Split.md
@@ -18,7 +18,7 @@ Examples:
{{ split "abc" "" }} → ["a", "b", "c"]
```
-> [!note]
-> The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice.
+> [!NOTE]
+> The `strings.Split` function essentially does the opposite of the [`collections.Delimit`][] function. While `split` creates a slice from a string, `delimit` creates a string from a slice.
[`collections.Delimit`]: /functions/collections/delimit/
diff --git a/docs/content/en/functions/strings/Title.md b/docs/content/en/functions/strings/Title.md
index 0ff79cdf0..e546336a8 100644
--- a/docs/content/en/functions/strings/Title.md
+++ b/docs/content/en/functions/strings/Title.md
@@ -15,9 +15,9 @@ aliases: [/functions/title]
{{ title "table of contents (TOC)" }} → Table of Contents (TOC)
```
-By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook]. Change your [project configuration] if you would prefer to:
+By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook][]. Change your [project configuration][] if you would prefer to:
-- Follow the capitalization rules published in the [Chicago Manual of Style]
+- Follow the capitalization rules published in the [Chicago Manual of Style][]
- Capitalize the first letter of every word
- Capitalize the first letter of the first word
- Disable the effects of the `title` function
diff --git a/docs/content/en/functions/strings/TrimSpace.md b/docs/content/en/functions/strings/TrimSpace.md
index 77da321d3..89ab85ef1 100644
--- a/docs/content/en/functions/strings/TrimSpace.md
+++ b/docs/content/en/functions/strings/TrimSpace.md
@@ -11,10 +11,10 @@ params:
{{< new-in 0.136.3 />}}
-Whitespace characters include `\t`, `\n`, `\v`, `\f`, `\r`, and characters in the [Unicode Space Separator] category.
-
-[Unicode Space Separator]: https://www.compart.com/en/unicode/category/Zs
+Whitespace characters include `\t`, `\n`, `\v`, `\f`, `\r`, and characters in the [Unicode Space Separator][] category.
```go-html-template
{{ strings.TrimSpace "\n\r\t foo \n\r\t" }} → foo
```
+
+[Unicode Space Separator]: https://www.compart.com/en/unicode/category/Zs
diff --git a/docs/content/en/functions/strings/Truncate.md b/docs/content/en/functions/strings/Truncate.md
index c4198229e..939e073be 100644
--- a/docs/content/en/functions/strings/Truncate.md
+++ b/docs/content/en/functions/strings/Truncate.md
@@ -17,7 +17,7 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s
{{ "Keep my HTML" | safeHTML | truncate 10 }} → Keep my …
```
-> [!note]
-> If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function.
+> [!NOTE]
+> If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safe.HTML`][] function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function.
-[`safeHTML`]: /functions/safe/html/
+[`safe.HTML`]: /functions/safe/html/
diff --git a/docs/content/en/functions/templates/Current.md b/docs/content/en/functions/templates/Current.md
index 47adf38ae..13ea77f44 100644
--- a/docs/content/en/functions/templates/Current.md
+++ b/docs/content/en/functions/templates/Current.md
@@ -10,7 +10,7 @@ params:
signatures: [templates.Current]
---
-> [!note]
+> [!NOTE]
> This function is experimental and subject to change.
{{< new-in 0.146.0 />}}
@@ -19,19 +19,21 @@ The `templates.Current` function provides introspection capabilities, allowing y
## Methods
-Ancestors
+Use these methods on the `CurrentTemplateInfo` object.
+
+`Ancestors`
: (`tpl.CurrentTemplateInfos`) Returns a slice containing information about each template in the current execution chain, starting from the parent of the current template and going up towards the initial template called. It excludes any base template applied via `define` and `block`. You can chain the `Reverse` method to this result to get the slice in chronological execution order.
-Base
+`Base`
: (`tpl.CurrentTemplateInfoCommonOps`) Returns an object representing the base template that was applied to the current template, if any. This may be `nil`.
-Filename
+`Filename`
: (`string`) Returns the absolute path of the current template. This will be empty for embedded templates.
-Name
+`Name`
: (`string`) Returns the name of the current template. This is usually the path relative to the layouts directory.
-Parent
+`Parent`
: (`tpl.CurrentTemplateInfo`) Returns an object representing the parent of the current template, if any. This may be `nil`.
## Examples
diff --git a/docs/content/en/functions/templates/Defer.md b/docs/content/en/functions/templates/Defer.md
index 272c36b0a..584936318 100644
--- a/docs/content/en/functions/templates/Defer.md
+++ b/docs/content/en/functions/templates/Defer.md
@@ -11,12 +11,10 @@ params:
aliases: [/functions/templates.defer]
---
-> [!note]
-> This feature should only be used in the main template, typically `layouts/baseof.html`. Using it in _shortcode_, _partial_, or _render hook_ templates may lead to unpredictable results. For further details, please refer to [this issue].
+> [!NOTE]
+> Do not call this function within a `partialCached` template. This restriction applies transitively: if `partialCached` calls a partial that calls `templates.Defer`, Hugo returns an error. Using this function within shortcode or render hook templates may also lead to unpredictable results.
-[this issue]: https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391
-
-In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/configuration/build/) to determine which classes and other HTML identifiers are being used in the final output:
+In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [css.TailwindCSS][] using the output of [`hugo_stats.json`][] to determine which classes and other HTML identifiers are being used in the final output:
```go-html-template {file="layouts/baseof.html" copy=true}
@@ -43,7 +41,7 @@ In some rare use cases, you may need to defer the execution of a template until
{{ end }}
```
-> [!note]
+> [!NOTE]
> This function only works in combination with the `with` keyword.
>
> Variables defined on the outside are not visible on the inside and vice versa. To pass in data, use the `data` [option](#options).
@@ -72,13 +70,13 @@ For the above to work well when running the server (or `hugo -w`), you want to h
## Options
-The `templates.Defer` function takes a single argument, a map with the following optional keys:
+The `templates.Defer` function requires a single argument, a map with the following optional keys:
-key (`string`)
-: The key to use for the deferred template. This will, combined with a hash of the template content, be used as a cache key. If this is not set, Hugo will execute the deferred template on every render. This is not what you want for shared resources like CSS and JavaScript.
+`key`
+: (`string`) The key to use for the deferred template. This will, combined with a hash of the template content, be used as a cache key. If this is not set, Hugo will execute the deferred template on every render. This is not what you want for shared resources like CSS and JavaScript.
-data (`map`)
-: Optional map to pass as data to the deferred template. This will be available in the deferred template as `.` or `$`.
+`data`
+: (`map`) Optional map to pass as data to the deferred template. This will be available in the deferred template as `.` or `$`.
```go-html-template
Language Outside: {{ site.Language.Name }}
@@ -92,4 +90,10 @@ I18n Outside: {{ i18n "hello" }}
{{ end }}
```
-The [output format](/configuration/output-formats/), [site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Name` and `.RelPermalink` will be the same on the inside and the outside of the deferred template.
+The [output format][], [site][], and [language][] will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Name` and `.RelPermalink` will be the same on the inside and the outside of the deferred template.
+
+[`hugo_stats.json`]: /configuration/build/
+[css.TailwindCSS]: /functions/css/tailwindcss/
+[language]: /methods/site/language/
+[output format]: /configuration/output-formats/
+[site]: /methods/page/site/
diff --git a/docs/content/en/functions/time/AsTime.md b/docs/content/en/functions/time/AsTime.md
index 884d6c61b..6db076a04 100644
--- a/docs/content/en/functions/time/AsTime.md
+++ b/docs/content/en/functions/time/AsTime.md
@@ -13,7 +13,7 @@ aliases: [/functions/time]
## Overview
-Hugo provides [functions] and [methods] to format, localize, parse, compare, and manipulate date/time values. Before you can do any of these with string representations of date/time values, you must first convert them to [`time.Time`] values using the `time.AsTime` function.
+Hugo provides [functions][] and [methods][] to format, localize, parse, compare, and manipulate date/time values. Before you can do any of these with string representations of date/time values, you must first convert them to [`time.Time`][] values using the `time.AsTime` function.
```go-html-template
{{ $t := "2023-10-15T13:18:50-07:00" }}
@@ -26,13 +26,13 @@ As shown above, the first argument must be a parsable string representation of a
{{% include "/_common/parsable-date-time-strings.md" %}}
-To override the default time zone, set the [`timeZone`] in your project configuration or provide a second argument to the `time.AsTime` function. For example:
+To override the default time zone, set the [`timeZone`][] in your project configuration or provide a second argument to the `time.AsTime` function. For example:
```go-html-template
{{ time.AsTime "15 Oct 2023" "America/Los_Angeles" }}
```
-The list of valid time zones may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database].
+The list of valid time zones may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database][].
The order of precedence for determining the time zone is:
diff --git a/docs/content/en/functions/time/Duration.md b/docs/content/en/functions/time/Duration.md
index bd6adfbfa..7430c98c9 100644
--- a/docs/content/en/functions/time/Duration.md
+++ b/docs/content/en/functions/time/Duration.md
@@ -11,7 +11,7 @@ params:
aliases: [/functions/duration]
---
-The `time.Duration` function returns a [`time.Duration`] value that you can use with any of the `Duration` [methods].
+The `time.Duration` function returns a [`time.Duration`][] value that you can use with any of the `Duration` [methods][].
This template:
diff --git a/docs/content/en/functions/time/Format.md b/docs/content/en/functions/time/Format.md
index 112a6e72e..9d3c2ff8f 100644
--- a/docs/content/en/functions/time/Format.md
+++ b/docs/content/en/functions/time/Format.md
@@ -29,14 +29,12 @@ Examples of parsable string representations:
{{% include "/_common/parsable-date-time-strings.md" %}}
-To override the default time zone, set the [`timeZone`] in your project configuration. The order of precedence for determining the time zone is:
+To override the default time zone, set the [`timeZone`][] in your project configuration. The order of precedence for determining the time zone is:
1. The time zone offset in the date/time string
1. The time zone specified in your project configuration
1. The `Etc/UTC` time zone
-[`timeZone`]: /configuration/all/#timezone
-
## Layout string
{{% include "/_common/time-layout-string.md" %}}
@@ -78,3 +76,5 @@ Token|Result
`:time_long`|`23:44:58 PST`
`:time_medium`|`23:44:58`
`:time_short`|`23:44`
+
+[`timeZone`]: /configuration/all/#timezone
diff --git a/docs/content/en/functions/time/In.md b/docs/content/en/functions/time/In.md
index 821eb99b7..ca628de79 100644
--- a/docs/content/en/functions/time/In.md
+++ b/docs/content/en/functions/time/In.md
@@ -16,9 +16,7 @@ The `time.In` function returns the given date/time as represented in the specifi
- If the time zone is an empty string or `UTC`, the time is returned in [UTC](g).
- If the time zone is `Local`, the time is returned in the system's local time zone.
-- Otherwise, the time zone must be a valid IANA [time zone name].
-
-[time zone name]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
+- Otherwise, the time zone must be a valid IANA [time zone name][].
```go-html-template
{{ $layout := "2006-01-02T15:04:05-07:00" }}
@@ -28,3 +26,5 @@ The `time.In` function returns the given date/time as represented in the specifi
{{ $t | time.In "Australia/Adelaide" | time.Format $layout }} → 2025-04-01T01:15:00+10:30
{{ $t | time.In "Europe/Oslo" | time.Format $layout }} → 2025-03-31T16:45:00+02:00
```
+
+[time zone name]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List
diff --git a/docs/content/en/functions/time/Now.md b/docs/content/en/functions/time/Now.md
index 9b6fa4692..67d201610 100644
--- a/docs/content/en/functions/time/Now.md
+++ b/docs/content/en/functions/time/Now.md
@@ -23,13 +23,13 @@ This produces a `time.Time` value, with a string representation such as:
2023-10-15 12:59:28.337140706 -0700 PDT m=+0.041752605
```
-To format and [localize](g) the value, pass it through the [`time.Format`] function:
+To format and [localize](g) the value, pass it through the [`time.Format`][] function:
```go-html-template
{{ time.Now | time.Format "Jan 2006" }} → Oct 2023
```
-The `time.Now` function returns a `time.Time` value, so you can chain any of the [time methods] to the resulting value. For example:
+The `time.Now` function returns a `time.Time` value, so you can chain any of the [time methods][] to the resulting value. For example:
```go-html-template
{{ time.Now.Year }} → 2023 (int)
diff --git a/docs/content/en/functions/time/ParseDuration.md b/docs/content/en/functions/time/ParseDuration.md
index 418632fc8..1e0c71243 100644
--- a/docs/content/en/functions/time/ParseDuration.md
+++ b/docs/content/en/functions/time/ParseDuration.md
@@ -11,7 +11,7 @@ params:
aliases: [/functions/time.parseduration]
---
-The `time.ParseDuration` function returns a [`time.Duration`] value that you can use with any of the `Duration` [methods].
+The `time.ParseDuration` function returns a [`time.Duration`][] value that you can use with any of the `Duration` [methods][].
A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
diff --git a/docs/content/en/functions/transform/Emojify.md b/docs/content/en/functions/transform/Emojify.md
index 6a4501fc5..226f85b0d 100644
--- a/docs/content/en/functions/transform/Emojify.md
+++ b/docs/content/en/functions/transform/Emojify.md
@@ -13,11 +13,11 @@ aliases: [/functions/emojify]
`emojify` runs a passed string through the Emoji emoticons processor.
-See the list of [emoji shortcodes] for available emoticons.
+See the list of [emoji shortcodes][] for available emoticons.
-The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set [`enableEmoji`] to `true` in your project configuration. Then you can write emoji shorthand directly into your content files;
+The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set [`enableEmoji`][] to `true` in your project configuration. Then you can write emoji shorthand directly into your content files;
-```text
+```md
I :heart: Hugo!
```
diff --git a/docs/content/en/functions/transform/HTMLEscape.md b/docs/content/en/functions/transform/HTMLEscape.md
index 069fd92f2..09f53787e 100644
--- a/docs/content/en/functions/transform/HTMLEscape.md
+++ b/docs/content/en/functions/transform/HTMLEscape.md
@@ -11,7 +11,7 @@ params:
aliases: [/functions/htmlescape]
---
-The `transform.HTMLEscape` function escapes five special characters by replacing them with [HTML entities]:
+The `transform.HTMLEscape` function escapes five special characters by replacing them with [HTML entities][]:
- `&` → `&`
- `<` → `<`
@@ -26,4 +26,4 @@ For example:
{{ htmlEscape "7 > 6" }} → 7 > 6
```
-[html entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
+[HTML entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
diff --git a/docs/content/en/functions/transform/HTMLUnescape.md b/docs/content/en/functions/transform/HTMLUnescape.md
index 828b80df3..0f53a9cd1 100644
--- a/docs/content/en/functions/transform/HTMLUnescape.md
+++ b/docs/content/en/functions/transform/HTMLUnescape.md
@@ -18,12 +18,12 @@ The `transform.HTMLUnescape` function replaces [HTML entities][] with their corr
{{ htmlUnescape "7 > 6" }} → 7 > 6
```
-In most contexts Go's [`html/template`][] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`][] function.
+In most contexts Go's [`html/template`][] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safe.HTML`][] function.
```go-html-template
{{ htmlUnescape "Lilo & Stitch" | safeHTML }}
```
-[`safehtml`]: /functions/safe/html/
-[html entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
+[HTML entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
[`html/template`]: https://pkg.go.dev/html/template
+[`safe.HTML`]: /functions/safe/html/
diff --git a/docs/content/en/functions/transform/HTMLtoMarkdown.md b/docs/content/en/functions/transform/HTMLtoMarkdown.md
index 1c05c7da2..18c232210 100644
--- a/docs/content/en/functions/transform/HTMLtoMarkdown.md
+++ b/docs/content/en/functions/transform/HTMLtoMarkdown.md
@@ -9,9 +9,9 @@ params:
signatures: [transform.HTMLToMarkdown INPUT]
---
-{{< new-in "0.151.0" />}}
+{{< new-in 0.151.0 />}}
-> [!note]
+> [!NOTE]
> This function is experimental and its API may change in the future.
The `transform.HTMLToMarkdown` function converts HTML to Markdown by utilizing the [`html-to-markdown`][] Go package.
@@ -29,9 +29,9 @@ The conversion process is enabled by the following `html-to-markdown` plugins:
Plugin|Description
:--|:--
Base|Implements basic shared functionality
-CommonMark|Implements Markdown according to the [Commonmark Spec][]
-Table|Implements tables according to the [GitHub Flavored Markdown Spec][]
+CommonMark|Implements Markdown according to the [Commonmark][] specification
+Table|Implements tables according to the [GitHub Flavored Markdown][] specification
+[Commonmark]: https://spec.commonmark.org/current/
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
[`html-to-markdown`]: https://github.com/JohannesKaufmann/html-to-markdown?tab=readme-ov-file#readme
-[Commonmark Spec]: https://spec.commonmark.org/current/
-[GitHub Flavored Markdown Spec]: https://github.github.com/gfm/
diff --git a/docs/content/en/functions/transform/Highlight.md b/docs/content/en/functions/transform/Highlight.md
index 72f154ea4..9918ac841 100644
--- a/docs/content/en/functions/transform/Highlight.md
+++ b/docs/content/en/functions/transform/Highlight.md
@@ -7,24 +7,22 @@ params:
functions_and_methods:
aliases: [highlight]
returnType: template.HTML
- signatures: ['transform.Highlight CODE LANG [OPTIONS]']
+ signatures: ['transform.Highlight CODE [LANG] [OPTIONS]']
aliases: [/functions/highlight]
---
-The `transform.Highlight` function uses the [`alecthomas/chroma`][] package to generate syntax-highlighted HTML from the provided code, [language][], and [options][].
+The `transform.Highlight` function uses the [`alecthomas/chroma`][] package to generate syntax-highlighted HTML from the provided code, [language][], and [options](#options-1).
## Arguments
-The `transform.Highlight` function takes three arguments.
-
-CODE
+`CODE`
: (`string`) The code to highlight.
-LANG
-: (`string`) The [language][] of the code to highlight. This value is case-insensitive.
+`LANG`
+: (`string`) The [language][] of the code to highlight. This value is case-insensitive. Optional; you can also set the language with the `type` key in OPTIONS. {{< new-in 0.162.0 />}}
-OPTIONS
-: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. You can set default values for each option in your [project configuration][]. The key names are case-insensitive.
+`OPTIONS`
+: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. See the [options](#options-1) below; you can set default values for each option in your [project configuration][]. The key names are case-insensitive.
## Examples
@@ -40,13 +38,26 @@ OPTIONS
{{ $lang := "bash" }}
{{ $opts := dict "lineNos" "table" "style" "dracula" }}
{{ transform.Highlight $input $lang $opts }}
+
+{{ $input := `print("Hello World!")` }}
+{{ $opts := dict "type" "python" "style" "dracula" }}
+{{ transform.Highlight $input $opts }}
```
## Options
+The `transform.Highlight` function accepts an options map.
+
{{% include "_common/syntax-highlighting-options.md" %}}
+`code`
+: {{< new-in 0.162.0 />}}
+: (`string`) Overrides the `CODE` argument.
+
+`type`
+: {{< new-in 0.162.0 />}}
+: (`string`) Overrides the `LANG` argument.
+
[`alecthomas/chroma`]: https://github.com/alecthomas/chroma
[language]: /content-management/syntax-highlighting#languages
-[options]: #options-1
[project configuration]: /configuration/markup#highlight
diff --git a/docs/content/en/functions/transform/HighlightCodeBlock.md b/docs/content/en/functions/transform/HighlightCodeBlock.md
index 2fc0b6f37..495c5d0b9 100644
--- a/docs/content/en/functions/transform/HighlightCodeBlock.md
+++ b/docs/content/en/functions/transform/HighlightCodeBlock.md
@@ -10,27 +10,65 @@ params:
signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]']
---
-This function is only useful within a code block render hook.
+The `transform.HighlightCodeBlock` function uses the [`alecthomas/chroma`][] package to generate syntax-highlighted HTML from code received in context within a code block render hook. This function is only useful within a code block render hook.
-Given the context passed into a code block render hook, `transform.HighlightCodeBlock` returns a `HighlightResult` object with two methods.
+## Arguments
-.Wrapped
-: (`template.HTML`) Returns highlighted code wrapped in ``, ``, and `` elements. This is identical to the value returned by the transform.Highlight function.
+CONTEXT
+: The [context][] passed into a code block render hook.
-.Inner
+OPTIONS
+: (`map`) A map of key-value pairs. See the [options](#options-1) below. The key names are case-insensitive.
+
+## Return value
+
+`transform.HighlightCodeBlock` returns a `HighlightResult` object with two methods.
+
+`Wrapped`
+: (`template.HTML`) Returns highlighted code wrapped in ``, ``, and `` elements. This is identical to the value returned by the `transform.Highlight` function.
+
+`Inner`
: (`template.HTML`) Returns highlighted code without any wrapping elements, allowing you to create your own wrapper.
+## Examples
+
```go-html-template
{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}
```
-To override the default [highlighting options]:
+To override the default options:
```go-html-template
-{{ $opts := merge .Options (dict "linenos" true) }}
+{{ $opts := merge .Options (dict "lineNos" true) }}
{{ $result := transform.HighlightCodeBlock . $opts }}
{{ $result.Wrapped }}
```
-[highlighting options]: /functions/transform/highlight/#options
+To fall back to plain text when the language is not supported by the highlighter:
+
+```go-html-template
+{{ $opts := dict }}
+{{ if not (transform.CanHighlight .Type) }}
+ {{ $opts = dict "type" "text" }}
+{{ end }}
+{{ $result := transform.HighlightCodeBlock . $opts }}
+{{ $result.Wrapped }}
+```
+
+## Options
+
+The `transform.HighlightCodeBlock` function accepts an options map.
+
+{{% include "_common/syntax-highlighting-options.md" %}}
+
+`code`
+: {{< new-in 0.162.0 />}}
+: (`string`) Overrides the code received from the code block context.
+
+`type`
+: {{< new-in 0.162.0 />}}
+: (`string`) Overrides the language received from the code block context.
+
+[`alecthomas/chroma`]: https://github.com/alecthomas/chroma
+[context]: /render-hooks/code-blocks/#context
diff --git a/docs/content/en/functions/transform/Markdownify.md b/docs/content/en/functions/transform/Markdownify.md
index c22de1efe..56a4c6acf 100644
--- a/docs/content/en/functions/transform/Markdownify.md
+++ b/docs/content/en/functions/transform/Markdownify.md
@@ -17,11 +17,11 @@ aliases: [/functions/markdownify]
If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags to produce inline HTML as required per the example above.
-To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] method on the `Page` object, setting the `display` option to `block`.
+To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`][] method on the `Page` object, setting the `display` option to `block`.
-> [!note]
-> Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details.
+> [!NOTE]
+> Although the `markdownify` function honors [Markdown render hooks][] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692][] for details.
[#9692]: https://github.com/gohugoio/hugo/issues/9692
-[`RenderString`]: /methods/page/renderstring/
[Markdown render hooks]: /render-hooks/
+[`RenderString`]: /methods/page/renderstring/
diff --git a/docs/content/en/functions/transform/PortableText.md b/docs/content/en/functions/transform/PortableText.md
index a100cd3c2..8a8ef24dc 100644
--- a/docs/content/en/functions/transform/PortableText.md
+++ b/docs/content/en/functions/transform/PortableText.md
@@ -9,17 +9,17 @@ params:
signatures: [transform.PortableText MAP]
---
-{{< new-in "0.145.0" />}}
+{{< new-in 0.145.0 />}}
[Portable Text][] is a JSON structure that represents rich text content in the [Sanity][] CMS. In Hugo, this function is typically used in a [content adapter][] that creates pages from Sanity data.
## Types supported
- `block` and `span`
-- `image`. Note that the image handling is currently very simple; we link to the `asset.url` using `asset.altText` as the image alt text and `asset.title` as the title. For more fine-grained control you may want to process the images in an [image render hook][].
+- `image`. Note that the image handling is currently basic; we link to the `asset.url` using `asset.altText` as the image alt text and `asset.title` as the title. For more fine-grained control you may want to process the images in an [image render hook][].
- `code` (see the [code-input][] plugin). Code will be rendered as fenced code blocks with any file name provided passed as a Markdown attribute.
-> [!note]
+> [!NOTE]
> Since the Portable Text gets converted to Markdown before it gets passed to Hugo, rendering of links, headings, images and code blocks can be controlled with [render hooks][].
## Example
diff --git a/docs/content/en/functions/transform/Remarshal.md b/docs/content/en/functions/transform/Remarshal.md
index d40c21728..547ef54c4 100644
--- a/docs/content/en/functions/transform/Remarshal.md
+++ b/docs/content/en/functions/transform/Remarshal.md
@@ -13,7 +13,7 @@ aliases: [/functions/transform.remarshal]
The format must be one of `json`, `toml`, `yaml`, or `xml`. If the input is a string of serialized data, it must be valid JSON, TOML, YAML, or XML.
-> [!note]
+> [!NOTE]
> This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML.
>
> This is not a general purpose converter, and may change without notice if required for Hugo's documentation site.
diff --git a/docs/content/en/functions/transform/ToMath.md b/docs/content/en/functions/transform/ToMath.md
index 95837ffaa..9bcc47098 100644
--- a/docs/content/en/functions/transform/ToMath.md
+++ b/docs/content/en/functions/transform/ToMath.md
@@ -11,15 +11,13 @@ params:
aliases: [/functions/tomath]
---
-{{< new-in 0.132.0 />}}
-
Hugo uses an embedded instance of the [KaTeX][] display engine to render mathematical markup to HTML. You do not need to install the KaTeX display engine.
```go-html-template
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
```
-> [!note]
+> [!NOTE]
> By default, Hugo renders mathematical markup to [MathML][], and does not require any CSS to display the result.
>
> To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet.
@@ -31,18 +29,18 @@ Hugo uses an embedded instance of the [KaTeX][] display engine to render mathema
## Options
-Pass a map of options as the second argument to the `transform.ToMath` function. The options below are a subset of the KaTeX [rendering options][].
+The `transform.ToMath` function accepts an options map. These options are a subset of the KaTeX [rendering options][].
-displayMode
+`displayMode`
: (`bool`) Whether to render in display mode instead of inline mode. Default is `false`.
-errorColor
+`errorColor`
: (`string`) The color of the error messages expressed as an RGB [hexadecimal color][]. Default is `#cc0000`.
-fleqn
+`fleqn`
: (`bool`) Whether to render flush left with a 2em left margin. Default is `false`.
-macros
+`macros`
: (`map`) A map of macros to be used in the math expression. Default is `{}`.
```go-html-template
@@ -54,24 +52,19 @@ macros
{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
```
-minRuleThickness
+`minRuleThickness`
: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
-output
+`output`
: (`string`) Determines the markup language of the output, one of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
With `html` and `htmlAndMathml` you must include the KaTeX style sheet within the `head` element of your base template.
```html
-
+
```
-strict
+`strict`
: {{< new-in 0.147.6 />}}
: (`string`) Controls how KaTeX handles LaTeX features that offer convenience but aren't officially supported, one of `error`, `ignore`, or `warn`. Default is `error`.
@@ -81,7 +74,7 @@ strict
The `newLineInDisplayMode` error code, which flags the use of `\\` or `\newline` in display mode outside an array or tabular environment, is intentionally designed not to throw an error, despite this behavior being questionable.
-throwOnError
+`throwOnError`
: (`bool`) Whether to throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`.
## Error handling
@@ -101,8 +94,6 @@ Instead of client-side JavaScript rendering of mathematical markup using MathJax
Step 1
: Enable and configure the Goldmark [passthrough extension][] in your project configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
-[passthrough extension]: /configuration/markup/#passthrough
-
{{< code-toggle file=hugo copy=true >}}
[markup.goldmark.extensions.passthrough]
enable = true
@@ -111,14 +102,12 @@ Step 1
inline = [['\(', '\)']]
{{< /code-toggle >}}
- > [!note]
+ > [!NOTE]
> The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you must double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
Step 2
: Create a [passthrough render hook][] to capture and render the LaTeX markup.4
-[passthrough render hook]: /render-hooks/passthrough/
-
```go-html-template {file="layouts/_markup/render-passthrough.html" copy=true}
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with try (transform.ToMath .Inner $opts) }}
@@ -138,19 +127,14 @@ Step 3
{{ $noop := .WordCount }}
{{ if .Page.Store.Get "hasMath" }}
-
+
{{ end }}
```
In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
- > [!note]
+ > [!NOTE]
> This conditional approach only identifies math on the current page. Mathematical expressions will not display correctly when one page's content is embedded within another. For example, if a [list page](g) calls the [`Content`][] or [`Summary`][] methods while ranging through its page collection, the list page will not load the KaTeX CSS.
>
> If this affects your site, use this conditional logic instead:
@@ -165,7 +149,7 @@ Step 3
Step 4
: Add some mathematical markup to your content, then test.
- ```text {file="content/example.md"}
+ ```md {file="content/example.md"}
This is an inline \(a^*=x-b^*\) equation.
These are block equations:
@@ -181,7 +165,7 @@ Step 4
You can also use the `transform.ToMath` function to render chemical equations, leveraging the `\ce` and `\pu` functions from the [`mhchem`][] package.
-```text
+```md
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
```
@@ -193,4 +177,6 @@ $$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
[`Summary`]: /methods/page/summary/
[`mhchem`]: https://mhchem.github.io/MathJax-mhchem/
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[passthrough extension]: /configuration/markup/#passthrough
+[passthrough render hook]: /render-hooks/passthrough/
[rendering options]: https://katex.org/docs/options.html
diff --git a/docs/content/en/functions/transform/Unmarshal.md b/docs/content/en/functions/transform/Unmarshal.md
index c92f6a054..8be76a10c 100644
--- a/docs/content/en/functions/transform/Unmarshal.md
+++ b/docs/content/en/functions/transform/Unmarshal.md
@@ -15,20 +15,22 @@ The input can be a string or a [resource](g).
## Options
-delimiter
+The `transform.Unmarshal` function accepts an options map.
+
+`delimiter`
: (`string`) Applicable to CSV files. The delimiter used. Default is `,`.
-comment
+`comment`
: (`string`) Applicable to CSV files. The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored.
-format
+`format`
: {{< new-in 0.149.0 />}}
: (`string`) The serialization format of the input, one of `csv`, `json`, `org`, `toml`, `xml`, or `yaml`. If empty or unspecified, Hugo infers the format from the input. For resources, this option is only needed if the file lacks an extension or to override the inferred format. For strings, it's only required when the format is ambiguous.
-lazyQuotes
+`lazyQuotes`
: (`bool`) Applicable to CSV files. Whether to allow a quote in an unquoted field, or to allow a non-doubled quote in a quoted field. Default is `false`.
-targetType
+`targetType`
: {{< new-in 0.146.7 />}}
: (`string`) Applicable to CSV files. The target data type, either `slice` or `map`. Default is `slice`.
@@ -53,7 +55,7 @@ Use the `transform.Unmarshal` function with global, page, and remote resources.
A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
-```text
+```tree
assets/
└── data/
└── books.json
@@ -77,9 +79,9 @@ assets/
### Page resource
-A page resource is a file within a [page bundle].
+A page resource is a file within a [page bundle][].
-```text
+```tree
content/
├── post/
│ └── book-reviews/
@@ -126,8 +128,8 @@ A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
{{ end }}
```
-> [!note]
-> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
+> [!NOTE]
+> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type][]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
>
> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead:
>
@@ -342,7 +344,7 @@ Each item node looks like this:
}
```
-The title keys do not begin with an underscore or a letter---they are not valid [identifiers](g). Use the [`index`] function to access the values:
+The title keys do not begin with an underscore or a letter---they are not valid [identifiers](g). Use the [`index`][] function to access the values:
```go-html-template
{{ with $data.channel.item }}
@@ -366,6 +368,6 @@ Hugo renders this to:
```
-[`index`]: /functions/collections/indexfunction/
[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+[`index`]: /functions/collections/indexfunction/
[page bundle]: /content-management/page-bundles/
diff --git a/docs/content/en/functions/transform/XMLEscape.md b/docs/content/en/functions/transform/XMLEscape.md
index a69803e01..51c1df9dc 100644
--- a/docs/content/en/functions/transform/XMLEscape.md
+++ b/docs/content/en/functions/transform/XMLEscape.md
@@ -10,7 +10,7 @@ params:
signatures: [transform.XMLEscape INPUT]
---
-The `transform.XMLEscape` function removes [disallowed characters][] as defined in the XML specification, then escapes the result by replacing the following characters with [HTML entities]:
+The `transform.XMLEscape` function removes [disallowed characters][] as defined in the XML specification, then escapes the result by replacing the following characters with [HTML entities][]:
- `"` → `"`
- `'` → `'`
@@ -33,6 +33,6 @@ When using `transform.XMLEscape` in a template rendered by Go's [`html/template`
{{ .Summary | transform.XMLEscape | safeHTML }}
```
-[disallowed characters]: https://www.w3.org/TR/xml/#charsets
-[html entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
+[HTML entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
[`html/template`]: https://pkg.go.dev/html/template
+[disallowed characters]: https://www.w3.org/TR/xml/#charsets
diff --git a/docs/content/en/functions/urls/AbsLangURL.md b/docs/content/en/functions/urls/AbsLangURL.md
index b2cf021c3..51913168e 100644
--- a/docs/content/en/functions/urls/AbsLangURL.md
+++ b/docs/content/en/functions/urls/AbsLangURL.md
@@ -68,5 +68,5 @@ When rendering the `en` site with `baseURL = https://example.org/docs/`
{{ absLangURL "/style.css" }} → https://example.org/en/style.css
```
-> [!note]
+> [!NOTE]
> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
diff --git a/docs/content/en/functions/urls/AbsURL.md b/docs/content/en/functions/urls/AbsURL.md
index e29862429..b81d75c36 100644
--- a/docs/content/en/functions/urls/AbsURL.md
+++ b/docs/content/en/functions/urls/AbsURL.md
@@ -11,7 +11,7 @@ params:
aliases: [/functions/absurl]
---
-With multilingual configurations, use the [`urls.AbsLangURL`] function instead. The URL returned by this function depends on:
+With multilingual configurations, use the [`urls.AbsLangURL`][] function instead. The URL returned by this function depends on:
- Whether the input begins with a slash (`/`)
- The `baseURL` in your project configuration
@@ -56,7 +56,7 @@ With `baseURL = https://example.org/docs/`
{{ absURL "/style.css" }} → https://example.org/style.css
```
-> [!note]
+> [!NOTE]
> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
[`urls.AbsLangURL`]: /functions/urls/abslangurl/
diff --git a/docs/content/en/functions/urls/Anchorize.md b/docs/content/en/functions/urls/Anchorize.md
index d529ec493..9d7062ca2 100644
--- a/docs/content/en/functions/urls/Anchorize.md
+++ b/docs/content/en/functions/urls/Anchorize.md
@@ -13,24 +13,6 @@ aliases: [/functions/anchorize]
{{% include "/_common/functions/urls/anchorize-vs-urlize.md" %}}
-## Sanitizing logic
+The `ursl.Anchorize` function sanitizes the resulting string per the [`autoIDType`][] setting in your project configuration.
-With the default Markdown renderer, Goldmark, the sanitizing logic is controlled by your project configuration:
-
-{{< code-toggle file=hugo >}}
-[markup.goldmark.parser]
-autoHeadingIDType = 'github'
-{{< /code-toggle >}}
-
-This controls the behavior of the `anchorize` function and the generation of heading IDs when rendering Markdown to HTML.
-
-Set `autoHeadingIDType` to one of:
-
-github
-: Compatible with GitHub. This is the default.
-
-github-ascii
-: Similar to the `github` setting, but removes non-ASCII characters.
-
-blackfriday
-: Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release.
+[`autoIDType`]: /configuration/markup/#parserautoidtype
diff --git a/docs/content/en/functions/urls/JoinPath.md b/docs/content/en/functions/urls/JoinPath.md
index b9da7e437..f518951f0 100644
--- a/docs/content/en/functions/urls/JoinPath.md
+++ b/docs/content/en/functions/urls/JoinPath.md
@@ -22,6 +22,6 @@ aliases: [/functions/urls.joinpath]
{{ urls.JoinPath (slice "a" "b") }} → a/b
```
-Unlike the [`path.Join`] function, `urls.JoinPath` retains consecutive leading slashes.
+Unlike the [`path.Join`][] function, `urls.JoinPath` retains consecutive leading slashes.
[`path.Join`]: /functions/path/join/
diff --git a/docs/content/en/functions/urls/Parse.md b/docs/content/en/functions/urls/Parse.md
index 7def5fb1d..89e67f7e1 100644
--- a/docs/content/en/functions/urls/Parse.md
+++ b/docs/content/en/functions/urls/Parse.md
@@ -11,9 +11,7 @@ params:
aliases: [/functions/urls.parse]
---
-The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/net/url#URL). The URL may be relative (a path, without a host) or absolute (starting with a [scheme]). Hugo throws an error when parsing an invalid URL.
-
-[scheme]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml#uri-schemes-1
+The `urls.Parse` function parses a URL into a [URL structure][]. The URL may be relative (a path, without a host) or absolute (starting with a [scheme][]). Hugo throws an error when parsing an invalid URL.
```go-html-template
{{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
@@ -33,3 +31,6 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/
{{ $u.Query.Has "b" }} → true
{{ $u.Fragment }} → bar
```
+
+[URL structure]: https://godoc.org/net/url#URL
+[scheme]: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml#uri-schemes-1
diff --git a/docs/content/en/functions/urls/RelLangURL.md b/docs/content/en/functions/urls/RelLangURL.md
index ea3131672..8a2450b79 100644
--- a/docs/content/en/functions/urls/RelLangURL.md
+++ b/docs/content/en/functions/urls/RelLangURL.md
@@ -78,5 +78,5 @@ When rendering the `en` site with `baseURL = https://example.org/docs/`
{{ relLangURL "/style.css" }} → /en/style.css
```
-> [!note]
+> [!NOTE]
> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
diff --git a/docs/content/en/functions/urls/RelURL.md b/docs/content/en/functions/urls/RelURL.md
index 97328eb2a..08ba91588 100644
--- a/docs/content/en/functions/urls/RelURL.md
+++ b/docs/content/en/functions/urls/RelURL.md
@@ -11,7 +11,7 @@ params:
aliases: [/functions/relurl]
---
-With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on:
+With multilingual configurations, use the [`urls.RelLangURL`][] function instead. The URL returned by this function depends on:
- Whether the input begins with a slash (`/`)
- The `baseURL` in your project configuration
@@ -66,7 +66,7 @@ With `baseURL = https://example.org/docs/`
{{ relURL "/style.css" }} → /style.css
```
-> [!note]
+> [!NOTE]
> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash.
[`urls.RelLangURL`]: /functions/urls/rellangurl/
diff --git a/docs/content/en/functions/urls/URLize.md b/docs/content/en/functions/urls/URLize.md
index 28bc1dc47..46f947462 100644
--- a/docs/content/en/functions/urls/URLize.md
+++ b/docs/content/en/functions/urls/URLize.md
@@ -33,7 +33,7 @@ authors = ['Victor Hugo']
The published site will have this structure:
-```text
+```tree
public/
├── authors/
│ ├── victor-hugo/
@@ -56,6 +56,6 @@ To create a link to the term page:
{{ end }}
```
-To generate a list of term pages associated with a given content page, use the [`GetTerms`] method on a `Page` object.
+To generate a list of term pages associated with a given content page, use the [`GetTerms`][] method on a `Page` object.
[`GetTerms`]: /methods/page/getterms/
diff --git a/docs/content/en/getting-started/directory-structure.md b/docs/content/en/getting-started/directory-structure.md
index 81dbe95b8..f203c3ebd 100644
--- a/docs/content/en/getting-started/directory-structure.md
+++ b/docs/content/en/getting-started/directory-structure.md
@@ -75,44 +75,44 @@ my-project/
Each of the subdirectories contributes to content, structure, behavior, or presentation.
-archetypes
-: The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/).
+`archetypes`
+: The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/).
-assets
-: The `assets` directory contains global resources typically passed through an asset pipeline. This includes resources such as images, CSS, Sass, JavaScript, and TypeScript. See [details](/hugo-pipes/introduction/).
+`assets`
+: The `assets` directory contains global resources typically passed through an asset pipeline. This includes resources such as images, CSS, Sass, JavaScript, and TypeScript. See [details](/hugo-pipes/introduction/).
-config
-: The `config` directory contains your project configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/configuration/introduction/#configuration-directory).
+`config`
+: The `config` directory contains your project configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details][configuration-directory].
-content
-: The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your project. See [details](/content-management/organization/).
+`content`
+: The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your project. See [details](/content-management/organization/).
-data
-: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/).
+`data`
+: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/).
-i18n
-: The `i18n` directory contains translation tables for multilingual projects. See [details](/content-management/multilingual/).
+`i18n`
+: The `i18n` directory contains translation tables for multilingual projects. See [details](/content-management/multilingual/).
-layouts
-: The `layouts` directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/).
+`layouts`
+: The `layouts` directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/).
-public
-: The `public` directory contains the published website, generated when you run the `hugo build` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-project).
+`public`
+: The `public` directory contains the published website, generated when you run the `hugo build` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details][build-your-project].
-resources
+`resources`
: The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo build` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed.
-static
-: The `static` directory contains files that will be copied to the `public` directory when you build your project. For example: `favicon.ico`, `robots.txt`, and files that verify website ownership. Before the introduction of [page bundles](g) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript.
+`static`
+: The `static` directory contains files that will be copied to the `public` directory when you build your project. For example: `favicon.ico`, `robots.txt`, and files that verify website ownership. Before the introduction of [page bundles](g) and [asset pipelines][], the `static` directory was also used for images, CSS, and JavaScript.
-themes
+`themes`
: The `themes` directory contains one or more [themes](g), each in its own subdirectory.
## Unified file system
Hugo creates a [unified file system](g), allowing you to mount two or more directories to the same location. For example, let's say your home directory contains a Hugo project in one directory, and shared content in another:
-```text
+```tree
home/
└── user/
├── my-project/
@@ -144,14 +144,14 @@ source = '/home/user/shared-content'
target = 'content'
{{< /code-toggle >}}
-> [!note]
+> [!NOTE]
> Defining a custom mount replaces the default mounting for that [component](g). To overlay an external directory on top of the project default, you must explicitly mount both.
>
> Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's unified file system instead.
After mounting, the unified file system has this structure:
-```text
+```tree
home/
└── user/
└── my-project/
@@ -172,21 +172,21 @@ home/
When two or more files share the same path, the version in the highest layer takes precedence. In the example above, if the `shared-content` directory contains `books/book-1.md`, it is ignored because the project's `content` directory is the first (highest) mount.
-You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/configuration/module/#mounts).
+You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details][mounts].
-You can also mount directories from Git repositories using Hugo Modules. See [details](/hugo-modules/).
+You can also mount directories from Git repositories using modules. See [details](/hugo-modules/).
## Theme skeleton
Hugo generates a functional theme skeleton when you create a new theme. For example, this command:
-```text
+```sh
hugo new theme my-theme
```
Creates this directory structure (subdirectories not shown):
-```text
+```tree
my-theme/
├── archetypes/
├── assets/
@@ -201,3 +201,8 @@ my-theme/
Using the unified file system described above, Hugo mounts each of these directories to the corresponding location in the project. When two files have the same path, the file in the project directory takes precedence. This allows you, for example, to override a theme's template by placing a copy in the same location within the project directory.
If you are simultaneously using components from two or more themes or modules, and there's a path collision, the first mount takes precedence.
+
+[asset pipelines]: /hugo-pipes/introduction/
+[build-your-project]: /getting-started/usage/#build-your-project
+[configuration-directory]: /configuration/introduction/#configuration-directory
+[mounts]: /configuration/module/#mounts
diff --git a/docs/content/en/getting-started/external-learning-resources/index.md b/docs/content/en/getting-started/external-learning-resources/index.md
index d3101be18..2cfcb28e7 100644
--- a/docs/content/en/getting-started/external-learning-resources/index.md
+++ b/docs/content/en/getting-started/external-learning-resources/index.md
@@ -7,7 +7,7 @@ keywords: []
weight: 40
---
-> [!note]
+> [!NOTE]
> Many of the resources on this page, including older books and videos, may contain out-of-date information. The Hugo software has undergone significant changes since these resources were created. These changes include the introduction of a new template system, the deprecation of various functions and settings, and the addition of new features like Markdown render hooks, content adapters, and support for mathematical markup. While some concepts may still be relevant, it's recommended to consult the official Hugo documentation for the most current and accurate information.
## Books
@@ -19,7 +19,7 @@ Hugo in Action is a step-by-step guide to using Hugo to create static websites.
[{{< img src="hugo-in-action.png" alt="Book cover: Hugo in Action" filter="process" filterArgs="resize x350 webp">}}](https://www.manning.com/books/hugo-in-action/)
Author: Atishay Jain\
-Publisher: [Manning Publications](https://www.manning.com/books/hugo-in-action/)\
+Publisher: [Manning Publications][]\
Publication date: March 2022\
Length: 488 pages\
ISBN: 9781617297007
@@ -31,7 +31,7 @@ In this book, you'll use Hugo to build a personal portfolio site that you can us
[{{< img src="build-websites-with-hugo.png" alt="Book cover: Build Websites with Hugo" filter="process" filterArgs="resize x350 webp">}}](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)
Author: Brian P. Hogan\
-Publisher: [Pragmatic Bookshelf](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)\
+Publisher: [Pragmatic Bookshelf][]\
Publication date: May 2020\
Length: 154 pages\
ISBN: 9781680507263
@@ -42,45 +42,79 @@ ISBN: 9781680507263
Welcome to this introduction to Hugo tutorial. This series aims to take you from a lion cub with basic web design knowledge to creating your first Hugo website. In this series, you'll learn how to set up a Hugo site, the basics of using Hugo layouts, partials, and templating, set up a blog, and finally, use data files. By the end of this series, you'll have the foundational knowledge to build your own Hugo sites.
-1. [Getting set up in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/)
-1. [Layouts in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/layouts-in-hugo/)
-1. [Hugo Partials](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-partials/)
-1. [Hugo templating basics](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-templating-basics/)
-1. [Blogging in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/blogging-in-hugo/)
-1. [Using Data in Hugo](https://cloudcannon.com/tutorials/hugo-beginner-tutorial/using-data-in-hugo/)
+1. [Getting set up in Hugo][]
+1. [Layouts in Hugo][]
+1. [Hugo Partials][]
+1. [Hugo templating basics][]
+1. [Blogging in Hugo][]
+1. [Using Data in Hugo][]
Creator: Mike Neumegen\
-Affiliation: [CloudCannon](https://cloudcannon.com/)\
+Affiliation: [CloudCannon][]\
Creation date: April 2022
### Hugo Static Site Generator
This course covers the basics of using the Hugo static site generator. Work your way through the articles, and we'll teach you everything you need to know to create a professional and scalable website or blog!
-1. [Introduction](https://www.giraffeacademy.com/static-site-generators/hugo/)
-1. [Windows Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-windows/)
-1. [Mac Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-mac/)
-1. [Creating A New Site](https://www.giraffeacademy.com/static-site-generators/hugo/hugo-directory-structure/)
-1. [Installing & Using Themes](https://www.giraffeacademy.com/static-site-generators/hugo/installing-using-themes/)
-1. [Content Organization](https://www.giraffeacademy.com/static-site-generators/hugo/content-organization/)
-1. [Front Matter](https://www.giraffeacademy.com/static-site-generators/hugo/front-matter/)
-1. [Archetypes](https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/)
-1. [Shortcodes](https://www.giraffeacademy.com/static-site-generators/hugo/shortcodes/)
-1. [Taxonomies](https://www.giraffeacademy.com/static-site-generators/hugo/taxonomies/)
-1. [Template Basics](https://www.giraffeacademy.com/static-site-generators/hugo/introduction-to-templates/)
-1. [List Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/list-page-templates/)
-1. [Single Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/single-page-templates/)
-1. [Home Page Templates](https://www.giraffeacademy.com/static-site-generators/hugo/home-page-templates/)
-1. [Section Templates](https://www.giraffeacademy.com/static-site-generators/hugo/section-templates/)
-1. [Block Templates](https://www.giraffeacademy.com/static-site-generators/hugo/block-templates/)
-1. [Variables](https://www.giraffeacademy.com/static-site-generators/hugo/variables/)
-1. [Functions](https://www.giraffeacademy.com/static-site-generators/hugo/functions/)
-1. [Conditionals](https://www.giraffeacademy.com/static-site-generators/hugo/conditionals/)
-1. [Data Templates](https://www.giraffeacademy.com/static-site-generators/hugo/data-templates/)
-1. [Partial Templates](https://www.giraffeacademy.com/static-site-generators/hugo/partial-templates/)
-1. [Shortcode Templates](https://www.giraffeacademy.com/static-site-generators/hugo/shortcode-templates/)
-1. [Building & Hosting](https://www.giraffeacademy.com/static-site-generators/hugo/building-&-hosting/)
+1. [Introduction][]
+1. [Windows Installation][]
+1. [Mac Installation][]
+1. [Creating A New Site][]
+1. [Installing & Using Themes][]
+1. [Content Organization][]
+1. [Front Matter][]
+1. [Archetypes][]
+1. [Shortcodes][]
+1. [Taxonomies][]
+1. [Template Basics][]
+1. [List Page Templates][]
+1. [Single Page Templates][]
+1. [Home Page Templates][]
+1. [Section Templates][]
+1. [Block Templates][]
+1. [Variables][]
+1. [Functions][]
+1. [Conditionals][]
+1. [Data Templates][]
+1. [Partial Templates][]
+1. [Shortcode Templates][]
+1. [Building & Hosting][]
Creator: Mike Dane\
-Affiliation: [Giraffe Academy](https://www.giraffeacademy.com/)\
+Affiliation: [Giraffe Academy][]\
Creation date: September 2017
+
+[Archetypes]: https://www.giraffeacademy.com/static-site-generators/hugo/archetypes/
+[Block Templates]: https://www.giraffeacademy.com/static-site-generators/hugo/block-templates/
+[Blogging in Hugo]: https://cloudcannon.com/tutorials/hugo-beginner-tutorial/blogging-in-hugo/
+[Building & Hosting]: https://www.giraffeacademy.com/static-site-generators/hugo/building-&-hosting/
+[CloudCannon]: https://cloudcannon.com/
+[Conditionals]: https://www.giraffeacademy.com/static-site-generators/hugo/conditionals/
+[Content Organization]: https://www.giraffeacademy.com/static-site-generators/hugo/content-organization/
+[Creating A New Site]: https://www.giraffeacademy.com/static-site-generators/hugo/hugo-directory-structure/
+[Data Templates]: https://www.giraffeacademy.com/static-site-generators/hugo/data-templates/
+[Front Matter]: https://www.giraffeacademy.com/static-site-generators/hugo/front-matter/
+[Functions]: https://www.giraffeacademy.com/static-site-generators/hugo/functions/
+[Getting set up in Hugo]: https://cloudcannon.com/tutorials/hugo-beginner-tutorial/
+[Giraffe Academy]: https://www.giraffeacademy.com/
+[Home Page Templates]: https://www.giraffeacademy.com/static-site-generators/hugo/home-page-templates/
+[Hugo Partials]: https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-partials/
+[Hugo templating basics]: https://cloudcannon.com/tutorials/hugo-beginner-tutorial/hugo-templating-basics/
+[Installing & Using Themes]: https://www.giraffeacademy.com/static-site-generators/hugo/installing-using-themes/
+[Introduction]: https://www.giraffeacademy.com/static-site-generators/hugo/
+[Layouts in Hugo]: https://cloudcannon.com/tutorials/hugo-beginner-tutorial/layouts-in-hugo/
+[List Page Templates]: https://www.giraffeacademy.com/static-site-generators/hugo/list-page-templates/
+[Mac Installation]: https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-mac/
+[Manning Publications]: https://www.manning.com/books/hugo-in-action/
+[Partial Templates]: https://www.giraffeacademy.com/static-site-generators/hugo/partial-templates/
+[Pragmatic Bookshelf]: https://pragprog.com/titles/bhhugo/build-websites-with-hugo/
+[Section Templates]: https://www.giraffeacademy.com/static-site-generators/hugo/section-templates/
+[Shortcode Templates]: https://www.giraffeacademy.com/static-site-generators/hugo/shortcode-templates/
+[Shortcodes]: https://www.giraffeacademy.com/static-site-generators/hugo/shortcodes/
+[Single Page Templates]: https://www.giraffeacademy.com/static-site-generators/hugo/single-page-templates/
+[Taxonomies]: https://www.giraffeacademy.com/static-site-generators/hugo/taxonomies/
+[Template Basics]: https://www.giraffeacademy.com/static-site-generators/hugo/introduction-to-templates/
+[Using Data in Hugo]: https://cloudcannon.com/tutorials/hugo-beginner-tutorial/using-data-in-hugo/
+[Variables]: https://www.giraffeacademy.com/static-site-generators/hugo/variables/
+[Windows Installation]: https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-windows/
diff --git a/docs/content/en/getting-started/quick-start.md b/docs/content/en/getting-started/quick-start.md
index 9ed328c18..cf8e5c06f 100644
--- a/docs/content/en/getting-started/quick-start.md
+++ b/docs/content/en/getting-started/quick-start.md
@@ -20,8 +20,8 @@ In this tutorial you will:
Before you begin this tutorial you must:
-1. [Install Hugo] (any edition, {{% param "minVersion" %}} or later)
-1. [Install Git]
+1. [Install Hugo][] (any edition, {{% param "minVersion" %}} or later)
+1. [Install Git][]
You must also be comfortable working from the command line.
@@ -29,7 +29,7 @@ You must also be comfortable working from the command line.
### Commands
-> [!note]
+> [!NOTE]
> **If you are a Windows user:**
>
> - Do not use the Command Prompt
@@ -40,13 +40,13 @@ You must also be comfortable working from the command line.
Verify that you have installed Hugo {{% param "minVersion" %}} or later.
-```text
+```sh
hugo version
```
Run these commands to create a Hugo project with the [Ananke][] theme. The next section provides an explanation of each command.
-```text
+```sh
hugo new project quickstart
cd quickstart
git init
@@ -61,37 +61,37 @@ View your project at the URL displayed in your terminal. Press `Ctrl + C` to sto
Create the [project skeleton][] for your project in the `quickstart` directory.
-```text
+```sh
hugo new project quickstart
```
Change the current directory to the root of your project.
-```text
+```sh
cd quickstart
```
Initialize an empty Git repository in the current directory.
-```text
+```sh
git init
```
Clone the [Ananke][] theme into the `themes` directory, adding it to your project as a [Git submodule][].
-```text
+```sh
git submodule add https://github.com/gohugo-ananke/ananke themes/ananke
```
Append a line to your project configuration file, indicating the current theme.
-```text
+```sh
echo "theme = 'ananke'" >> hugo.toml
```
Start Hugo's development server.
-```text
+```sh
hugo server
```
@@ -101,13 +101,13 @@ Press `Ctrl + C` to stop Hugo's development server.
Add a new page to your project.
-```text
+```sh
hugo new content content/posts/my-first-post.md
```
Hugo created the file in the `content/posts` directory. Open the file with your editor.
-```text
+```md
+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
@@ -119,7 +119,7 @@ Notice the `draft` value in the [front matter][] is `true`. By default, Hugo doe
Add some [Markdown][] to the body of the post, but do not change the `draft` value.
-```text
+```md
+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
@@ -134,7 +134,7 @@ Visit the [Hugo](https://gohugo.io) website!
Save the file, then start Hugo's development server. You can run either of the following commands to include draft content.
-```text
+```sh
hugo server --buildDrafts
hugo server -D
```
@@ -143,14 +143,14 @@ View your project at the URL displayed in your terminal. Keep the development se
When satisfied with your new content, set the front matter `draft` parameter to `false`.
-> [!note]
+> [!NOTE]
> Hugo's rendering engine conforms to the CommonMark [specification][] for Markdown. The CommonMark organization provides a useful [live testing tool][] powered by the reference implementation.
## Configure the project
-With your editor, open your [project configuration][] file (`hugo.toml`) in the root of your project.
+With your editor, open the [project configuration][] file in the root of your project directory:
-```text
+```toml {file="hugo.toml"}
baseURL = 'https://example.org/'
locale = 'en-us'
title = 'My New Hugo Project'
@@ -165,11 +165,11 @@ Make the following changes:
Start Hugo's development server to see your changes, remembering to include draft content.
-```text
+```sh
hugo server -D
```
-> [!note]
+> [!NOTE]
> Now that you have the Ananke theme installed, check out their [documentation][] and [demonstration site][] to learn how to configure and customize it.
## Publish the project
@@ -178,7 +178,7 @@ In this step you will _publish_ your project, but you will not _deploy_ it.
When you publish your project, Hugo renders all build artifacts to the `public` directory in the root of your project. This includes the HTML files for every site, along with assets such as images, CSS, and JavaScript. The command is simple.
-```text
+```sh
hugo
```
@@ -186,13 +186,18 @@ To learn how to _deploy_ your project, see the [host and deploy][] section.
## Ask for help
-Hugo's [forum][] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+Hugo's [forum][] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help][] before asking your first question.
## Other resources
For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources][] page.
[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke
+[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Install Hugo]: /installation/
+[Markdown]: https://daringfireball.net/projects/markdown
+[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
[are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3
[demonstration site]: https://ananke-theme.netlify.app/
[documentation]: https://ananke-documentation.netlify.app/
@@ -200,13 +205,8 @@ For other resources to help you learn Hugo, including books and video tutorials,
[external learning resources]: /getting-started/external-learning-resources/
[forum]: https://discourse.gohugo.io/
[front matter]: /content-management/front-matter/
-[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
[host and deploy]: /host-and-deploy/
-[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
-[Install Hugo]: /installation/
[live testing tool]: https://spec.commonmark.org/dingus/
-[Markdown]: https://daringfireball.net/projects/markdown
-[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
[project configuration]: /configuration/
[project skeleton]: /getting-started/directory-structure/#project-skeleton
[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
diff --git a/docs/content/en/getting-started/usage.md b/docs/content/en/getting-started/usage.md
index 42d4e3f98..c647e2c53 100644
--- a/docs/content/en/getting-started/usage.md
+++ b/docs/content/en/getting-started/usage.md
@@ -9,7 +9,7 @@ aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
## Test your installation
-After [installing] Hugo, test your installation by running:
+After [installing][] Hugo, test your installation by running:
```sh
hugo version
@@ -37,24 +37,24 @@ To build your project, `cd` into your project directory and run:
hugo build
```
-The [`hugo build`] command builds your project, publishing the files to the `public` directory. To publish your project to a different directory, use the [`--destination`] flag or set [`publishDir`] in your project configuration.
+The [`hugo build`][] command builds your project, publishing the files to the `public` directory. To publish your project to a different directory, use the [`--destination`][] flag or set [`publishDir`][] in your project configuration.
-> [!note]
+> [!NOTE]
> Hugo does not clear the `public` directory before building your project. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build.
>
> Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build.
## Draft, future, and expired content
-Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [front matter] of your content. By default, Hugo will not publish content when:
+Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [front matter][] of your content. By default, Hugo will not publish content when:
- The `draft` value is `true`
- The `date` is in the future
- The `publishDate` is in the future
- The `expiryDate` is in the past
-> [!note]
-> Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
+> [!NOTE]
+> Hugo publishes descendants of draft, future, and expired [branch](g) pages. To prevent publication of these descendants, use the [`cascade`][] front matter field to cascade [build options][] to the descendant pages.
You can override the default behavior when running `hugo build` or `hugo server` with command line flags:
@@ -66,7 +66,7 @@ hugo build --buildFuture # or -F
Although you can also set these values in your project configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.
-> [!note]
+> [!NOTE]
> As noted above, Hugo does not clear the `public` directory before building your project. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build.
>
> A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
@@ -79,13 +79,13 @@ To view your site while developing layouts or creating content, `cd` into your p
hugo server
```
-The [`hugo server`] command builds your site and serves your pages using a minimal HTTP server. When you run `hugo server` it will display the URL of your local site:
+The [`hugo server`][] command builds your site and serves your pages using a minimal HTTP server. When you run `hugo server` it will display the URL of your local site:
```text
Web Server is available at http://localhost:1313/
```
-While the server is running, it watches your project directory for changes to assets, configuration, content, data, layouts, translations, and static files. When it detects a change, the server rebuilds your site and refreshes your browser using [LiveReload].
+While the server is running, it watches your project directory for changes to assets, configuration, content, data, layouts, translations, and static files. When it detects a change, the server rebuilds your site and refreshes your browser using [LiveReload][].
Most Hugo builds are so fast that you may not notice the change unless you are looking directly at your browser.
@@ -103,7 +103,7 @@ hugo server --navigateToChanged
## Deploy your site
-> [!note]
+> [!NOTE]
> As noted above, Hugo does not clear the `public` directory before building your project. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
When you are ready to deploy your site, run:
@@ -114,7 +114,7 @@ hugo
This builds your site, publishing the files to the `public` directory. The directory structure will look something like this:
-```text
+```tree
public/
├── categories/
│ ├── index.html
@@ -134,17 +134,17 @@ public/
In a simple hosting environment, where you typically `ftp`, `rsync`, or `scp` your files to the root of a virtual host, the contents of the `public` directory are all that you need.
-Most of our users deploy their sites to a [CI/CD](g) platform, where a push[^1] to their remote Git repository triggers a build and deployment. Learn more in the [host and deploy] section.
+Most of our users deploy their sites to a [CI/CD](g) platform, where a push[^1] to their remote Git repository triggers a build and deployment. Learn more in the [host and deploy][] section.
[^1]: The Git repository contains the entire project directory, typically excluding the `public` directory because the site is built _after_ the push.
+[LiveReload]: https://github.com/livereload/livereload-js
[`--destination`]: /commands/hugo/#options
[`cascade`]: /content-management/front-matter/#cascade
-[`hugo server`]: /commands/hugo_server/
[`hugo build`]: /commands/hugo/
+[`hugo server`]: /commands/hugo_server/
[`publishDir`]: /configuration/all/#publishdir
[build options]: /content-management/build-options/
[front matter]: /content-management/front-matter/
[host and deploy]: /host-and-deploy/
[installing]: /installation/
-[LiveReload]: https://github.com/livereload/livereload-js
diff --git a/docs/content/en/host-and-deploy/deploy-with-hugo-deploy.md b/docs/content/en/host-and-deploy/deploy-with-hugo-deploy.md
index b894fef94..0fa3f4058 100644
--- a/docs/content/en/host-and-deploy/deploy-with-hugo-deploy.md
+++ b/docs/content/en/host-and-deploy/deploy-with-hugo-deploy.md
@@ -8,30 +8,29 @@ aliases: [/hosting-and-deployment/hugo-deploy/]
Use the `hugo deploy` command to deploy your site Amazon S3, Azure Blob Storage, or Google Cloud Storage.
-> [!note]
-> This feature requires the deploy or extended/deploy edition. See the [installation] section for details.
+> [!NOTE]
+> This feature requires the deploy or extended/deploy edition. See the [installation][] section for details.
## Assumptions
-1. You have completed the [Quick Start] or have a Hugo website you are ready to deploy and share with the world.
-1. You have an account with the service provider ([AWS], [Azure], or [Google Cloud]) that you want to deploy to.
+1. You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world.
+1. You have an account with the service provider ([AWS][], [Azure][], or [Google Cloud][]) that you want to deploy to.
1. You have authenticated.
- - AWS: [Install the CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and run [`aws configure`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).
- - Azure: [Install the CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and run [`az login`](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli).
- - Google Cloud: [Install the CLI](https://cloud.google.com/sdk) and run [`gcloud auth login`](https://cloud.google.com/sdk/gcloud/reference/auth/login).
+ - AWS: [Install the CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and run [`aws configure`][].
+ - Azure: [Install the CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) and run [`az login`][].
+ - Google Cloud: [Install the CLI](https://cloud.google.com/sdk) and run [`gcloud auth login`][].
- Each service supports various authentication methods, including environment variables. See [details](https://gocloud.dev/howto/blob/#services).
+ Each service supports various authentication methods, including environment variables. See [details][].
1. You have created a bucket to deploy to. If you want your site to be
public, be sure to configure the bucket to be publicly readable as a static website.
- AWS: [create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [host a static website](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
- - Azure: [create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal) and [host a static website](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website)
-
+ - Azure: [create a storage container][] and [host a static website](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website)
- Google Cloud: [create a bucket](https://cloud.google.com/storage/docs/creating-buckets) and [host a static website](https://cloud.google.com/storage/docs/hosting-static-website)
## Configuration
-Create a deployment target in your [project configuration]. The only required parameters are [`name`] and [`url`]:
+Create a deployment target in your [project configuration][]. The only required parameters are [`name`][] and [`url`][]:
{{< code-toggle file=hugo >}}
[deployment]
@@ -50,23 +49,23 @@ hugo deploy [--target=]
This command syncs the contents of your local `public` directory (the default publish directory) with the destination bucket. If no target is specified, Hugo deploys to the first configured target.
-For more command-line options, see `hugo help deploy` or the [CLI documentation].
+For more command-line options, see `hugo help deploy` or the [CLI documentation][].
### File list creation
-`hugo deploy` creates local and remote file lists by traversing the local publish directory and the remote bucket. Inclusion and exclusion are determined by the deployment target's [configuration]:
+`hugo deploy` creates local and remote file lists by traversing the local publish directory and the remote bucket. Inclusion and exclusion are determined by the deployment target's [configuration][]:
- `include`: All files are skipped by default except those that match the pattern.
- `exclude`: Files matching the pattern are skipped.
-> [!note]
-> During local file list creation, Hugo skips `.DS_Store` files and hidden directories (those starting with a period, like `.git`), except for the [`.well-known`] directory, which is traversed if present.
+> [!NOTE]
+> During local file list creation, Hugo skips `.DS_Store` files and hidden directories (those starting with a period, like `.git`), except for the [`.well-known`][] directory, which is traversed if present.
### File list comparison
Hugo compares the local and remote file lists to identify necessary changes. It first compares file names. If both exist, it compares sizes and MD5 checksums. Any difference triggers a re-upload, and remote files not present locally are deleted.
-> [!note]
+> [!NOTE]
> Excluded remote files (due to `include`/`exclude` configuration) won't be deleted.
The `--force` flag forces all files to be re-uploaded, even if Hugo detects no local/remote differences.
@@ -77,21 +76,27 @@ The `--confirm` or `--dryRun` flags cause Hugo to display the detected differenc
Hugo applies the changes to the remote bucket: uploading missing or changed files and deleting remote files not present locally. Uploaded file headers are configured remotely based on the matchers configuration.
-> [!note]
+> [!NOTE]
> To prevent accidental data loss, Hugo will not delete more than 256 remote files by default. Use the `--maxDeletes` flag to override this limit.
## Advanced configuration
-See [configure deployment](/configuration/deployment/).
+See [configure deployment][].
-[`.well-known`]: https://en.wikipedia.org/wiki/Well-known_URI
-[`name`]: /configuration/deployment/#name
-[`url`]: /configuration/deployment/#url
[AWS]: https://aws.amazon.com
[Azure]: https://azure.microsoft.com
[CLI documentation]: /commands/hugo_deploy/
-[configuration]: /configuration/deployment/#targets-1
[Google Cloud]: https://cloud.google.com/
-[installation]: /installation/
[Quick Start]: /getting-started/quick-start/
+[`.well-known`]: https://en.wikipedia.org/wiki/Well-known_URI
+[`aws configure`]: https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html
+[`az login`]: https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli
+[`gcloud auth login`]: https://cloud.google.com/sdk/gcloud/reference/auth/login
+[`name`]: /configuration/deployment/#name
+[`url`]: /configuration/deployment/#url
+[configuration]: /configuration/deployment/#targets-1
+[configure deployment]: /configuration/deployment/
+[create a storage container]: https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal
+[details]: https://gocloud.dev/howto/blob/#services
+[installation]: /installation/
[project configuration]: /configuration/deployment/
diff --git a/docs/content/en/host-and-deploy/deploy-with-rclone.md b/docs/content/en/host-and-deploy/deploy-with-rclone.md
index b5e898d83..9f25287d3 100644
--- a/docs/content/en/host-and-deploy/deploy-with-rclone.md
+++ b/docs/content/en/host-and-deploy/deploy-with-rclone.md
@@ -9,10 +9,10 @@ aliases: [/hosting-and-deployment/deployment-with-rclone/]
## Assumptions
- A web host running a web server. This could be a shared hosting environment or a VPS.
-- Access to your web host with any of the [protocols supported by rclone](https://rclone.org/#providers), such as SFTP.
+- Access to your web host with any of the [protocols supported by rclone][], such as SFTP.
- A functional static website built with Hugo
-- Deploying from an [Rclone](https://rclone.org) compatible operating system
-- You have [installed Rclone](https://rclone.org/install/).
+- Deploying from an [Rclone][] compatible operating system
+- You have [installed Rclone][].
**NB**: You can remove `--interactive` in the commands below once you are comfortable with rclone, if you wish. Also, `--gc` and `--minify` are optional in the commands below.
@@ -29,7 +29,7 @@ rclone sync --interactive --sftp-host sftp.example.com --sftp-user www-data --sf
The easiest way is simply to run `rclone config`.
-The [Rclone docs](https://rclone.org/docs/) provide [an example of configuring Rclone to use SFTP](https://rclone.org/sftp/).
+The [Rclone docs][] provide [an example of configuring Rclone to use SFTP][].
For the next commands, we will assume you configured a remote you named `hugo-www`.
@@ -41,3 +41,9 @@ rclone sync --interactive public/ hugo-www:www/
```
After you issue the above commands (and respond to any prompts), check your website and you will see that it is deployed.
+
+[Rclone docs]: https://rclone.org/docs/
+[Rclone]: https://rclone.org
+[an example of configuring Rclone to use SFTP]: https://rclone.org/sftp/
+[installed Rclone]: https://rclone.org/install/
+[protocols supported by rclone]: https://rclone.org/#providers
diff --git a/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md b/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md
index 15446f2e9..a9f0bba16 100644
--- a/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md
+++ b/docs/content/en/host-and-deploy/host-on-aws-amplify/index.md
@@ -8,6 +8,8 @@ aliases: [/hosting-and-deployment/hosting-on-aws-amplify/]
Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+{{% include "/_common/gitignore-public.md" %}}
+
## Prerequisites
Please complete the following tasks before continuing:
@@ -17,9 +19,9 @@ Please complete the following tasks before continuing:
1. [Create](https://github.com/signup) a GitHub account
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
-1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote][] reference to your GitHub repository
1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
-1. Commit the changes to your local Git repository and push to your GitHub repository.
+1. Commit the changes to your local Git repository and push to your GitHub repository
## Procedure
@@ -40,9 +42,9 @@ Step 2
env:
variables:
# Application versions
- DART_SASS_VERSION: 1.99.0
- GO_VERSION: 1.26.2
- HUGO_VERSION: 0.161.1
+ DART_SASS_VERSION: 1.101.0
+ GO_VERSION: 1.26.4
+ HUGO_VERSION: 0.163.2
# Time zone
TZ: Europe/Oslo
# Cache
@@ -91,7 +93,7 @@ Step 2
# Configure Git
- echo "Configuring Git..."
- - git config core.quotepath false
+ - git config --global core.quotepath false
build:
commands:
- echo "Building site..."
@@ -116,7 +118,7 @@ Step 3
```
Step 4
-: Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button.
+: Log in to your AWS account, navigate to the [Amplify Console][], then press the **Deploy an app** button.
Step 5
: Choose a source code provider, then press the **Next** button.
@@ -155,3 +157,4 @@ Step 12
[Amplify Console]: https://console.aws.amazon.com/amplify/apps
+[remote]: https://git-scm.com/docs/git-remote
diff --git a/docs/content/en/host-and-deploy/host-on-azure-static-web-apps.md b/docs/content/en/host-and-deploy/host-on-azure-static-web-apps.md
index 68fe145ab..b4c60d260 100644
--- a/docs/content/en/host-and-deploy/host-on-azure-static-web-apps.md
+++ b/docs/content/en/host-and-deploy/host-on-azure-static-web-apps.md
@@ -8,4 +8,6 @@ aliases: [/hosting-and-deployment/hosting-on-azure-static-web-apps/]
You can create and deploy a Hugo web application to Azure Static Web Apps. The final result is a new Azure Static Web App with associated GitHub Actions that give you control over how the app is built and published. You'll learn how to create a Hugo app, set up an Azure Static Web App and deploy the Hugo app to Azure.
-Here's the tutorial on how to [Publish a Hugo site to Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/publish-hugo).
+Here's the tutorial on how to [Publish a Hugo site to Azure Static Web Apps][].
+
+[Publish a Hugo site to Azure Static Web Apps]: https://docs.microsoft.com/en-us/azure/static-web-apps/publish-hugo
diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-07.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-07.png
index 0f31143e2..6cfe03831 100644
Binary files a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-07.png and b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-07.png differ
diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-08.png b/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-08.png
deleted file mode 100644
index 6cfe03831..000000000
Binary files a/docs/content/en/host-and-deploy/host-on-cloudflare/cloudflare-08.png and /dev/null differ
diff --git a/docs/content/en/host-and-deploy/host-on-cloudflare/index.md b/docs/content/en/host-and-deploy/host-on-cloudflare/index.md
index d1e672579..06d9224ae 100644
--- a/docs/content/en/host-and-deploy/host-on-cloudflare/index.md
+++ b/docs/content/en/host-and-deploy/host-on-cloudflare/index.md
@@ -7,17 +7,20 @@ keywords: []
Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+{{% include "/_common/gitignore-public.md" %}}
+
## Prerequisites
Please complete the following tasks before continuing:
-1. [Create](https://dash.cloudflare.com/sign-up) a Cloudflare account
-1. [Log in](https://dash.cloudflare.com/login) to your Cloudflare account
-1. [Create](https://github.com/signup) a GitHub account
-1. [Log in](https://github.com/login) to your GitHub account
-1. [Create](https://github.com/new) a GitHub repository for your project
-1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
-1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. [Create](https://dash.cloudflare.com/sign-up) a Cloudflare account.
+1. [Log in](https://dash.cloudflare.com/login) to your Cloudflare account.
+1. [Create](https://github.com/signup) a GitHub account.
+1. [Log in](https://github.com/login) to your GitHub account.
+1. [Create](https://github.com/new) a GitHub repository for your project.
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote][] reference to your GitHub repository.
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command.
+1. Commit the changes to your local Git repository and push to your GitHub repository.
## Procedure
@@ -45,8 +48,6 @@ Step 2
#------------------------------------------------------------------------------
# @file
# Builds a Hugo site hosted on a Cloudflare Worker.
- #
- # The Cloudflare Worker automatically installs Node.js dependencies.
#------------------------------------------------------------------------------
# Exit on error, undefined variables, or pipe failures
@@ -56,7 +57,7 @@ Step 2
# Perform cleanup
cleanup() {
- if [[ -n "${build_temp_dir:-}" && -d "${build_temp_dir}" ]]; then
+ if [[ -n "${build_temp_dir}" && -d "${build_temp_dir}" ]]; then
rm -rf "${build_temp_dir}"
fi
}
@@ -66,14 +67,17 @@ Step 2
main() {
# Define tool versions
- DART_SASS_VERSION=1.99.0
- GO_VERSION=1.26.2
- HUGO_VERSION=0.161.1
- NODE_VERSION=24.15.0
+ DART_SASS_VERSION=1.101.0
+ GO_VERSION=1.26.4
+ HUGO_VERSION=0.163.2
+ NODE_VERSION=24.16.0
# Set the build timezone
export TZ=Europe/Oslo
+ # Set the build cache directory
+ export HUGO_CACHEDIR="${PWD}/.cache/hugo_cache"
+
# Create and move into a temporary directory for downloads
build_temp_dir=$(mktemp -d)
pushd "${build_temp_dir}" > /dev/null
@@ -83,26 +87,26 @@ Step 2
# Install Dart Sass
echo "Installing Dart Sass ${DART_SASS_VERSION}..."
- curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ curl -sLO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
export PATH="${HOME}/.local/dart-sass:${PATH}"
# Install Go
echo "Installing Go ${GO_VERSION}..."
- curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ curl -sLO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
export PATH="${HOME}/.local/go/bin:${PATH}"
# Install Hugo
echo "Installing Hugo ${HUGO_VERSION}..."
- curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ curl -sLO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
mkdir -p "${HOME}/.local/hugo"
tar -C "${HOME}/.local/hugo" -xf "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
export PATH="${HOME}/.local/hugo:${PATH}"
# Install Node.js
echo "Installing Node.js ${NODE_VERSION}..."
- curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ curl -sLO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
@@ -118,11 +122,17 @@ Step 2
# Configure Git
echo "Configuring Git..."
- git config core.quotepath false
+ git config --global core.quotepath false
if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
git fetch --unshallow
fi
+ # Install Node.js dependencies
+ if [ -f package-lock.json ]; then
+ echo "Installing Node.js dependencies..."
+ npm ci
+ fi
+
# Build the site
echo "Building the site..."
hugo build --gc --minify
@@ -135,7 +145,7 @@ Step 3
: Commit the changes to your local Git repository and push to your GitHub repository.
Step 4
-: In the upper right corner of the Cloudflare [dashboard](https://dash.cloudflare.com/), press the **Add** button and select "Workers" from the drop down menu.
+: In the upper right corner of the Cloudflare [dashboard][], press the **Add** button and select "Workers" from the drop down menu.
@@ -165,13 +175,31 @@ Step 9
Step 10
-: On the "Create a Worker" page, under the "Set up your application" heading, provide a project name, leave the build command blank, then press the **Deploy** button.
+: On the "Create a Worker" page, under the "Set up your application" heading, perform the following steps:
- 
+ 1. Provide a **Project name**.
+ 1. Leave the **Build command** blank and ensure the **Deploy command** is `npx wrangler deploy`.
+ 1. Expand the **Advanced settings** panel.
+ 1. In the **Variable name** field, enter `SKIP_DEPENDENCY_INSTALL`.
+ 1. In the **Variable value** field, enter `true`.
+ 1. Press the **Deploy** button.
Step 11
: Wait for the site to build and deploy, then press the **Visit** button in the upper left corner of your screen.
- 
+ 
In the future, whenever you push a change from your local Git repository, Cloudflare will rebuild and deploy your site.
+
+## Build cache
+
+The build script shown in [Step 2](#step-2) sets Hugo's [cache directory][] to the path required by Cloudflare's build cache, which is disabled by default. To enable the Cloudflare build cache:
+
+1. Navigate to Workers & Pages Overview on the [dashboard][].
+1. Find your Workers project.
+1. Go to **Settings** > **Build** > **Build cache**.
+1. Press the **Enable** button.
+
+[cache directory]: /configuration/all/#cache-directory
+[dashboard]: https://dash.cloudflare.com/
+[remote]: https://git-scm.com/docs/git-remote
diff --git a/docs/content/en/host-and-deploy/host-on-firebase.md b/docs/content/en/host-and-deploy/host-on-firebase.md
index 9a28f1f63..af121bf61 100644
--- a/docs/content/en/host-and-deploy/host-on-firebase.md
+++ b/docs/content/en/host-and-deploy/host-on-firebase.md
@@ -8,8 +8,8 @@ aliases: [/hosting-and-deployment/hosting-on-firebase/]
## Assumptions
-1. You have an account with [Firebase][signup]. (If you don't, you can sign up for free using your Google account.)
-1. You have completed the [Quick Start] or have a completed Hugo website ready for deployment.
+1. You have an account with [Firebase][signup].
+1. You have completed the [Quick Start][] or have a completed Hugo website ready for deployment.
## Initial setup
@@ -88,7 +88,7 @@ firebase login:ci
You can also set up your CI and add the token to a private variable like `$FIREBASE_DEPLOY_TOKEN`.
-> [!note]
+> [!NOTE]
> This is a private secret and it should not appear in a public repository. Make sure you understand your chosen CI and that it's not visible to others.
You can then add a step in your build to do the deployment using the token:
@@ -99,8 +99,9 @@ firebase deploy --token $FIREBASE_DEPLOY_TOKEN
## Reference links
-- [Firebase CLI Reference](https://firebase.google.com/docs/cli/#administrative_commands)
+- [Firebase CLI Reference][]
-[console]: https://console.firebase.google.com/
+[Firebase CLI Reference]: https://firebase.google.com/docs/cli/#administrative_commands
[Quick Start]: /getting-started/quick-start/
+[console]: https://console.firebase.google.com/
[signup]: https://console.firebase.google.com/
diff --git a/docs/content/en/host-and-deploy/host-on-github-pages/index.md b/docs/content/en/host-and-deploy/host-on-github-pages/index.md
index 2b0ac3a86..56649ca4a 100644
--- a/docs/content/en/host-and-deploy/host-on-github-pages/index.md
+++ b/docs/content/en/host-and-deploy/host-on-github-pages/index.md
@@ -6,21 +6,25 @@ keywords: []
aliases: [/hosting-and-deployment/hosting-on-github/]
---
+Use these instructions to enable continuous deployment from a GitHub repository using GitHub Actions.
+
+{{% include "/_common/gitignore-public.md" %}}
+
## Types of sites
There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com.
-> [!note]
-> See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming.
+> [!NOTE]
+> See the [GitHub Pages documentation][] to understand the requirements for repository ownership and naming.
## Prerequisites
Please complete the following tasks before continuing:
1. [Create](https://github.com/signup) a GitHub account
-1. [Log in](https://github.com/login) to your GitHub account
+1. [Log in][] to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
-1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote][] reference to your GitHub repository
1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
1. Commit the changes to your local Git repository and push to your GitHub repository
@@ -36,19 +40,19 @@ Step 1
Step 2
-: In your project configuration, change the location of the image cache to the [`cacheDir`] as shown below:
+: In your project configuration, change the location of the image cache to the [`cacheDir`][] as shown below:
{{< code-toggle file=hugo copy=true >}}
[caches.images]
dir = ':cacheDir/images'
{{< /code-toggle >}}
- See [configure file caches] for more information.
+ See [configure file caches][] for more information.
Step 3
: Create a file named `hugo.yaml` in a directory named `.github/workflows`.
- ```text
+ ```sh
mkdir -p .github/workflows
touch .github/workflows/hugo.yaml
```
@@ -77,10 +81,10 @@ Step 4
build:
runs-on: ubuntu-latest
env:
- DART_SASS_VERSION: 1.99.0
- GO_VERSION: 1.26.2
- HUGO_VERSION: 0.161.1
- NODE_VERSION: 24.15.0
+ DART_SASS_VERSION: 1.101.0
+ GO_VERSION: 1.26.4
+ HUGO_VERSION: 0.163.2
+ NODE_VERSION: 24.16.0
TZ: Europe/Oslo
steps:
- name: Checkout
@@ -127,7 +131,7 @@ Step 4
[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
- name: Configure Git
run: |
- git config core.quotepath false
+ git config --global core.quotepath false
- name: Cache restore
id: cache-restore
uses: actions/cache/restore@v5
@@ -187,10 +191,15 @@ In the future, whenever you push a change from your local Git repository, GitHub
## Other resources
-- [Learn more about GitHub Actions](https://docs.github.com/en/actions)
-- [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows)
-- [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)
+- [Learn more about GitHub Actions][]
+- [Caching dependencies to speed up workflows][]
+- [Manage a custom domain for your GitHub Pages site][]
+[Caching dependencies to speed up workflows]: https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows
+[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
+[Learn more about GitHub Actions]: https://docs.github.com/en/actions
+[Log in]: https://github.com/login
+[Manage a custom domain for your GitHub Pages site]: https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages
[`cacheDir`]: /configuration/all/#cachedir
[configure file caches]: /configuration/caches/
-[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
+[remote]: https://git-scm.com/docs/git-remote
diff --git a/docs/content/en/host-and-deploy/host-on-gitlab-pages.md b/docs/content/en/host-and-deploy/host-on-gitlab-pages.md
index 0cb722b9c..89f9c7d1e 100644
--- a/docs/content/en/host-and-deploy/host-on-gitlab-pages.md
+++ b/docs/content/en/host-and-deploy/host-on-gitlab-pages.md
@@ -6,132 +6,130 @@ keywords: []
aliases: [/hosting-and-deployment/hosting-on-gitlab/]
---
-## Assumptions
+Use these instructions to enable continuous deployment from a GitLab repository.
-- Working familiarity with Git for version control
-- Completion of the Hugo [Quick Start]
-- A [GitLab account](https://gitlab.com/users/sign_in)
-- A Hugo website on your local machine that you are ready to publish
+{{% include "/_common/gitignore-public.md" %}}
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://gitlab.com/users/sign_up) a GitLab account
+1. [Log in](https://gitlab.com/users/sign_in) to your GitLab account
+1. [Create](https://gitlab.com/projects/new) a GitLab repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote][] reference to your GitLab repository
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitLab repository
## BaseURL
-The `baseURL` in your [project configuration](/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://.gitlab.io//`) and not a custom domain.
+The [`baseURL`][] in your project configuration must reflect the full URL of your GitLab Pages repository if you are using the default GitLab Pages URL (e.g., `https://.gitlab.io//`) and not a custom domain.
-## Configure GitLab CI/CD
+## Procedure
-Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of your project.
+Step 1
+: Create a `.gitlab-ci.yml` file in the root of your project.
-```yaml {file=".gitlab-ci.yml" copy=true}
-variables:
- # Application versions
- DART_SASS_VERSION: 1.99.0
- HUGO_VERSION: 0.161.1
- NODE_VERSION: 24.15.0
- # Git
- GIT_DEPTH: 0
- GIT_STRATEGY: clone
- GIT_SUBMODULE_STRATEGY: recursive
- # Time zone
- TZ: Europe/Oslo
+ ```yaml {file=".gitlab-ci.yml" copy=true}
+ variables:
+ # Application versions
+ DART_SASS_VERSION: 1.101.0
+ HUGO_VERSION: 0.163.2
+ NODE_VERSION: 24.16.0
+ # Git
+ GIT_DEPTH: 0
+ GIT_STRATEGY: clone
+ GIT_SUBMODULE_STRATEGY: recursive
+ # Time zone
+ TZ: Europe/Oslo
-image:
- name: golang:1.26.2-bookworm
+ image:
+ name: golang:1.26.4-bookworm
-pages:
- stage: deploy
- script:
- - |
- # Create directory for user-specific executable files
- echo "Creating directory for user-specific executable files..."
- mkdir -p "${HOME}/.local"
+ pages:
+ stage: deploy
+ script:
+ - |
+ # Create directory for user-specific executable files
+ echo "Creating directory for user-specific executable files..."
+ mkdir -p "${HOME}/.local"
- # Install utilities
- echo "Installing utilities..."
- apt-get update
- apt-get install -y brotli xz-utils zstd
+ # Install utilities
+ echo "Installing utilities..."
+ apt-get update
+ apt-get install -y brotli xz-utils zstd
- # Install Dart Sass
- echo "Installing Dart Sass ${DART_SASS_VERSION}..."
- curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- export PATH="${HOME}/.local/dart-sass:${PATH}"
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
- # Install Hugo
- echo "Installing Hugo ${HUGO_VERSION}..."
- curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
- mkdir -p "${HOME}/.local/hugo"
- tar -C "${HOME}/.local/hugo" -xf "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
- rm "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
- export PATH="${HOME}/.local/hugo:${PATH}"
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir -p "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
- # Install Node.js
- echo "Installing Node.js ${NODE_VERSION}..."
- curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
- tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
- rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
- export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
- # Verify installations
- echo "Verifying installations..."
- echo "Dart Sass: $(sass --version)"
- echo "Go: $(go version)"
- echo "Hugo: $(hugo version)"
- echo "Node.js: $(node --version)"
- echo "brotli: $(brotli --version)"
- echo "xz: $(xz --version)"
- echo "zstd: $(zstd --version)"
+ # Verify installations
+ echo "Verifying installations..."
+ echo "Dart Sass: $(sass --version)"
+ echo "Go: $(go version)"
+ echo "Hugo: $(hugo version)"
+ echo "Node.js: $(node --version)"
+ echo "brotli: $(brotli --version)"
+ echo "xz: $(xz --version)"
+ echo "zstd: $(zstd --version)"
- # Install Node.js dependencies
- echo "Installing Node.js dependencies..."
- [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true
+ # Install Node.js dependencies
+ echo "Installing Node.js dependencies..."
+ [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true
- # Configure Git
- echo "Configuring Git..."
- git config core.quotepath false
+ # Configure Git
+ echo "Configuring Git..."
+ git config --global core.quotepath false
- # Build site
- echo "Building site..."
- hugo --gc --minify --baseURL "${CI_PAGES_URL}"
+ # Build site
+ echo "Building site..."
+ hugo --gc --minify --baseURL "${CI_PAGES_URL}"
- # Compress published files
- echo "Compressing published files..."
- find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
- time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
- time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
- artifacts:
- paths:
- - public
- rules:
- - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
-```
+ # Compress published files
+ echo "Compressing published files..."
+ find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
+ time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
+ time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+ ```
-## Push your Hugo website to GitLab
+Step 2
+: Commit the changes to your local Git repository and push to your GitLab repository.
-Next, create a new repository on GitLab. It is not necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
+Step 3
+: From your GitLab repository, navigate to **Build** > **Pipelines** to follow the CI pipeline building your page.
-```sh
-# initialize new git repository
-git init
+Step 4
+: When the pipeline has passed, your new website is available at `https://.gitlab.io//`.
-# add /public directory to our .gitignore file
-echo "/public" >> .gitignore
+In the future, whenever you push a change from your local Git repository, GitLab Pages will rebuild and deploy your site.
-# commit and push code to master branch
-git add .
-git commit -m "Initial commit"
-git remote add origin https://gitlab.com/YourUsername/your-hugo-site.git
-git push -u origin master
-```
+## Other resources
-## Wait for your page to build
+- [GitLab Pages documentation][]
-That's it! You can now follow the CI agent building your page at `https://gitlab.com///pipelines`.
-
-After the build has passed, your new website is available at `https://.gitlab.io//`.
-
-## Next steps
-
-GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).
-
-[Quick Start]: /getting-started/quick-start/
+[GitLab Pages documentation]: https://docs.gitlab.com/user/project/pages/
+[`baseURL`]: /configuration/all/#baseurl
+[remote]: https://git-scm.com/docs/git-remote
diff --git a/docs/content/en/host-and-deploy/host-on-netlify/index.md b/docs/content/en/host-and-deploy/host-on-netlify/index.md
index 4847212c8..9577cdcf1 100644
--- a/docs/content/en/host-and-deploy/host-on-netlify/index.md
+++ b/docs/content/en/host-and-deploy/host-on-netlify/index.md
@@ -8,6 +8,8 @@ aliases: [/hosting-and-deployment/hosting-on-netlify/]
Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Azure DevOps, Bitbucket, or GitLab for version control.
+{{% include "/_common/gitignore-public.md" %}}
+
## Prerequisites
Please complete the following tasks before continuing:
@@ -17,9 +19,9 @@ Please complete the following tasks before continuing:
1. [Create](https://github.com/signup) a GitHub account
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
-1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote][] reference to your GitHub repository
1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
-1. Commit the changes to your local Git repository and push to your GitHub repository.
+1. Commit the changes to your local Git repository and push to your GitHub repository
## Procedure
@@ -28,30 +30,30 @@ Please complete the following tasks before continuing:
Step 1
: Create a `netlify.toml` file in the root of your project.
- ```text {file="netlify.toml" copy=true}
+ ```toml {file="netlify.toml" copy=true}
[build.environment]
- DART_SASS_VERSION = "1.99.0"
- GO_VERSION = "1.26.2"
- HUGO_VERSION = "0.161.1"
- NODE_VERSION = "24.15.0"
+ DART_SASS_VERSION = "1.101.0"
+ GO_VERSION = "1.26.4"
+ HUGO_VERSION = "0.163.2"
+ NODE_VERSION = "24.16.0"
TZ = "Europe/Oslo"
[build]
publish = "public"
command = """\
- git config core.quotepath false && \
+ git config --global core.quotepath false && \
hugo build --gc --minify --baseURL "${URL}"
"""
```
If your site requires Dart Sass to transpile Sass to CSS, set the `DART_SASS_VERSION` and include the Dart Sass installation in the build step.
- ```text {file="netlify.toml" copy=true}
+ ```toml {file="netlify.toml" copy=true}
[build.environment]
- DART_SASS_VERSION = "1.99.0"
- GO_VERSION = "1.26.2"
- HUGO_VERSION = "0.161.1"
- NODE_VERSION = "24.15.0"
+ DART_SASS_VERSION = "1.101.0"
+ GO_VERSION = "1.26.4"
+ HUGO_VERSION = "0.163.2"
+ NODE_VERSION = "24.16.0"
TZ = "Europe/Oslo"
[build]
@@ -61,7 +63,7 @@ Step 1
tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
export PATH="${HOME}/.local/dart-sass:${PATH}" && \
- git config core.quotepath false && \
+ git config --global core.quotepath false && \
hugo build --gc --minify --baseURL "${URL}"
"""
```
@@ -119,3 +121,5 @@ Step 11
In the future, whenever you push a change from your local Git repository, Netlify will rebuild and deploy your site.
+
+[remote]: https://git-scm.com/docs/git-remote
diff --git a/docs/content/en/host-and-deploy/host-on-render/index.md b/docs/content/en/host-and-deploy/host-on-render/index.md
index 3211abd96..71d97950a 100644
--- a/docs/content/en/host-and-deploy/host-on-render/index.md
+++ b/docs/content/en/host-and-deploy/host-on-render/index.md
@@ -8,6 +8,8 @@ aliases: [/hosting-and-deployment/hosting-on-render/]
Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+{{% include "/_common/gitignore-public.md" %}}
+
## Prerequisites
Please complete the following tasks before continuing:
@@ -17,15 +19,16 @@ Please complete the following tasks before continuing:
1. [Create](https://github.com/signup) a GitHub account
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
-1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote][] reference to your GitHub repository
1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository
## Procedure
Step 1
: Create a [Render Blueprint][] in the root of your project.
- ``` {file="render.yaml" copy=true}
+ ```yaml {file="render.yaml" copy=true}
services:
- type: web
name: hosting-render
@@ -35,13 +38,13 @@ Step 1
staticPublishPath: public
envVars:
- key: DART_SASS_VERSION
- value: 1.99.0
+ value: 1.101.0
- key: GO_VERSION
- value: 1.26.2
+ value: 1.26.4
- key: HUGO_VERSION
- value: 0.161.1
+ value: 0.163.2
- key: NODE_VERSION
- value: 24.15.0
+ value: 24.16.0
- key: TZ
value: Europe/Oslo
```
@@ -113,7 +116,7 @@ Step 2
# Configure Git
echo "Configuring Git..."
- git config core.quotepath false
+ git config --global core.quotepath false
if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
git fetch --unshallow
fi
@@ -183,3 +186,4 @@ In the future, whenever you push a change from your local Git repository, Render
[Render Blueprint]: https://render.com/docs/blueprint-spec
[dashboard]: https://dashboard.render.com/
+[remote]: https://git-scm.com/docs/git-remote
diff --git a/docs/content/en/host-and-deploy/host-on-sourcehut-pages.md b/docs/content/en/host-and-deploy/host-on-sourcehut-pages.md
index 5d84b30b6..e9b556140 100644
--- a/docs/content/en/host-and-deploy/host-on-sourcehut-pages.md
+++ b/docs/content/en/host-and-deploy/host-on-sourcehut-pages.md
@@ -6,34 +6,27 @@ keywords: []
aliases: [/hosting-and-deployment/hosting-on-sourcehut/]
---
-## Assumptions
+Use these instructions to host your site on SourceHut Pages using either manual deployment or the SourceHut build system.
+
+{{% include "/_common/gitignore-public.md" %}}
+
+## Prerequisites
- Working familiarity with [Git][] or [Mercurial][] for version control
- Completion of the Hugo [Quick Start][]
- A [SourceHut account][]
- A Hugo website on your local machine that you are ready to publish
-[Git]: https://git-scm.com/
-[Mercurial]: https://www.mercurial-scm.org/
-[SourceHut account]: https://meta.sr.ht/login
-[Quick Start]: /getting-started/quick-start/
-
Any and all mentions of `` refer to your actual SourceHut username and must be substituted accordingly.
## BaseURL
The [`baseURL`][] in your project configuration must reflect the full URL provided by SourceHut Pages if you are using the default address (e.g. `https://.srht.site/`). If you want to use another domain, check the [custom domain section][] of the official documentation.
-[`baseURL`]: /configuration/all/#baseurl
-[custom domain section]: https://srht.site/custom-domains
-
## Manual deployment
This method does not require a paid account. To proceed you will need to create a [SourceHut personal access token][] and install and configure the [hut][] CLI tool:
-[SourceHut personal access token]: https://meta.sr.ht/oauth2/personal-token
-[hut]: https://sr.ht/~xenrox/hut/
-
```sh
hugo build
tar -C public -cvz . > site.tar.gz
@@ -49,8 +42,6 @@ This method requires a paid account and relies on the SourceHut build system.
First, define your [build manifest][] by creating a `.build.yml` file in the root of your project. The following is a bare-bones template:
-[build manifest]: https://man.sr.ht/builds.sr.ht/#build-manifests
-
```yaml {file=".build.yml" copy=true}
image: alpine/edge
packages:
@@ -70,9 +61,6 @@ tasks:
If your site requires [Dart Sass][] to transpile Sass to CSS, set the DART_SASS_VERSION to the [latest version number][] and include the Dart Sass installation lines before running the Hugo build step. Note that for Alpine, the `linux-x64-musl` version is used.
-[Dart Sass]: https://gohugo.io/functions/css/sass/#dart-sass
-[latest version number]: https://github.com/sass/dart-sass/releases
-
```yaml {file=".build.yml" copy=true}
image: alpine/edge
packages:
@@ -84,7 +72,7 @@ environment:
site: .srht.site
tasks:
- package: |
- DART_SASS_VERSION=1.99.0
+ DART_SASS_VERSION=1.101.0
mkdir -p $HOME/.local
curl -L https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64-musl.tar.gz -o dart-sass.tar.gz
tar -xzf dart-sass.tar.gz -C $HOME/.local
@@ -99,21 +87,7 @@ tasks:
hut pages publish -d $site site.tar.gz
```
-Now what's left is creating a repository titled `.srht.site` (or your custom domain, if applicable) and pushing your local project. Here's an example using Git:
-
-```sh
-# initialize new git repository
-git init
-
-# add /public directory to our .gitignore file
-echo "/public" >> .gitignore
-
-# commit and push code to main branch
-git add .
-git commit -m "Initial commit"
-git remote add origin https://git.sr.ht/~/.srht.site
-git push -u origin main
-```
+Create a repository titled `.srht.site` (or your custom domain, if applicable) and push your local project to the repository.
You can now follow the build progress of your page at `https://builds.sr.ht/`.
@@ -121,5 +95,19 @@ After the build has passed, a TLS certificate will be automatically obtained for
## Other resources
-- [SourceHut Pages](https://srht.site/)
-- [SourceHut Builds user manual](https://man.sr.ht/builds.sr.ht/)
+- [SourceHut Pages][]
+- [SourceHut Builds user manual][]
+
+[Dart Sass]: https://gohugo.io/functions/css/sass/#dart-sass
+[Git]: https://git-scm.com/
+[Mercurial]: https://www.mercurial-scm.org/
+[Quick Start]: /getting-started/quick-start/
+[SourceHut Builds user manual]: https://man.sr.ht/builds.sr.ht/
+[SourceHut Pages]: https://srht.site/
+[SourceHut account]: https://meta.sr.ht/login
+[SourceHut personal access token]: https://meta.sr.ht/oauth2/personal-token
+[`baseURL`]: /configuration/all/#baseurl
+[build manifest]: https://man.sr.ht/builds.sr.ht/#build-manifests
+[custom domain section]: https://srht.site/custom-domains
+[hut]: https://sr.ht/~xenrox/hut/
+[latest version number]: https://github.com/sass/dart-sass/releases
diff --git a/docs/content/en/host-and-deploy/host-on-vercel/index.md b/docs/content/en/host-and-deploy/host-on-vercel/index.md
index be04aa4a1..07107d266 100644
--- a/docs/content/en/host-and-deploy/host-on-vercel/index.md
+++ b/docs/content/en/host-and-deploy/host-on-vercel/index.md
@@ -7,6 +7,8 @@ keywords: []
Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+{{% include "/_common/gitignore-public.md" %}}
+
## Prerequisites
Please complete the following tasks before continuing:
@@ -16,8 +18,9 @@ Please complete the following tasks before continuing:
1. [Create](https://github.com/signup) a GitHub account
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
-1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote][] reference to your GitHub repository
1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository
## Procedure
@@ -62,10 +65,10 @@ Step 2
main() {
# Define tool versions
- DART_SASS_VERSION=1.99.0
- GO_VERSION=1.26.2
- HUGO_VERSION=0.161.1
- NODE_VERSION=24.15.0
+ DART_SASS_VERSION=1.101.0
+ GO_VERSION=1.26.4
+ HUGO_VERSION=0.163.2
+ NODE_VERSION=24.16.0
# Set the build timezone
export TZ=Europe/Oslo
@@ -114,7 +117,7 @@ Step 2
# Configure Git
echo "Configuring Git..."
- git config core.quotepath false
+ git config --global core.quotepath false
if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
git fetch --unshallow
fi
@@ -183,3 +186,5 @@ Step 13
In the future, whenever you push a change from your local Git repository, Vercel will rebuild and deploy your site.
+
+[remote]: https://git-scm.com/docs/git-remote
diff --git a/docs/content/en/hugo-modules/_index.md b/docs/content/en/hugo-modules/_index.md
index 7a538ea15..8dbf661d4 100644
--- a/docs/content/en/hugo-modules/_index.md
+++ b/docs/content/en/hugo-modules/_index.md
@@ -1,6 +1,6 @@
---
-title: Hugo Modules
-description: Use Hugo Modules to manage the content, presentation, and behavior of your site.
+title: Hugo modules
+description: Use Hugo modules to manage the content, presentation, and behavior of your site.
categories: []
keywords: []
weight: 10
diff --git a/docs/content/en/hugo-modules/introduction.md b/docs/content/en/hugo-modules/introduction.md
index ba1dd6a46..13687f36c 100644
--- a/docs/content/en/hugo-modules/introduction.md
+++ b/docs/content/en/hugo-modules/introduction.md
@@ -1,6 +1,6 @@
---
title: Introduction
-description: A brief introduction to Hugo Modules.
+description: A brief introduction to Hugo modules.
categories: []
keywords: []
weight: 10
@@ -13,7 +13,7 @@ Modules are combinable in any arrangement, and external directories (including t
Some example projects:
-: A theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo's directory structure.
+: A theme that has been ported to Hugo modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo's directory structure.
: A simple site used for testing.
diff --git a/docs/content/en/hugo-modules/nodejs-dependencies.md b/docs/content/en/hugo-modules/nodejs-dependencies.md
index 6adb18367..92ec02ae9 100644
--- a/docs/content/en/hugo-modules/nodejs-dependencies.md
+++ b/docs/content/en/hugo-modules/nodejs-dependencies.md
@@ -1,30 +1,32 @@
---
title: Node.js dependencies
-description: How to manage Node dependencies in Hugo Modules.
-date: 2026-03-22
+description: How to manage Node dependencies in Hugo modules.
categories: []
keywords: []
weight: 40
---
-Hugo Modules that need Node packages (e.g. for Tailwind CSS) can declare those dependencies in a standard `package.json` at the module root. Hugo consolidates dependencies from all modules into an [npm workspace], so you only need a single `npm install` at the project level.
-
-[npm workspace]: https://docs.npmjs.com/cli/using-npm/workspaces
+Modules that need Node packages (e.g. for Tailwind CSS) can declare those dependencies in a standard `package.json` at the module root. Hugo consolidates dependencies from all modules into an [npm workspace][], so you only need a single `npm install` at the project level.
## Declaring dependencies
-Each Hugo Module declares its Node dependencies in a `package.json` file in its root directory, using the standard `dependencies` and `devDependencies` fields.
+Each module declares its Node dependencies in a `package.json` file in its root directory, using the standard `dependencies` and `devDependencies` fields.
-> [!note]
-> We improved this setup greatly in Hugo [v0.159.0](https://github.com/gohugoio/hugo/releases/tag/v0.159.0), but we kept the old `package.hugo.json` in the search path. Mostly to preserve as much backward compatibility as possible, but it may also be useful in some situations to reserve a separate set of Node dependencies for Hugo.
+
+
+> [!NOTE]
+> We improved this setup greatly in Hugo [v0.159.0][], but we kept the old `package.hugo.json` in the search path. Mostly to preserve as much backward compatibility as possible, but it may also be useful in some situations to reserve a separate set of Node dependencies for Hugo.
## Consolidating with `hugo mod npm pack`
-Run [`hugo mod npm pack`] to collect Node dependencies from all modules and write them to `packages/hugoautogen/package.json`. Hugo also adds a `workspaces` entry to your project's root `package.json` pointing to this auto-generated package.
+Run [`hugo mod npm pack`][] to collect Node dependencies from all modules and write them to `packages/hugoautogen/package.json`. Hugo also adds a `workspaces` entry to your project's root `package.json` pointing to this auto-generated package.
The resulting project structure:
-```text
+```tree
project/
├── package.json # your project's package.json (updated with workspaces entry)
├── packages/
@@ -34,8 +36,13 @@ project/
└── ...
```
-> [!note]
-In Hugo < v0.159.0 Hugo wrote the dependencies into your project's package.json, so if you have used `hugo mod npm pack` on your project using older Hugo versions, now is the time to do a spring cleaning of your project `package.json` file: Only direct Node dependencies needs to live in this file, all incoming dependencies from imported Hugo Modules gets written to `packages/hugoautogen/package.json`.
+
+
+> [!NOTE]
+In Hugo < v0.159.0 Hugo wrote the dependencies into your project's package.json, so if you have used `hugo mod npm pack` on your project using older Hugo versions, now is the time to do a spring cleaning of your project `package.json` file: Only direct Node dependencies needs to live in this file, all incoming dependencies from imported modules gets written to `packages/hugoautogen/package.json`.
When merging, the **topmost version, starting from the project, take precedence**. If a module declares `tailwindcss@4.1` but your project already has `tailwindcss@4.0`, the project version wins and the module dependency is excluded from the generated workspace package.
@@ -49,4 +56,6 @@ WARN npm dependencies are out of sync, please run "hugo mod npm pack" (you may
This ensures you don't forget to re-run `hugo mod npm pack` after updating module versions.
-[`hugo mod npm pack`]: /commands/hugo_mod_npm_pack
+[`hugo mod npm pack`]: /commands/hugo_mod_npm_pack/
+[npm workspace]: https://docs.npmjs.com/cli/using-npm/workspaces
+[v0.159.0]: https://github.com/gohugoio/hugo/releases/tag/v0.159.0
diff --git a/docs/content/en/hugo-modules/use-modules.md b/docs/content/en/hugo-modules/use-modules.md
index e432afb8d..17b8527b2 100644
--- a/docs/content/en/hugo-modules/use-modules.md
+++ b/docs/content/en/hugo-modules/use-modules.md
@@ -1,5 +1,5 @@
---
-title: Use Hugo Modules
+title: Use modules
description: Use modules to manage the content, layout, presentation, and behavior of your site.
categories: []
keywords: []
@@ -7,7 +7,7 @@ weight: 20
aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
---
-> [!note]
+> [!NOTE]
> To work with modules you must install [Git][] and [Go][] 1.18 or later.
## Introduction
@@ -29,7 +29,7 @@ hugo mod init github.com/user/project
This will generate a [`go.mod`][] file in the project root.
-> [!note]
+> [!NOTE]
> The module name is a unique identifier rather than a hosting requirement. Using a name like `github.com/user/project` is a common convention but it does not mean you must use Git or host your code on GitHub. You can use any name you like if you do not plan to have others import your project as a module. For example, you could use a simple name such as `my-project` when you run the initialization command.
Then define one or more imports in your project configuration. This contrived example imports three modules, each containing custom shortcodes:
@@ -46,7 +46,7 @@ Then define one or more imports in your project configuration. This contrived ex
Import precedence is top-down. For example, if `shortcodes-a`, `shortcodes-b`, and `shortcodes-c` each define an `image` shortcode, the `image` shortcode from `shortcodes-a` will take effect.
-> [!note]
+> [!NOTE]
> If multiple modules contain data files or [translation tables](g) with identical paths, the data is deeply merged, following top-down precedence.
When you build your project, Hugo will:
@@ -127,7 +127,7 @@ This command creates a `_vendor` directory containing copies of all imported mod
- Modules within the `themes` directory are not vendored.
- The `--ignoreVendorPaths` flag allows you to exclude vendored modules matching a [glob pattern](g) from specific commands.
-> [!important]
+> [!IMPORTANT]
> Instead of modifying files directly within the `_vendor` directory, override them by creating a corresponding file with the same relative path in your project's root.
To remove the vendored modules, delete the `_vendor` directory.
@@ -146,12 +146,12 @@ With `hugo serve`r running, this change will trigger a configuration reload and
{{% glossary-term "workspace" %}}
-Workspaces simplify local development of sites with modules. Create a `.work` file to define a workspace, and activate it via the [`workspace`][] configuration parameter or the `HUGO_MODULE_WORKSPACE` environment variable.
+Workspaces simplify local development of sites with modules. Create a `.work` file to define a workspace, and activate it via the [`workspace`][] configuration setting or the `HUGO_MODULE_WORKSPACE` environment variable.
A `.work` file example:
```text
-go 1.25
+go 1.26
use .
use ../my-hugo-module
@@ -187,6 +187,8 @@ Imported modules automatically mount their component directories to Hugo's [unif
See [configuring module mounts][] for details.
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
[`cacheDir`]: /configuration/all/#cachedir
[`go.mod`]: https://go.dev/ref/mod#go-mod-file
[`go.sum`]: https://go.dev/ref/mod#go-sum-files
@@ -195,6 +197,4 @@ See [configuring module mounts][] for details.
[configuring file caches]: /configuration/caches/
[configuring module imports]: /configuration/module/#imports
[configuring module mounts]: /configuration/module/#mounts
-[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
-[Go]: https://go.dev/doc/install
[merge configuration settings]: /configuration/introduction/#merge-configuration-settings
diff --git a/docs/content/en/hugo-pipes/introduction.md b/docs/content/en/hugo-pipes/introduction.md
index fa9493f20..4a2cbad00 100755
--- a/docs/content/en/hugo-pipes/introduction.md
+++ b/docs/content/en/hugo-pipes/introduction.md
@@ -13,15 +13,12 @@ aliases: [/assets/]
This is about global and remote resources.
global resource
-: A file within the `assets` directory, or within any directory [mounted] to the `assets` directory.
+: A file within the `assets` directory, or within any directory [mounted][] to the `assets` directory.
remote resource
: A file on a remote server, accessible via HTTP or HTTPS.
-For `.Page` scoped resources, see the [page resources] section.
-
-[mounted]: /configuration/module/#mounts
-[page resources]: /content-management/page-resources/
+For `.Page` scoped resources, see the [page resources][] section.
## Get a resource
@@ -29,20 +26,18 @@ In order to process an asset with Hugo Pipes, it must be retrieved as a resource
For global resources, use:
-- [`resources.ByType`](/functions/resources/bytype/)
-- [`resources.Get`](/functions/resources/get/)
-- [`resources.GetMatch`](/functions/resources/getmatch/)
-- [`resources.Match`](/functions/resources/match/)
+- [`resources.ByType`][]
+- [`resources.Get`][]
+- [`resources.GetMatch`][]
+- [`resources.Match`][]
For remote resources, use:
-- [`resources.GetRemote`](/functions/resources/getremote/)
-
-See the [GoDoc Page](https://pkg.go.dev/github.com/gohugoio/hugo/tpl/resources) for the `resources` package for an up to date overview of all template functions in this namespace.
+- [`resources.GetRemote`][]
## Copy a resource
-See the [`resources.Copy`](/functions/resources/copy/) function.
+See the [`resources.Copy`][] function.
## Asset directory
@@ -54,7 +49,7 @@ Hugo publishes assets to the `publishDir` (typically `public`) when you invoke `
## Go Pipes
-For improved readability, the Hugo Pipes examples of this documentation will be written using [Go Pipes](/templates/introduction/#pipes):
+For improved readability, the Hugo Pipes examples of this documentation will be written using [Go Pipes][]:
```go-html-template
{{ $style := resources.Get "sass/main.scss" | css.Sass | resources.Minify | resources.Fingerprint }}
@@ -72,3 +67,13 @@ An example of a pipe chain is:
```
The pipe chain is only invoked the first time it is encountered in a site build, and results are otherwise loaded from cache. As such, Hugo Pipes can be used in templates which are executed thousands or millions of times without negatively impacting the build performance.
+
+[Go Pipes]: /templates/introduction/#pipes
+[`resources.ByType`]: /functions/resources/bytype/
+[`resources.Copy`]: /functions/resources/copy/
+[`resources.GetMatch`]: /functions/resources/getmatch/
+[`resources.GetRemote`]: /functions/resources/getremote/
+[`resources.Get`]: /functions/resources/get/
+[`resources.Match`]: /functions/resources/match/
+[mounted]: /configuration/module/#mounts
+[page resources]: /content-management/page-resources/
diff --git a/docs/content/en/hugo-pipes/js.md b/docs/content/en/hugo-pipes/js.md
index 18572d538..461cc84f6 100644
--- a/docs/content/en/hugo-pipes/js.md
+++ b/docs/content/en/hugo-pipes/js.md
@@ -6,4 +6,6 @@ categories: []
keywords: []
---
-See [JS functions](/functions/js/).
+See [JS functions][].
+
+[JS functions]: /functions/js/
diff --git a/docs/content/en/installation/bsd.md b/docs/content/en/installation/bsd.md
index 7b8e8c82c..f49b00c07 100644
--- a/docs/content/en/installation/bsd.md
+++ b/docs/content/en/installation/bsd.md
@@ -14,50 +14,40 @@ weight: 40
## Repository packages
-Most BSD derivatives maintain a repository for commonly installed applications. Please note that these repositories may not contain the [latest release].
-
-[latest release]: https://github.com/gohugoio/hugo/releases/latest
+Most BSD derivatives maintain a repository for commonly installed applications. Please note that these repositories may not contain the [latest release][].
### DragonFly BSD
-[DragonFly BSD] includes Hugo in its package repository. To install the extended edition of Hugo:
+[DragonFly BSD][] includes Hugo in its package repository. To install the extended edition of Hugo:
```sh
sudo pkg install gohugo
```
-[DragonFly BSD]: https://www.dragonflybsd.org/
-
### FreeBSD
-[FreeBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
+[FreeBSD][] includes Hugo in its package repository. To install the extended edition of Hugo:
```sh
sudo pkg install gohugo
```
-[FreeBSD]: https://www.freebsd.org/
-
### NetBSD
-[NetBSD] includes Hugo in its package repository. To install the extended edition of Hugo:
+[NetBSD][] includes Hugo in its package repository. To install the extended edition of Hugo:
```sh
sudo pkgin install go-hugo
```
-[NetBSD]: https://www.netbsd.org/
-
### OpenBSD
-[OpenBSD] includes Hugo in its package repository. This will prompt you to select which edition of Hugo to install:
+[OpenBSD][] includes Hugo in its package repository. This will prompt you to select which edition of Hugo to install:
```sh
doas pkg_add hugo
```
-[OpenBSD]: https://www.openbsd.org/
-
{{% include "/_common/installation/04-build-from-source.md" %}}
## Comparison
@@ -69,3 +59,9 @@ Easy to upgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
Easy to downgrade?|:heavy_check_mark:|varies|:heavy_check_mark:
Automatic updates?|:x:|varies|:x:
Latest version available?|:heavy_check_mark:|varies|:heavy_check_mark:
+
+[DragonFly BSD]: https://www.dragonflybsd.org/
+[FreeBSD]: https://www.freebsd.org/
+[NetBSD]: https://www.netbsd.org/
+[OpenBSD]: https://www.openbsd.org/
+[latest release]: https://github.com/gohugoio/hugo/releases/latest
diff --git a/docs/content/en/installation/linux.md b/docs/content/en/installation/linux.md
index 6e8c9cd49..bce3eaefc 100644
--- a/docs/content/en/installation/linux.md
+++ b/docs/content/en/installation/linux.md
@@ -16,9 +16,9 @@ weight: 20
### Snap
-[Snap] is a free and open-source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated.
+[Snap][] is a free and open-source package manager for Linux. Available for [most distributions][], snap packages are simple to install and are automatically updated.
-The Hugo snap package is [strictly confined]. Strictly confined snaps run in complete isolation, up to a minimal access level that's deemed always safe. The sites you create and build must be located within your home directory, or on removable media.
+The Hugo snap package is [strictly confined][]. Strictly confined snaps run in complete isolation, up to a minimal access level that's deemed always safe. The sites you create and build must be located within your home directory, or on removable media.
To install the extended edition of Hugo:
@@ -56,24 +56,20 @@ sudo snap connect hugo:ssh-keys
sudo snap disconnect hugo:ssh-keys
```
-[strictly confined]: https://snapcraft.io/docs/snap-confinement
-[most distributions]: https://snapcraft.io/docs/installing-snapd
-[Snap]: https://snapcraft.io/
-
{{% include "/_common/installation/homebrew.md" %}}
## Repository packages
Most Linux distributions maintain a repository for commonly installed applications.
-> [!note]
-> The Hugo version available in package repositories varies based on Linux distribution and release, and in some cases will not be the [latest version].
+> [!NOTE]
+> The Hugo version available in package repositories varies based on Linux distribution and release, and in some cases will not be the [latest version][].
>
> Use one of the other installation methods if your package repository does not provide the desired version.
### Alpine Linux
-To install the extended edition of Hugo on [Alpine Linux]:
+To install the extended edition of Hugo on [Alpine Linux][]:
```sh
doas apk add --no-cache --repository=https://dl-cdn.alpinelinux.org/alpine/edge/community hugo
@@ -81,7 +77,7 @@ doas apk add --no-cache --repository=https://dl-cdn.alpinelinux.org/alpine/edge/
### Arch Linux
-Derivatives of the [Arch Linux] distribution of Linux include [EndeavourOS], [Garuda Linux], [Manjaro], and others. To install the extended edition of Hugo:
+Derivatives of the [Arch Linux][] distribution of Linux include [EndeavourOS][], [Garuda Linux][], [Manjaro][], and others. To install the extended edition of Hugo:
```sh
sudo pacman -S hugo
@@ -89,7 +85,7 @@ sudo pacman -S hugo
### Debian
-Derivatives of the [Debian] distribution of Linux include [elementary OS], [KDE neon], [Linux Lite], [Linux Mint], [MX Linux], [Pop!_OS], [Ubuntu], [Zorin OS], and others. To install the extended edition of Hugo:
+Derivatives of the [Debian][] distribution of Linux include [elementary OS][], [KDE neon][], [Linux Lite][], [Linux Mint][], [MX Linux][], [Pop!_OS][], [Ubuntu][], [Zorin OS][], and others. To install the extended edition of Hugo:
```sh
sudo apt install hugo
@@ -99,7 +95,7 @@ You can also download Debian packages from the [latest release][] page.
### Exherbo
-To install the extended edition of Hugo on [Exherbo]:
+To install the extended edition of Hugo on [Exherbo][]:
1. Add this line to /etc/paludis/options.conf:
@@ -116,7 +112,7 @@ To install the extended edition of Hugo on [Exherbo]:
### Fedora
-Derivatives of the [Fedora] distribution of Linux include [CentOS], [Red Hat Enterprise Linux], and others. To install the extended edition of Hugo:
+Derivatives of the [Fedora][] distribution of Linux include [CentOS][], [Red Hat Enterprise Linux][], and others. To install the extended edition of Hugo:
```sh
sudo dnf install hugo
@@ -124,9 +120,9 @@ sudo dnf install hugo
### Gentoo
-Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. To install the extended edition of Hugo:
+Derivatives of the [Gentoo][] distribution of Linux include [Calculate Linux][], [Funtoo][], and others. To install the extended edition of Hugo:
-1. Specify the `extended` [USE] flag in /etc/portage/package.use/hugo:
+1. Specify the `extended` [USE][] flag in /etc/portage/package.use/hugo:
```text
www-apps/hugo extended
@@ -148,7 +144,7 @@ nix-env -iA nixos.hugo
### openSUSE
-Derivatives of the [openSUSE] distribution of Linux include [GeckoLinux], [Linux Karmada], and others. To install the extended edition of Hugo:
+Derivatives of the [openSUSE][] distribution of Linux include [GeckoLinux][], [Linux Karmada][], and others. To install the extended edition of Hugo:
```sh
sudo zypper install hugo
@@ -156,7 +152,7 @@ sudo zypper install hugo
### Solus
-The [Solus] distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo:
+The [Solus][] distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo:
```sh
sudo eopkg install hugo
@@ -164,7 +160,7 @@ sudo eopkg install hugo
### Void Linux
-To install the extended edition of Hugo on [Void Linux]:
+To install the extended edition of Hugo on [Void Linux][]:
```sh
sudo xbps-install -S hugo
@@ -190,7 +186,6 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch
[Calculate Linux]: https://www.calculate-linux.org/
[CentOS]: https://www.centos.org/
[Debian]: https://www.debian.org/
-[elementary OS]: https://elementary.io/
[EndeavourOS]: https://endeavouros.com/
[Exherbo]: https://www.exherbolinux.org/
[Fedora]: https://getfedora.org/
@@ -199,18 +194,22 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch
[GeckoLinux]: https://geckolinux.github.io/
[Gentoo]: https://www.gentoo.org/
[KDE neon]: https://neon.kde.org/
-[latest release]: https://github.com/gohugoio/hugo/releases/latest
-[latest version]: https://github.com/gohugoio/hugo/releases/latest
[Linux Karmada]: https://linuxkamarada.com/
[Linux Lite]: https://www.linuxliteos.com/
[Linux Mint]: https://linuxmint.com/
-[Manjaro]: https://manjaro.org/
[MX Linux]: https://mxlinux.org/
-[openSUSE]: https://www.opensuse.org/
+[Manjaro]: https://manjaro.org/
[Pop!_OS]: https://pop.system76.com/
[Red Hat Enterprise Linux]: https://www.redhat.com/
+[Snap]: https://snapcraft.io/
[Solus]: https://getsol.us/
-[Ubuntu]: https://ubuntu.com/
[USE]: https://packages.gentoo.org/packages/www-apps/hugo
+[Ubuntu]: https://ubuntu.com/
[Void Linux]: https://voidlinux.org/
[Zorin OS]: https://zorin.com/os/
+[elementary OS]: https://elementary.io/
+[latest release]: https://github.com/gohugoio/hugo/releases/latest
+[latest version]: https://github.com/gohugoio/hugo/releases/latest
+[most distributions]: https://snapcraft.io/docs/installing-snapd
+[openSUSE]: https://www.opensuse.org/
+[strictly confined]: https://snapcraft.io/docs/snap-confinement
diff --git a/docs/content/en/installation/macos.md b/docs/content/en/installation/macos.md
index 1984d1a8e..d78402151 100644
--- a/docs/content/en/installation/macos.md
+++ b/docs/content/en/installation/macos.md
@@ -18,14 +18,12 @@ weight: 10
### MacPorts
-[MacPorts] is a free and open-source package manager for macOS. To install the extended edition of Hugo:
+[MacPorts][] is a free and open-source package manager for macOS. To install the extended edition of Hugo:
```sh
sudo port install hugo
```
-[MacPorts]: https://www.macports.org/
-
{{% include "/_common/installation/04-build-from-source.md" %}}
## Comparison
@@ -40,3 +38,5 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar
[^1]: Easy if a previous version is still installed.
[^2]: Possible but requires advanced configuration.
+
+[MacPorts]: https://www.macports.org/
diff --git a/docs/content/en/installation/windows.md b/docs/content/en/installation/windows.md
index 3cc6ee4a8..516575946 100644
--- a/docs/content/en/installation/windows.md
+++ b/docs/content/en/installation/windows.md
@@ -6,8 +6,8 @@ keywords: []
weight: 30
---
-> [!note]
-> Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016.
+> [!NOTE]
+> Hugo requires Windows 10, Windows Server 2016, or later.
{{% include "/_common/installation/01-editions.md" %}}
@@ -19,7 +19,7 @@ weight: 30
### Chocolatey
-[Chocolatey] is a free and open-source package manager for Windows. To install the extended edition of Hugo:
+[Chocolatey][] is a free and open-source package manager for Windows. To install the extended edition of Hugo:
```sh
choco install hugo-extended
@@ -27,7 +27,7 @@ choco install hugo-extended
### Scoop
-[Scoop] is a free and open-source package manager for Windows. To install the extended edition of Hugo:
+[Scoop][] is a free and open-source package manager for Windows. To install the extended edition of Hugo:
```sh
scoop install hugo-extended
@@ -35,7 +35,7 @@ scoop install hugo-extended
### Winget
-[Winget] is Microsoft's official free and open-source package manager for Windows. To install the extended edition of Hugo:
+[Winget][] is Microsoft's official free and open-source package manager for Windows. To install the extended edition of Hugo:
```sh
winget install Hugo.Hugo.Extended
@@ -51,10 +51,10 @@ winget uninstall --name "Hugo (Extended)"
To build Hugo from source you must install:
-1. [Git]
-1. [Go] version 1.25.0 or later
+1. [Git][]
+1. [Go][] version {{% current-go-version %}} or later
-> [!note]
+> [!NOTE]
> The Bash-style `KEY=VALUE cmd` syntax used in the macOS and Linux build-from-source instructions does not work in PowerShell or Command Prompt. Use the code block matching your shell.
### Standard edition
@@ -95,7 +95,7 @@ go install -tags withdeploy github.com/gohugoio/hugo@latest
### Extended edition
-To build and install the extended edition, first install a C compiler such as [GCC] or [Clang] and then run the following command:
+To build and install the extended edition, first install a C compiler such as [GCC][] or [Clang][] and then run the following command:
PowerShell:
@@ -112,7 +112,7 @@ go install -tags extended github.com/gohugoio/hugo@latest
### Extended/deploy edition
-To build and install the extended/deploy edition, first install a C compiler such as [GCC] or [Clang] and then run the following command:
+To build and install the extended/deploy edition, first install a C compiler such as [GCC][] or [Clang][] and then run the following command:
PowerShell:
@@ -127,8 +127,8 @@ set CGO_ENABLED=1
go install -tags extended,withdeploy github.com/gohugoio/hugo@latest
```
-> [!note]
-> See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
+> [!NOTE]
+> See these [detailed instructions][] to install GCC on Windows.
## Comparison
@@ -150,3 +150,4 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar
[Go]: https://go.dev/doc/install
[Scoop]: https://scoop.sh/
[Winget]: https://learn.microsoft.com/en-us/windows/package-manager/
+[detailed instructions]: https://discourse.gohugo.io/t/41370
diff --git a/docs/content/en/methods/menu-entry/Identifier.md b/docs/content/en/methods/menu-entry/Identifier.md
index 7310ff3ba..97b8befed 100644
--- a/docs/content/en/methods/menu-entry/Identifier.md
+++ b/docs/content/en/methods/menu-entry/Identifier.md
@@ -9,7 +9,7 @@ params:
signatures: [MENUENTRY.Identifier]
---
-The `Identifier` method returns the `identifier` property of the menu entry. If you define the menu entry [automatically], it returns the page's section.
+The `Identifier` method returns the `identifier` property of the menu entry. If you define the menu entry [automatically][], it returns the page's section.
{{< code-toggle file=hugo >}}
[[menus.main]]
@@ -35,7 +35,7 @@ This example uses the `Identifier` method when querying the translation table on
```
-> [!note]
+> [!NOTE]
> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
[automatically]: /content-management/menus/#define-automatically
diff --git a/docs/content/en/methods/menu-entry/KeyName.md b/docs/content/en/methods/menu-entry/KeyName.md
index abf639667..6a4382bfe 100644
--- a/docs/content/en/methods/menu-entry/KeyName.md
+++ b/docs/content/en/methods/menu-entry/KeyName.md
@@ -34,6 +34,6 @@ 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.
+In the example above, we need to pass the value returned by `.KeyName` through the [`strings.ToLower`][] function because the keys in the translation table are lowercase.
-[`lower`]: /functions/strings/tolower/
+[`strings.ToLower`]: /functions/strings/tolower/
diff --git a/docs/content/en/methods/menu-entry/Menu.md b/docs/content/en/methods/menu-entry/Menu.md
index 074911eeb..a172629d0 100644
--- a/docs/content/en/methods/menu-entry/Menu.md
+++ b/docs/content/en/methods/menu-entry/Menu.md
@@ -15,7 +15,7 @@ params:
{{ end }}
```
-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].
+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/
diff --git a/docs/content/en/methods/menu-entry/Name.md b/docs/content/en/methods/menu-entry/Name.md
index a00601b2d..7b909d790 100644
--- a/docs/content/en/methods/menu-entry/Name.md
+++ b/docs/content/en/methods/menu-entry/Name.md
@@ -9,9 +9,9 @@ params:
signatures: [MENUENTRY.Name]
---
-If you define the menu entry [automatically], the `Name` method returns the page's [`LinkTitle`], falling back to its [`Title`].
+If you define the menu entry [automatically][], the `Name` method returns the page's [`LinkTitle`][], falling back to its [`Title`][].
-If you define the menu entry in [front matter] or in your [project configuration], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`], falling back to its [`Title`].
+If you define the menu entry in [front matter][] or in your [project configuration][], the `Name` method returns the `name` property of the given menu entry. If the `name` is not defined, and the menu entry resolves to a page, the `Name` returns the page [`LinkTitle`][], falling back to its [`Title`][].
```go-html-template
diff --git a/docs/content/en/methods/menu-entry/Page.md b/docs/content/en/methods/menu-entry/Page.md
index 489ee7acc..2689e06df 100644
--- a/docs/content/en/methods/menu-entry/Page.md
+++ b/docs/content/en/methods/menu-entry/Page.md
@@ -9,7 +9,7 @@ params:
signatures: [MENUENTRY.Page]
---
-Regardless of how you [define menu entries], an entry associated with a page has access to its [methods].
+Regardless of how you [define menu entries][], an entry associated with a page has access to its [methods][].
In this menu definition, the first two entries are associated with a page, the last entry is not:
@@ -28,7 +28,7 @@ url = 'https://gohugo.io'
weight = 30
{{< /code-toggle >}}
-In this example, if the menu entry is associated with a page, we use page's [`RelPermalink`] and [`LinkTitle`] when rendering the anchor element.
+In this example, if the menu entry is associated with a page, we use page's [`RelPermalink`][] and [`LinkTitle`][] when rendering the anchor element.
If the entry is not associated with a page, we use its `url` and `name` properties.
@@ -44,7 +44,7 @@ If the entry is not associated with a page, we use its `url` and `name` properti
```
-See the [menu templates] section for more information.
+See the [menu templates][] section for more information.
[`LinkTitle`]: /methods/page/linktitle/
[`RelPermalink`]: /methods/page/relpermalink/
diff --git a/docs/content/en/methods/menu-entry/PageRef.md b/docs/content/en/methods/menu-entry/PageRef.md
index f75a4f6ec..ce1800ba5 100644
--- a/docs/content/en/methods/menu-entry/PageRef.md
+++ b/docs/content/en/methods/menu-entry/PageRef.md
@@ -9,39 +9,39 @@ params:
signatures: [MENUENTRY.PageRef]
---
-> [!note]
+> [!NOTE]
> The use case for this method is rare.
-> In almost also scenarios you should use the [`URL`] method instead.
+> In almost also scenarios you should use the [`URL`][] method instead.
## Explanation
-If you specify a `pageRef` property when [defining a menu entry] in your project configuration, Hugo looks for a matching page when rendering the entry.
+If you specify a `pageRef` property when [defining a menu entry][] in your project configuration, Hugo looks for a matching page when rendering the entry.
If a matching page is found:
-- The [`URL`] method returns the page's relative permalink
-- The [`Page`] method returns the corresponding `Page` object
-- The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return the expected values
+- The [`URL`][] method returns the page's relative permalink
+- The [`Page`][] method returns the corresponding `Page` object
+- The [`HasMenuCurrent`][] and [`IsMenuCurrent`][] methods on a `Page` object return the expected values
If a matching page is not found:
-- The [`URL`] method returns the entry's `url` property if set, else an empty string
-- The [`Page`] method returns nil
-- The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return `false`
+- The [`URL`][] method returns the entry's `url` property if set, else an empty string
+- The [`Page`][] method returns nil
+- The [`HasMenuCurrent`][] and [`IsMenuCurrent`][] methods on a `Page` object return `false`
-> [!note]
-> In almost also scenarios you should use the [`URL`] method instead.
+> [!NOTE]
+> In almost also scenarios you should use the [`URL`][] method instead.
## Example
This example is contrived.
-> [!note]
-> In almost also scenarios you should use the [`URL`] method instead.
+> [!NOTE]
+> In almost also scenarios you should use the [`URL`][] method instead.
Consider this content structure:
-```text
+```tree
content/
├── products.md
└── _index.md
diff --git a/docs/content/en/methods/menu-entry/Params.md b/docs/content/en/methods/menu-entry/Params.md
index 113178147..c05149f0b 100644
--- a/docs/content/en/methods/menu-entry/Params.md
+++ b/docs/content/en/methods/menu-entry/Params.md
@@ -9,7 +9,7 @@ params:
signatures: [MENUENTRY.Params]
---
-When you define menu entries in your [project configuration] or in [front matter], you can include a `params` key to attach additional information to the entry. For example:
+When you define menu entries in your [project configuration][] or in [front matter][], you can include a `params` key to attach additional information to the entry. For example:
{{< code-toggle file=hugo >}}
[[menus.main]]
@@ -54,8 +54,8 @@ Hugo renders:
```
-See the [menu templates] section for more information.
+See the [menu templates][] section for more information.
-[menu templates]: /templates/menu/#menu-entry-parameters
[front matter]: /content-management/menus/#define-in-front-matter
+[menu templates]: /templates/menu/#menu-entry-parameters
[project configuration]: /content-management/menus/
diff --git a/docs/content/en/methods/menu-entry/Title.md b/docs/content/en/methods/menu-entry/Title.md
index 526132d7c..e5512fdc7 100644
--- a/docs/content/en/methods/menu-entry/Title.md
+++ b/docs/content/en/methods/menu-entry/Title.md
@@ -9,9 +9,7 @@ params:
signatures: [MENUENTRY.Title]
---
-The `Title` method returns the `title` property of the given menu entry. If the `title` is not defined, and the menu entry resolves to a page, the `Title` returns the page [`Title`].
-
-[`Title`]: /methods/page/title/
+The `Title` method returns the `title` property of the given menu entry. If the `title` is not defined, and the menu entry resolves to a page, the `Title` returns the page [`Title`][].
```go-html-template
@@ -20,3 +18,5 @@ The `Title` method returns the `title` property of the given menu entry. If the
{{ end }}
```
+
+[`Title`]: /methods/page/title/
diff --git a/docs/content/en/methods/menu-entry/URL.md b/docs/content/en/methods/menu-entry/URL.md
index e29a6f058..5512dfe2a 100644
--- a/docs/content/en/methods/menu-entry/URL.md
+++ b/docs/content/en/methods/menu-entry/URL.md
@@ -9,7 +9,7 @@ params:
signatures: [MENUENTRY.URL]
---
-For menu entries associated with a page, the `URL` method returns the page's [`RelPermalink`], otherwise it returns the entry's `url` property.
+For menu entries associated with a page, the `URL` method returns the page's [`RelPermalink`][], otherwise it returns the entry's `url` property.
```go-html-template
diff --git a/docs/content/en/methods/menu-entry/Weight.md b/docs/content/en/methods/menu-entry/Weight.md
index 17fc3a43b..6c952325e 100644
--- a/docs/content/en/methods/menu-entry/Weight.md
+++ b/docs/content/en/methods/menu-entry/Weight.md
@@ -9,9 +9,9 @@ params:
signatures: [MENUENTRY.Weight]
---
-If you define the menu entry [automatically], the `Weight` method returns the page's [`Weight`].
+If you define the menu entry [automatically][], the `Weight` method returns the page's [`Weight`][].
-If you define the menu entry in [front matter] or in your [project configuration], the `Weight` method returns the `weight` property, falling back to the page's `Weight`.
+If you define the menu entry in [front matter][] or in your [project configuration][], the `Weight` method returns the `weight` property, falling back to the page's `Weight`.
In this contrived example, we limit the number of menu entries based on weight:
diff --git a/docs/content/en/methods/menu/ByName.md b/docs/content/en/methods/menu/ByName.md
index d98a4aced..e8a262e5d 100644
--- a/docs/content/en/methods/menu/ByName.md
+++ b/docs/content/en/methods/menu/ByName.md
@@ -50,7 +50,7 @@ Hugo renders this to:
```
-You can also sort menu entries using the [`sort`] function. For example, to sort by `name` in descending order:
+You can also sort menu entries using the [`sort`][] function. For example, to sort by `name` in descending order:
```go-html-template
diff --git a/docs/content/en/methods/menu/ByWeight.md b/docs/content/en/methods/menu/ByWeight.md
index 013d37e13..5ccfce11e 100644
--- a/docs/content/en/methods/menu/ByWeight.md
+++ b/docs/content/en/methods/menu/ByWeight.md
@@ -53,10 +53,10 @@ Hugo renders this to:
```
-> [!note]
+> [!NOTE]
> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
-You can also sort menu entries using the [`sort`] function. For example, to sort by `weight` in descending order:
+You can also sort menu entries using the [`sort`][] function. For example, to sort by `weight` in descending order:
```go-html-template
diff --git a/docs/content/en/methods/output-format/MediaType.md b/docs/content/en/methods/output-format/MediaType.md
index 9283868bf..812d0d2e3 100644
--- a/docs/content/en/methods/output-format/MediaType.md
+++ b/docs/content/en/methods/output-format/MediaType.md
@@ -11,26 +11,22 @@ params:
{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+## Example
+
```go-html-template
{{ with .Site.Home.OutputFormats.Get "rss" }}
{{ with .MediaType }}
- {{ .Type }} → application/rss+xml
- {{ .MainType }} → application
- {{ .SubType }} → rss
+ {{ .Type }} → application/rss+xml
+ {{ .MainType }} → application
+ {{ .SubType }} → rss
+ {{ .Suffixes }} → [rss]
+ {{ .FirstSuffix.Suffix }} → rss
{{ end }}
{{ end }}
```
## Methods
-### MainType
+Use these methods on the `MediaType` object.
-(`string`) Returns the main type of the output format's media type.
-
-### SubType
-
-(`string`) Returns the subtype of the current format's media type.
-
-### Type
-
-(`string`) Returns the current format's media type.
+{{% include "/_common/methods/media-type/core-methods.md" %}}
diff --git a/docs/content/en/methods/page/Aliases.md b/docs/content/en/methods/page/Aliases.md
index f159ba868..17a52c03a 100644
--- a/docs/content/en/methods/page/Aliases.md
+++ b/docs/content/en/methods/page/Aliases.md
@@ -19,7 +19,7 @@ By default, Hugo handles aliases by creating individual HTML files for each alia
While functional, generating a single `_redirects` file allows your hosting provider to handle redirects at the server level. This is more efficient than client-side redirection and improves performance by eliminating the need to load a middle-man HTML page.
-> [!tip]
+> [!TIP]
> You can use the same general approach to generate an `.htaccess` file.
## Example
@@ -30,7 +30,7 @@ The following example demonstrates how to configure your site and create a templ
The content structure for this multilingual example looks like this:
-```text
+```tree
content/
├── examples/
│ ├── a.de.md aliases = ['a-old']
diff --git a/docs/content/en/methods/page/AllTranslations.md b/docs/content/en/methods/page/AllTranslations.md
index 6baeb407f..09578fccc 100644
--- a/docs/content/en/methods/page/AllTranslations.md
+++ b/docs/content/en/methods/page/AllTranslations.md
@@ -35,7 +35,7 @@ weight = 3
And this content:
-```text
+```tree
content/
├── de/
│ ├── books/
diff --git a/docs/content/en/methods/page/AlternativeOutputFormats.md b/docs/content/en/methods/page/AlternativeOutputFormats.md
index 72ef9f5d0..73a33cb53 100644
--- a/docs/content/en/methods/page/AlternativeOutputFormats.md
+++ b/docs/content/en/methods/page/AlternativeOutputFormats.md
@@ -11,7 +11,7 @@ params:
{{% glossary-term "output format" %}}
-The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/).
+The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page. See [details][].
For example, to generate a `link` element for each of the alternative output formats:
@@ -27,3 +27,5 @@ Hugo renders this to something like:
```
+
+[details]: /configuration/output-formats/
diff --git a/docs/content/en/methods/page/Ancestors.md b/docs/content/en/methods/page/Ancestors.md
index d8275cf76..f3abf0cd3 100644
--- a/docs/content/en/methods/page/Ancestors.md
+++ b/docs/content/en/methods/page/Ancestors.md
@@ -11,7 +11,7 @@ params:
With this content structure:
-```text
+```tree
content/
├── auctions/
│ ├── 2023-11/
diff --git a/docs/content/en/methods/page/BundleType.md b/docs/content/en/methods/page/BundleType.md
index e919511da..cf7f8c0e1 100644
--- a/docs/content/en/methods/page/BundleType.md
+++ b/docs/content/en/methods/page/BundleType.md
@@ -9,11 +9,11 @@ params:
signatures: [PAGE.BundleType]
---
-A page bundle is a directory that encapsulates both content and associated [resources](g). There are two types of page bundles: [leaf bundles](g) and [branch bundles](g). See [details](/content-management/page-bundles/).
+A page bundle is a directory that encapsulates both content and associated [resources](g). There are two types of page bundles: [leaf bundles](g) and [branch bundles](g). See [details][].
The `BundleType` method on a `Page` object returns `branch` for branch bundles, `leaf` for leaf bundles, and an empty string if the page is not a page bundle.
-```text
+```tree
content/
├── films/
│ ├── film-1/
@@ -31,3 +31,5 @@ To get the value within a template:
```go-html-template
{{ .BundleType }}
```
+
+[details]: /content-management/page-bundles/
diff --git a/docs/content/en/methods/page/CodeOwners.md b/docs/content/en/methods/page/CodeOwners.md
index 00afa7549..4aa0bf0da 100644
--- a/docs/content/en/methods/page/CodeOwners.md
+++ b/docs/content/en/methods/page/CodeOwners.md
@@ -11,14 +11,11 @@ params:
GitHub and GitLab support CODEOWNERS files. This file specifies the users responsible for developing and maintaining software and documentation. This definition can apply to the entire repository, specific directories, or to individual files. To learn more:
-- [GitHub CODEOWNERS documentation]
-- [GitLab CODEOWNERS documentation]
+- [GitHub CODEOWNERS documentation][]
+- [GitLab CODEOWNERS documentation][]
Use the `CodeOwners` method on a `Page` object to determine the code owners for the given page.
-[GitHub CODEOWNERS documentation]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
-[GitLab CODEOWNERS documentation]: https://docs.gitlab.com/ee/user/project/code_owners.html
-
To use the `CodeOwners` method you must enable access to your local Git repository:
{{< code-toggle file=hugo >}}
@@ -27,7 +24,7 @@ enableGitInfo = true
Consider this project structure:
-```text
+```tree
my-project/
├── content/
│ ├── books/
@@ -60,6 +57,8 @@ Render the code owners for each content page:
{{ end }}
```
-Combine this method with [`resources.GetRemote`] to retrieve names and avatars from your Git provider by querying their API.
+Combine this method with [`resources.GetRemote`][] to retrieve names and avatars from your Git provider by querying their API.
+[GitHub CODEOWNERS documentation]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+[GitLab CODEOWNERS documentation]: https://docs.gitlab.com/ee/user/project/code_owners.html
[`resources.GetRemote`]: /functions/resources/getremote/
diff --git a/docs/content/en/methods/page/ContentWithoutSummary.md b/docs/content/en/methods/page/ContentWithoutSummary.md
index 4923b1197..5c3edbb9c 100644
--- a/docs/content/en/methods/page/ContentWithoutSummary.md
+++ b/docs/content/en/methods/page/ContentWithoutSummary.md
@@ -11,12 +11,12 @@ params:
{{< new-in 0.134.0 />}}
-Applicable when using manual or automatic [content summaries], the `ContentWithoutSummary` method on a `Page` object renders Markdown and shortcodes to HTML, excluding the content summary from the result.
-
-[content summaries]: /content-management/summaries/#manual-summary
+Applicable when using manual or automatic [content summaries][], the `ContentWithoutSummary` method on a `Page` object renders Markdown and shortcodes to HTML, excluding the content summary from the result.
```go-html-template
{{ .ContentWithoutSummary }}
```
The `ContentWithoutSummary` method returns the same as `Content` if you define the content summary in front matter.
+
+[content summaries]: /content-management/summaries/#manual-summary
diff --git a/docs/content/en/methods/page/CurrentSection.md b/docs/content/en/methods/page/CurrentSection.md
index 93457f13f..6e20096f2 100644
--- a/docs/content/en/methods/page/CurrentSection.md
+++ b/docs/content/en/methods/page/CurrentSection.md
@@ -11,12 +11,12 @@ params:
{{% glossary-term section %}}
-> [!note]
+> [!NOTE]
> The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself.
Consider this content structure:
-```text
+```tree
content/
├── auctions/
│ ├── 2023-11/
diff --git a/docs/content/en/methods/page/Data.md b/docs/content/en/methods/page/Data.md
index 3d4433a8e..f3c975930 100644
--- a/docs/content/en/methods/page/Data.md
+++ b/docs/content/en/methods/page/Data.md
@@ -11,10 +11,10 @@ params:
The `Data` method on a `Page` object returns a unique data object for each [page kind](g).
-> [!note]
+> [!NOTE]
> The `Data` method is only useful within [taxonomy](g) and [term](g) templates.
>
-> Themes that are not actively maintained may still use `.Data.Pages` in their templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`]
+> Themes that are not actively maintained may still use `.Data.Pages` in their templates. Although that syntax remains functional, use one of these methods instead: [`Pages`][], [`RegularPages`][], or [`RegularPagesRecursive`][]
The examples that follow are based on this project configuration:
@@ -26,7 +26,7 @@ author = 'authors'
And this content structure:
-```text
+```tree
content/
├── books/
│ ├── and-then-there-were-none.md --> genres: suspense
@@ -40,62 +40,62 @@ content/
Use these methods on the `Data` object within a _taxonomy_ template.
-Singular
+`Singular`
: (`string`) Returns the singular name of the taxonomy.
```go-html-template
{{ .Data.Singular }} → genre
```
-Plural
+`Plural`
: (`string`) Returns the plural name of the taxonomy.
```go-html-template
{{ .Data.Plural }} → genres
```
-Terms
+`Terms`
: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages](g) associated with each term.
```go-html-template
{{ $taxonomyObject := .Data.Terms }}
```
-> [!note]
-> Once you have captured the `Taxonomy` object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages.
+> [!NOTE]
+> Once you have captured the `Taxonomy` object, use any of the [taxonomy methods][] to sort, count, or capture a subset of its weighted pages.
-Learn more about [taxonomy templates].
+Learn more about [taxonomy templates][].
## In a term template
Use these methods on the `Data` object within a _term_ template.
-Singular
+`Singular`
: (`string`) Returns the singular name of the taxonomy.
```go-html-template
{{ .Data.Singular }} → genre
```
-Plural
+`Plural`
: (`string`) Returns the plural name of the taxonomy.
```go-html-template
{{ .Data.Plural }} → genres
```
-Term
+`Term`
: (`string`) Returns the name of the term.
```go-html-template
{{ .Data.Term }} → suspense
```
-Learn more about [term templates].
+Learn more about [term templates][].
[`Pages`]: /methods/page/pages/
-[`RegularPages`]: /methods/page/regularpages/
[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
+[`RegularPages`]: /methods/page/regularpages/
[taxonomy methods]: /methods/taxonomy/
[taxonomy templates]: /templates/types/#taxonomy
[term templates]: /templates/types/#term
diff --git a/docs/content/en/methods/page/Date.md b/docs/content/en/methods/page/Date.md
index ffddcf047..1cc7e9c1d 100644
--- a/docs/content/en/methods/page/Date.md
+++ b/docs/content/en/methods/page/Date.md
@@ -16,16 +16,16 @@ title = 'Article 1'
date = 2023-10-19T00:40:04-07:00
{{< /code-toggle >}}
-> [!note]
-> The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your project, in your project configuration. See [details].
+> [!NOTE]
+> The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your project, in your project configuration. See [details][].
-The date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+The date is a [time.Time][] value. Format and localize the value with the [`time.Format`][] function, or use it with any of the [time methods][].
```go-html-template
{{ .Date | time.Format ":date_medium" }} → Oct 19, 2023
```
-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].
+In the example above we explicitly set the date in front matter. With Hugo's default configuration, the `Date` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the date is not defined in front matter. See [details][].
[`time.Format`]: /functions/time/format/
[details]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/page/Description.md b/docs/content/en/methods/page/Description.md
index 7a609bb07..7e44bd0e9 100644
--- a/docs/content/en/methods/page/Description.md
+++ b/docs/content/en/methods/page/Description.md
@@ -9,7 +9,7 @@ params:
signatures: [PAGE.Description]
---
-Conceptually different from 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'
diff --git a/docs/content/en/methods/page/ExpiryDate.md b/docs/content/en/methods/page/ExpiryDate.md
index 67e6b30d3..e59687c4a 100644
--- a/docs/content/en/methods/page/ExpiryDate.md
+++ b/docs/content/en/methods/page/ExpiryDate.md
@@ -18,13 +18,13 @@ title = 'Article 1'
expiryDate = 2024-10-19T00:32:13-07:00
{{< /code-toggle >}}
-The expiry date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
+The expiry date is a [time.Time][] value. Format and localize the value with the [`time.Format`][] function, or use it with any of the [time methods][].
```go-html-template
{{ .ExpiryDate | time.Format ":date_medium" }} → Oct 19, 2024
```
-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].
+In the example above we explicitly set the expiry date in front matter. With Hugo's default configuration, the `ExpiryDate` method returns the front matter value. This behavior is configurable, allowing you to set fallback values if the expiry date is not defined in front matter. See [details][].
[`time.Format`]: /functions/time/format/
[details]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/page/File.md b/docs/content/en/methods/page/File.md
index 0bf2fdecf..9644e0da3 100644
--- a/docs/content/en/methods/page/File.md
+++ b/docs/content/en/methods/page/File.md
@@ -13,7 +13,7 @@ By default, not all pages are backed by a file, including top-level [section pag
To back one of the pages above with a file, create an `_index.md` file in the corresponding directory. For example:
-```text
+```tree
content/
└── books/
├── _index.md <-- the top-slevel section page
@@ -21,129 +21,120 @@ content/
└── book-2.md
```
-> [!note]
+> [!NOTE]
> Code defensively by verifying file existence as shown in the examples below.
## Methods
-> [!note]
+Use these methods on the `File` object.
+
+> [!NOTE]
> The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system.
-### BaseFileName
+`BaseFileName`
+: (`string`) The file name, excluding the extension.
-(`string`) The file name, excluding the extension.
+ ```go-html-template
+ {{ with .File }}
+ {{ .BaseFileName }}
+ {{ end }}
+ ```
-```go-html-template
-{{ with .File }}
- {{ .BaseFileName }}
-{{ end }}
-```
+`ContentBaseName`
+: (`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `TranslationBaseName`.
-### ContentBaseName
+ ```go-html-template
+ {{ with .File }}
+ {{ .ContentBaseName }}
+ {{ end }}
+ ```
-(`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `TranslationBaseName`.
+`Dir`
+: (`string`) The file path, excluding the file name, relative to the `content` directory.
-```go-html-template
-{{ with .File }}
- {{ .ContentBaseName }}
-{{ end }}
-```
+ ```go-html-template
+ {{ with .File }}
+ {{ .Dir }}
+ {{ end }}
+ ```
-### Dir
+`Ext`
+: (`string`) The file extension.
-(`string`) The file path, excluding the file name, relative to the `content` directory.
+ ```go-html-template
+ {{ with .File }}
+ {{ .Ext }}
+ {{ end }}
+ ```
-```go-html-template
-{{ with .File }}
- {{ .Dir }}
-{{ end }}
-```
+`Filename`
+: (`string`) The absolute file path.
-### Ext
+ ```go-html-template
+ {{ with .File }}
+ {{ .Filename }}
+ {{ end }}
+ ```
-(`string`) The file extension.
+`IsContentAdapter`
+: (`bool`) Reports whether the file is a [content adapter][].
-```go-html-template
-{{ with .File }}
- {{ .Ext }}
-{{ end }}
-```
+ ```go-html-template
+ {{ with .File }}
+ {{ .IsContentAdapter }}
+ {{ end }}
+ ```
-### Filename
+`LogicalName`
+: (`string`) The file name.
-(`string`) The absolute file path.
+ ```go-html-template
+ {{ with .File }}
+ {{ .LogicalName }}
+ {{ end }}
+ ```
-```go-html-template
-{{ with .File }}
- {{ .Filename }}
-{{ end }}
-```
+`Path`
+: (`string`) The file path, relative to the `content` directory.
-### IsContentAdapter
+ ```go-html-template
+ {{ with .File }}
+ {{ .Path }}
+ {{ end }}
+ ```
-(`bool`) Reports whether the file is a [content adapter].
+`Section`
+: (`string`) The name of the top-level section in which the file resides.
-```go-html-template
-{{ with .File }}
- {{ .IsContentAdapter }}
-{{ end }}
-```
+ ```go-html-template
+ {{ with .File }}
+ {{ .Section }}
+ {{ end }}
+ ```
-### LogicalName
+`TranslationBaseName`
+: (`string`) The file name, excluding the extension and language identifier.
-(`string`) The file name.
+ ```go-html-template
+ {{ with .File }}
+ {{ .TranslationBaseName }}
+ {{ end }}
+ ```
-```go-html-template
-{{ with .File }}
- {{ .LogicalName }}
-{{ end }}
-```
+`UniqueID`
+: (`string`) The MD5 hash of `.File.Path`.
-### Path
-
-(`string`) The file path, relative to the `content` directory.
-
-```go-html-template
-{{ with .File }}
- {{ .Path }}
-{{ 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.
-
-```go-html-template
-{{ with .File }}
- {{ .TranslationBaseName }}
-{{ end }}
-```
-
-### UniqueID
-
-(`string`) The MD5 hash of `.File.Path`.
-
-```go-html-template
-{{ with .File }}
- {{ .UniqueID }}
-{{ end }}
-```
+ ```go-html-template
+ {{ with .File }}
+ {{ .UniqueID }}
+ {{ end }}
+ ```
## Examples
Consider this content structure in a multilingual project:
-```text
+```tree
content/
├── news/
│ ├── b/
diff --git a/docs/content/en/methods/page/FirstSection.md b/docs/content/en/methods/page/FirstSection.md
index 73ddd2d7b..074be443b 100644
--- a/docs/content/en/methods/page/FirstSection.md
+++ b/docs/content/en/methods/page/FirstSection.md
@@ -11,12 +11,12 @@ params:
{{% glossary-term section %}}
-> [!note]
+> [!NOTE]
> When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself.
Consider this content structure:
-```text
+```tree
content/
├── auctions/
│ ├── 2023-11/
diff --git a/docs/content/en/methods/page/Fragments.md b/docs/content/en/methods/page/Fragments.md
index 9df47f31c..ce8a13137 100644
--- a/docs/content/en/methods/page/Fragments.md
+++ b/docs/content/en/methods/page/Fragments.md
@@ -17,93 +17,92 @@ In a URL, whether absolute or relative, the [fragment](g) links to an `id` attri
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](g) 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](g) 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](g) the `Fragments.Map` data structure.
+Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking](g) the `Fragments.Map` data structure. Use the methods below to inspect, validate, and render page fragments.
## Methods
-### Headings
+Use these methods on the `Fragments` object.
-(`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
+`Headings`
+: (`slice`) A slice of maps of all headings on the page, with first-level keys for each heading. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
-```go-html-template
-
{{ debug.Dump .Fragments.Headings }}
-```
+ ```go-html-template
+ {{ debug.Dump .Fragments.Headings }}
+ ```
-### HeadingsMap
+`HeadingsMap`
+: (`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
-(`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
+ {{ debug.Dump .Fragments.HeadingsMap }}
+ ```
-```go-html-template
-{{ debug.Dump .Fragments.HeadingsMap }}
-```
+`Identifiers`
+: (`slice`) A slice containing the `id` attribute of each heading on the page. If so configured, will also contain the `id` attribute of each description term (i.e., `dt` element) on the page.
-### Identifiers
+ See [configure Markup][].
-(`slice`) A slice containing the `id` attribute of each heading on the page. If so configured, will also contain the `id` attribute of each description term (i.e., `dt` element) on the page.
+ To inspect the data structure:
-See [configure Markup](/configuration/markup/#parserautodefinitiontermid).
+ ```go-html-template
+ {{ debug.Dump .Fragments.Identifiers }}
+ ```
-To inspect the data structure:
+`Identifiers.Contains ID`
+: (`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook](g).
-```go-html-template
-{{ debug.Dump .Fragments.Identifiers }}
-```
+ ```go-html-template
+ {{ .Fragments.Identifiers.Contains "section-2" }} → true
+ ```
-### Identifiers.Contains ID
+`Identifiers.Count ID`
+: (`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates.
-(`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook](g).
+ ```go-html-template
+ {{ .Fragments.Identifiers.Count "section-2" }} → 1
+ ```
-```go-html-template
-{{ .Fragments.Identifiers.Contains "section-2" }} → true
-```
+`ToHTML`
+: (`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`][] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list).
-### Identifiers.Count ID
+ Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your project configuration.
-(`int`) The number of headings on a page with the given `id` attribute, useful for detecting duplicates.
+ ```go-html-template
+ {{ $startLevel := 2 }}
+ {{ $endLevel := 3 }}
+ {{ $ordered := true }}
+ {{ .Fragments.ToHTML $startLevel $endLevel $ordered }}
+ ```
-```go-html-template
-{{ .Fragments.Identifiers.Count "section-2" }} → 1
-```
+ Hugo renders this to:
-### ToHTML
+ ```html
+
+ ```
-(`template.HTML`) Returns a TOC as a nested list, either ordered or unordered, identical to the HTML returned by the [`TableOfContents`] method. This method take three arguments: the start level (`int`), the end level (`int`), and a boolean (`true` to return an ordered list, `false` to return an unordered list).
+## Notes
-Use this method when you want to control the start level, end level, or list type independently from the table of contents settings in your project configuration.
-
-```go-html-template
-{{ $startLevel := 2 }}
-{{ $endLevel := 3 }}
-{{ $ordered := true }}
-{{ .Fragments.ToHTML $startLevel $endLevel $ordered }}
-```
-
-Hugo renders this to:
-
-```html
-
-```
-
-> [!note]
+> [!NOTE]
> It is safe to use the `Fragments` methods within a render hook, even for the current page.
>
-> When using the `Fragments` methods within a shortcode, call the shortcode using [standard notation]. If you use [Markdown notation] the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop.
+> When using the `Fragments` methods within a shortcode, call the shortcode using [standard notation][]. If you use [Markdown notation][] the rendered shortcode is included in the creation of the fragments map, resulting in a circular loop.
-[`TableOfContents`]: /methods/page/tableofcontents/
[ATX]: https://spec.commonmark.org/current/#atx-headings
[Markdown notation]: /content-management/shortcodes/#notation
+[`TableOfContents`]: /methods/page/tableofcontents/
+[configure Markup]: /configuration/markup/#parserautodefinitiontermid
[setext]: https://spec.commonmark.org/current/#setext-headings
[standard notation]: /content-management/shortcodes/#notation
[table of contents]: /methods/page/tableofcontents/
diff --git a/docs/content/en/methods/page/FuzzyWordCount.md b/docs/content/en/methods/page/FuzzyWordCount.md
index 815a07402..36c0f2542 100644
--- a/docs/content/en/methods/page/FuzzyWordCount.md
+++ b/docs/content/en/methods/page/FuzzyWordCount.md
@@ -13,6 +13,6 @@ params:
{{ .FuzzyWordCount }} → 200
```
-To get the exact word count, use the [`WordCount`] method.
+To get the exact word count, use the [`WordCount`][] method.
[`WordCount`]: /methods/page/wordcount/
diff --git a/docs/content/en/methods/page/GetPage.md b/docs/content/en/methods/page/GetPage.md
index 7c1e45dd9..641765d67 100644
--- a/docs/content/en/methods/page/GetPage.md
+++ b/docs/content/en/methods/page/GetPage.md
@@ -10,9 +10,7 @@ params:
aliases: [/functions/getpage]
---
-The `GetPage` method is also available on a `Site` object. See [details].
-
-[details]: /methods/site/getpage/
+The `GetPage` method is also available on a `Site` object. See [details][].
When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the `content` directory.
@@ -20,7 +18,7 @@ If Hugo cannot resolve the path to a page, the method returns nil. If the path i
Consider this content structure:
-```text
+```tree
content/
├── works/
│ ├── paintings/
@@ -62,3 +60,5 @@ The examples below depict the result of rendering `works/paintings/the-mona-lisa
{{ .Title }} → David
{{ end }}
```
+
+[details]: /methods/site/getpage/
diff --git a/docs/content/en/methods/page/GitInfo.md b/docs/content/en/methods/page/GitInfo.md
index 8a60f0934..35df8e627 100644
--- a/docs/content/en/methods/page/GitInfo.md
+++ b/docs/content/en/methods/page/GitInfo.md
@@ -11,7 +11,7 @@ params:
The `GitInfo` method on a `Page` object provides access to commit metadata from your Git history, such as the author's name, the commit hash, and the commit message.
-> [!note]
+> [!NOTE]
> Hugo's Git integration is performant, but may increase build times for large projects.
## Prerequisites
@@ -24,7 +24,7 @@ You must also allow Hugo to access your repository by adding this to your projec
enableGitInfo = true
{{< /code-toggle >}}
-> [!note]
+> [!NOTE]
> When you set [`enableGitInfo`][] to `true`, the last modification date for each content page will automatically be the Author Date of the last commit for that file.
>
> This is configurable. See [details][].
@@ -43,115 +43,113 @@ Hugo retrieves commit metadata for files tracked within your project's local rep
Hugo also retrieves commit metadata for content provided by modules. This allows you to display commit data for remote repositories that are mounted as content directories, such as when aggregating documentation from multiple sources.
+> [!NOTE]
+> The `GitInfo` method returns nil for module content in these cases:
+>
+> - The module is vendored via `hugo mod vendor`
+> - A [module replacement][] is configured via a `replace` directive in `go.mod` or the [`replacements`][] configuration parameter
+
## Methods
-### AbbreviatedHash
+Use these methods on the `GitInfo` object.
-(`string`) Returns the seven-character shortened version of the commit hash.
+`AbbreviatedHash`
+: (`string`) Returns the seven-character shortened version of the commit hash.
-```go-html-template
-{{ with .GitInfo }}
- {{ .AbbreviatedHash }} → aab9ec0
-{{ end }}
-```
-
-### AuthorDate
-
-(`time.Time`) Returns the date the author originally created the commit.
-
-```go-html-template
-{{ with .GitInfo }}
- {{ .AuthorDate.Format "2006-01-02" }} → 2023-10-09
-{{ end }}
-```
-
-### AuthorEmail
-
-(`string`) Returns the author's email address, respecting [gitmailmap][].
-
-```go-html-template
-{{ with .GitInfo }}
- {{ .AuthorEmail }} → jsmith@example.org
-{{ end }}
-```
-
-### AuthorName
-
-(`string`) Returns the author's name, respecting [gitmailmap][].
-
-```go-html-template
-{{ with .GitInfo }}
- {{ .AuthorName }} → John Smith
-{{ end }}
-```
-
-### CommitDate
-
-(`time.Time`) Returns the date the commit was applied to the branch.
-
-```go-html-template
-{{ with .GitInfo }}
- {{ .CommitDate.Format "2006-01-02" }} → 2023-10-09
-{{ end }}
-```
-
-### Hash
-
-(`string`) Returns the full SHA-1 commit hash.
-
-```go-html-template
-{{ with .GitInfo }}
- {{ .Hash }} → aab9ec0b31ebac916a1468c4c9c305f2bebf78d4
-{{ end }}
-```
-
-### Subject
-
-(`string`) Returns the first line of the commit message (the summary).
-
-```go-html-template
-{{ with .GitInfo }}
- {{ .Subject }} → Add tutorials
-{{ end }}
-```
-
-### Body
-
-(`string`) Returns the full content of the commit message, excluding the subject line.
-
-```go-html-template
-{{ with .GitInfo }}
- {{ .Body }} → Two new pages added.
-{{ end }}
-```
-
-### Ancestors
-
-(`gitmap.GitInfos`) Returns a list of previous commits for this specific file, ordered from most recent to oldest.
-
-For example, to list the last 5 commits:
-
-```go-html-template
-{{ with .GitInfo }}
- {{ range .Ancestors | first 5 }}
- {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ .AbbreviatedHash }} → aab9ec0
{{ end }}
-{{ end }}
-```
+ ```
-To reverse the order:
+`AuthorDate`
+: (`time.Time`) Returns the date the author originally created the commit.
-```go-html-template
-{{ with .GitInfo }}
- {{ range .Ancestors.Reverse | first 5 }}
- {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ .AuthorDate.Format "2006-01-02" }} → 2023-10-09
{{ end }}
-{{ end }}
-```
+ ```
-### Parent
+`AuthorEmail`
+: (`string`) Returns the author's email address, respecting [gitmailmap][].
-(`*gitmap.GitInfo`) Returns the most recent ancestor commit for the file, if any.
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ .AuthorEmail }} → jsmith@example.org
+ {{ end }}
+ ```
+
+`AuthorName`
+: (`string`) Returns the author's name, respecting [gitmailmap][].
+
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ .AuthorName }} → John Smith
+ {{ end }}
+ ```
+
+`CommitDate`
+: (`time.Time`) Returns the date the commit was applied to the branch.
+
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ .CommitDate.Format "2006-01-02" }} → 2023-10-09
+ {{ end }}
+ ```
+
+`Hash`
+: (`string`) Returns the full SHA-1 commit hash.
+
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ .Hash }} → aab9ec0b31ebac916a1468c4c9c305f2bebf78d4
+ {{ end }}
+ ```
+
+`Subject`
+: (`string`) Returns the first line of the commit message (the summary).
+
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ .Subject }} → Add tutorials
+ {{ end }}
+ ```
+
+`Body`
+: (`string`) Returns the full content of the commit message, excluding the subject line.
+
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ .Body }} → Two new pages added.
+ {{ end }}
+ ```
+
+`Ancestors`
+: (`gitmap.GitInfos`) Returns a list of previous commits for this specific file, ordered from most recent to oldest.
+
+ For example, to list the last 5 commits:
+
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ range .Ancestors | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+ {{ end }}
+ ```
+
+ To reverse the order:
+
+ ```go-html-template
+ {{ with .GitInfo }}
+ {{ range .Ancestors.Reverse | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+ {{ end }}
+ ```
+
+`Parent`
+: (`*gitmap.GitInfo`) Returns the most recent ancestor commit for the file, if any.
## Last modified date
@@ -178,17 +176,19 @@ Vercel|Shallow|Yes [^1]
[^1]: To perform a deep clone when hosting on Cloudflare, Render, or Vercel, include this code in the build script after the repository has been cloned:
- ```text
+ ```sh
if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
git fetch --unshallow
fi
```
-[^2]: To perform a deep clone when hosting on GitHub Pages, set `fetch-depth: 0` in the `checkout` step of the GitHub Action. See [example](/host-and-deploy/host-on-github-pages/#step-7).
+[^2]: To perform a deep clone when hosting on GitHub Pages, set `fetch-depth: 0` in the `checkout` step of the GitHub Action.
-[^3]: To perform a deep clone when hosting on GitLab Pages, set the `GIT_DEPTH` environment variable to `0` in the workflow file. See [example](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd).
+[^3]: To perform a deep clone when hosting on GitLab Pages, set the `GIT_DEPTH` environment variable to `0` in the workflow file.
[`enableGitInfo`]: /configuration/all/#enablegitinfo
+[`replacements`]: /configuration/module/#replacements
[details]: /configuration/front-matter/#dates
[gitmailmap]: https://git-scm.com/docs/gitmailmap
+[module replacement]: /hugo-modules/use-modules/#replace
[project configuration]: /configuration/front-matter/
diff --git a/docs/content/en/methods/page/HasMenuCurrent.md b/docs/content/en/methods/page/HasMenuCurrent.md
index 22bcc6483..cbdc2edab 100644
--- a/docs/content/en/methods/page/HasMenuCurrent.md
+++ b/docs/content/en/methods/page/HasMenuCurrent.md
@@ -25,9 +25,9 @@ If the `Page` object associated with the menu entry is a section, this method al
{{ end }}
```
-See [menu templates] for a complete example.
+See [menu templates][] for a complete example.
-> [!note]
+> [!NOTE]
> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your project configuration.
[menu templates]: /templates/menu/#example
diff --git a/docs/content/en/methods/page/HasShortcode.md b/docs/content/en/methods/page/HasShortcode.md
index 2e585da31..7b8841628 100644
--- a/docs/content/en/methods/page/HasShortcode.md
+++ b/docs/content/en/methods/page/HasShortcode.md
@@ -9,11 +9,9 @@ params:
signatures: [PAGE.HasShortcode NAME]
---
-By example, let's use [Plotly] to render a chart:
+By example, let's use [Plotly][] to render a chart:
-[Plotly]: https://plotly.com/javascript/
-
-```text {file="content/example.md"}
+```md {file="content/example.md"}
{{}}
{
"data": [
@@ -48,3 +46,5 @@ Now we can selectively load the required JavaScript on pages that call the "plot
...
```
+
+[Plotly]: https://plotly.com/javascript/
diff --git a/docs/content/en/methods/page/HeadingsFiltered.md b/docs/content/en/methods/page/HeadingsFiltered.md
index 86c989d43..5f01f2c8e 100644
--- a/docs/content/en/methods/page/HeadingsFiltered.md
+++ b/docs/content/en/methods/page/HeadingsFiltered.md
@@ -9,7 +9,7 @@ params:
signatures: [PAGE.HeadingsFiltered]
---
-Use in conjunction with the [`Related`] method on a [`Pages`] object. See [details].
+Use in conjunction with the [`Related`][] method on a [`Pages`][] object. See [details][].
[`Pages`]: /methods/pages/
[`Related`]: /methods/pages/related/
diff --git a/docs/content/en/methods/page/InSection.md b/docs/content/en/methods/page/InSection.md
index b56c92b97..b2b9891c2 100644
--- a/docs/content/en/methods/page/InSection.md
+++ b/docs/content/en/methods/page/InSection.md
@@ -15,7 +15,7 @@ The `InSection` method on a `Page` object reports whether the given page is in t
With this content structure:
-```text
+```tree
content/
├── auctions/
│ ├── 2023-11/
@@ -52,7 +52,7 @@ When rendering the `auction-1` page:
{{ end }}
```
-In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
+In the examples above we are coding defensively using the [`with`][] statement, returning nothing if the page does not exist. By adding an [`else`][] clause we can do some error reporting:
```go-html-template
{{ $path := "/auctions/2023-11" }}
@@ -75,7 +75,7 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj
The result would be wrong when rendering the `auction-1` page because we are comparing the section page to itself.
-> [!note]
+> [!NOTE]
> Use the `$` to get the context passed into the template.
```go-html-template
@@ -84,7 +84,7 @@ The result would be wrong when rendering the `auction-1` page because we are com
{{ end }}
```
-> [!note]
+> [!NOTE]
> Gaining a thorough understanding of context is critical for anyone writing template code.
[`else`]: /functions/go-template/else/
diff --git a/docs/content/en/methods/page/IsAncestor.md b/docs/content/en/methods/page/IsAncestor.md
index 68d56ecbd..87c344102 100644
--- a/docs/content/en/methods/page/IsAncestor.md
+++ b/docs/content/en/methods/page/IsAncestor.md
@@ -11,7 +11,7 @@ params:
With this content structure:
-```text
+```tree
content/
├── auctions/
│ ├── 2023-11/
@@ -48,7 +48,7 @@ When rendering the `auctions` page:
{{ end }}
```
-In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
+In the examples above we are coding defensively using the [`with`][] statement, returning nothing if the page does not exist. By adding an [`else`][] clause we can do some error reporting:
```go-html-template
{{ $path := "/auctions/2023-11" }}
@@ -71,7 +71,7 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj
The result would be wrong when rendering the `auction-1` page because we are comparing the section page to itself.
-> [!note]
+> [!NOTE]
> Use the `$` to get the context passed into the template.
```go-html-template
@@ -80,7 +80,7 @@ The result would be wrong when rendering the `auction-1` page because we are com
{{ end }}
```
-> [!note]
+> [!NOTE]
> Gaining a thorough understanding of context is critical for anyone writing template code.
[`else`]: /functions/go-template/else/
diff --git a/docs/content/en/methods/page/IsBranch.md b/docs/content/en/methods/page/IsBranch.md
new file mode 100644
index 000000000..bc5811878
--- /dev/null
+++ b/docs/content/en/methods/page/IsBranch.md
@@ -0,0 +1,32 @@
+---
+title: IsBranch
+description: Reports whether the given page is a branch.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.IsBranch]
+---
+
+{{< new-in 0.163.0 />}}
+
+{{% glossary-term branch %}}
+
+```tree
+content/
+├── books/
+│ ├── book-1/
+│ │ └── index.md <-- kind = page IsBranch = false
+│ ├── book-2.md <-- kind = page IsBranch = false
+│ └── _index.md <-- kind = section IsBranch = true
+├── tags
+│ ├── fiction
+│ │ └── _index.md <-- kind = term IsBranch = true
+│ └── _index.md <-- kind = taxonomy IsBranch = true
+└── _index.md <-- kind = home IsBranch = true
+```
+
+```go-html-template
+{{ .IsBranch }}
+```
diff --git a/docs/content/en/methods/page/IsDescendant.md b/docs/content/en/methods/page/IsDescendant.md
index 1ccb79196..97dfd1353 100644
--- a/docs/content/en/methods/page/IsDescendant.md
+++ b/docs/content/en/methods/page/IsDescendant.md
@@ -11,7 +11,7 @@ params:
With this content structure:
-```text
+```tree
content/
├── auctions/
│ ├── 2023-11/
@@ -48,7 +48,7 @@ When rendering the `auctions` page:
{{ end }}
```
-In the examples above we are coding defensively using the [`with`] statement, returning nothing if the page does not exist. By adding an [`else`] clause we can do some error reporting:
+In the examples above we are coding defensively using the [`with`][] statement, returning nothing if the page does not exist. By adding an [`else`][] clause we can do some error reporting:
```go-html-template
{{ $path := "/auctions/2023-11" }}
@@ -71,7 +71,7 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj
The result would be wrong when rendering the `auction-1` page because we are comparing the section page to itself.
-> [!note]
+> [!NOTE]
> Use the `$` to get the context passed into the template.
```go-html-template
@@ -80,7 +80,7 @@ The result would be wrong when rendering the `auction-1` page because we are com
{{ end }}
```
-> [!note]
+> [!NOTE]
> Gaining a thorough understanding of context is critical for anyone writing template code.
[`else`]: /functions/go-template/else/
diff --git a/docs/content/en/methods/page/IsHome.md b/docs/content/en/methods/page/IsHome.md
index 66d8180b0..9c7219d86 100644
--- a/docs/content/en/methods/page/IsHome.md
+++ b/docs/content/en/methods/page/IsHome.md
@@ -11,7 +11,7 @@ params:
The `IsHome` method on a `Page` object returns `true` if the [page kind](g) is `home`.
-```text
+```tree
content/
├── books/
│ ├── book-1/
diff --git a/docs/content/en/methods/page/IsMenuCurrent.md b/docs/content/en/methods/page/IsMenuCurrent.md
index 60b68428a..08ddc7407 100644
--- a/docs/content/en/methods/page/IsMenuCurrent.md
+++ b/docs/content/en/methods/page/IsMenuCurrent.md
@@ -23,9 +23,9 @@ aliases: [/functions/ismenucurrent]
{{ end }}
```
-See [menu templates] for a complete example.
+See [menu templates][] for a complete example.
-> [!note]
+> [!NOTE]
> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your project configuration.
[menu templates]: /templates/menu/#example
diff --git a/docs/content/en/methods/page/IsNode.md b/docs/content/en/methods/page/IsNode.md
index 24e7c033e..55f7f7d2c 100644
--- a/docs/content/en/methods/page/IsNode.md
+++ b/docs/content/en/methods/page/IsNode.md
@@ -1,30 +1,15 @@
---
title: IsNode
-description: Reports whether the given page is a node.
+description: Reports whether the given page is a branch.
categories: []
keywords: []
params:
functions_and_methods:
returnType: bool
signatures: [PAGE.IsNode]
+expiryDate: 2028-06-06 # deprecated 2026-06-06 in v0.163.0
---
-The `IsNode` method on a `Page` object checks if the [page kind](g) is one of the following: `home`, `section`, `taxonomy`, or `term`. If it is, the method returns `true`, indicating the page is a [node](g). Otherwise, if the page kind is page, it returns `false`.
-
-```text
-content/
-├── books/
-│ ├── book-1/
-│ │ └── index.md <-- kind = page IsNode = false
-│ ├── book-2.md <-- kind = page IsNode = false
-│ └── _index.md <-- kind = section IsNode = true
-├── tags
-│ ├── fiction
-│ │ └── _index.md <-- kind = term IsNode = true
-│ └── _index.md <-- kind = taxonomy IsNode = true
-└── _index.md <-- kind = home IsNode = true
-```
-
-```go-html-template
-{{ .IsNode }}
-```
+{{< deprecated-in 0.163.0 >}}
+Use the [`IsBranch`](/methods/page/isbranch/) method instead.
+{{< /deprecated-in >}}
diff --git a/docs/content/en/methods/page/IsPage.md b/docs/content/en/methods/page/IsPage.md
index 910a3a7e1..b122fbc27 100644
--- a/docs/content/en/methods/page/IsPage.md
+++ b/docs/content/en/methods/page/IsPage.md
@@ -11,7 +11,7 @@ params:
The `IsPage` method on a `Page` object returns `true` if the [page kind](g) is `page`.
-```text
+```tree
content/
├── books/
│ ├── book-1/
diff --git a/docs/content/en/methods/page/IsSection.md b/docs/content/en/methods/page/IsSection.md
index 7a04fbd8f..17490355d 100644
--- a/docs/content/en/methods/page/IsSection.md
+++ b/docs/content/en/methods/page/IsSection.md
@@ -11,7 +11,7 @@ params:
The `IsSection` method on a `Page` object returns `true` if the [page kind](g) is `section`.
-```text
+```tree
content/
├── books/
│ ├── book-1/
diff --git a/docs/content/en/methods/page/IsTranslated.md b/docs/content/en/methods/page/IsTranslated.md
index a9d12b9fb..1aa554cd1 100644
--- a/docs/content/en/methods/page/IsTranslated.md
+++ b/docs/content/en/methods/page/IsTranslated.md
@@ -29,7 +29,7 @@ weight = 2
And this content:
-```text
+```tree
content/
├── de/
│ ├── books/
diff --git a/docs/content/en/methods/page/Keywords.md b/docs/content/en/methods/page/Keywords.md
index 7c940984e..79bd07375 100644
--- a/docs/content/en/methods/page/Keywords.md
+++ b/docs/content/en/methods/page/Keywords.md
@@ -9,9 +9,7 @@ params:
signatures: [PAGE.Keywords]
---
-By default, Hugo evaluates the keywords when creating collections of [related content].
-
-[related content]: /content-management/related-content/
+By default, Hugo evaluates the keywords when creating collections of [related content][].
{{< code-toggle file=content/recipes/sushi.md fm=true >}}
title = 'How to make spicy tuna hand rolls'
@@ -26,15 +24,13 @@ To list the keywords within a template:
{{ end }}
```
-Or use the [delimit] function:
+Or use the [`delimit`][] function:
```go-html-template
{{ delimit .Keywords ", " ", and " }} → tuna, sriracha, nori, and rice
```
-[delimit]: /functions/collections/delimit/
-
-Keywords are also a useful [taxonomy]:
+Keywords are also a useful [taxonomy][]:
{{< code-toggle file=hugo >}}
[taxonomies]
@@ -43,4 +39,6 @@ keyword = 'keywords'
category = 'categories'
{{< /code-toggle >}}
+[`delimit`]: /functions/collections/delimit/
+[related content]: /content-management/related-content/
[taxonomy]: /content-management/taxonomies/
diff --git a/docs/content/en/methods/page/Kind.md b/docs/content/en/methods/page/Kind.md
index a01877e8c..9cda910a8 100644
--- a/docs/content/en/methods/page/Kind.md
+++ b/docs/content/en/methods/page/Kind.md
@@ -11,7 +11,7 @@ params:
The [page kind](g) is one of `home`, `page`, `section`, `taxonomy`, or `term`.
-```text
+```tree
content/
├── books/
│ ├── book-1/
diff --git a/docs/content/en/methods/page/Language.md b/docs/content/en/methods/page/Language.md
index 0ee7a9284..68cbd88cc 100644
--- a/docs/content/en/methods/page/Language.md
+++ b/docs/content/en/methods/page/Language.md
@@ -11,10 +11,12 @@ params:
The `Language` method on a `Page` object returns the `Language` object for the given page, derived from the language definition in your project configuration.
-You can also use the `Language` method on a `Site` object. See [details][].
+You can also use the `Language` method on a `Site` object. See [details][].
## Methods
+Use these methods on the `Language` object.
+
The examples below assume the following language definition.
{{< code-toggle file=hugo >}}
@@ -25,83 +27,64 @@ locale = 'de-DE'
weight = 2
{{< /code-toggle >}}
-### Direction
+`Direction`
+: {{< new-in 0.158.0 />}}
+: (`string`) Returns the [`direction`][] from the language definition.
-{{< new-in 0.158.0 />}}
+ ```go-html-template
+ {{ .Language.Direction }} → ltr
+ ```
-(`string`) Returns the [`direction`][] from the language definition.
+`IsDefault`
+: {{< new-in 0.153.0 />}}
+: (`bool`) Reports whether this is the [default language](g).
-```go-html-template
-{{ .Language.Direction }} → ltr
-```
+ ```go-html-template
+ {{ .Language.IsDefault }} → true
+ ```
-### IsDefault
+`Label`
+: {{< new-in 0.158.0 />}}
+: (`string`) Returns the [`label`][] from the language definition.
-{{< new-in 0.153.0 />}}
+ ```go-html-template
+ {{ .Language.Label }} → Deutsch
+ ```
-(`bool`) Reports whether this is the [default language](g).
+`Lang`
+: {{An emphasized word
```
-Render with [Pandoc]:
+Render [Pandoc] content to HTML in block display mode:
```go-html-template
{{ $s := "H~2~O" }}
-{{ $opts := dict "markup" "pandoc" }}
+{{ $opts := dict "markup" "pandoc" "display" "block" }}
{{ $s | .RenderString $opts }} → H2O
-
-{{ $opts := dict "display" "block" "markup" "pandoc" }}
-{{ .RenderString $opts $s }} → H2O
```
+[Pandoc]: /content-management/formats/#pandoc
[markup identifier]: /content-management/formats/#classification
-[pandoc]: https://pandoc.org/
diff --git a/docs/content/en/methods/page/Resources.md b/docs/content/en/methods/page/Resources.md
index a99ca2f21..8861ec035 100644
--- a/docs/content/en/methods/page/Resources.md
+++ b/docs/content/en/methods/page/Resources.md
@@ -11,70 +11,66 @@ params:
The `Resources` method on a `Page` object returns a collection of page resources. A page resource is a file within a [page bundle](g).
-To work with global or remote resources, see the [`resources`] functions.
+To work with global or remote resources, see the [`resources`][] functions.
## Methods
-### ByType
+Use these methods on the `Resources` object.
-(`resource.Resources`) Returns a collection of page resources of the given [media type], or nil if none found. The media type is typically one of `image`, `text`, `audio`, `video`, or `application`.
+`ByType`
+: (`resource.Resources`) Returns a collection of page resources of the given [media type][], or nil if none found. The media type is typically one of `image`, `text`, `audio`, `video`, or `application`.
-```go-html-template
-{{ range .Resources.ByType "image" }}
- 
-{{ end }}
-```
+ ```go-html-template
+ {{ range .Resources.ByType "image" }}
+
+ {{ end }}
+ ```
-When working with global resources instead of page resources, use the [`resources.ByType`] function.
+ When working with global resources instead of page resources, use the [`resources.ByType`][] function.
-### Get
+`Get`
+: (`resource.Resource`) Returns a page resource from the given path, or nil if none found.
-(`resource.Resource`) Returns a page resource from the given path, or nil if none found.
+ ```go-html-template
+ {{ with .Resources.Get "images/a.jpg" }}
+
+ {{ end }}
+ ```
-```go-html-template
-{{ with .Resources.Get "images/a.jpg" }}
-
-{{ end }}
-```
+ When working with global resources instead of page resources, use the [`resources.Get`][] function.
-When working with global resources instead of page resources, use the [`resources.Get`] function.
+`GetMatch`
+: (`resource.Resource`) Returns the first page resource from paths matching the given [glob pattern](g), or nil if none found.
-### GetMatch
+ ```go-html-template
+ {{ with .Resources.GetMatch "images/*.jpg" }}
+
+ {{ end }}
+ ```
-(`resource.Resource`) Returns the first page resource from paths matching the given [glob pattern](g), or nil if none found.
+ When working with global resources instead of page resources, use the [`resources.GetMatch`][] function.
-```go-html-template
-{{ with .Resources.GetMatch "images/*.jpg" }}
-
-{{ end }}
-```
+`Match`
+: (`resource.Resources`) Returns a collection of page resources from paths matching the given [glob pattern](g), or nil if none found.
-When working with global resources instead of page resources, use the [`resources.GetMatch`] function.
+ ```go-html-template
+ {{ range .Resources.Match "images/*.jpg" }}
+
+ {{ end }}
+ ```
-### Match
+ When working with global resources instead of page resources, use the [`resources.Match`][] function.
-(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob pattern](g), or nil if none found.
+`Mount`
+: {{< new-in 0.140.0 />}}
+: (`ResourceGetter`) Mounts the given resources from the two arguments base (`string`) to the given target path (`string`) and returns an object that implements [Get](#get). Note that leading slashes in target marks an absolute path. Relative target paths allows you to mount resources relative to another set, e.g. a [Page bundle][]:
-```go-html-template
-{{ range .Resources.Match "images/*.jpg" }}
-
-{{ end }}
-```
+ ```go-html-template
+ {{ $common := resources.Match "/js/headlessui/*.*" }}
+ {{ $importContext := (slice $.Page ($common.Mount "/js/headlessui" ".")) }}
+ ```
-When working with global resources instead of page resources, use the [`resources.Match`] function.
-
-### Mount
-
-{{< new-in 0.140.0 />}}
-
-(`ResourceGetter`) Mounts the given resources from the two arguments base (`string`) to the given target path (`string`) and returns an object that implements [Get](#get). Note that leading slashes in target marks an absolute path. Relative target paths allows you to mount resources relative to another set, e.g. a [Page bundle](/content-management/page-bundles/):
-
-```go-html-template
-{{ $common := resources.Match "/js/headlessui/*.*" }}
-{{ $importContext := (slice $.Page ($common.Mount "/js/headlessui" ".")) }}
-```
-
-This method is currently only useful in [js.Batch](/functions/js/batch/#import-context).
+ This method is currently only useful when using the [`js.Batch`][] function.
## Pattern matching
@@ -82,9 +78,11 @@ With the `GetMatch` and `Match` methods, Hugo determines a match using a case-in
{{% include "/_common/glob-patterns.md" %}}
-[`resources.ByType`]: /functions/resources/ByType/
-[`resources.GetMatch`]: /functions/resources/ByType/
-[`resources.Get`]: /functions/resources/ByType/
-[`resources.Match`]: /functions/resources/ByType/
+[Page bundle]: /content-management/page-bundles/
+[`js.Batch`]: /functions/js/batch/#import-context
+[`resources.ByType`]: /functions/resources/bytype/
+[`resources.GetMatch`]: /functions/resources/getmatch/
+[`resources.Get`]: /functions/resources/get/
+[`resources.Match`]: /functions/resources/match/
[`resources`]: /functions/resources/
[media type]: https://en.wikipedia.org/wiki/Media_type
diff --git a/docs/content/en/methods/page/Scratch.md b/docs/content/en/methods/page/Scratch.md
index 61c5dc19e..1e4c5e650 100644
--- a/docs/content/en/methods/page/Scratch.md
+++ b/docs/content/en/methods/page/Scratch.md
@@ -1,6 +1,6 @@
---
title: Scratch
-description: Returns a "scratch pad" to store and manipulate data, scoped to the current page.
+description: Returns a persistent data structure for storing and manipulating keyed values, scoped to the current page.
categories: []
keywords: []
params:
@@ -11,11 +11,9 @@ expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft)
---
{{< deprecated-in 0.138.0 >}}
-Use the [`PAGE.Store`] method instead.
+Use the [`PAGE.Store`](/methods/page/store/) method instead.
This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `PAGE.Store` as soon as possible.
Beginning with v0.138.0 the `PAGE.Scratch` method is aliased to `PAGE.Store`.
-
-[`PAGE.Store`]: /methods/page/store/
{{< /deprecated-in >}}
diff --git a/docs/content/en/methods/page/Section.md b/docs/content/en/methods/page/Section.md
index 04c6a8a24..58318c5b5 100644
--- a/docs/content/en/methods/page/Section.md
+++ b/docs/content/en/methods/page/Section.md
@@ -13,7 +13,7 @@ params:
With this content structure:
-```text
+```tree
content/
├── lessons/
│ ├── math/
@@ -32,7 +32,7 @@ When rendering lesson-1.md:
In the example above "lessons" is the top-level section.
-The `Section` method is often used with the [`where`] function to build a page collection.
+The `Section` method is often used with the [`where`][] function to build a page collection.
```go-html-template
{{ range where .Site.RegularPages "Section" "lessons" }}
@@ -40,7 +40,7 @@ The `Section` method is often used with the [`where`] function to build a page c
{{ end }}
```
-This is similar to using the [`Type`] method with the `where` function
+This is similar to using the [`Type`][] method with the `where` function
```go-html-template
{{ range where .Site.RegularPages "Type" "lessons" }}
@@ -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/
diff --git a/docs/content/en/methods/page/Sections.md b/docs/content/en/methods/page/Sections.md
index 12f0a8c24..10cd27ebe 100644
--- a/docs/content/en/methods/page/Sections.md
+++ b/docs/content/en/methods/page/Sections.md
@@ -13,7 +13,7 @@ The `Sections` method on a `Page` object is available to these [page kinds](g):
With this content structure:
-```text
+```tree
content/
├── auctions/
│ ├── 2023-11/
diff --git a/docs/content/en/methods/page/Site.md b/docs/content/en/methods/page/Site.md
index 4649e5e00..39a221c55 100644
--- a/docs/content/en/methods/page/Site.md
+++ b/docs/content/en/methods/page/Site.md
@@ -9,10 +9,10 @@ params:
signatures: [PAGE.Site]
---
-See [Site methods].
-
-[Site methods]: /methods/site/
+See [Site methods][].
```go-html-template
{{ .Site.Title }}
```
+
+[Site methods]: /methods/site/
diff --git a/docs/content/en/methods/page/Sitemap.md b/docs/content/en/methods/page/Sitemap.md
index 53f8cae82..f5599cf74 100644
--- a/docs/content/en/methods/page/Sitemap.md
+++ b/docs/content/en/methods/page/Sitemap.md
@@ -9,33 +9,32 @@ params:
signatures: [PAGE.Sitemap]
---
-Access to the `Sitemap` method on a `Page` object is restricted to [sitemap templates].
+Access to the `Sitemap` method on a `Page` object is restricted to [sitemap templates][].
## Methods
-### ChangeFreq
+Use these methods on the `Sitemap` object.
-(`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef).
+`ChangeFreq`
+: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details][changefreqdef].
-```go-html-template
-{{ .Sitemap.ChangeFreq }}
-```
+ ```go-html-template
+ {{ .Sitemap.ChangeFreq }}
+ ```
-### Disable
+`Disable`
+: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
-(`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
+ ```go-html-template
+ {{ .Sitemap.Disable }}
+ ```
-```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][prioritydef].
-### Priority
-
-(`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef).
-
-```go-html-template
-{{ .Sitemap.Priority }}
-```
+ ```go-html-template
+ {{ .Sitemap.Priority }}
+ ```
## Example
@@ -76,4 +75,6 @@ And this simplistic sitemap template:
The change frequency will be `hourly` for the news page, and `monthly` for other pages.
+[changefreqdef]: https://www.sitemaps.org/protocol.html#changefreqdef
+[prioritydef]: https://www.sitemaps.org/protocol.html#prioritydef
[sitemap templates]: /templates/sitemap/
diff --git a/docs/content/en/methods/page/Sites.md b/docs/content/en/methods/page/Sites.md
index 293590bfa..cef0a43d3 100644
--- a/docs/content/en/methods/page/Sites.md
+++ b/docs/content/en/methods/page/Sites.md
@@ -11,5 +11,5 @@ expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
---
{{< deprecated-in 0.156.0 >}}
-Use [`hugo.Sites`](/functions/hugo/sites/) instead.
+Use the [`hugo.Sites`](/functions/hugo/sites/) function instead.
{{< /deprecated-in >}}
diff --git a/docs/content/en/methods/page/Store.md b/docs/content/en/methods/page/Store.md
index c5ad6b316..d48a32192 100644
--- a/docs/content/en/methods/page/Store.md
+++ b/docs/content/en/methods/page/Store.md
@@ -1,6 +1,6 @@
---
title: Store
-description: Returns a "scratch pad" to store and manipulate data, scoped to the current page.
+description: Returns a persistent data structure for storing and manipulating keyed values, scoped to the current page.
categories: []
keywords: []
params:
@@ -10,17 +10,17 @@ params:
aliases: [/functions/store/,/extras/scratch/,/doc/scratch/,/functions/scratch]
---
-Use the `Store` method on a `Page` object to create a [scratch pad](g) to store and manipulate data, scoped to the current page. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
+Use the `Store` method on a `Page` object to create a persistent data structure for storing and manipulating keyed values, scoped to the current page. To create a data structure with a different [scope](g), refer to the [scope](#scope) section below.
{{% include "_common/store-methods.md" %}}
-{{% include "_common/scratch-pad-scope.md" %}}
+{{% include "_common/store-scope.md" %}}
## Determinate values
-The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
+The `Store` method is often used to set values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the stored values are indeterminate 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](g) variable:
+If you need to access a stored 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](g) variable:
```go-html-template
{{ $noop := .Content }}
diff --git a/docs/content/en/methods/page/Summary.md b/docs/content/en/methods/page/Summary.md
index c72a2440d..0a1aae94f 100644
--- a/docs/content/en/methods/page/Summary.md
+++ b/docs/content/en/methods/page/Summary.md
@@ -14,7 +14,7 @@ params:
-You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
+You can define a [summary][] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
To list the pages in a section with a summary beneath each link:
@@ -25,10 +25,10 @@ To list the pages in a section with a summary beneath each link:
{{ end }}
```
-> [!warning]
-> Automatic `.Summary` may cut block tags (e.g., `blockquote`) in the middle, causing the browser to recover the end tag. See [automatic summary] for details and for ways to avoid this.
+> [!WARNING]
+> Automatic `.Summary` may cut block tags (e.g., `blockquote`) in the middle, causing the browser to recover the end tag. See [automatic summary][] for details and for ways to avoid this.
-Depending on content length and how you define the summary, the summary may be equivalent to the content itself. To determine whether the content length exceeds the summary length, use the [`Truncated`] method on a `Page` object. This is useful for conditionally rendering a “read more” link:
+Depending on content length and how you define the summary, the summary may be equivalent to the content itself. To determine whether the content length exceeds the summary length, use the [`Truncated`][] method on a `Page` object. This is useful for conditionally rendering a “read more” link:
```go-html-template
{{ range .Pages }}
@@ -40,9 +40,9 @@ Depending on content length and how you define the summary, the summary may be e
{{ end }}
```
-> [!note]
+> [!NOTE]
> The `Truncated` method returns `false` if you define the summary in front matter.
-[`Truncated`]: /methods/page/truncated
-[summary]: /content-management/summaries/
+[`Truncated`]: /methods/page/truncated/
[automatic summary]: /content-management/summaries/#automatic-summary
+[summary]: /content-management/summaries/
diff --git a/docs/content/en/methods/page/TableOfContents.md b/docs/content/en/methods/page/TableOfContents.md
index d5ae21639..05bcdd7a5 100644
--- a/docs/content/en/methods/page/TableOfContents.md
+++ b/docs/content/en/methods/page/TableOfContents.md
@@ -10,10 +10,7 @@ params:
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.
-
-[atx]: https://spec.commonmark.org/current/#atx-headings
-[setext]: https://spec.commonmark.org/current/#setext-headings
+The `TableOfContents` method on a `Page` object returns an ordered or unordered list of the Markdown [ATX][] and [setext][] headings within the page content.
This template code:
@@ -45,3 +42,6 @@ endLevel = 3
ordered = false
startLevel = 2
{{< /code-toggle >}}
+
+[ATX]: https://spec.commonmark.org/current/#atx-headings
+[setext]: https://spec.commonmark.org/current/#setext-headings
diff --git a/docs/content/en/methods/page/Title.md b/docs/content/en/methods/page/Title.md
index 5135c5ac4..a7cdc9872 100644
--- a/docs/content/en/methods/page/Title.md
+++ b/docs/content/en/methods/page/Title.md
@@ -41,6 +41,6 @@ You can change the capitalization style in your project configuration to one of
titleCaseStyle = "firstupper"
{{< /code-toggle >}}
-See [details].
+See [details][].
[details]: /configuration/all/#title-case-style
diff --git a/docs/content/en/methods/page/TranslationKey.md b/docs/content/en/methods/page/TranslationKey.md
index 3cbcb4acd..8588a8c87 100644
--- a/docs/content/en/methods/page/TranslationKey.md
+++ b/docs/content/en/methods/page/TranslationKey.md
@@ -31,7 +31,7 @@ weight = 2
And this content:
-```text
+```tree
content/
├── de/
│ ├── books/
diff --git a/docs/content/en/methods/page/Translations.md b/docs/content/en/methods/page/Translations.md
index 1310bdab1..76b8e777c 100644
--- a/docs/content/en/methods/page/Translations.md
+++ b/docs/content/en/methods/page/Translations.md
@@ -35,7 +35,7 @@ weight = 3
And this content:
-```text
+```tree
content/
├── de/
│ ├── books/
diff --git a/docs/content/en/methods/page/Truncated.md b/docs/content/en/methods/page/Truncated.md
index 8c2573069..98d02da59 100644
--- a/docs/content/en/methods/page/Truncated.md
+++ b/docs/content/en/methods/page/Truncated.md
@@ -9,9 +9,7 @@ params:
signatures: [PAGE.Truncated]
---
-You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
-
-[summary]: /content-management/summaries/
+You can define a [summary][] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
The `Truncated` method returns `true` if the content length exceeds the summary length. This is useful for conditionally rendering a "read more" link:
@@ -25,5 +23,7 @@ The `Truncated` method returns `true` if the content length exceeds the summary
{{ end }}
```
-> [!note]
+> [!NOTE]
> The `Truncated` method returns `false` if you define the summary in front matter.
+
+[summary]: /content-management/summaries/
diff --git a/docs/content/en/methods/page/Type.md b/docs/content/en/methods/page/Type.md
index 6f855fbe3..623709168 100644
--- a/docs/content/en/methods/page/Type.md
+++ b/docs/content/en/methods/page/Type.md
@@ -13,7 +13,7 @@ The `Type` method on a `Page` object returns the [content type](g) of the given
With this content structure:
-```text
+```tree
content/
├── auction/
│ ├── _index.md
@@ -46,6 +46,6 @@ Hugo renders this to;
Item 2
```
-The `type` field in front matter is also useful for targeting a template. See [details].
+The `type` field in front matter is also useful for targeting a template. See [details][].
[details]: /templates/lookup-order/#target-a-template
diff --git a/docs/content/en/methods/page/WordCount.md b/docs/content/en/methods/page/WordCount.md
index 3950244ca..e14b1982f 100644
--- a/docs/content/en/methods/page/WordCount.md
+++ b/docs/content/en/methods/page/WordCount.md
@@ -13,6 +13,6 @@ params:
{{ .WordCount }} → 103
```
-To round up to nearest multiple of 100, use the [`FuzzyWordCount`] method.
+To round up to nearest multiple of 100, use the [`FuzzyWordCount`][] method.
[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
diff --git a/docs/content/en/methods/pager/PageGroups.md b/docs/content/en/methods/pager/PageGroups.md
index df668ddd2..cc6939b8c 100644
--- a/docs/content/en/methods/pager/PageGroups.md
+++ b/docs/content/en/methods/pager/PageGroups.md
@@ -9,9 +9,7 @@ params:
signatures: [PAGER.PageGroups]
---
-Use the `PageGroups` method with any of the [grouping methods].
-
-[grouping methods]: /quick-reference/page-collections/#group
+Use the `PageGroups` method with any of the [grouping methods][].
```go-html-template
{{ $pages := where site.RegularPages "Type" "posts" }}
@@ -26,3 +24,5 @@ Use the `PageGroups` method with any of the [grouping methods].
{{ partial "pagination.html" . }}
```
+
+[grouping methods]: /quick-reference/page-collections/#group
diff --git a/docs/content/en/methods/pager/PagerSize.md b/docs/content/en/methods/pager/PagerSize.md
index 1bec9e4ea..a16592a4f 100644
--- a/docs/content/en/methods/pager/PagerSize.md
+++ b/docs/content/en/methods/pager/PagerSize.md
@@ -10,10 +10,7 @@ params:
aliases: [/methods/pager/pagesize/]
---
-The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [project configuration].
-
-[`Paginate`]: /methods/page/paginate/
-[project configuration]: /templates/pagination/#configuration
+The number of pages per pager is determined by the optional second argument passed to the [`Paginate`][] method, falling back to the `pagerSize` as defined in your [project configuration][].
```go-html-template
{{ $pages := where site.RegularPages "Type" "posts" }}
@@ -27,3 +24,6 @@ The number of pages per pager is determined by the optional second argument pass
{{ .PagerSize }}
{{ end }}
```
+
+[`Paginate`]: /methods/page/paginate/
+[project configuration]: /templates/pagination/#configuration
diff --git a/docs/content/en/methods/pages/ByDate.md b/docs/content/en/methods/pages/ByDate.md
index 5d1e339a0..4baca8c10 100644
--- a/docs/content/en/methods/pages/ByDate.md
+++ b/docs/content/en/methods/pages/ByDate.md
@@ -9,9 +9,7 @@ params:
signatures: [PAGES.ByDate]
---
-When sorting by date, the value is determined by your [project configuration], defaulting to the `date` field in front matter.
-
-[project configuration]: /configuration/front-matter/#dates
+When sorting by date, the value is determined by your [project configuration][], defaulting to the `date` field in front matter.
```go-html-template
{{ range .Pages.ByDate }}
@@ -26,3 +24,5 @@ To sort in descending order:
{{ .LinkTitle }}
{{ end }}
```
+
+[project configuration]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/pages/ByExpiryDate.md b/docs/content/en/methods/pages/ByExpiryDate.md
index 4f34c6e03..812248a66 100644
--- a/docs/content/en/methods/pages/ByExpiryDate.md
+++ b/docs/content/en/methods/pages/ByExpiryDate.md
@@ -9,9 +9,7 @@ params:
signatures: [PAGES.ByExpiryDate]
---
-When sorting by expiration date, the value is determined by your [project configuration], defaulting to the `expiryDate` field in front matter.
-
-[project configuration]: /configuration/front-matter/#dates
+When sorting by expiration date, the value is determined by your [project configuration][], defaulting to the `expiryDate` field in front matter.
```go-html-template
{{ range .Pages.ByExpiryDate }}
@@ -26,3 +24,5 @@ To sort in descending order:
{{ .LinkTitle }}
{{ end }}
```
+
+[project configuration]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/pages/ByLastmod.md b/docs/content/en/methods/pages/ByLastmod.md
index 7fc865e0a..00098779e 100644
--- a/docs/content/en/methods/pages/ByLastmod.md
+++ b/docs/content/en/methods/pages/ByLastmod.md
@@ -9,9 +9,7 @@ params:
signatures: [PAGES.ByLastmod]
---
-When sorting by last modification date, the value is determined by your [project configuration], defaulting to the `lastmod` field in front matter.
-
-[project configuration]: /configuration/front-matter/#dates
+When sorting by last modification date, the value is determined by your [project configuration][], defaulting to the `lastmod` field in front matter.
```go-html-template
{{ range .Pages.ByLastmod }}
@@ -26,3 +24,5 @@ To sort in descending order:
{{ .LinkTitle }}
{{ end }}
```
+
+[project configuration]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/pages/ByPublishDate.md b/docs/content/en/methods/pages/ByPublishDate.md
index 76d2b2b58..3ba65e8c1 100644
--- a/docs/content/en/methods/pages/ByPublishDate.md
+++ b/docs/content/en/methods/pages/ByPublishDate.md
@@ -9,9 +9,7 @@ params:
signatures: [PAGES.ByPublishDate]
---
-When sorting by publish date, the value is determined by your [project configuration], defaulting to the `publishDate` field in front matter.
-
-[project configuration]: /configuration/front-matter/#dates
+When sorting by publish date, the value is determined by your [project configuration][], defaulting to the `publishDate` field in front matter.
```go-html-template
{{ range .Pages.ByPublishDate }}
@@ -26,3 +24,5 @@ To sort in descending order:
{{ .LinkTitle }}
{{ end }}
```
+
+[project configuration]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/pages/GroupByDate.md b/docs/content/en/methods/pages/GroupByDate.md
index 19f791886..c6413cdfb 100644
--- a/docs/content/en/methods/pages/GroupByDate.md
+++ b/docs/content/en/methods/pages/GroupByDate.md
@@ -9,13 +9,9 @@ params:
signatures: ['PAGES.GroupByDate LAYOUT [SORT]']
---
-When grouping by date, the value is determined by your [project configuration], defaulting to the `date` field in front matter.
+When grouping by date, the value is determined by your [project configuration][], defaulting to the `date` field in front matter.
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
-
-[`time.Format`]: /functions/time/format/
-[layout string]: #layout-string
-[project configuration]: /configuration/front-matter/#dates
+The [layout string](#layout-string) has the same format as the layout string for the [`time.Format`][] function. The resulting group key is [localized](g) for language and region.
{{% include "/_common/methods/pages/group-sort-order.md" %}}
@@ -61,3 +57,6 @@ The pages within each group will also be sorted by date, either ascending or des
## Layout string
{{% include "/_common/time-layout-string.md" %}}
+
+[`time.Format`]: /functions/time/format/
+[project configuration]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/pages/GroupByExpiryDate.md b/docs/content/en/methods/pages/GroupByExpiryDate.md
index 7fe0282c2..3618b901b 100644
--- a/docs/content/en/methods/pages/GroupByExpiryDate.md
+++ b/docs/content/en/methods/pages/GroupByExpiryDate.md
@@ -9,13 +9,9 @@ params:
signatures: ['PAGES.GroupByExpiryDate LAYOUT [SORT]']
---
-When grouping by expiration date, the value is determined by your [project configuration], defaulting to the `expiryDate` field in front matter.
+When grouping by expiration date, the value is determined by your [project configuration][], defaulting to the `expiryDate` field in front matter.
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
-
-[`time.Format`]: /functions/time/format/
-[layout string]: #layout-string
-[project configuration]: /configuration/front-matter/#dates
+The [layout string](#layout-string) has the same format as the layout string for the [`time.Format`][] function. The resulting group key is [localized](g) for language and region.
{{% include "/_common/methods/pages/group-sort-order.md" %}}
@@ -61,3 +57,6 @@ The pages within each group will also be sorted by expiration date, either ascen
## Layout string
{{% include "/_common/time-layout-string.md" %}}
+
+[`time.Format`]: /functions/time/format/
+[project configuration]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/pages/GroupByLastmod.md b/docs/content/en/methods/pages/GroupByLastmod.md
index 45da5af31..4c79de5e4 100644
--- a/docs/content/en/methods/pages/GroupByLastmod.md
+++ b/docs/content/en/methods/pages/GroupByLastmod.md
@@ -9,13 +9,9 @@ params:
signatures: ['PAGES.GroupByLastmod LAYOUT [SORT]']
---
-When grouping by last modification date, the value is determined by your [project configuration], defaulting to the `lastmod` field in front matter.
+When grouping by last modification date, the value is determined by your [project configuration][], defaulting to the `lastmod` field in front matter.
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
-
-[`time.Format`]: /functions/time/format/
-[layout string]: #layout-string
-[project configuration]: /configuration/front-matter/#dates
+The [layout string](#layout-string) has the same format as the layout string for the [`time.Format`][] function. The resulting group key is [localized](g) for language and region.
{{% include "/_common/methods/pages/group-sort-order.md" %}}
@@ -61,3 +57,6 @@ The pages within each group will also be sorted by last modification date, eithe
## Layout string
{{% include "/_common/time-layout-string.md" %}}
+
+[`time.Format`]: /functions/time/format/
+[project configuration]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/pages/GroupByParamDate.md b/docs/content/en/methods/pages/GroupByParamDate.md
index b05a096d2..3c0811ccf 100644
--- a/docs/content/en/methods/pages/GroupByParamDate.md
+++ b/docs/content/en/methods/pages/GroupByParamDate.md
@@ -9,10 +9,7 @@ params:
signatures: ['PAGES.GroupByParamDate PARAM LAYOUT [SORT]']
---
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
-
-[`time.Format`]: /functions/time/format/
-[layout string]: #layout-string
+The [layout string](#layout-string) has the same format as the layout string for the [`time.Format`][] function. The resulting group key is [localized](g) for language and region.
{{% include "/_common/methods/pages/group-sort-order.md" %}}
@@ -58,3 +55,5 @@ The pages within each group will also be sorted by the parameter date, either as
## Layout string
{{% include "/_common/time-layout-string.md" %}}
+
+[`time.Format`]: /functions/time/format/
diff --git a/docs/content/en/methods/pages/GroupByPublishDate.md b/docs/content/en/methods/pages/GroupByPublishDate.md
index 629a8480a..b47df3cce 100644
--- a/docs/content/en/methods/pages/GroupByPublishDate.md
+++ b/docs/content/en/methods/pages/GroupByPublishDate.md
@@ -9,13 +9,9 @@ params:
signatures: ['PAGES.GroupByPublishDate LAYOUT [SORT]']
---
-When grouping by publish date, the value is determined by your [project configuration], defaulting to the `publishDate` field in front matter.
+When grouping by publish date, the value is determined by your [project configuration][], defaulting to the `publishDate` field in front matter.
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
-
-[`time.Format`]: /functions/time/format/
-[layout string]: #layout-string
-[project configuration]: /configuration/front-matter/#dates
+The [layout string](#layout-string) has the same format as the layout string for the [`time.Format`][] function. The resulting group key is [localized](g) for language and region.
{{% include "/_common/methods/pages/group-sort-order.md" %}}
@@ -61,3 +57,6 @@ The pages within each group will also be sorted by publish date, either ascendin
## Layout string
{{% include "/_common/time-layout-string.md" %}}
+
+[`time.Format`]: /functions/time/format/
+[project configuration]: /configuration/front-matter/#dates
diff --git a/docs/content/en/methods/pages/Related.md b/docs/content/en/methods/pages/Related.md
index 6d3859560..a20b8c213 100644
--- a/docs/content/en/methods/pages/Related.md
+++ b/docs/content/en/methods/pages/Related.md
@@ -11,7 +11,7 @@ params:
- PAGES.Related OPTIONS
---
-Based on front matter, Hugo uses several factors to identify content related to the given page. Use the default [related content configuration], or tune the results to the desired indices and parameters. See [details].
+Based on front matter, Hugo uses several factors to identify content related to the given page. Use the default [related content configuration][], or tune the results to the desired indices and parameters. See [details][].
The argument passed to the `Related` method may be a `Page` or an options map. For example, to pass the current page:
@@ -45,18 +45,16 @@ To pass an options map:
## Options
-indices
+`indices`
: (`slice`) The indices to search within.
-document
+`document`
: (`page`) The page for which to find related content. Required when specifying an options map.
-namedSlices
-: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function.
+`namedSlices`
+: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`][] function.
-[`keyVals`]: /functions/collections/keyvals/
-
-fragments
+`fragments`
: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment](g) identifiers of the documents.
A contrived example using all of the above:
@@ -71,5 +69,6 @@ A contrived example using all of the above:
}}
```
+[`keyVals`]: /functions/collections/keyvals/
[details]: /content-management/related-content/
[related content configuration]: /configuration/related-content/
diff --git a/docs/content/en/methods/resource/Colors.md b/docs/content/en/methods/resource/Colors.md
index b2490688e..104295efc 100644
--- a/docs/content/en/methods/resource/Colors.md
+++ b/docs/content/en/methods/resource/Colors.md
@@ -13,7 +13,7 @@ params:
The `Colors` method returns a slice of the most dominant colors in a [processable image](g), ordered from most dominant to least dominant.
-> [!note]
+> [!NOTE]
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
## Usage
@@ -24,15 +24,13 @@ This method is fast, but if you downscale your image first, you can further impr
Each color in the slice is an object with the following methods:
-### ColorHex
+`ColorHex`
+: (`string`) Returns the [hexadecimal color][] value, prefixed with a hash sign.
-(`string`) Returns the [hexadecimal color][] value, prefixed with a hash sign.
+`Luminance`
+: (`float64`) Returns the [relative luminance][] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.
-### Luminance
-
-(`float64`) Returns the [relative luminance][] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.
-
-> [!note]
+> [!NOTE]
> Image filters such as [`images.Dither`][], [`images.Padding`][], and [`images.Text`][] accept either hexadecimal color values or `images.Color` objects as arguments. Hugo renders an `images.Color` object as a hexadecimal color value.
## Sorting
diff --git a/docs/content/en/methods/resource/Content.md b/docs/content/en/methods/resource/Content.md
index ff2ad6de8..b3f445eb9 100644
--- a/docs/content/en/methods/resource/Content.md
+++ b/docs/content/en/methods/resource/Content.md
@@ -11,9 +11,7 @@ params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Content` method on a `Resource` object returns `template.HTML` when the [resource type] is `page`, otherwise it returns a `string`.
-
-[resource type]: /methods/resource/resourcetype/
+The `Content` method on a `Resource` object returns `template.HTML` when the [resource type][] is `page`, otherwise it returns a `string`.
```text {file="assets/quotations/kipling.txt"}
He travels the fastest who travels alone.
@@ -58,3 +56,5 @@ To create inline JavaScript:
{{ end }}
```
+
+[resource type]: /methods/resource/resourcetype/
diff --git a/docs/content/en/methods/resource/Crop.md b/docs/content/en/methods/resource/Crop.md
index e764be167..4cbed6ca4 100644
--- a/docs/content/en/methods/resource/Crop.md
+++ b/docs/content/en/methods/resource/Crop.md
@@ -11,9 +11,9 @@ params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Crop` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+The `Crop` method returns a new resource from a [processable image](g) according to the given [processing specification](#processing-specification).
-> [!note]
+> [!NOTE]
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
## Usage
@@ -51,4 +51,3 @@ In the example above, `"200x200 TopRight"` is the processing specification.
>}}
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
-[processing specification]: #processing-specification
diff --git a/docs/content/en/methods/resource/Data.md b/docs/content/en/methods/resource/Data.md
index 01b22823d..4d6dbd157 100644
--- a/docs/content/en/methods/resource/Data.md
+++ b/docs/content/en/methods/resource/Data.md
@@ -9,7 +9,7 @@ params:
signatures: [RESOURCE.Data]
---
-The `Data` method on a resource returned by the [`resources.GetRemote`] function returns information from the HTTP response.
+The `Data` method on a resource returned by the [`resources.GetRemote`][] function returns information from the HTTP response.
## Example
@@ -36,29 +36,25 @@ The `Data` method on a resource returned by the [`resources.GetRemote`] function
## Methods
-### ContentLength
+Use these methods on the `Data` object.
-(`int`) The content length in bytes.
+`ContentLength`
+: (`int`) The content length in bytes.
-### ContentType
+`ContentType`
+: (`string`) The content type.
-(`string`) The content type.
+`Headers`
+: (`map[string][]string`) A map of response headers matching those requested in the [`responseHeaders`][] option passed to the `resources.GetRemote` function. The header name matching is case-insensitive. In most cases there will be one value per header key.
-### Headers
+`Status`
+: (`string`) The HTTP status text.
-(`map[string][]string`) A map of response headers matching those requested in the [`responseHeaders`] option passed to the `resources.GetRemote` function. The header name matching is case-insensitive. In most cases there will be one value per header key.
+`StatusCode`
+: (`int`) The HTTP status code.
-### Status
-
-(`string`) The HTTP status text.
-
-### StatusCode
-
-(`int`) The HTTP status code.
-
-### TransferEncoding
-
-(`string`) The transfer encoding.
+`TransferEncoding`
+: (`string`) The transfer encoding.
[`resources.GetRemote`]: /functions/resources/getremote/
[`responseHeaders`]: /functions/resources/getremote/#responseheaders
diff --git a/docs/content/en/methods/resource/Err.md b/docs/content/en/methods/resource/Err.md
index aa0d076b1..cabaf20fb 100644
--- a/docs/content/en/methods/resource/Err.md
+++ b/docs/content/en/methods/resource/Err.md
@@ -11,7 +11,5 @@ expiryDate: 2027-01-16 # deprecated 2025-01-16 in v0.141.0
---
{{< deprecated-in 0.141.0 >}}
-Use the `try` statement instead. See [example].
-
-[example]: /functions/go-template/try/#example
+Use the [`try`](/functions/go-template/try/) statement instead.
{{< /deprecated-in >}}
diff --git a/docs/content/en/methods/resource/Exif.md b/docs/content/en/methods/resource/Exif.md
index bc060f4c9..3ec7a33c8 100644
--- a/docs/content/en/methods/resource/Exif.md
+++ b/docs/content/en/methods/resource/Exif.md
@@ -11,5 +11,5 @@ expiryDate: 2028-01-28 # deprecated 2026-01-28 in v0.155.0
---
{{< deprecated-in 0.155.0 >}}
-Use [`Meta`](/methods/resource/meta/) instead.
+Use the [`Meta`](/methods/resource/meta/) method instead.
{{< /deprecated-in >}}
diff --git a/docs/content/en/methods/resource/Fill.md b/docs/content/en/methods/resource/Fill.md
index c510afe6d..63b47a5a0 100644
--- a/docs/content/en/methods/resource/Fill.md
+++ b/docs/content/en/methods/resource/Fill.md
@@ -11,9 +11,9 @@ params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Fill` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+The `Fill` method returns a new resource from a [processable image](g) according to the given [processing specification](#processing-specification).
-> [!note]
+> [!NOTE]
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
## Usage
@@ -51,4 +51,3 @@ In the example above, `"500x200 TopRight"` is the _processing specification.
>}}
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
-[processing specification]: #processing-specification
diff --git a/docs/content/en/methods/resource/Filter.md b/docs/content/en/methods/resource/Filter.md
index 812466a55..291b74721 100644
--- a/docs/content/en/methods/resource/Filter.md
+++ b/docs/content/en/methods/resource/Filter.md
@@ -14,7 +14,7 @@ params:
The `Filter` method returns a new resource from a [processable image](g) after applying one or more [image filters](#image-filters).
-> [!note]
+> [!NOTE]
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
## Usage
diff --git a/docs/content/en/methods/resource/Fit.md b/docs/content/en/methods/resource/Fit.md
index 2c0a7c91c..fe82075d1 100644
--- a/docs/content/en/methods/resource/Fit.md
+++ b/docs/content/en/methods/resource/Fit.md
@@ -11,9 +11,9 @@ params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Fit` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+The `Fit` method returns a new resource from a [processable image](g) according to the given [processing specification](#processing-specification).
-> [!note]
+> [!NOTE]
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
## Usage
@@ -53,4 +53,3 @@ In the example above, `"300x175"` is the processing specification.
[`Fill`]: /methods/resource/fill/
[`Resize`]: /methods/resource/resize/
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
-[processing specification]: #processing-specification
diff --git a/docs/content/en/methods/resource/MediaType.md b/docs/content/en/methods/resource/MediaType.md
index 7721f69ba..19f304238 100644
--- a/docs/content/en/methods/resource/MediaType.md
+++ b/docs/content/en/methods/resource/MediaType.md
@@ -11,56 +11,20 @@ params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `MediaType` method on a `Resource` object returns an object with additional methods.
-
-## Methods
-
-### Type
-
-(`string`) The resource's media type.
+## Example
```go-html-template
{{ with resources.Get "images/a.jpg" }}
{{ .MediaType.Type }} → image/jpeg
-{{ end }}
-```
-
-### MainType
-
-(`string`) The main type of the resource's media type.
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
{{ .MediaType.MainType }} → image
-{{ end }}
-```
-
-### SubType
-
-(`string`) The subtype of the resource's media type. This may or may not correspond to the file suffix.
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
{{ .MediaType.SubType }} → jpeg
-{{ end }}
-```
-
-### Suffixes
-
-(`slice`) A slice of possible file suffixes for the resource's media type.
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
{{ .MediaType.Suffixes }} → [jpg jpeg jpe jif jfif]
-{{ end }}
-```
-
-### FirstSuffix.Suffix
-
-(`string`) The first of the possible file suffixes for the resource's media type.
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
{{ .MediaType.FirstSuffix.Suffix }} → jpg
{{ end }}
```
+
+## Methods
+
+Use these methods on the `MediaType` object.
+
+{{% include "/_common/methods/media-type/core-methods.md" %}}
diff --git a/docs/content/en/methods/resource/Meta.md b/docs/content/en/methods/resource/Meta.md
index 8a992ba72..fa369fbbd 100644
--- a/docs/content/en/methods/resource/Meta.md
+++ b/docs/content/en/methods/resource/Meta.md
@@ -13,11 +13,11 @@ params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Meta` method on an image `Resource` object returns an object containing [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata.
+The `Meta` method on an image `Resource` object returns an object containing [Exif][], [IPTC][], and [XMP][] metadata.
While Hugo classifies many file types as images, only certain formats support metadata extraction. Supported formats include AVIF, BMP, GIF, HEIC, HEIF, JPEG, PNG, TIFF, and WebP.
-> [!note]
+> [!NOTE]
> Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from supported formats.
## Usage
@@ -36,48 +36,42 @@ Use the [`reflect.IsImageResourceWithMeta`][] function to verify that a resource
## Methods
-### Date
+Use these methods on the `Meta` object.
-(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`][] function.
+`Date`
+: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`][] function.
-### Lat
+`Lat`
+: (`float64`) Returns the GPS latitude in degrees from Exif metadata, with a fallback to XMP metadata.
-(`float64`) Returns the GPS latitude in degrees from Exif metadata, with a fallback to XMP metadata.
+`Long`
+: (`float64`) Returns the GPS longitude in degrees from Exif metadata, with a fallback to XMP metadata.
-### Long
+`Orientation`
+: (`int`) Returns the value of the Exif `Orientation` tag, one of eight possible values.
-(`float64`) Returns the GPS longitude in degrees from Exif metadata, with a fallback to XMP metadata.
+ Value|Description
+ :--|:--
+ `1`|Horizontal (normal)
+ `2`|Mirrored horizontal
+ `3`|Rotated 180 degrees
+ `4`|Mirrored vertical
+ `5`|Mirrored horizontal and rotated 270 degrees clockwise
+ `6`|Rotated 90 degrees clockwise
+ `7`|Mirrored horizontal and rotated 90 degrees clockwise
+ `8`|Rotated 270 degrees clockwise
-### Orientation
+ > [!TIP]
+ > Use the [`images.AutoOrient`][] image filter to rotate and flip an image as needed per its Exif orientation tag
-(`int`) Returns the value of the Exif `Orientation` tag, one of eight possible values.
+`Exif`
+: (`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
-Value|Description
-:--|:--
-`1`|Horizontal (normal)
-`2`|Mirrored horizontal
-`3`|Rotated 180 degrees
-`4`|Mirrored vertical
-`5`|Mirrored horizontal and rotated 270 degrees clockwise
-`6`|Rotated 90 degrees clockwise
-`7`|Mirrored horizontal and rotated 90 degrees clockwise
-`8`|Rotated 270 degrees clockwise
-{class="!mt-0"}
+`IPTC`
+: (`meta.Tags`) Returns a collection of available IPTC fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
-> [!tip]
-> Use the [`images.AutoOrient`][] image filter to rotate and flip an image as needed per its Exif orientation tag
-
-### Exif
-
-(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
-
-### IPTC
-
-(`meta.Tags`) Returns a collection of available IPTC fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
-
-### XMP
-
-(`meta.Tags`) Returns a collection of available XMP fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
+`XMP`
+: (`meta.Tags`) Returns a collection of available XMP fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
## Examples
@@ -100,11 +94,11 @@ To list the creation date, latitude, longitude, and orientation:
{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
+[Exif]: https://en.wikipedia.org/wiki/Exif
+[IPTC]: https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model
+[XMP]: https://en.wikipedia.org/wiki/Extensible_Metadata_Platform
[`fields`]: /configuration/imaging/#fields
[`images.AutoOrient`]: /functions/images/autoorient/
[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
[`sources`]: /configuration/imaging/#sources
[`time.Format`]: /functions/time/format/
-[Exif_Definition]: https://en.wikipedia.org/wiki/Exif
-[IPTC_Definition]: https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model
-[XMP_Definition]: https://en.wikipedia.org/wiki/Extensible_Metadata_Platform
diff --git a/docs/content/en/methods/resource/Name.md b/docs/content/en/methods/resource/Name.md
index 3331bb50d..1f4b762bd 100644
--- a/docs/content/en/methods/resource/Name.md
+++ b/docs/content/en/methods/resource/Name.md
@@ -15,7 +15,7 @@ The value returned by the `Name` method on a `Resource` object depends on the re
With a [global resource](g), the `Name` method returns the path to the resource, relative to the `assets` directory.
-```text
+```tree
assets/
└── images/
└── Sunrise in Bryce Canyon.jpg
@@ -31,7 +31,7 @@ assets/
With a [page resource](g), if you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter.
-```text
+```tree
content/
├── example/
│ ├── images/
@@ -63,7 +63,7 @@ You can also capture the image by specifying its `name` instead of its path:
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
+```tree
content/
├── example/
│ ├── images/
diff --git a/docs/content/en/methods/resource/Params.md b/docs/content/en/methods/resource/Params.md
index 38f2ef6c2..2aa65b1f3 100644
--- a/docs/content/en/methods/resource/Params.md
+++ b/docs/content/en/methods/resource/Params.md
@@ -13,7 +13,7 @@ Use the `Params` method with [page resources](g). It is not applicable to either
With this content structure:
-```text
+```tree
content/
├── posts/
│ ├── cats/
@@ -56,6 +56,6 @@ Hugo renders:
```
-See the [page resources] section for more information.
+See the [page resources][] section for more information.
[page resources]: /content-management/page-resources/
diff --git a/docs/content/en/methods/resource/Process.md b/docs/content/en/methods/resource/Process.md
index 9edb086e0..93cebcb72 100644
--- a/docs/content/en/methods/resource/Process.md
+++ b/docs/content/en/methods/resource/Process.md
@@ -12,9 +12,9 @@ params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Process` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+The `Process` method returns a new resource from a [processable image](g) according to the given [processing specification](#processing-specification).
-> [!note]
+> [!NOTE]
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
## Usage
@@ -67,4 +67,3 @@ The `Process` method is also available as a filter. This is more effective if yo
[`Resize`]: /methods/resource/resize/
[`images.Process`]: /functions/images/process/
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
-[processing specification]: #processing-specification
diff --git a/docs/content/en/methods/resource/Resize.md b/docs/content/en/methods/resource/Resize.md
index f1e08dbaf..743ed7411 100644
--- a/docs/content/en/methods/resource/Resize.md
+++ b/docs/content/en/methods/resource/Resize.md
@@ -11,9 +11,9 @@ params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Resize` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+The `Resize` method returns a new resource from a [processable image](g) according to the given [processing specification](#processing-specification).
-> [!note]
+> [!NOTE]
> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
## Usage
@@ -53,4 +53,3 @@ In the example above, `"300x"` is the processing specification.
>}}
[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
-[processing specification]: #processing-specification
diff --git a/docs/content/en/methods/resource/ResourceType.md b/docs/content/en/methods/resource/ResourceType.md
index 70dc59108..514a1b76f 100644
--- a/docs/content/en/methods/resource/ResourceType.md
+++ b/docs/content/en/methods/resource/ResourceType.md
@@ -22,7 +22,7 @@ Common resource types include `audio`, `image`, `text`, and `video`.
When working with content files, the resource type is `page`.
-```text
+```tree
content/
├── lessons/
│ ├── lesson-1/
diff --git a/docs/content/en/methods/resource/Title.md b/docs/content/en/methods/resource/Title.md
index c02d29ff8..672343d8f 100644
--- a/docs/content/en/methods/resource/Title.md
+++ b/docs/content/en/methods/resource/Title.md
@@ -15,7 +15,7 @@ The value returned by the `Title` method on a `Resource` object depends on the r
With a [global resource](g), the `Title` method returns the path to the resource, relative to the `assets` directory.
-```text
+```tree
assets/
└── images/
└── Sunrise in Bryce Canyon.jpg
@@ -31,7 +31,7 @@ assets/
With a [page resource](g), if you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter.
-```text
+```tree
content/
├── example/
│ ├── images/
@@ -55,7 +55,7 @@ title = 'A beautiful sunrise in Bryce Canyon'
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
+```tree
content/
├── example/
│ ├── images/
diff --git a/docs/content/en/methods/shortcode/Get.md b/docs/content/en/methods/shortcode/Get.md
index aef9987f0..bf7c94c50 100644
--- a/docs/content/en/methods/shortcode/Get.md
+++ b/docs/content/en/methods/shortcode/Get.md
@@ -11,14 +11,14 @@ params:
Specify the argument by position or by name. When calling a shortcode within Markdown, use either positional or named argument, but not both.
-> [!note]
+> [!NOTE]
> Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details.
## Positional arguments
This shortcode call uses positional arguments:
-```text {file="content/about.md"}
+```md {file="content/about.md"}
{{}}
```
@@ -32,7 +32,7 @@ To retrieve arguments by position:
This shortcode call uses named arguments:
-```text {file="content/about.md"}
+```md {file="content/about.md"}
{{}}
```
@@ -42,5 +42,5 @@ To retrieve arguments by name:
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
```
-> [!note]
+> [!NOTE]
> Argument names are case-sensitive.
diff --git a/docs/content/en/methods/shortcode/Inner.md b/docs/content/en/methods/shortcode/Inner.md
index bb5a16a01..5a2029942 100644
--- a/docs/content/en/methods/shortcode/Inner.md
+++ b/docs/content/en/methods/shortcode/Inner.md
@@ -11,7 +11,7 @@ params:
This content:
-```text {file="content/services.md"}
+```md {file="content/services.md"}
{{}}
We design the **best** widgets in the world.
{{}}
@@ -41,15 +41,15 @@ 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 [`strings.TrimSpace`] function as shown above to remove carriage returns and newlines.
+> [!NOTE]
+> Content between opening and closing shortcode tags may include leading and/or trailing newlines, depending on placement within the Markdown. Use the [`strings.TrimSpace`][] function as shown above to remove carriage returns and newlines.
-> [!note]
+> [!NOTE]
> In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML.
## Use RenderString
-Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object:
+Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`][] method on the `Page` object:
```go-html-template {file="layouts/_shortcodes/card.html"}
@@ -73,13 +73,13 @@ Hugo renders this to:
```
-You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See [details].
+You can use the [`markdownify`][] function instead of the `RenderString` method, but the latter is more flexible. See [details][].
## Alternative notation
Instead of calling the shortcode with the `{{}}` notation, use the `{{%/* */%}}` notation:
-```text {file="content/services.md"}
+```md {file="content/services.md"}
{{%/* card title="Product Design" */%}}
We design the **best** widgets in the world.
{{%/* /card */%}}
@@ -94,9 +94,9 @@ First, configure the renderer to allow raw HTML within Markdown:
unsafe = true
{{< /code-toggle >}}
-This configuration is not unsafe if _you_ control the content. Read more about Hugo's [security model].
+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.
```go-html-template {file="layouts/_shortcodes/card.html"}
@@ -129,15 +129,15 @@ The difference between this and the previous example is subtle but required. Not
```
-> [!note]
-> Don't process the `Inner` value with `RenderString` or `markdownify` when using [Markdown notation] to call the shortcode.
+> [!NOTE]
+> Don't process the `Inner` value with `RenderString` or `markdownify` when using [Markdown notation][] to call the shortcode.
-[`markdownify`]: /functions/transform/markdownify/
-[`RenderString`]: /methods/page/renderstring/
-[`strings.TrimSpace`]: /functions/strings/trimspace/
[CommonMark]: https://spec.commonmark.org/current/
+[Markdown notation]: /content-management/shortcodes/#notation
+[`RenderString`]: /methods/page/renderstring/
+[`markdownify`]: /functions/transform/markdownify/
+[`strings.TrimSpace`]: /functions/strings/trimspace/
[details]: /methods/page/renderstring/
[indentation]: https://spec.commonmark.org/current/#indented-code-blocks
-[Markdown notation]: /content-management/shortcodes/#notation
[raw HTML blocks]: https://spec.commonmark.org/current/#html-blocks
[security model]: /about/security/
diff --git a/docs/content/en/methods/shortcode/InnerDeindent.md b/docs/content/en/methods/shortcode/InnerDeindent.md
index 3d7536b6b..f09d9bd80 100644
--- a/docs/content/en/methods/shortcode/InnerDeindent.md
+++ b/docs/content/en/methods/shortcode/InnerDeindent.md
@@ -9,13 +9,13 @@ params:
signatures: [SHORTCODE.InnerDeindent]
---
-Similar to the [`Inner`] method, `InnerDeindent` returns the content between opening and closing shortcode tags. However, with `InnerDeindent`, indentation before the content is removed.
+Similar to the [`Inner`][] method, `InnerDeindent` returns the content between opening and closing shortcode tags. However, with `InnerDeindent`, indentation before the content is removed.
-This allows us to effectively bypass the rules governing [indentation] as provided in the [CommonMark] specification.
+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:
-```text {file="content/about.md"}
+```md {file="content/about.md"}
- Gallery one
{{}}
@@ -93,6 +93,5 @@ Hugo renders the Markdown to:
```
-[commonmark]: https://commonmark.org/
-[indentation]: https://spec.commonmark.org/current/#indented-code-blocks
+[CommonMark]: https://spec.commonmark.org/current/#indented-code-blocks
[`Inner`]: /methods/shortcode/inner/
diff --git a/docs/content/en/methods/shortcode/IsNamedParams.md b/docs/content/en/methods/shortcode/IsNamedParams.md
index 0574128ec..4cc1ae91e 100644
--- a/docs/content/en/methods/shortcode/IsNamedParams.md
+++ b/docs/content/en/methods/shortcode/IsNamedParams.md
@@ -23,7 +23,7 @@ With this _shortcode_ template:
Both of these calls return the same value:
-```text {file="content/about.md"}
+```md {file="content/about.md"}
{{}}
{{}}
```
diff --git a/docs/content/en/methods/shortcode/Ordinal.md b/docs/content/en/methods/shortcode/Ordinal.md
index b16758952..501365af3 100644
--- a/docs/content/en/methods/shortcode/Ordinal.md
+++ b/docs/content/en/methods/shortcode/Ordinal.md
@@ -11,12 +11,12 @@ params:
The `Ordinal` method returns the zero-based ordinal of the shortcode in relation to its parent. If the parent is the page itself, the ordinal represents the position of this shortcode in the page content.
-> [!note]
+> [!NOTE]
> Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page.
This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example:
-```text {file="content/about.md"}
+```md {file="content/about.md"}
{{}}
{{}}
@@ -46,7 +46,7 @@ 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.
+> [!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/
diff --git a/docs/content/en/methods/shortcode/Page.md b/docs/content/en/methods/shortcode/Page.md
index 0fa1c9cc9..f979e34c6 100644
--- a/docs/content/en/methods/shortcode/Page.md
+++ b/docs/content/en/methods/shortcode/Page.md
@@ -20,7 +20,7 @@ isbn = '978-0451419439'
Calling this shortcode:
-```text
+```md
{{}}
```
diff --git a/docs/content/en/methods/shortcode/Params.md b/docs/content/en/methods/shortcode/Params.md
index c8252f5b1..5c5e02340 100644
--- a/docs/content/en/methods/shortcode/Params.md
+++ b/docs/content/en/methods/shortcode/Params.md
@@ -11,7 +11,7 @@ params:
When you call a shortcode using positional arguments, the `Params` method returns a slice.
-```text {file="content/about.md"}
+```md {file="content/about.md"}
{{}}
```
@@ -22,7 +22,7 @@ When you call a shortcode using positional arguments, the `Params` method return
When you call a shortcode using named arguments, the `Params` method returns a map.
-```text {file="content/about.md"}
+```md {file="content/about.md"}
{{}}
```
diff --git a/docs/content/en/methods/shortcode/Parent.md b/docs/content/en/methods/shortcode/Parent.md
index 4597d1034..38e1ba954 100644
--- a/docs/content/en/methods/shortcode/Parent.md
+++ b/docs/content/en/methods/shortcode/Parent.md
@@ -13,7 +13,7 @@ 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.
-```text {file="content/welcome.md"}
+```md {file="content/welcome.md"}
{{}}
Welcome. Today is {{}}.
{{}}
diff --git a/docs/content/en/methods/shortcode/Position.md b/docs/content/en/methods/shortcode/Position.md
index 4052a735b..3b00249e5 100644
--- a/docs/content/en/methods/shortcode/Position.md
+++ b/docs/content/en/methods/shortcode/Position.md
@@ -26,5 +26,5 @@ In the absence of a "greeting" argument, Hugo will throw an error message and fa
ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
```
-> [!note]
+> [!NOTE]
> The position can be expensive to calculate. Limit its use to error reporting.
diff --git a/docs/content/en/methods/shortcode/Ref.md b/docs/content/en/methods/shortcode/Ref.md
index 3a877d568..2e172d07e 100644
--- a/docs/content/en/methods/shortcode/Ref.md
+++ b/docs/content/en/methods/shortcode/Ref.md
@@ -11,7 +11,7 @@ params:
## Usage
-The `Ref` method accepts a single argument: an options map.
+The `Ref` method requires a single argument: an options map.
## Options
diff --git a/docs/content/en/methods/shortcode/RelRef.md b/docs/content/en/methods/shortcode/RelRef.md
index 273705a95..92e634837 100644
--- a/docs/content/en/methods/shortcode/RelRef.md
+++ b/docs/content/en/methods/shortcode/RelRef.md
@@ -11,7 +11,7 @@ params:
## Usage
-The `RelRef` method accepts a single argument: an options map.
+The `RelRef` method requires a single argument: an options map.
## Options
diff --git a/docs/content/en/methods/shortcode/Scratch.md b/docs/content/en/methods/shortcode/Scratch.md
index 6efec2097..30304a568 100644
--- a/docs/content/en/methods/shortcode/Scratch.md
+++ b/docs/content/en/methods/shortcode/Scratch.md
@@ -1,6 +1,6 @@
---
title: Scratch
-description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode.
+description: Returns a persistent data structure for storing and manipulating keyed values, scoped to the current shortcode.
categories: []
keywords: []
params:
@@ -11,11 +11,9 @@ expiryDate: 2026-11-18 # deprecated 2024-11-18 (soft)
---
{{< deprecated-in 0.139.0 >}}
-Use the [`SHORTCODE.Store`] method instead.
+Use the [`SHORTCODE.Store`](/methods/shortcode/store/) method instead.
This is a soft deprecation. This method will be removed in a future release, but the removal date has not been established. Although Hugo will not emit a warning if you continue to use this method, you should begin using `SHORTCODE.Store` as soon as possible.
Beginning with v0.139.0 the `SHORTCODE.Scratch` method is aliased to `SHORTCODE.Store`.
-
-[`SHORTCODE.Store`]: /methods/shortcode/store/
{{< /deprecated-in >}}
diff --git a/docs/content/en/methods/shortcode/Site.md b/docs/content/en/methods/shortcode/Site.md
index 4c5a9a9b5..bfffff4ef 100644
--- a/docs/content/en/methods/shortcode/Site.md
+++ b/docs/content/en/methods/shortcode/Site.md
@@ -9,10 +9,10 @@ params:
signatures: [SHORTCODE.Site]
---
-See [Site methods].
-
-[Site methods]: /methods/site/
+See [Site methods][].
```go-html-template
{{ .Site.Title }}
```
+
+[Site methods]: /methods/site/
diff --git a/docs/content/en/methods/shortcode/Store.md b/docs/content/en/methods/shortcode/Store.md
index 76cb9237d..e2d52d76f 100644
--- a/docs/content/en/methods/shortcode/Store.md
+++ b/docs/content/en/methods/shortcode/Store.md
@@ -1,6 +1,6 @@
---
title: Store
-description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode.
+description: Returns a persistent data structure for storing and manipulating keyed values, scoped to the current shortcode.
categories: []
keywords: []
params:
@@ -11,14 +11,14 @@ params:
{{< new-in 0.139.0 />}}
-Use the `Store` method to create a [scratch pad](g) to store and manipulate data, scoped to the current shortcode. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
+Use the `Store` method to create a persistent data structure for storing and manipulating keyed values, scoped to the current shortcode. To create a data structure with a different [scope](g), refer to the [scope](#scope) section below.
-> [!note]
-> With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete.
+> [!NOTE]
+> With the introduction of the [`newScratch`][] function, and the ability to [assign values to template variables][] after initialization, the `Store` method within a shortcode is mostly obsolete.
{{% include "_common/store-methods.md" %}}
-{{% include "_common/scratch-pad-scope.md" %}}
+{{% include "_common/store-scope.md" %}}
[`newScratch`]: /functions/collections/newScratch/
[assign values to template variables]: https://go.dev/doc/go1.11#texttemplatepkgtexttemplate
diff --git a/docs/content/en/methods/site/BaseURL.md b/docs/content/en/methods/site/BaseURL.md
index 7b1b5e870..dcaa2baef 100644
--- a/docs/content/en/methods/site/BaseURL.md
+++ b/docs/content/en/methods/site/BaseURL.md
@@ -21,10 +21,10 @@ Template:
{{ .Site.BaseURL }} → https://example.org/docs/
```
-> [!note]
+> [!NOTE]
> There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration.
>
-> Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead.
+> Use the [`absURL`][], [`absLangURL`][], [`relURL`][], or [`relLangURL`][] functions instead.
[`absLangURL`]: /functions/urls/absLangURL/
[`absURL`]: /functions/urls/absURL/
diff --git a/docs/content/en/methods/site/Config.md b/docs/content/en/methods/site/Config.md
index 9cc885650..52d0192c5 100644
--- a/docs/content/en/methods/site/Config.md
+++ b/docs/content/en/methods/site/Config.md
@@ -13,11 +13,9 @@ The `Config` method on a `Site` object provides access to a subset of your proje
## Services
-See [configure services](/configuration/services).
+See [configure services][].
-For example, to use Hugo's built-in Google Analytics template you must add a [Google tag ID]:
-
-[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
+For example, to use Hugo's built-in Google Analytics template you must add a [Google tag ID][]:
{{< code-toggle file=hugo >}}
[services.googleAnalytics]
@@ -34,7 +32,7 @@ You must capitalize each identifier as shown above.
## Privacy
-See [configure privacy](/configuration/privacy).
+See [configure privacy][].
For example, to disable usage of the built-in YouTube shortcode:
@@ -50,3 +48,7 @@ To access this value from a template:
```
You must capitalize each identifier as shown above.
+
+[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
+[configure privacy]: /configuration/privacy/
+[configure services]: /configuration/services/
diff --git a/docs/content/en/methods/site/Data.md b/docs/content/en/methods/site/Data.md
index 0790c4f86..78ae10b06 100644
--- a/docs/content/en/methods/site/Data.md
+++ b/docs/content/en/methods/site/Data.md
@@ -11,5 +11,5 @@ expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
---
{{< deprecated-in 0.156.0 >}}
-Use [`hugo.Data`](/functions/hugo/data/) instead.
+Use the [`hugo.Data`](/functions/hugo/data/) function instead.
{{< /deprecated-in >}}
diff --git a/docs/content/en/methods/site/GetPage.md b/docs/content/en/methods/site/GetPage.md
index fab6e0465..a6663f543 100644
--- a/docs/content/en/methods/site/GetPage.md
+++ b/docs/content/en/methods/site/GetPage.md
@@ -9,9 +9,7 @@ params:
signatures: [SITE.GetPage PATH]
---
-The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See [details].
-
-[details]: /methods/page/getpage/
+The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See [details][].
When using the `GetPage` method on a `Site` object, specify a path relative to the `content` directory.
@@ -19,7 +17,7 @@ If Hugo cannot resolve the path to a page, the method returns nil.
Consider this content structure:
-```text
+```tree
content/
├── works/
│ ├── paintings/
@@ -84,7 +82,7 @@ To get a page from a different language, query the `Sites` object:
Consider this content structure:
-```text
+```tree
content/
├── headless/
│ ├── a.jpg
@@ -103,3 +101,5 @@ In the _home_ template, use the `GetPage` method on a `Site` object to render al
{{ end }}
{{ end }}
```
+
+[details]: /methods/page/getpage/
diff --git a/docs/content/en/methods/site/Language.md b/docs/content/en/methods/site/Language.md
index 73f097dda..9c48dbd3f 100644
--- a/docs/content/en/methods/site/Language.md
+++ b/docs/content/en/methods/site/Language.md
@@ -11,10 +11,12 @@ params:
The `Language` method on a `Site` object returns the `Language` object for the given site, derived from the language definition in your project configuration.
-You can also use the `Language` method on a `Page` object. See [details][].
+You can also use the `Language` method on a `Page` object. See [details][].
## Methods
+Use these methods on the `Language` object.
+
The examples below assume the following language definition.
{{< code-toggle file=hugo >}}
@@ -25,83 +27,64 @@ locale = 'de-DE'
weight = 2
{{< /code-toggle >}}
-### Direction
+`Direction`
+: {{< new-in 0.158.0 />}}
+: (`string`) Returns the [`direction`][] from the language definition.
-{{< new-in 0.158.0 />}}
+ ```go-html-template
+ {{ .Site.Language.Direction }} → ltr
+ ```
-(`string`) Returns the [`direction`][] from the language definition.
+`IsDefault`
+: {{< new-in 0.153.0 />}}
+: (`bool`) Reports whether this is the [default language](g).
-```go-html-template
-{{ .Site.Language.Direction }} → ltr
-```
+ ```go-html-template
+ {{ .Site.Language.IsDefault }} → true
+ ```
-### IsDefault
+`Label`
+: {{< new-in 0.158.0 />}}
+: (`string`) Returns the [`label`][] from the language definition.
-{{< new-in 0.153.0 />}}
+ ```go-html-template
+ {{ .Site.Language.Label }} → Deutsch
+ ```
-(`bool`) Reports whether this is the [default language](g).
+`Lang`
+: {{{{ .LinkTitle }}
{{ end }}
```
+
+[`RegularPages`]: /methods/site/regularpages/
diff --git a/docs/content/en/methods/site/Params.md b/docs/content/en/methods/site/Params.md
index 62bc8f1f5..42df53b74 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](g) the [identifiers](g):
{{ .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:
+In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`][] function:
```go-html-template
{{ index .Site.Params "copyright-year" }} → 2023
diff --git a/docs/content/en/methods/site/RegularPages.md b/docs/content/en/methods/site/RegularPages.md
index 69a460529..08d19357b 100644
--- a/docs/content/en/methods/site/RegularPages.md
+++ b/docs/content/en/methods/site/RegularPages.md
@@ -21,7 +21,7 @@ The `RegularPages` method on a `Site` object returns a collection of all [regula
[default sort order](g)
-To change the sort order, use any of the `Pages` [sorting methods]. For example:
+To change the sort order, use any of the `Pages` [sorting methods][]. For example:
```go-html-template
{{ range .Site.RegularPages.ByTitle }}
diff --git a/docs/content/en/methods/site/Role.md b/docs/content/en/methods/site/Role.md
index b3d909752..9aa415090 100644
--- a/docs/content/en/methods/site/Role.md
+++ b/docs/content/en/methods/site/Role.md
@@ -11,22 +11,24 @@ params:
{{< new-in 0.153.0 />}}
+## Overview
+
The `Role` method on a `Site` object returns the `Role` object for the given site, derived from the role definition in your project configuration.
## Methods
-### IsDefault
+Use these methods on the `Role` object.
-(`bool`) Reports whether this is the [default role](g).
+`IsDefault`
+: (`bool`) Reports whether this is the [default role](g).
-```go-html-template
-{{ .Site.Role.IsDefault }} → true
-```
+ ```go-html-template
+ {{ .Site.Role.IsDefault }} → true
+ ```
-### Name
+`Name`
+: (`string`) Returns the role name. This is the lowercased key from your project configuration.
-(`string`) Returns the role name. This is the lowercased key from your project configuration.
-
-```go-html-template
-{{ .Site.Role.Name }} → guest
-```
+ ```go-html-template
+ {{ .Site.Role.Name }} → guest
+ ```
diff --git a/docs/content/en/methods/site/Sections.md b/docs/content/en/methods/site/Sections.md
index 0ddaf0626..f3715df69 100644
--- a/docs/content/en/methods/site/Sections.md
+++ b/docs/content/en/methods/site/Sections.md
@@ -13,7 +13,7 @@ The `Sections` method on a `Site` object returns a collection of top-level [sect
Given this content structure:
-```text
+```tree
content/
├── books/
│ ├── book-1.md
diff --git a/docs/content/en/methods/site/Sites.md b/docs/content/en/methods/site/Sites.md
index ef7ff8bbd..84e668d3d 100644
--- a/docs/content/en/methods/site/Sites.md
+++ b/docs/content/en/methods/site/Sites.md
@@ -11,5 +11,5 @@ expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
---
{{< deprecated-in 0.156.0 >}}
-Use [`hugo.Sites`](/functions/hugo/sites/) instead.
+Use the [`hugo.Sites`](/functions/hugo/sites/) function instead.
{{< /deprecated-in >}}
diff --git a/docs/content/en/methods/site/Store.md b/docs/content/en/methods/site/Store.md
index 6c6d57a90..e7af6b595 100644
--- a/docs/content/en/methods/site/Store.md
+++ b/docs/content/en/methods/site/Store.md
@@ -1,6 +1,6 @@
---
title: Store
-description: Returns a "scratch pad" to store and manipulate data, scoped to the current site.
+description: Returns a persistent data structure for storing and manipulating keyed values, scoped to the current site.
categories: []
keywords: []
params:
@@ -11,98 +11,93 @@ params:
{{< new-in 0.139.0 />}}
-Use the `Store` method on a `Site` object to create a [scratch pad](g) to store and manipulate data, scoped to the current site. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
+Use the `Store` method on a `Site` object to create a persistent data structure for storing and manipulating keyed values, scoped to the current site. To create a data structure with a different [scope](g), refer to the [scope](#scope) section below.
## Methods
-### Set
+Use these methods on the data structure.
-Sets the value of a given key.
+`Set`
+: Sets the value of a given key.
-```go-html-template
-{{ site.Store.Set "greeting" "Hello" }}
-```
-
-### Get
-
-Gets the value of a given key.
-
-```go-html-template
-{{ site.Store.Set "greeting" "Hello" }}
-{{ site.Store.Get "greeting" }} → Hello
-```
-
-### Add
-
-Adds a given value to existing value(s) of the given key.
-
-For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
-
-```go-html-template
-{{ site.Store.Set "greeting" "Hello" }}
-{{ site.Store.Add "greeting" "Welcome" }}
-{{ site.Store.Get "greeting" }} → HelloWelcome
-```
-
-```go-html-template
-{{ site.Store.Set "total" 3 }}
-{{ site.Store.Add "total" 7 }}
-{{ site.Store.Get "total" }} → 10
-```
-
-```go-html-template
-{{ site.Store.Set "greetings" (slice "Hello") }}
-{{ site.Store.Add "greetings" (slice "Welcome" "Cheers") }}
-{{ site.Store.Get "greetings" }} → [Hello Welcome Cheers]
+ ```go-html-template
+ {{ site.Store.Set "greeting" "Hello" }}
```
-### SetInMap
+`Get`
+: (`any`) Gets the value of a given key.
-Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
+ ```go-html-template
+ {{ site.Store.Set "greeting" "Hello" }}
+ {{ site.Store.Get "greeting" }} → Hello
+ ```
-```go-html-template
-{{ site.Store.SetInMap "greetings" "english" "Hello" }}
-{{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
-{{ site.Store.Get "greetings" }} → map[english:Hello french:Bonjour]
-```
+`Add`
+: Adds a given value to existing value(s) of the given key.
-### DeleteInMap
+ For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
-Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
+ ```go-html-template
+ {{ site.Store.Set "greeting" "Hello" }}
+ {{ site.Store.Add "greeting" "Welcome" }}
+ {{ site.Store.Get "greeting" }} → HelloWelcome
+ ```
-```go-html-template
-{{ site.Store.SetInMap "greetings" "english" "Hello" }}
-{{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
-{{ site.Store.DeleteInMap "greetings" "english" }}
-{{ site.Store.Get "greetings" }} → map[french:Bonjour]
-```
+ ```go-html-template
+ {{ site.Store.Set "total" 3 }}
+ {{ site.Store.Add "total" 7 }}
+ {{ site.Store.Get "total" }} → 10
+ ```
-### GetSortedMapValues
+ ```go-html-template
+ {{ site.Store.Set "greetings" (slice "Hello") }}
+ {{ site.Store.Add "greetings" (slice "Welcome" "Cheers") }}
+ {{ site.Store.Get "greetings" }} → [Hello Welcome Cheers]
+ ```
-Returns an array of values from `key` sorted by `mapKey`.
+`SetInMap`
+: Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
-```go-html-template
-{{ site.Store.SetInMap "greetings" "english" "Hello" }}
-{{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
-{{ site.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
-```
+ ```go-html-template
+ {{ site.Store.SetInMap "greetings" "english" "Hello" }}
+ {{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
+ {{ site.Store.Get "greetings" }} → map[english:Hello french:Bonjour]
+ ```
-### Delete
+`DeleteInMap`
+: Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
-Removes the given key.
+ ```go-html-template
+ {{ site.Store.SetInMap "greetings" "english" "Hello" }}
+ {{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
+ {{ site.Store.DeleteInMap "greetings" "english" }}
+ {{ site.Store.Get "greetings" }} → map[french:Bonjour]
+ ```
-```go-html-template
-{{ site.Store.Set "greeting" "Hello" }}
-{{ site.Store.Delete "greeting" }}
-```
+`GetSortedMapValues`
+: (`[]any`) Returns an array of values from `key` sorted by `mapKey`.
-{{% include "_common/scratch-pad-scope.md" %}}
+ ```go-html-template
+ {{ site.Store.SetInMap "greetings" "english" "Hello" }}
+ {{ site.Store.SetInMap "greetings" "french" "Bonjour" }}
+ {{ site.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour]
+ ```
+
+`Delete`
+: Removes the given key.
+
+ ```go-html-template
+ {{ site.Store.Set "greeting" "Hello" }}
+ {{ site.Store.Delete "greeting" }}
+ ```
+
+{{% include "_common/store-scope.md" %}}
## Determinate values
-The `Store` method is often used to set scratch pad values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
+The `Store` method is often used to set values within a _shortcode_ template, a _partial_ template called by a _shortcode_ template, or by a _render hook_ template. In all three cases, the stored values are indeterminate 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](g) variable:
+If you need to access a stored 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](g) variable:
```go-html-template
{{ $noop := .Content }}
diff --git a/docs/content/en/methods/site/Taxonomies.md b/docs/content/en/methods/site/Taxonomies.md
index 4417c9ef7..13f846b0a 100644
--- a/docs/content/en/methods/site/Taxonomies.md
+++ b/docs/content/en/methods/site/Taxonomies.md
@@ -40,7 +40,7 @@ author = 'authors'
And this content structure:
-```text
+```tree
content/
├── books/
│ ├── and-then-there-were-none.md --> genres: suspense
@@ -93,10 +93,10 @@ Hugo renders this to:
```
-> [!note]
+> [!NOTE]
> Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages.
>
-> Please see the [taxonomies] section for a complete explanation and examples.
+> Please see the [taxonomies][] section for a complete explanation and examples.
## Examples
@@ -114,7 +114,7 @@ If you are using a taxonomy for something like a series of posts, you can list i
### List all content in a given taxonomy
-This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
+This is useful in a sidebar as "featured content". You could even have different sections of "featured content" by assigning different terms to the content.
```go-html-template