diff --git a/.cspell.json b/.cspell.json
index 264d0f01a..bf61489da 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -60,6 +60,7 @@
"redirections",
"subexpression",
"suppressible",
+ "synchronisation",
"templating",
"transpile",
"unmarshal",
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
index ee0a28909..dbb5b2ee8 100644
--- a/.markdownlint.yaml
+++ b/.markdownlint.yaml
@@ -22,5 +22,6 @@ MD041: false
MD046: false
MD049: false
MD050: false
+MD051: false
MD053: false
MD055: false
diff --git a/archetypes/functions.md b/archetypes/functions.md
index 85859dc04..de2d72060 100644
--- a/archetypes/functions.md
+++ b/archetypes/functions.md
@@ -6,7 +6,6 @@ keywords: []
params:
functions_and_methods:
aliases: []
- related: []
returnType:
signatures: []
---
diff --git a/archetypes/methods.md b/archetypes/methods.md
index 11fb01224..944fe527c 100644
--- a/archetypes/methods.md
+++ b/archetypes/methods.md
@@ -5,7 +5,6 @@ categories: []
keywords: []
params:
functions_and_methods:
- related: []
returnType:
signatures: []
---
diff --git a/archetypes/news.md b/archetypes/news.md
index 18e4a674e..04792a152 100644
--- a/archetypes/news.md
+++ b/archetypes/news.md
@@ -1,7 +1,7 @@
---
title: {{ replace .File.ContentBaseName "-" " " | strings.FirstUpper }}
-publishDate: {{ .Date }}
description:
categories: []
keywords: []
+publishDate: {{ .Date }}
---
diff --git a/content/en/_common/filter-sort-group.md b/content/en/_common/filter-sort-group.md
index f4955ef99..ac73766da 100644
--- a/content/en/_common/filter-sort-group.md
+++ b/content/en/_common/filter-sort-group.md
@@ -2,8 +2,7 @@
_comment: Do not remove front matter.
---
-{{< note >}}
-The [page collections quick reference guide] describes methods and functions to filter, sort, and group page collections.
+> [!note]
+> The [page collections quick reference guide] describes methods and functions to filter, sort, and group page collections.
[page collections quick reference guide]: /quick-reference/page-collections/
-{{< /note >}}
diff --git a/content/en/_common/functions/locales.md b/content/en/_common/functions/locales.md
index f27cfd893..1cfd7a1e6 100644
--- a/content/en/_common/functions/locales.md
+++ b/content/en/_common/functions/locales.md
@@ -2,8 +2,7 @@
_comment: Do not remove front matter.
---
-{{< note >}}
-Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales.
+> [!note]
+> Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales.
[gohugoio/locales]: https://github.com/gohugoio/locales
-{{< /note >}}
diff --git a/content/en/_common/functions/postcss-windows-warning.md b/content/en/_common/functions/postcss-windows-warning.md
deleted file mode 100644
index e2d97850b..000000000
--- a/content/en/_common/functions/postcss-windows-warning.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-_comment: Do not remove front matter.
----
-
-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].
-
-[this example]: https://github.com/postcss/postcss-load-config#packagejson
-[#7333]: https://github.com/gohugoio/hugo/issues/7333
diff --git a/content/en/_common/gomodules-info.md b/content/en/_common/gomodules-info.md
new file mode 100644
index 000000000..8beddeda6
--- /dev/null
+++ b/content/en/_common/gomodules-info.md
@@ -0,0 +1,13 @@
+---
+_comment: Do not remove front matter.
+---
+
+> [!warning] Hugo Modules are Go Modules
+> You need [Go] version 1.18 or later and [Git] to use Hugo Modules. For older sites hosted on Netlify, please ensure the `GO_VERSION` environment variable is set to `1.18` or higher.
+>
+> Go Modules resources:
+> - [go.dev/wiki/Modules](https://go.dev/wiki/Modules)
+> - [blog.golang.org/using-go-modules](https://go.dev/blog/using-go-modules)
+
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
diff --git a/content/en/_common/methods/resource/global-page-remote-resources.md b/content/en/_common/methods/resource/global-page-remote-resources.md
index e1812dfad..49146aed4 100644
--- a/content/en/_common/methods/resource/global-page-remote-resources.md
+++ b/content/en/_common/methods/resource/global-page-remote-resources.md
@@ -2,6 +2,5 @@
_comment: Do not remove front matter.
---
-{{< note >}}
-Use this method with [global resources](g), [page resources](g), or [remote resources](g).
-{{< /note >}}
+> [!note]
+> Use this method with [global resources](g), [page resources](g), or [remote resources](g).
diff --git a/content/en/_common/render-hooks/pageinner.md b/content/en/_common/render-hooks/pageinner.md
index ecd50b8a9..a598b880a 100644
--- a/content/en/_common/render-hooks/pageinner.md
+++ b/content/en/_common/render-hooks/pageinner.md
@@ -33,16 +33,15 @@ Any render hook triggered while rendering `/posts/p2` 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].
-
-[Markdown notation]: /content-management/shortcodes/#notation
-[`RenderShortcodes`]: /methods/page/rendershortcodes/
-{{< /note >}}
+> [!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]({{% eturl render-link %}})
-- [Embedded image render hook]({{% eturl render-image %}})
+- [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 %}}
diff --git a/content/en/_common/syntax-highlighting-options.md b/content/en/_common/syntax-highlighting-options.md
index baf10c6e2..36144e090 100644
--- a/content/en/_common/syntax-highlighting-options.md
+++ b/content/en/_common/syntax-highlighting-options.md
@@ -11,9 +11,8 @@ codeFences
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 >}}
- The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
- {{< /note >}}
+ > [!note]
+ > The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
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.
@@ -28,7 +27,11 @@ lineNoStart
: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
lineNos
-: (`bool`) Whether to display a number at the beginning of each line. Default is `false`.
+: (`any`) Controls line number display. Default is `false`.
+ - `true`: Enable line numbers, controlled by `lineNumbersInTable`.
+ - `false`: Disable line numbers.
+ - `inline`: Enable inline line numbers (sets `lineNumbersInTable` to `false`).
+ - `table`: Enable table-based line numbers (sets `lineNumbersInTable` to `true`).
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`.
@@ -50,16 +53,4 @@ wrapperClass
: {{< new-in 0.140.2 />}}
: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
-{{< note >}}
-Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
-
-lineNos=inline
-: equivalent to `lineNos=true` and `lineNumbersInTable=false`
-
-lineNos=table
-: equivalent to `lineNos=true` and `lineNumbersInTable=true`
-{{< /note >}}
-
-[Short snippets]: https://xyproto.github.io/splash/docs/all.html
-[Long snippets]: https://xyproto.github.io/splash/docs/longer/all.html
[syntax highlighting styles]: /quick-reference/syntax-highlighting-styles/
diff --git a/content/en/about/features.md b/content/en/about/features.md
index ff8b220d5..ff1a6b8eb 100644
--- a/content/en/about/features.md
+++ b/content/en/about/features.md
@@ -78,7 +78,7 @@ weight: 20
## Asset pipelines
[Image processing]
-: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data.
+: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data.
[JavaScript bundling]
: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
diff --git a/content/en/configuration/all.md b/content/en/configuration/all.md
index a4c51e83c..43ea3f33b 100644
--- a/content/en/configuration/all.md
+++ b/content/en/configuration/all.md
@@ -294,28 +294,6 @@ titleCaseStyle
uglyurls
: See [configure ugly URLs](/configuration/ugly-urls/).
-[IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
-[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
-[`GitInfo`]: /methods/page/gitinfo/
-[`MainSections`]: /methods/site/mainsections/
-[`Summary`]: /methods/page/summary/
-[`WordCount`]: /methods/page/wordcount/
-[`disabled`]: /configuration/languages/#disabled
-[`erroridf`]: /functions/fmt/erroridf/
-[`segments`]: /configuration/segments/
-[`strings.Title`]: /functions/strings/title
-[`time.AsTime`]: /functions/time/astime/
-[`time.Format`]: /functions/time/format/
-[`warnidf`]: /functions/fmt/warnidf/
-[automatic summaries]: /content-management/summaries/#automatic-summary
-[default front matter configuration]: /configuration/front-matter/
-[duration]: https://pkg.go.dev/time#Duration
-[embedded Open Graph template]: {{% eturl opengraph %}}
-[embedded RSS template]: {{% eturl rss %}}
-[embedded alias template]: {{% eturl alias %}}
-[module mounts]: /configuration/module/#mounts
-
## Cache directory
Hugo's file cache directory is configurable via the [`cacheDir`] configuration option or the `HUGO_CACHEDIR` environment variable. If neither is set, Hugo will use, in order of preference:
@@ -330,11 +308,6 @@ To determine the current `cacheDir`:
hugo config | grep cachedir
```
-[XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/
-[`cacheDir`]: #cachedir
-[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir
-[this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml
-
## Title case style
Hugo's [`titleCaseStyle`] setting governs capitalization for automatically generated section titles and the [`strings.Title`] function. By default, it follows the capitalization rules published in the Associated Press Stylebook. Change this setting to use other capitalization rules.
@@ -354,11 +327,36 @@ firstupper
none
: Disable transformation of automatic section titles, and disable the transformation performed by the `strings.Title` function. This is useful if you would prefer to manually capitalize section titles as needed, and to bypass opinionated theme usage of the `strings.Title` function.
-[Associated Press Stylebook]: https://www.apstylebook.com/
-[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
-[`strings.Title`]: /functions/strings/title/
-[`titleCaseStyle`]: #titlecasestyle
-
## Localized settings
Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages](/configuration/languages/#localized-settings).
+
+[`cacheDir`]: #cachedir
+[`disabled`]: /configuration/languages/#disabled
+[`erroridf`]: /functions/fmt/erroridf/
+[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
+[`GitInfo`]: /methods/page/gitinfo/
+[`MainSections`]: /methods/site/mainsections/
+[`segments`]: /configuration/segments/
+[`strings.Title`]: /functions/strings/title/
+[`strings.Title`]: /functions/strings/title
+[`Summary`]: /methods/page/summary/
+[`time.AsTime`]: /functions/time/astime/
+[`time.Format`]: /functions/time/format/
+[`titleCaseStyle`]: #titlecasestyle
+[`warnidf`]: /functions/fmt/warnidf/
+[`WordCount`]: /methods/page/wordcount/
+[Associated Press Stylebook]: https://www.apstylebook.com/
+[automatic summaries]: /content-management/summaries/#automatic-summary
+[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
+[default front matter configuration]: /configuration/front-matter/
+[duration]: https://pkg.go.dev/time#Duration
+[embedded alias template]: {{% eturl alias %}}
+[embedded Open Graph template]: {{% eturl opengraph %}}
+[embedded RSS template]: {{% eturl rss %}}
+[IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+[module mounts]: /configuration/module/#mounts
+[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml
+[XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/
diff --git a/content/en/configuration/build.md b/content/en/configuration/build.md
index a86e0ac71..4f69bf676 100644
--- a/content/en/configuration/build.md
+++ b/content/en/configuration/build.md
@@ -71,12 +71,11 @@ disableTags
disableClasses
: (`bool`) Whether to exclude `class` attributes. Default is `false`.
-{{< note >}}
-Given that CSS purging is typically limited to production builds, place the `buildStats` object below [`config/production`].
-
-[`config/production`]: /configuration/introduction/#configuration-directory
-
-Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential.
-{{< /note >}}
+> [!note]
+> Given that CSS purging is typically limited to production builds, place the `buildStats` object below [`config/production`].
+>
+> Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential.
Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build.
+
+[`config/production`]: /configuration/introduction/#configuration-directory
diff --git a/content/en/configuration/cascade.md b/content/en/configuration/cascade.md
index 04723c95a..d91996301 100644
--- a/content/en/configuration/cascade.md
+++ b/content/en/configuration/cascade.md
@@ -8,11 +8,8 @@ keywords: []
You can configure your site to cascade front matter values to the home page and any of its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor [node](g) has already cascaded a value for the same field through its front matter's `cascade` key.
-{{< note >}}
-You can also configure cascading behavior within a page's front matter. See [details].
-
-[details]: /content-management/front-matter/#cascade-1
-{{< /note >}}
+> [!note]
+> You can also configure cascading behavior within a page's front matter. See [details].
For example, to cascade a "color" parameter to the home page and all its descendants:
@@ -55,8 +52,6 @@ lang
path
: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
-[page language]: /methods/page/language/
-
## Array
Define an array of cascade parameters to apply different values to different targets. For example:
@@ -77,3 +72,6 @@ path = '{/films/**}'
kind = 'page'
environment = 'production'
{{< /code-toggle >}}
+
+[details]: /content-management/front-matter/#cascade-1
+[page language]: /methods/page/language/
diff --git a/content/en/configuration/deployment.md b/content/en/configuration/deployment.md
index 1f520aa0f..f0beb12d0 100644
--- a/content/en/configuration/deployment.md
+++ b/content/en/configuration/deployment.md
@@ -6,9 +6,8 @@ categories: []
keywords: []
---
-{{< note >}}
-This configuration is only relevant when running `hugo deploy`. See [details](/host-and-deploy/deploy-with-hugo-deploy/).
-{{< /note >}}
+> [!note]
+> This configuration is only relevant when running `hugo deploy`. See [details](/host-and-deploy/deploy-with-hugo-deploy/).
## Top-level options
diff --git a/content/en/configuration/http-cache.md b/content/en/configuration/http-cache.md
index 862e17ab9..788d22a08 100644
--- a/content/en/configuration/http-cache.md
+++ b/content/en/configuration/http-cache.md
@@ -6,11 +6,8 @@ categories: []
keywords: []
---
-{{< note >}}
-This configuration is only relevant when using the [`resources.GetRemote`] function.
-
-[`resources.GetRemote`]: /functions/resources/getremote/
-{{< /note >}}
+> [!note]
+> This configuration is only relevant when using the [`resources.GetRemote`] function.
## Layered caching
@@ -41,10 +38,6 @@ HTTP Cache
File cache
: See [configure file caches].
-[cache-busting]: /configuration/build/#cache-busters
-[RFC 9111]: https://datatracker.ietf.org/doc/html/rfc9111
-[configure file caches]: /configuration/caches/
-
The HTTP cache involves two key aspects: determining which content to cache (the caching process itself) and defining the frequency with which to check for updates (the polling strategy).
## HTTP caching
@@ -107,4 +100,8 @@ Polling and HTTP caching interact as follows:
- If polling is enabled but HTTP caching is disabled, the remote is checked for changes only after the file cache's TTL expires (e.g., a `maxAge` of `10h` with a `1s` polling interval is inefficient).
- If both polling and HTTP caching are enabled, changes are checked for even before the file cache's TTL expires. Cached `eTag` and `last-modified` values are sent in `if-none-match` and `if-modified-since` headers, respectively, and a cached response is returned on HTTP [304].
+[`resources.GetRemote`]: /functions/resources/getremote/
[304]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304
+[cache-busting]: /configuration/build/#cache-busters
+[configure file caches]: /configuration/caches/
+[RFC 9111]: https://datatracker.ietf.org/doc/html/rfc9111
diff --git a/content/en/configuration/imaging.md b/content/en/configuration/imaging.md
index a8fc75a3a..286c30f14 100644
--- a/content/en/configuration/imaging.md
+++ b/content/en/configuration/imaging.md
@@ -60,8 +60,7 @@ excludeFields
includeFields
: (`string`) A regular expression matching the tags to include when extracting EXIF data. To include all available tags, set this value to `".*"`.
-{{< note >}}
-To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
-
-To control tag availability, change the `excludeFields` or `includeFields` settings as described above.
-{{< /note >}}
+> [!note]
+> To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
+>
+> To control tag availability, change the `excludeFields` or `includeFields` settings as described above.
diff --git a/content/en/configuration/introduction.md b/content/en/configuration/introduction.md
index 82cca48bb..e2590a8ec 100644
--- a/content/en/configuration/introduction.md
+++ b/content/en/configuration/introduction.md
@@ -18,9 +18,8 @@ title = 'My New Hugo Site'
Only define settings that deviate from the defaults. A smaller configuration file is easier to read, understand, and debug. Keep your configuration concise.
-{{< note >}}
-The best configuration file is a short configuration file.
-{{< /note >}}
+> [!note]
+> The best configuration file is a short configuration file.
## Configuration file
@@ -31,9 +30,8 @@ my-project/
└── hugo.toml
```
-{{< note >}}
-For versions v0.109.0 and earlier, the site configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`.
-{{< /note >}}
+> [!note]
+> For versions v0.109.0 and earlier, the site configuration file was named `config`. While you can still use this name, it's recommended to switch to the newer naming convention, `hugo`.
A simple example:
@@ -60,13 +58,8 @@ Combine two or more configuration files, with left-to-right precedence:
hugo --config a.toml,b.yaml,c.json
```
-{{< note >}}
-See the specifications for each file format: [TOML], [YAML], and [JSON].
-
-[TOML]: https://toml.io/en/latest
-[YAML]: https://yaml.org/spec/
-[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
-{{< /note >}}
+> [!note]
+> See the specifications for each file format: [TOML], [YAML], and [JSON].
## Configuration directory
@@ -135,8 +128,6 @@ Considering the structure above, when running `hugo --environment staging`, Hugo
Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify a [Google tag ID] in your site configuration:
-[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
-
{{< code-toggle file=hugo >}}
[services.googleAnalytics]
ID = 'G-XXXXXXXXX'
@@ -236,28 +227,18 @@ hugo
The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configuration options and then builds your site.
-[`baseURL`]: /configuration/all#baseurl
-[`enableGitInfo`]: /configuration/all#enablegitinfo
-[`environment`]: /configuration/all#environment
-
-{{< note >}}
-An environment variable takes precedence over the values set in the configuration file. This means that if you set a configuration value with both an environment variable and in the configuration file, the value in the environment variable will be used.
-{{< /note >}}
+> [!note]
+> An environment variable takes precedence over the values set in the configuration file. This means that if you set a configuration value with both an environment variable and in the configuration file, the value in the environment variable will be used.
Environment variables simplify configuration for CI/CD deployments like GitHub Pages, GitLab Pages, and Netlify by allowing you to set values directly within their respective configuration and workflow files.
-[CI/CD]: https://en.wikipedia.org/wiki/CI/CD
-
-{{< note >}}
-Environment variable names must be prefixed with `HUGO_`.
-
-To set custom site parameters, prefix the name with `HUGO_PARAMS_`.
-{{< /note >}}
+> [!note]
+> Environment variable names must be prefixed with `HUGO_`.
+>
+> To set custom site parameters, prefix the name with `HUGO_PARAMS_`.
For snake_case variable names, the standard `HUGO_` prefix won't work. Hugo infers the delimiter from the first character following `HUGO`. This allows for variations like `HUGOxPARAMSxAPI_KEY=abcdefgh` using any [permitted delimiter].
-[permitted delimiter]: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html
-
In addition to configuring standard settings, environment variables may be used to override default values for certain internal settings:
DART_SASS_BINARY
@@ -292,3 +273,12 @@ Display the configured file mounts with:
```sh
hugo config mounts
```
+
+[`baseURL`]: /configuration/all#baseurl
+[`enableGitInfo`]: /configuration/all#enablegitinfo
+[`environment`]: /configuration/all#environment
+[Google tag ID]: https://support.google.com/tagmanager/answer/12326985?hl=en
+[JSON]: https://datatracker.ietf.org/doc/html/rfc7159
+[permitted delimiter]: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html
+[TOML]: https://toml.io/en/latest
+[YAML]: https://yaml.org/spec/
diff --git a/content/en/configuration/languages.md b/content/en/configuration/languages.md
index 348f545e6..45634329a 100644
--- a/content/en/configuration/languages.md
+++ b/content/en/configuration/languages.md
@@ -30,8 +30,6 @@ disableDefaultLanguageRedirect
disableLanguages
: (`[]string]`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`](#disabled) key under each language instead.
-[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
-
## Language settings
Configure each language under the `languages` key:
@@ -64,16 +62,6 @@ title
weight
: (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language. Access this value from a template using the [`Language.Weight`] method on a `Site` or `Page` object.
-[`Language.LanguageCode`]: /methods/site/language/#languagecode
-[`Language.LanguageDirection`]: /methods/site/language/#languagedirection
-[`Language.LanguageName`]: /methods/site/language/#languagename
-[`Language.Weight`]: /methods/site/language/#weight
-[`Title`]: /methods/site/title/
-[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
-[built-in OpenGraph template]: {{% eturl opengraph %}}
-[built-in RSS template]: {{% eturl rss %}}
-[built-in alias template]: {{% eturl alias %}}
-
## Localized settings
Some configuration settings can be defined separately for each language. For example:
@@ -121,11 +109,8 @@ weight = 1
weight = 2
{{< /code-toggle >}}
-{{< note >}}
-Private use subtags must not exceed 8 alphanumeric characters.
-{{< /note >}}
-
-[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
+> [!note]
+> Private use subtags must not exceed 8 alphanumeric characters.
## Example
@@ -159,19 +144,15 @@ weight = 2
subtitle = 'Reference, Tutorials, and Explanations'
{{< /code-toggle >}}
-{{< note >}}
-In the example above, omit `contentDir` if [translating by file name].
-
-[translating by file name]: /content-management/multilingual/#translation-by-file-name
-{{< /note >}}
+> [!note]
+> In the example above, omit `contentDir` if [translating by file name].
## Multihost
Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`.
-{{< note >}}
-If you define a `baseURL` for one language, you must define a unique `baseURL` for all languages.
-{{< /note >}}
+> [!note]
+> If you define a `baseURL` for one language, you must define a unique `baseURL` for all languages.
For example:
@@ -197,3 +178,16 @@ public
├── en
└── fr
```
+
+[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
+[`Language.LanguageCode`]: /methods/site/language/#languagecode
+[`Language.LanguageDirection`]: /methods/site/language/#languagedirection
+[`Language.LanguageName`]: /methods/site/language/#languagename
+[`Language.Weight`]: /methods/site/language/#weight
+[`Title`]: /methods/site/title/
+[built-in alias template]: {{% eturl alias %}}
+[built-in OpenGraph template]: {{% eturl opengraph %}}
+[built-in RSS template]: {{% eturl rss %}}
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
+[translating by file name]: /content-management/multilingual/#translation-by-file-name
diff --git a/content/en/configuration/markup.md b/content/en/configuration/markup.md
index fe8982ec3..3006f6f18 100644
--- a/content/en/configuration/markup.md
+++ b/content/en/configuration/markup.md
@@ -30,20 +30,8 @@ To use a different renderer for Markdown files, specify one of `asciidocext`, `o
To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].
-{{< note >}}
-Unless you need a unique capability provided by one of the alternative Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
-
-[commonmark]: https://spec.commonmark.org/0.30/
-[github flavored markdown]: https://github.github.com/gfm/
-{{< /note >}}
-
-[asciidoc]: https://asciidoc.org/
-[content format]: /content-management/formats/#formats
-[emacs org mode]: https://orgmode.org/
-[goldmark]: https://github.com/yuin/goldmark/
-[pandoc]: https://pandoc.org/
-[restructuredtext]: https://docutils.sourceforge.io/rst.html
-[security policy]: /configuration/security/
+> [!note]
+> Unless you need a unique capability provided by one of the alternative Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).
## Goldmark
@@ -68,17 +56,6 @@ Extension|Documentation|Enabled
`taskList`|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark:
`typographer`|[Goldmark Extensions: Typographer]|:heavy_check_mark:
-[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension-
-[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
-[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension-
-[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension-
-[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension
-[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension
-[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension
-[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension
-[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list
-[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes
-
#### Extras
{{< new-in 0.126.0 />}}
@@ -93,12 +70,6 @@ Mark text|`==baz==`|`baz`
Subscript|`H~2~O`|`H2O`
Superscript|`1^st^`|`1st`
-[deleted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
-[inserted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
-[mark text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
-[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
-[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
-
To avoid a conflict when enabling the "subscript" feature of the Extras extension, if you want to render subscript and strikethrough text concurrently you must:
1. Disable the Strikethrough extension
@@ -123,8 +94,6 @@ enable = true
Enable the Passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details.
-[mathematics in Markdown]: content-management/mathematics/
-
#### Typographer
The Typographer extension replaces certain character combinations with HTML entities as specified below:
@@ -150,12 +119,8 @@ duplicateResourceFiles
: {{< new-in 0.123.0 />}}
: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host sites. See [multilingual page resources] for details. Default is `false`.
- {{< note >}}
- With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites.
-
- [embedded image render hook]: /render-hooks/images/#default
- [embedded link render hook]: /render-hooks/links/#default
- {{< /note >}}
+ > [!note]
+ > With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites.
parser.wrapStandAloneImageWithinParagraph
: (`bool`) Whether to wrap image elements without adjacent content within a `p` element when rendered. This is the default Markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`.
@@ -186,21 +151,15 @@ renderHooks.image.enableDefault
: {{< new-in 0.123.0 />}}
: (`bool`) Whether to enable the [embedded image render hook]. Default is `false`.
- {{< note >}}
- The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
-
- [duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
- {{< /note >}}
+ > [!note]
+ > The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
renderHooks.link.enableDefault
: {{< new-in 0.123.0 />}}
: (`bool`) Whether to enable the [embedded link render hook]. Default is `false`.
- {{< note >}}
- The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
-
- [duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
- {{< /note >}}
+ > [!note]
+ > The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
renderer.hardWraps
: (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`.
@@ -208,12 +167,6 @@ renderer.hardWraps
renderer.unsafe
: (`bool`) Whether to render raw HTML mixed within Markdown. This is unsafe unless the content is under your control. Default is `false`.
-[Markdown attributes]: /content-management/markdown-attributes/
-[embedded image render hook]: /render-hooks/images/#default
-[embedded link render hook]: /render-hooks/links/#default
-[image render hook]: /render-hooks/images/
-[multilingual page resources]: /content-management/page-resources/#multilingual
-[`Fragments.Identifiers`]: /methods/page/fragments/#identifiers
## AsciiDoc
This is the default configuration for the AsciiDoc renderer:
@@ -231,9 +184,8 @@ backend
extensions
: (`string array`) An array of enabled extensions, one or more of `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, or `asciidoctor-question`.
- {{< note >}}
- To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`.
- {{< /note >}}
+ > [!note]
+ > To mitigate security risks, entries in the extension array may not contain forward slashes (`/`), backslashes (`\`), or periods. Due to this restriction, extensions must be in Ruby's `$LOAD_PATH`.
failureLevel
: (`string`) The minimum logging level that triggers a non-zero exit code (failure). Default is `fatal`.
@@ -259,11 +211,6 @@ verbose
workingFolderCurrent
: (`bool`) Whether to set the working directory to be the same as that of the AsciiDoc file being processed, allowing [includes] to work with relative paths. Set to `true` to render diagrams with the [asciidoctor-diagram] extension. Default is `false`.
-[`TableOfContents`]: /methods/page/tableofcontents/
-[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
-[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
-[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes
-
### Configuration example
{{< code-toggle file=hugo >}}
@@ -353,3 +300,38 @@ endLevel
ordered
: (`bool`) Whether to generates an ordered list instead of an unordered list. Default is `false`.
+
+[`Fragments.Identifiers`]: /methods/page/fragments/#identifiers
+[`TableOfContents`]: /methods/page/tableofcontents/
+[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
+[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
+[CommonMark]: https://spec.commonmark.org/current/
+[deleted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded image render hook]: /render-hooks/images/#default
+[embedded image render hook]: /render-hooks/images/#default
+[embedded link render hook]: /render-hooks/links/#default
+[embedded link render hook]: /render-hooks/links/#default
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension-
+[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
+[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension-
+[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension-
+[Goldmark]: https://github.com/yuin/goldmark/
+[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension
+[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension
+[Hugo Goldmark Extensions: Extras]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#extras-extension
+[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension
+[image render hook]: /render-hooks/images/
+[includes]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes
+[inserted text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins
+[mark text]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark
+[Markdown attributes]: /content-management/markdown-attributes/
+[mathematics in Markdown]: content-management/mathematics/
+[multilingual page resources]: /content-management/page-resources/#multilingual
+[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list
+[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes
+[security policy]: /configuration/security/
+[subscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sub
+[superscript]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/sup
diff --git a/content/en/configuration/media-types.md b/content/en/configuration/media-types.md
index f1b8f1020..ea89ee04a 100644
--- a/content/en/configuration/media-types.md
+++ b/content/en/configuration/media-types.md
@@ -14,9 +14,8 @@ Configured media types serve multiple purposes in Hugo, including the definition
The `suffixes` column in the table above shows the suffixes associated with each media type. For example, Hugo associates `.html` and `.htm` files with the `text/html` media type.
-{{< note >}}
-The first suffix is the primary suffix. Use the primary suffix when naming template files. For example, when creating a template for an RSS feed, use the `xml` suffix.
-{{< /note >}}
+> [!note]
+> The first suffix is the primary suffix. Use the primary suffix when naming template files. For example, when creating a template for an RSS feed, use the `xml` suffix.
## Default configuration
diff --git a/content/en/configuration/menus.md b/content/en/configuration/menus.md
index f851152a3..759f53ff3 100644
--- a/content/en/configuration/menus.md
+++ b/content/en/configuration/menus.md
@@ -6,11 +6,8 @@ categories: []
keywords: []
---
-{{< note >}}
-To understand Hugo's menu system, please refer to the [menus] page.
-
-[menus]: /content-management/menus/
-{{< /note >}}
+> [!note]
+> To understand Hugo's menu system, please refer to the [menus] page.
There are three ways to define menu entries:
@@ -73,11 +70,6 @@ Access this menu structure in the same way:
{{ end }}
```
-[Automatically]: /content-management/menus/#define-automatically
-[In front matter]: /content-management/menus/#define-in-front-matter
-[`Menus`]: /methods/site/menus/
-[menu templates]: /templates/menu/
-
## Properties
Menu entries usually include at least three properties: `name`, `weight`, and either `pageRef` or `url`. Use `pageRef` for internal page destinations and `url` for external destinations.
@@ -135,3 +127,9 @@ weight = 30
[menus.main.params]
rel = 'external'
{{< /code-toggle >}}
+
+[`Menus`]: /methods/site/menus/
+[Automatically]: /content-management/menus/#define-automatically
+[In front matter]: /content-management/menus/#define-in-front-matter
+[menu templates]: /templates/menu/
+[menus]: /content-management/menus/
diff --git a/content/en/configuration/module.md b/content/en/configuration/module.md
index 2b9add881..d736b7c6f 100644
--- a/content/en/configuration/module.md
+++ b/content/en/configuration/module.md
@@ -59,7 +59,7 @@ export HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."
export HUGO_MODULE_WORKSPACE="/my/hugo.work"
```
-{{< gomodules-info >}}
+{{% include "/_common/gomodules-info.md" %}}
## Hugo version
@@ -114,7 +114,7 @@ path
[`themesDir`]: /configuration/all#themesDir
-{{< gomodules-info >}}
+{{% include "/_common/gomodules-info.md" %}}
## Mounts
@@ -129,15 +129,13 @@ you cannot use both.
[`layoutDi`]: /configuration/all/
[`staticDir`]: /configuration/all/
-{{< note >}}
-If you use module mounts do not use the legacy settings.
-{{< /note >}}
+> [!note]
+> If you use module mounts do not use the legacy settings.
### Default mounts
-{{< note >}}
-Adding a new mount to a target root will cause the existing default mount for that root to be ignored. If you still need the default mount, you must explicitly add it along with the new mount.
-{{< /note >}}
+> [!note]
+> Adding a new mount to a target root will cause the existing default mount for that root to be ignored. If you still need the default mount, you must explicitly add it along with the new mount.
The are the default mounts:
diff --git a/content/en/configuration/outputs.md b/content/en/configuration/outputs.md
index 2ceaa6518..9a83cb6e9 100644
--- a/content/en/configuration/outputs.md
+++ b/content/en/configuration/outputs.md
@@ -10,8 +10,6 @@ keywords: []
Learn more about creating and configuring output formats in the [configure output formats] section.
-[configure output formats]: /configuration/output-formats/
-
## Outputs per page kind
The following default configuration determines the output formats generated for each page kind:
@@ -27,17 +25,12 @@ home = ['html','rss','json']
Notice in this example that we only specified the `home` page kind. You don't need to include entries for other page kinds unless you intend to modify their default output formats.
-{{< note >}}
-The order of the output formats in the arrays above is important. The first element will be the _primary output format_ for that page kind, and in most cases that should be `html` as shown in the default configuration.
-
-The primary output format for a given page kind determines the value returned by the [`Permalink`] and [`RelPermalink`] methods on a `Page` object.
-
-See the [link to output formats] section for details.
-
-[`Permalink`]: /methods/page/permalink/
-[`RelPermalink`]: /methods/page/relpermalink/
-[link to output formats]: configuration/output-formats/#link-to-output-formats
-{{< /note >}}
+> [!note]
+> The order of the output formats in the arrays above is important. The first element will be the _primary output format_ for that page kind, and in most cases that should be `html` as shown in the default configuration.
+>
+> The primary output format for a given page kind determines the value returned by the [`Permalink`] and [`RelPermalink`] methods on a `Page` object.
+>
+> See the [link to output formats] section for details.
## Outputs per page
@@ -49,3 +42,8 @@ outputs = ['json']
{{< /code-toggle >}}
In its default configuration, Hugo will render both the `html` and `json` output formats for this page. The `outputs` field appends to, rather than replaces, the site's configured outputs.
+
+[`Permalink`]: /methods/page/permalink/
+[`RelPermalink`]: /methods/page/relpermalink/
+[configure output formats]: /configuration/output-formats/
+[link to output formats]: configuration/output-formats/#link-to-output-formats
diff --git a/content/en/configuration/page.md b/content/en/configuration/page.md
index 0af23c1c8..81169e546 100644
--- a/content/en/configuration/page.md
+++ b/content/en/configuration/page.md
@@ -27,9 +27,8 @@ To reverse the meaning of _next_ and _previous_:
nextPrevSortOrder = 'asc'
{{< /code-toggle >}}
-{{< note >}}
-These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object.
+> [!note]
+> These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object.
[`Next`]: /methods/pages/next
[`Prev`]: /methods/pages/next
-{{< /note >}}
diff --git a/content/en/configuration/permalinks.md b/content/en/configuration/permalinks.md
index c2a50df21..0810624a6 100644
--- a/content/en/configuration/permalinks.md
+++ b/content/en/configuration/permalinks.md
@@ -12,11 +12,8 @@ This is the default configuration:
Define a URL pattern for each top-level section. Each URL pattern can target a given language and/or page kind.
-{{< note >}}
-The [`url`] front matter field overrides any matching permalink pattern.
-
-[`url`]: /content-management/front-matter/#url
-{{< /note >}}
+> [!note]
+> The [`url`] front matter field overrides any matching permalink pattern.
## Monolingual example
@@ -161,3 +158,5 @@ public/
Use these tokens when defining a URL pattern.
{{% include "/_common/permalink-tokens.md" %}}
+
+[`url`]: /content-management/front-matter/#url
diff --git a/content/en/configuration/privacy.md b/content/en/configuration/privacy.md
index 4ea8f5cb6..c94f2c1c3 100644
--- a/content/en/configuration/privacy.md
+++ b/content/en/configuration/privacy.md
@@ -26,9 +26,8 @@ Some of these templates include settings to enhance privacy.
## Configuration
-{{< note >}}
-These settings affect the behavior of some of Hugo's embedded templates. These settings may or may not affect the behavior of templates provided by third parties in their modules or themes.
-{{< /note >}}
+> [!note]
+> These settings affect the behavior of some of Hugo's embedded templates. These settings may or may not affect the behavior of templates provided by third parties in their modules or themes.
These are the default privacy settings for Hugo's embedded templates:
diff --git a/content/en/configuration/related-content.md b/content/en/configuration/related-content.md
index 18e440ffb..c6e182fae 100644
--- a/content/en/configuration/related-content.md
+++ b/content/en/configuration/related-content.md
@@ -6,11 +6,8 @@ categories: []
keywords: []
---
-{{< note >}}
-To understand Hugo's related content identification, please refer to the [related content] page.
-
-[related content]: /content-management/related-content/
-{{< /note >}}
+> [!note]
+> To understand Hugo's related content identification, please refer to the [related content] page.
Hugo provides a sensible default configuration for identifying related content, but you can customize it in your site configuration, either globally or per language.
@@ -20,9 +17,8 @@ This is the default configuration:
{{< code-toggle config=related />}}
-{{< note >}}
-Adding a `related` section to your site configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings.
-{{< /note >}}
+> [!note]
+> Adding a `related` section to your site configuration requires you to provide a full configuration. You cannot override individual default values without specifying all related settings.
## Top-level options
@@ -111,3 +107,5 @@ Then render a list of 5 related reviews with a partial template like this:
{{ end }}
```
+
+[related content]: /content-management/related-content/
diff --git a/content/en/configuration/security.md b/content/en/configuration/security.md
index fb95e87e1..a7d0cc578 100644
--- a/content/en/configuration/security.md
+++ b/content/en/configuration/security.md
@@ -33,13 +33,8 @@ http.mediaTypes
http.urls
: (`[]string`) A slice of regular expressions matching the URLs that the `resources.GetRemote` function is allowed to access.
-[inline shortcodes]: /content-management/shortcodes/#inline
-[`os.Getenv`]: /functions/os/getenv
-[`resources.GetRemote`]: /functions/resources/getremote
-
-{{< note >}}
-Setting an allow list to the string `none` will completely disable the associated feature.
-{{< /note >}}
+> [!note]
+> Setting an allow list to the string `none` will completely disable the associated feature.
You can also override the site configuration with environment variables. For example, to block `resources.GetRemote` from accessing any URL:
@@ -49,4 +44,7 @@ export HUGO_SECURITY_HTTP_URLS=none
Learn more about [using environment variables] to configure your site.
+[`os.Getenv`]: /functions/os/getenv
+[`resources.GetRemote`]: /functions/resources/getremote
+[inline shortcodes]: /content-management/shortcodes/#inline
[using environment variables]: /configuration/introduction/#environment-variables
diff --git a/content/en/configuration/segments.md b/content/en/configuration/segments.md
index 180d6389b..0c4098770 100644
--- a/content/en/configuration/segments.md
+++ b/content/en/configuration/segments.md
@@ -8,9 +8,8 @@ keywords: []
{{< new-in 0.124.0 />}}
-{{< note >}}
-The `segments` configuration applies only to segmented rendering. While it controls when content is rendered, it doesn't restrict access to Hugo's complete object graph (sites and pages), which remains fully available.
-{{< /note >}}
+> [!note]
+> The `segments` configuration applies only to segmented rendering. While it controls when content is rendered, it doesn't restrict access to Hugo's complete object graph (sites and pages), which remains fully available.
Segmented rendering offers several advantages:
@@ -43,8 +42,6 @@ output
path
: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
-[page language]: /methods/page/language/
-
## Example
Place broad filters, such as those for language or output format, in the excludes section. For example:
@@ -77,3 +74,4 @@ hugo --renderSegments segment1,segment2
```
[`renderSegments`]: /configuration/all/#rendersegments
+[page language]: /methods/page/language/
diff --git a/content/en/content-management/build-options.md b/content/en/content-management/build-options.md
index e3bdeaab8..8c29a19b9 100644
--- a/content/en/content-management/build-options.md
+++ b/content/en/content-management/build-options.md
@@ -41,18 +41,8 @@ render
- `link`: Do not render the page to disk, but assign `Permalink` and `RelPermalink` values.
- `never`: Never render the page to disk, and exclude it from all page collections.
-[page bundles]: /content-management/page-bundles/
-[page resources]: /content-management/page-resources/
-[`Permalink`]: /methods/resource/permalink/
-[`RelPermalink`]: /methods/resource/relpermalink/
-[`Publish`]: /methods/resource/publish/
-
-{{< note >}}
-Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
-
-[`.Page.GetPage`]: /methods/page/getpage/
-[`.Site.GetPage`]: /methods/site/getpage/
-{{< /note >}}
+> [!note]
+> Any page, regardless of its build options, will always be available by using the [`.Page.GetPage`] or [`.Site.GetPage`] method.
## Example -- headless page
@@ -107,8 +97,6 @@ In the example above, note that:
Create a unpublished section whose content and resources can be included in other pages.
-[branch bundle]: /content-management/page-bundles/
-
```text
content/
├── headless/
@@ -305,3 +293,11 @@ public/
│ └── index.html
└── index.html
```
+
+[`.Page.GetPage`]: /methods/page/getpage/
+[`.Site.GetPage`]: /methods/site/getpage/
+[`Permalink`]: /methods/resource/permalink/
+[`Publish`]: /methods/resource/publish/
+[`RelPermalink`]: /methods/resource/relpermalink/
+[page bundles]: /content-management/page-bundles/
+[page resources]: /content-management/page-resources/
diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md
index 33200272d..68433f384 100644
--- a/content/en/content-management/content-adapters.md
+++ b/content/en/content-management/content-adapters.md
@@ -85,9 +85,8 @@ Returns the `Site` to which the pages will be added.
{{ .Site.Title }}
```
-{{< note >}}
-Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized".
-{{< /note >}}
+> [!note]
+> Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized".
### Store
@@ -135,11 +134,10 @@ Key|Description|Required
`path`|The page's [logical path](g) relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
`title`|The page title.|
-{{< note >}}
-While `path` is the only required field, we recommend setting `title` as well.
-
-When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`.
-{{< /note >}}
+> [!note]
+> While `path` is the only required field, we recommend setting `title` as well.
+>
+> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C` produces a logical path of `/section/a-b-c`.
## Resource map
@@ -154,11 +152,10 @@ Key|Description|Required
`path`|The resources's [logical path](g) relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
`title`|The resource title.|
-{{< note >}}
-If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource.
-
-When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`.
-{{< /note >}}
+> [!note]
+> If the `content.value` is a string Hugo creates a new resource. If the `content.value` is a resource, Hugo obtains the value from the existing resource.
+>
+> When setting the `path`, Hugo transforms the given string to a logical path. For example, setting `path` to `A B C/cover.jpg` produces a logical path of `/section/a-b-c/cover.jpg`.
## Example
diff --git a/content/en/content-management/data-sources.md b/content/en/content-management/data-sources.md
index b0ce08e41..3fc98b36a 100644
--- a/content/en/content-management/data-sources.md
+++ b/content/en/content-management/data-sources.md
@@ -16,9 +16,8 @@ The `data` directory in the root of your project may contain one or more data fi
Hugo also merges data directories from themes and modules into this single data structure, where the `data` directory in the root of your project takes precedence.
-{{< note >}}
-Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead.
-{{< /note >}}
+> [!note]
+> Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead.
Theme and module authors may wish to namespace their data files to prevent collisions. For example:
@@ -29,14 +28,11 @@ project/
└── foo.json
```
-{{< note >}}
-Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources.
-{{< /note >}}
+> [!note]
+> Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources.
See the documentation for the [`Data`] method on a `Site` object for details and examples.
-[`Data`]: /methods/site/data/
-
## Global resources
Use the `resources.Get` and `transform.Unmarshal` functions to access data files that exist as global resources.
@@ -111,4 +107,5 @@ Felix|cat|Malicious|7
Use [content adapters] to create new content.
+[`Data`]: /methods/site/data/
[content adapters]: /content-management/content-adapters/
diff --git a/content/en/content-management/diagrams.md b/content/en/content-management/diagrams.md
index b771779a8..0070ced59 100644
--- a/content/en/content-management/diagrams.md
+++ b/content/en/content-management/diagrams.md
@@ -9,9 +9,6 @@ keywords: []
Hugo natively supports [GoAT] diagrams with an [embedded code block render hook]. This means that this code block:
-[GoAT]: https://github.com/bep/goat
-[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
-
````txt
```goat
. . . .--- 1 .-- 1 / 1
@@ -42,8 +39,6 @@ Will be rendered as:
Hugo does not provide a built-in template for Mermaid diagrams. Create your own using a [code block render hook]:
-[code block render hook]: /render-hooks/code-blocks/
-
```go-html-template {file="layouts/_default/_markup/render-codeblock-mermaid.html" copy=true}
{{ .Inner | htmlEscape | safeHTML }}
@@ -259,3 +254,7 @@ Created from
│LITERAL = """" character { character } """" .│
└────────────────────────────────────────────────┘
```
+
+[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/content/en/content-management/formats.md b/content/en/content-management/formats.md
index 08f0a2432..1acaae063 100644
--- a/content/en/content-management/formats.md
+++ b/content/en/content-management/formats.md
@@ -58,7 +58,7 @@ Hugo provides custom Markdown features including:
[Markdown]: https://daringfireball.net/projects/markdown/
[Mathematics]: /content-management/mathematics/
[Render hooks]: /render-hooks/introduction/
-[configure goldmark]:/configuration/markup/#goldmark
+[configure goldmark]: /configuration/markup/#goldmark
### HTML
diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md
index 30110c604..8bfbd1acc 100644
--- a/content/en/content-management/front-matter.md
+++ b/content/en/content-management/front-matter.md
@@ -39,11 +39,10 @@ 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 >}}
-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] section for details.
+> [!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] section for details.
[parameters]: #parameters
-{{< /note >}}
aliases
: (`string array`) An array of one or more aliases, where each alias is a relative URL that will redirect the browser to the current location. Access these values from a template using the [`Aliases`] method on a `Page` object. See the [aliases] section for details.
@@ -205,11 +204,6 @@ Parameter|Data type|Used by these embedded templates
The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
-[`opengraph.html`]: {{% eturl opengraph %}}
-[`schema.html`]: {{% eturl schema %}}
-[`twitter_cards.html`]: {{% eturl twitter_cards %}}
-[embedded templates]: /templates/embedded/
-
## Taxonomies
Classify content by adding taxonomy terms to front matter. For example, with this site configuration:
@@ -320,11 +314,10 @@ path = '{/films/**}'
kind = 'page'
{{< /code-toggle >}}
-{{< note >}}
-For multilingual sites, defining cascade values in your site configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/).
-
-If you choose to define cascade values in front matter for a multilingual site, you must create a corresponding home, section, taxonomy, or term page for every language.
-{{< /note >}}
+> [!note]
+> For multilingual sites, defining cascade values in your site configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/).
+>
+> If you choose to define cascade values in front matter for a multilingual site, you must create a corresponding home, section, taxonomy, or term page for every language.
## Emacs Org Mode
@@ -362,3 +355,8 @@ To override the default time zone, set the [`timeZone`](/configuration/all/#time
1. The time zone offset in the date/time string
1. The time zone specified in your site configuration
1. The `Etc/UTC` time zone
+
+[`opengraph.html`]: {{% eturl opengraph %}}
+[`schema.html`]: {{% eturl schema %}}
+[`twitter_cards.html`]: {{% eturl twitter_cards %}}
+[embedded templates]: /templates/embedded/
diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md
index 3549f35e6..7fd20a63a 100644
--- a/content/en/content-management/image-processing/index.md
+++ b/content/en/content-management/image-processing/index.md
@@ -100,17 +100,15 @@ Example 4: Skips rendering if there's problem accessing a remote resource.
The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods.
-{{< note >}}
-Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the `Exif` method with the _original_ image to extract EXIF metadata from JPEG, PNG, TIFF, and WebP images.
-{{< /note >}}
+> [!note]
+> Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the `Exif` method with the _original_ image to extract EXIF metadata from JPEG, PNG, TIFF, and WebP images.
### Process
{{< new-in 0.119.0 />}}
-{{< note >}}
-The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
-{{< /note >}}
+> [!note]
+> The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
Process processes the image with the given specification. The specification can contain an optional action, one of `resize`, `crop`, `fit` or `fill`. This means that you can use this method instead of [`Resize`], [`Fit`], [`Fill`], or [`Crop`].
@@ -248,8 +246,6 @@ You may also access EXIF fields individually, using the [`lang.FormatNumber`] fu
Date
: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
-[time.Format]: /functions/time/format/
-
Lat
: (`float64`) Returns the GPS latitude in degrees.
@@ -344,8 +340,6 @@ The default value is 75. You may override the default value in the [site configu
Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the `-preset` flag for the [`cwebp`] encoder.
-[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
-
Value|Example
:--|:--
`drawing`|Hand or line drawing with high-contrast details
@@ -434,20 +428,20 @@ hugo --gc
```
[`anchor`]: /content-management/image-processing#anchor
-[mounted]: /configuration/module/#mounts
-[page bundle]: /content-management/page-bundles/
-[`lang.FormatNumber`]: /functions/lang/formatnumber/
-[filters]: /functions/images/filter/#image-filters
-[github.com/disintegration/imaging]: https://github.com/disintegration/imaging#image-resizing
-[Smartcrop]: https://github.com/muesli/smartcrop#smartcrop
-[Exif]: https://en.wikipedia.org/wiki/Exif
-[`Process`]: #process
[`Colors`]: #colors
[`Crop`]: #crop
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
[`Exif`]: #exif
[`Fill`]: #fill
[`Filter`]: #filter
[`Fit`]: #fit
+[`lang.FormatNumber`]: /functions/lang/formatnumber/
+[`Process`]: #process
[`Resize`]: #resize
-[site configuration]: /configuration/imaging/
+[`time.Format`]: /functions/time/format/
[`with`]: /functions/go-template/with/
+[EXIF]: https://en.wikipedia.org/wiki/Exif
+[filters]: /functions/images/filter/#image-filters
+[github.com/disintegration/imaging]: https://github.com/disintegration/imaging#image-resizing
+[site configuration]: /configuration/imaging/
+[Smartcrop]: https://github.com/muesli/smartcrop#smartcrop
diff --git a/content/en/content-management/mathematics.md b/content/en/content-management/mathematics.md
index 50f33af4e..e0c8ba4d0 100644
--- a/content/en/content-management/mathematics.md
+++ b/content/en/content-management/mathematics.md
@@ -36,13 +36,10 @@ 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 >}}
-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 site.
-
-The first approach is described below.
-
-[`transform.ToMath`]: /functions/transform/tomath/
-{{< /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 site.
+>
+> The first approach is described below.
## Setup
@@ -66,11 +63,10 @@ math = true
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 site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3].
-{{< 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 will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
-
-See the [inline delimiters](#inline-delimiters) section for details.
-{{< /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 will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
+>
+> See the [inline delimiters](#inline-delimiters) section for details.
To disable passthrough of inline snippets, omit the `inline` key from the configuration:
@@ -171,19 +167,17 @@ If you add the `$...$` delimiter pair to your configuration and JavaScript, you
A \\$5 bill _saved_ is a \\$5 bill _earned_.
```
-{{< 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](https://github.com/KaTeX/KaTeX/issues/437).
-{{< /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](https://github.com/KaTeX/KaTeX/issues/437).
## Engines
MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.11.
-{{< 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](https://github.com/KaTeX/KaTeX/issues/437).
-
-See the [inline delimiters](#inline-delimiters) section for details.
-{{< /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](https://github.com/KaTeX/KaTeX/issues/437).
+>
+>See the [inline delimiters](#inline-delimiters) section for details.
To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
@@ -235,10 +229,10 @@ $$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
As shown in [Step 2] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs).
+[`transform.ToMath`]: /functions/transform/tomath/
[KaTeX]: https://katex.org/
[LaTeX]: https://www.latex-project.org/
[MathJax]: https://www.mathjax.org/
-[Step 1]: #step-1
+[passthrough extension]: /configuration/markup/#passthrough
[Step 2]: #step-2
[Step 3]: #step-3
-[passthrough extension]: /configuration/markup/#passthrough
diff --git a/content/en/content-management/menus.md b/content/en/content-management/menus.md
index 2defcfd12..ab1bcbfa1 100644
--- a/content/en/content-management/menus.md
+++ b/content/en/content-management/menus.md
@@ -22,9 +22,8 @@ There are three ways to define menu entries:
1. In front matter
1. In site configuration
-{{< note >}}
-Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
-{{< /note >}}
+> [!note]
+> Although you can use these methods in combination when defining a menu, the menu will be easier to conceptualize and maintain if you use one method throughout the site.
## Define automatically
@@ -56,9 +55,8 @@ menus = ['main','footer']
Access the entry with `site.Menus.main` and `site.Menus.footer` in your templates. See [menu templates] for details.
-{{< note >}}
-The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
-{{< /note >}}
+> [!note]
+> The configuration key in the examples above is `menus`. The `menu` (singular) configuration key is an alias for `menus`.
### Properties
@@ -94,7 +92,6 @@ Hugo provides two methods to localize your menu entries. See [multilingual].
See [menu templates].
-[localize]: /content-management/multilingual/#menus
[menu templates]: /templates/menu/
[multilingual]: /content-management/multilingual/#menus
[template]: /templates/menu/
diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md
index 745e5917b..d419f4381 100644
--- a/content/en/content-management/multilingual.md
+++ b/content/en/content-management/multilingual.md
@@ -29,9 +29,8 @@ Their language is __assigned__ according to the language code added as a __suffi
By having the same **path and base file name**, the content pieces are __linked__ together as translated pages.
-{{< note >}}
-If a file has no language code, it will be assigned the default language.
-{{< /note >}}
+> [!note]
+> If a file has no language code, it will be assigned the default language.
### Translation by content directory
@@ -88,9 +87,6 @@ To localize URLs:
- For a regular page, set either [`slug`] or [`url`] in front matter
- For a section page, set [`url`] in front matter
-[`slug`]: /content-management/urls/#slug
-[`url`]: /content-management/urls/#url
-
For example, a French translation can have its own localized slug.
{{< code-toggle file=content/about.fr.md fm=true >}}
@@ -111,9 +107,8 @@ If, across the linked bundles, two or more files share the same basename, only o
- File from current language bundle, if present.
- First file found across bundles by order of language `Weight`.
-{{< note >}}
-Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
-{{< /note >}}
+> [!note]
+> Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
## Reference translated content
@@ -152,8 +147,6 @@ The above also uses the [`i18n` function][i18func] described in the next section
See the [`lang.Translate`] template function.
-[`lang.Translate`]: /functions/lang/translate
-
## Localization
The following localization examples assume your site's primary language is English, with translations to French and German.
@@ -335,8 +328,6 @@ pageRef = '/services'
weight = 20
{{< /code-toggle >}}
-[configuration directory]: /configuration/introduction/#configuration-directory
-
### Use translation tables
When rendering the text that appears in menu each entry, the [example menu template] does this:
@@ -374,20 +365,14 @@ products = 'Produkte'
services = 'Leistungen'
{{< / code-toggle >}}
-[example menu template]: /templates/menu/#example
-[automatically]: /content-management/menus/#define-automatically
-[in front matter]: /content-management/menus/#define-in-front-matter
-[in site configuration]: /content-management/menus/#define-in-site-configuration
-
## Missing translations
If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown.
While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation.
-{{< note >}}
-Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments.
-{{< /note >}}
+> [!note]
+> Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments.
For merging of content from other languages (i.e. missing content translations), see [lang.Merge].
@@ -423,18 +408,22 @@ hugo new content content/en/post/test.md
hugo new content content/de/post/test.md
```
-[`abslangurl`]: /functions/urls/abslangurl/
+[`absLangURL`]: /functions/urls/abslangurl/
+[`lang.Translate`]: /functions/lang/translate
+[`relLangURL`]: /functions/urls/rellangurl/
+[`slug`]: /content-management/urls/#slug
+[`time.Format`]: /functions/time/format/
+[`url`]: /content-management/urls/#url
+[automatically]: /content-management/menus/#define-automatically
[config]: /configuration/
-[go-i18n-source]: https://github.com/nicksnyder/go-i18n
-[go-i18n]: https://github.com/nicksnyder/go-i18n
-[Hugo Multilingual Part 1: Content translation]: https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/
+[configuration directory]: /configuration/introduction/#configuration-directory
+[example menu template]: /templates/menu/#example
[i18func]: /functions/lang/translate/
+[in front matter]: /content-management/menus/#define-in-front-matter
+[in site configuration]: /content-management/menus/#define-in-site-configuration
[lang.FormatAccounting]: /functions/lang/formataccounting/
[lang.FormatCurrency]: /functions/lang/formatcurrency/
[lang.FormatNumber]: /functions/lang/formatnumber/
[lang.FormatNumberCustom]: /functions/lang/formatnumbercustom/
[lang.FormatPercent]: /functions/lang/formatpercent/
[lang.Merge]: /functions/lang/merge/
-[menus]: /content-management/menus/
-[`rellangurl`]: /functions/urls/rellangurl/
-[`time.Format`]: /functions/time/format/
diff --git a/content/en/content-management/organization/index.md b/content/en/content-management/organization/index.md
index 1cbce5f09..a7682bfad 100644
--- a/content/en/content-management/organization/index.md
+++ b/content/en/content-management/organization/index.md
@@ -67,9 +67,8 @@ The following demonstrates the relationships between your content organization a
`_index.md` has a special role in Hugo. It allows you to add front matter and content to `home`, `section`, `taxonomy`, and `term` pages.
-{{< note >}}
-**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/methods/page/getpage).
-{{< /note >}}
+> [!note]
+> Access the content and metadata within an `_index.md` file by invoking the `GetPage` method on a `Site` or `Page` object.
You can create one `_index.md` for your home page and one in each of your content sections, taxonomies, and terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website:
@@ -147,10 +146,6 @@ A content's `path` is determined by the section's path to the file. The file `pa
The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details.
[config]: /configuration/
-[formats]: /content-management/formats/
-[front matter]: /content-management/front-matter/
-[getpage]: /methods/page/getpage/
[pretty]: /content-management/urls/#appearance
[sections]: /content-management/sections/
[single template]: /templates/types/#single
-[urls]: /content-management/urls/
diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md
index da34646aa..f6a5cf771 100644
--- a/content/en/content-management/page-bundles.md
+++ b/content/en/content-management/page-bundles.md
@@ -29,9 +29,8 @@ leaf bundle
branch bundle
: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top-level directories with or without `_index.md` files are also branch bundles. This includes the home page.
-{{< note >}}
-In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc.
-{{< /note >}}
+> [!note]
+> In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc.
## Comparison
@@ -47,12 +46,6 @@ Page bundle characteristics vary by bundle type.
| Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles |
| [Resource types](g) | `page`, `image`, `video`, etc. | all but `page` |
-[single]: /templates/types/#single
-[home]: /templates/types/#home
-[section]: /templates/types/#section
-[taxonomy]: /templates/types/#taxonomy
-[term]: /templates/types/#term
-
Files with [resource type](g) `page` include content written in Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode. In a leaf bundle, excluding the index file, these files are only accessible as page resources. In a branch bundle, these files are only accessible as content pages.
## Leaf bundles
@@ -102,9 +95,8 @@ my-other-post
another-leaf-bundle
: This leaf bundle does not contain any page resources.
-{{< note >}}
-Create leaf bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
-{{< /note >}}
+> [!note]
+> Create leaf bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
## Branch bundles
@@ -136,9 +128,8 @@ branch-bundle-1
branch-bundle-2
: This branch bundle contains an index file and a leaf bundle.
-{{< note >}}
-Create branch bundles at any depth within the `content` directory. Branch bundles may have descendants.
-{{< /note >}}
+> [!note]
+> Create branch bundles at any depth within the `content` directory. Branch bundles may have descendants.
## Headless bundles
@@ -146,4 +137,9 @@ Use [build options] in front matter to create an unpublished leaf or branch bund
[`Resources`]: /methods/page/resources/
[build options]: /content-management/build-options/
+[home]: /templates/types/#home
[page resources]: /content-management/page-resources/
+[section]: /templates/types/#section
+[single]: /templates/types/#single
+[taxonomy]: /templates/types/#taxonomy
+[term]: /templates/types/#term
diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md
index 174612594..204ca5301 100644
--- a/content/en/content-management/page-resources.md
+++ b/content/en/content-management/page-resources.md
@@ -42,12 +42,6 @@ Use any of these methods on a `Page` object to capture page resources:
Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action.
-[`Resource`]: /methods/resource
-[`Resources.ByType`]: /methods/page/resources#bytype
-[`Resources.GetMatch`]: /methods/page/resources#getmatch
-[`Resources.Get`]: /methods/page/resources#get
-[`Resources.Match`]: /methods/page/resources#match
-
The following examples assume this content structure:
```text
@@ -114,16 +108,14 @@ List the titles in the data file, and throw an error if the file does not exist.
The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm).
-{{< note >}}
-Resources of type `page` get `Title` etc. from their own front matter.
-{{< /note >}}
+> [!note]
+> Resources of type `page` get `Title` etc. from their own front matter.
name
: (`string`) Sets the value returned in `Name`.
-{{< note >}}
-The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
-{{< /note >}}
+> [!note]
+> The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
title
: (`string`) Sets the value returned in `Title`
@@ -167,9 +159,8 @@ From the example above:
- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`.
- Every docx in the bundle will receive the `word` icon.
-{{< note >}}
-The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
-{{< /note >}}
+> [!note]
+> The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
### The `:counter` placeholder in `name` and `title`
@@ -204,11 +195,8 @@ the `Name` and `Title` will be assigned to the resource files as follows:
By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site.
-{{< note >}}
-This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle.
-
-[content formats]: /content-management/formats/
-{{< /note >}}
+> [!note]
+> This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle.
Consider this site configuration:
@@ -283,18 +271,12 @@ public/
This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.
-{{< note >}}
-To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method.
-
-By default, with multilingual single-host sites, Hugo enables its [embedded link render hook] and [embedded image render hook] to resolve Markdown link and image destinations.
-
-You may override the embedded render hooks as needed, provided they capture the resource as described above.
-
-[embedded link render hook]: /render-hooks/links/#default
-[embedded image render hook]: /render-hooks/images/#default
-[`Resources.Get`]: /methods/page/resources/#get
-[`RelPermalink`]: /methods/resource/relpermalink/
-{{< /note >}}
+> [!note]
+> To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method.
+>
+> By default, with multilingual single-host sites, Hugo enables its [embedded link render hook] and [embedded image render hook] to resolve Markdown link and image destinations.
+>
+> You may override the embedded render hooks as needed, provided they capture the resource as described above.
Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired:
@@ -302,3 +284,14 @@ Although duplicating shared page resources is inefficient, you can enable this f
[markup.goldmark]
duplicateResourceFiles = true
{{< /code-toggle >}}
+
+[`RelPermalink`]: /methods/resource/relpermalink/
+[`Resource`]: /methods/resource
+[`Resources.ByType`]: /methods/page/resources#bytype
+[`Resources.Get`]: /methods/page/resources#get
+[`Resources.Get`]: /methods/page/resources/#get
+[`Resources.GetMatch`]: /methods/page/resources#getmatch
+[`Resources.Match`]: /methods/page/resources#match
+[content formats]: /content-management/formats/
+[embedded image render hook]: /render-hooks/images/#default
+[embedded link render hook]: /render-hooks/links/#default
diff --git a/content/en/content-management/related-content.md b/content/en/content-management/related-content.md
index 48fd246c4..d7b18dab0 100644
--- a/content/en/content-management/related-content.md
+++ b/content/en/content-management/related-content.md
@@ -37,8 +37,6 @@ namedSlices
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.
-[`keyVals`]: /functions/collections/keyvals/
-
A fictional example using all of the above options:
```go-html-template
@@ -51,9 +49,8 @@ A fictional example using all of the above options:
}}
```
-{{< note >}}
-We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
-{{< /note >}}
+> [!note]
+> We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 different methods: `Related`, `RelatedTo` and `RelatedIndices`. Now we have only one method: `Related`. The old methods are still available but deprecated. Also see [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature.
## Index content headings
@@ -101,3 +98,5 @@ weight = 80
## Configuration
See [configure related content](/configuration/related-content/).
+
+[`keyVals`]: /functions/collections/keyvals/
diff --git a/content/en/content-management/sections.md b/content/en/content-management/sections.md
index 6fbe7aacc..f7a2296f5 100644
--- a/content/en/content-management/sections.md
+++ b/content/en/content-management/sections.md
@@ -9,13 +9,7 @@ aliases: [/content/sections/]
## Overview
-A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](g). Section templates receive one or more page [collections](g) in [context](g).
-
-{{< note >}}
-Although top-level directories without `_index.md` files are sections, we recommend creating `_index.md` files in _all_ sections.
-{{< /note >}}
-
-A typical site consists of one or more sections. For example:
+{{% glossary-term "section" %}}
```text
content/
@@ -72,9 +66,6 @@ With the file structure from the [example above](#overview):
1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `RegularPagesRecursive` method instead of the `Pages` method in the list template.
1. All directories in the products section have list pages; each directory is a section.
-[`Pages`]: /methods/page/pages/
-[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
-
## Template selection
Hugo has a defined [lookup order] to determine which template to use when rendering a page. The [lookup rules] consider the top-level section name; subsection names are not considered when selecting a template.
@@ -95,9 +86,6 @@ Content directory|Single template
If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter.
-[lookup rules]: /templates/lookup-order/#lookup-rules
-[lookup order]: /templates/lookup-order/
-
## Ancestors and descendants
A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview):
@@ -147,9 +135,5 @@ Hugo renders this, where each breadcrumb is a link to the corresponding page:
Home » Products » Product 1 » Benefits » Benefit 1
```
-[archetype]: /content-management/archetypes/
-[content type]: /content-management/types/
-[directory structure]: /getting-started/directory-structure/
-[section templates]: /templates/types/#section
-[leaf bundles]: /content-management/page-bundles/#leaf-bundles
-[branch bundles]: /content-management/page-bundles/#branch-bundles
+[lookup order]: /templates/lookup-order/
+[lookup rules]: /templates/lookup-order/#lookup-rules
diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md
index 31e36826b..9022d5594 100644
--- a/content/en/content-management/shortcodes.md
+++ b/content/en/content-management/shortcodes.md
@@ -36,8 +36,6 @@ Then call the shortcode from within markup:
Learn more about creating shortcodes in the [shortcode templates] section.
-[shortcode templates]: /templates/shortcode/
-
## Inline
An inline shortcode is a shortcode template defined within content.
@@ -55,8 +53,6 @@ For more information see [configure security](/configuration/security).
The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string].
-[layout string]: /functions/time/format/#layout-string
-
```text {file="content/example.md"}
Today is
{{}}
@@ -75,11 +71,8 @@ In the example above, the inline shortcode is executed twice: once upon definiti
Inline shortcodes process their inner content within the same context as regular shortcode templates, allowing you to use any available [shortcode method].
-[shortcode method]: /templates/shortcode/#methods
-
-{{< note >}}
-You cannot [nest](#nesting) inline shortcodes.
-{{< /note >}}
+> [!note]
+> You cannot [nest](#nesting) inline shortcodes.
Learn more about creating shortcodes in the [shortcode templates] section.
@@ -117,10 +110,6 @@ Or use the self-closing syntax with a trailing slash to pass the text as an argu
{{}}
```
-[`details`]: /shortcodes/details
-[`instagram`]: /shortcodes/instagram
-[`qr`]: /shortcodes/qr
-
Refer to each shortcode's documentation for specific usage instructions and available arguments.
### Arguments
@@ -129,8 +118,6 @@ Shortcode arguments can be either _named_ or _positional_.
Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`] shortcode. The `src` argument, for instance, is required.
-[`figure`]: /shortcodes/figure
-
```text
{{}}
```
@@ -188,8 +175,6 @@ Standard|`{{}} ## Section 2 {{}}`
Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the [`TableOfContents`] method on the `Page` object.
-[`TableOfContents`]: /methods/page/tableofcontents/
-
#### Standard notation
With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the `TableOfContents` method on the `Page` object.
@@ -234,4 +219,12 @@ Shortcodes (excluding [inline](#inline) shortcodes) can be nested, creating pare
The [shortcode templates][nesting] section provides a detailed explanation and examples.
+[`details`]: /shortcodes/details
+[`figure`]: /shortcodes/figure
+[`instagram`]: /shortcodes/instagram
+[`qr`]: /shortcodes/qr
+[`TableOfContents`]: /methods/page/tableofcontents/
+[layout string]: /functions/time/format/#layout-string
[nesting]: /templates/shortcode/#nesting
+[shortcode method]: /templates/shortcode/#methods
+[shortcode templates]: /templates/shortcode/
diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md
index 8b6ab27d1..c9febb849 100644
--- a/content/en/content-management/urls.md
+++ b/content/en/content-management/urls.md
@@ -37,14 +37,10 @@ https://example.org/posts/my-first-post/
Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
-{{< note >}}
-Hugo does not sanitize the `url` front matter field, allowing you to generate:
-
-- File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system.
-- URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL.
-
-[reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
-{{< /note >}}
+> [!note]
+> Hugo does not sanitize the `url` front matter field, allowing you to generate:
+> - File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system.
+> - URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL.
If you set both `slug` and `url` in front matter, the `url` value takes precedence.
@@ -101,8 +97,6 @@ https://example.org/articles/my-first-article.html
With monolingual sites, `url` values with or without a leading slash are relative to the [`baseURL`]. With multilingual sites, `url` values with a leading slash are relative to the `baseURL`, and `url` values without a leading slash are relative to the `baseURL` plus the language prefix.
-[`baseURL`]: /configuration/all/#baseurl
-
Site type|Front matter `url`|Resulting URL
:--|:--|:--
monolingual|`/about`|`https://example.org/about/`
@@ -142,11 +136,9 @@ Hugo provides two mutually exclusive configuration options to alter URLs _after_
#### Canonical URLs
-{{< note >}}
-This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release].
-
-[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733
-{{< /note >}}
+> [!caution]
+> This is a legacy configuration option, superseded by template functions and Markdown render hooks, and will likely be [removed in a future release].
+{class="!mt-6"}
If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then prepends the `baseURL` to create absolute URLs.
@@ -165,9 +157,9 @@ canonifyURLs = true
#### Relative URLs
-{{< note >}}
-Do not enable this option unless you are creating a serverless site, navigable via the file system.
-{{< /note >}}
+> [!caution]
+> Do not enable this option unless you are creating a serverless site, navigable via the file system.
+{class="!mt-6"}
If enabled, Hugo performs a search and replace _after_ it renders the page. It searches for site-relative URLs (those with a leading slash) associated with `action`, `href`, `src`, `srcset`, and `url` attributes. It then transforms the URL to be relative to the current page.
@@ -267,4 +259,7 @@ Permalink
Page
: The Page data for the page being aliased.
+[`baseURL`]: /configuration/all/#baseurl
+[removed in a future release]: https://github.com/gohugoio/hugo/issues/4733
+[reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
[source code]: {{% eturl alias %}}
diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md
index b4e669772..cc2fc7902 100644
--- a/content/en/contribute/development.md
+++ b/content/en/contribute/development.md
@@ -27,16 +27,6 @@ If there is sufficient interest, [create a proposal]. Do not submit a pull reque
For a complete guide to contributing to Hugo, see the [Contribution Guide].
-[bugs]: https://github.com/gohugoio/hugo/issues?q=is%3Aopen+is%3Aissue+label%3ABug
-[contributing]: CONTRIBUTING.md
-[create a proposal]: https://github.com/gohugoio/hugo/issues/new?labels=Proposal%2C+NeedsTriage&template=feature_request.md
-[documentation repository]: https://github.com/gohugoio/hugoDocs
-[documentation]: /documentation
-[forum]: https://discourse.gohugo.io
-[issue queue]: https://github.com/gohugoio/hugo/issues
-[themes]: https://themes.gohugo.io/
-[contribution guide]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md
-
## Prerequisites
To build the extended or extended/deploy edition from source you must:
@@ -46,21 +36,13 @@ To build the extended or extended/deploy edition from source you must:
1. Install a C compiler, either [GCC] or [Clang]
1. Update your `PATH` environment variable as described in the [Go documentation]
-[Clang]: https://clang.llvm.org/
-[GCC]: https://gcc.gnu.org/
-[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
-[Go documentation]: https://go.dev/doc/code#Command
-[Go]: https://go.dev/doc/install
-
-{{< note >}}
-See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
-{{< /note >}}
+> [!note]
+> See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
## GitHub workflow
-{{< note >}}
-This section assumes that you have a working knowledge of Go, Git and GitHub, and are comfortable working on the command line.
-{{< /note >}}
+> [!note]
+> This section assumes that you have a working knowledge of Go, Git and GitHub, and are comfortable working on the command line.
Use this workflow to create and submit pull requests.
@@ -157,10 +139,6 @@ Visit the [project repository] and create a pull request (PR).
A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
-[commit message guidelines]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md#git-commit-message-guidelines
-[issues]: https://github.com/gohugoio/hugo/issues
-[project repository]: https://github.com/gohugoio/hugo/
-
## Building from source
You can build, install, and test Hugo at any point in its development history. The examples below build and install the extended edition of Hugo.
@@ -188,3 +166,20 @@ To build and install at a specific commit:
```sh
CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@0851c17
```
+
+[bugs]: https://github.com/gohugoio/hugo/issues?q=is%3Aopen+is%3Aissue+label%3ABug
+[Clang]: https://clang.llvm.org/
+[commit message guidelines]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md#git-commit-message-guidelines
+[Contribution Guide]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md
+[create a proposal]: https://github.com/gohugoio/hugo/issues/new?labels=Proposal%2C+NeedsTriage&template=feature_request.md
+[documentation]: /documentation
+[documentation repository]: https://github.com/gohugoio/hugoDocs
+[forum]: https://discourse.gohugo.io
+[GCC]: https://gcc.gnu.org/
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
+[Go documentation]: https://go.dev/doc/code#Command
+[issue queue]: https://github.com/gohugoio/hugo/issues
+[issues]: https://github.com/gohugoio/hugo/issues
+[project repository]: https://github.com/gohugoio/hugo/
+[themes]: https://themes.gohugo.io/
diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md
index e1f256d7b..62bf12772 100644
--- a/content/en/contribute/documentation.md
+++ b/content/en/contribute/documentation.md
@@ -19,8 +19,6 @@ We welcome corrections and improvements to the documentation. The documentation
Follow Google's [developer documentation style guide].
-[developer documentation style guide]: https://developers.google.com/style
-
### Markdown
Adhere to these Markdown conventions:
@@ -28,7 +26,7 @@ Adhere to these Markdown conventions:
- Use [ATX] headings (levels 2-4), not [setext] headings.
- Use [fenced code blocks], not [indented code blocks].
- Use hyphens, not asterisks, for unordered [list items].
-- Use the [note shortcode](#note) instead of blockquotes or bold text for emphasis.
+- Use the [callouts](#callouts) instead bold text for emphasis.
- Do not mix [raw HTML] within Markdown.
- Do not use bold text in place of a heading or description term (`dt`).
- Remove consecutive blank lines.
@@ -99,17 +97,13 @@ Minimize adverbs.
No → Hugo is extremely fast.\
Yes → Hugo is fast.
-{{< note >}}
-"It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995).
-{{< /note >}}
+> [!note]
+> "It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995).
### Function and method descriptions
Start descriptions in the functions and methods sections with "Returns" or "Reports whether" for boolean values.
-[functions]: /functions
-[methods]: /methods
-
### File paths and names
Enclose directory names, file names, and file paths in backticks, except when used in:
@@ -124,15 +118,13 @@ Enclose directory names, file names, and file paths in backticks, except when us
Other best practices:
- Introduce lists with a sentence or phrase, not directly under a heading.
-- Avoid bold text; use the [note shortcode](#note) for emphasis.
+- Avoid bold text; use [callouts](#callouts) for emphasis.
- Do not put description terms (`dt`) in backticks unless syntactically necessary.
- Do not use Hugo's `ref` or `relref` shortcodes.
- Prioritize current best practices over multiple options or historical information.
- Use short, focused code examples.
- Use [basic english] where possible for a global audience.
-[basic english]: https://simple.wikipedia.org/wiki/Basic_English
-
## Front matter fields
This site uses the front matter fields listed in the table below.
@@ -177,8 +169,6 @@ Seq|Field|Description|Required
When available, the "See also" sidebar displays related pages using Hugo's [related content] feature, based on front matter keywords. We ensure consistent keyword usage by validating them against `data/keywords.yaml` during the build process. If a keyword is not found, you'll be alerted and must either modify the keyword or update the data file. This validation process helps to refine the related content for better results.
-[related content]: /content-management/related-content/
-
If the title in the "See also" sidebar is ambiguous or the same as another page, you can define an alternate title in the front matter:
{{< code-toggle file=hugo >}}
@@ -189,10 +179,9 @@ altTitle = "Whatever you want"
{{< /code-toggle >}}
Use of the alternate title is limited to the "See also" sidebar.
-{{< note >}}
-Think carefully before setting the `altTitle`. Use it only when absolutely necessary.
-{{< /note >}}
+> [!note]
+> Think carefully before setting the `altTitle`. Use it only when absolutely necessary.
## Code examples
@@ -269,6 +258,50 @@ draft = false
{{}}
```
+## Callouts
+
+Also known as admonitions, use callouts to visually highlight important information. The type (e.g., NOTE, TIP) is case-insensitive.
+
+```text
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+```
+
+> [!NOTE]
+> Useful information that users should know, even when skimming content.
+
+```text
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+```
+
+> [!TIP]
+> Helpful advice for doing things better or more easily.
+
+```text
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+```
+
+> [!IMPORTANT]
+> Key information users need to know to achieve their goal.
+
+```text
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+```
+
+> [!WARNING]
+> Urgent info that needs immediate user attention to avoid problems.
+
+```text
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+```
+
+> [!CAUTION]
+> Advises about risks or negative outcomes of certain actions.
+
## Shortcodes
These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
@@ -358,18 +391,6 @@ This is a new feature.
{{}}
```
-### note
-
-Use the `note` shortcode to call attention to important content:
-
-```text
-{{}}
-Use the [`math.Mod`] function to control...
-
-[`math.Mod`]: /functions/math/mod/
-{{}}
-```
-
## New features
Use the [new-in shortcode](#new-in) to indicate a new feature:
@@ -402,9 +423,8 @@ Set the `expiryDate` to two years from the date of deprecation, and add a brief
## GitHub workflow
-{{< note >}}
-This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line.
-{{< /note >}}
+> [!note]
+> This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line.
Use this workflow to create and submit pull requests.
@@ -467,9 +487,9 @@ Visit the [documentation repository] and create a pull request (PR).
A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
[ATX]: https://spec.commonmark.org/0.30/#atx-headings
-[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/
[basic english]: https://simple.wikipedia.org/wiki/Basic_English
-[code examples]: #code-examples
+[basic english]: https://simple.wikipedia.org/wiki/Basic_English
+[developer documentation style guide]: https://developers.google.com/style
[documentation repository]: https://github.com/gohugoio/hugoDocs/
[fenced code blocks]: https://spec.commonmark.org/0.30/#fenced-code-blocks
[glossary]: /quick-reference/glossary/
@@ -478,4 +498,5 @@ A project maintainer will review your PR and may request changes. You may delete
[list items]: https://spec.commonmark.org/0.30/#list-items
[project repository]: https://github.com/gohugoio/hugo
[raw HTML]: https://spec.commonmark.org/0.30/#raw-html
+[related content]: /content-management/related-content/
[setext]: https://spec.commonmark.org/0.30/#setext-heading
diff --git a/content/en/functions/cast/ToInt.md b/content/en/functions/cast/ToInt.md
index 350713a9e..4ede69229 100644
--- a/content/en/functions/cast/ToInt.md
+++ b/content/en/functions/cast/ToInt.md
@@ -44,8 +44,7 @@ With a hexadecimal (base 16) input:
{{ int "0x11" }} → 17 (int)
```
-{{< note >}}
-Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros:
+> [!note]
+> Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros:
`{{ strings.TrimLeft "0" "0011" | int }} → 11`
-{{< /note >}}
diff --git a/content/en/functions/collections/Complement.md b/content/en/functions/collections/Complement.md
index a73e3d4a6..ce810dc00 100644
--- a/content/en/functions/collections/Complement.md
+++ b/content/en/functions/collections/Complement.md
@@ -21,11 +21,8 @@ To find the elements within `$c3` that do not exist in `$c1` or `$c2`:
{{ complement $c1 $c2 $c3 }} → [1 2]
```
-{{< note >}}
-Make your code simpler to understand by using a [chained pipeline]:
-
-[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines
-{{< /note >}}
+> [!note]
+> Make your code simpler to understand by using a [chained pipeline]:
```go-html-template
{{ $c3 | complement $c1 $c2 }} → [1 2]
@@ -52,11 +49,8 @@ To list everything except blog articles (`blog`) and frequently asked questions
{{ end }}
```
-{{< note >}}
-Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
-
-[`where`]: /functions/collections/where/
-{{< /note >}}
+> [!note]
+> Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
```go-html-template
{{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }}
@@ -74,4 +68,6 @@ In this example we use the `complement` function to remove [stop words] from a s
{{ delimit $filtered " " }} → The quick brown fox jumps lazy dog
```
+[`where`]: /functions/collections/where/
+[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines
[stop words]: https://en.wikipedia.org/wiki/Stop_word
diff --git a/content/en/functions/collections/Delimit.md b/content/en/functions/collections/Delimit.md
index b9a71b506..9d09620aa 100644
--- a/content/en/functions/collections/Delimit.md
+++ b/content/en/functions/collections/Delimit.md
@@ -21,9 +21,8 @@ Delimit a slice:
Delimit a map:
-{{< note >}}
-The `delimit` function sorts maps by key, returning the values.
-{{< /note >}}
+> [!note]
+> The `delimit` function sorts maps by key, returning the values.
```go-html-template
{{ $m := dict "b" 2 "a" 1 "c" 3 }}
diff --git a/content/en/functions/collections/IsSet.md b/content/en/functions/collections/IsSet.md
index 8bc9e6837..5457df5d4 100644
--- a/content/en/functions/collections/IsSet.md
+++ b/content/en/functions/collections/IsSet.md
@@ -38,6 +38,5 @@ But if the value of `showHeroImage` is `false`, we can't use either `if` or `wit
{{ end }}
```
-{{< note >}}
-When using the `isset` function you must reference the key using lower case. See the previous example.
-{{< /note >}}
+> [!note]
+> When using the `isset` function you must reference the key using lower case. See the previous example.
diff --git a/content/en/functions/collections/Merge.md b/content/en/functions/collections/Merge.md
index e4de6d6f3..c9998be39 100644
--- a/content/en/functions/collections/Merge.md
+++ b/content/en/functions/collections/Merge.md
@@ -63,6 +63,5 @@ Example 4
{{ $merged.z.a }} → huey
```
-{{< note >}}
-Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append).
-{{< /note >}}
+> [!note]
+> Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append).
diff --git a/content/en/functions/collections/Seq.md b/content/en/functions/collections/Seq.md
index efae0b5fd..1431061e4 100644
--- a/content/en/functions/collections/Seq.md
+++ b/content/en/functions/collections/Seq.md
@@ -32,6 +32,5 @@ A contrived example of iterating over a sequence of integers:
{{ $product }} → 24
```
-{{< note >}}
-The slice created by the `seq` function is limited to 2000 elements.
-{{< /note >}}
+> [!note]
+> The slice created by the `seq` function is limited to 2000 elements.
diff --git a/content/en/functions/collections/Sort.md b/content/en/functions/collections/Sort.md
index 0728dfabf..67e5de5cb 100644
--- a/content/en/functions/collections/Sort.md
+++ b/content/en/functions/collections/Sort.md
@@ -61,9 +61,8 @@ firstName = "Jean"
lastName = "Valjean"
{{< /code-toggle >}}
-{{< note >}}
-When sorting maps, the `KEY` argument must be lowercase.
-{{< /note >}}
+> [!note]
+> When sorting maps, the `KEY` argument must be lowercase.
### Ascending order {#map-ascending-order}
@@ -137,11 +136,8 @@ After sorting:
## Sort a page collection
-{{< note >}}
-Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well.
-
-[sorting and grouping methods]: /methods/pages/
-{{< /note >}}
+> [!note]
+> Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well.
In this contrived example, sort the site's regular pages by `.Type` in descending order:
@@ -150,3 +146,5 @@ In this contrived example, sort the site's regular pages by `.Type` in descendin
{{ end }}
```
+
+[sorting and grouping methods]: /methods/pages/
diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md
index 05dafe3c9..0a0d4eeb6 100644
--- a/content/en/functions/collections/Where.md
+++ b/content/en/functions/collections/Where.md
@@ -91,9 +91,8 @@ Use any of the following logical operators:
: {{< new-in 0.116.0 />}}
: (`bool`) Reports whether the given field value matches the regular expression specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression.
-{{< note >}}
-The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.
-{{< /note >}}
+> [!note]
+> The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.
## String comparison
@@ -156,7 +155,7 @@ To return a collection of pages where the "color" page parameter is neither "red
## Intersection comparison
-Compare a [`slice`] to a [`slice`], returning collection elements with common values. This is frequently used when comparing taxonomy terms.
+Compare a `slice` to a `slice`, returning collection elements with common values. This is frequently used when comparing taxonomy terms.
For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance":
@@ -179,9 +178,8 @@ To return a collection of pages where the "author" page parameter begins with ei
{{% include "/_common/functions/regular-expressions.md" %}}
-{{< note >}}
-Use the `like` operator to compare string values. Comparing other data types will result in an empty collection.
-{{< /note >}}
+> [!note]
+> Use the `like` operator to compare string values. Comparing other data types will result in an empty collection.
## Date comparison
@@ -189,12 +187,6 @@ Use the `like` operator to compare string values. Comparing other data types wil
There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons.
-[`date`]: /methods/page/date/
-[`publishdate`]: /methods/page/publishdate/
-[`lastmod`]: /methods/page/lastmod/
-[`expirydate`]: /methods/page/expirydate/
-[`time.Time`]: https://pkg.go.dev/time#Time
-
For example, to return a collection of pages that were created before the current year:
```go-html-template
@@ -206,9 +198,8 @@ For example, to return a collection of pages that were created before the curren
With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON).
-{{< note >}}
-Using TOML for pages with custom front matter dates enables precise date comparisons.
-{{< /note >}}
+> [!note]
+> Using TOML for pages with custom front matter dates enables precise date comparisons.
With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons.
@@ -273,8 +264,6 @@ These are equivalent:
Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object.
-[`MainSections`]: /methods/site/mainsections/
-
```go-html-template
{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
```
@@ -387,8 +376,6 @@ To exclude a page with an undefined field from a boolean _inequality_ test:
1. Create a collection using a nil comparison
1. Subtract the second collection from the first collection using the [`collections.Complement`] function.
-[`collections.Complement`]: /functions/collections/complement/
-
This template:
```go-html-template
@@ -428,3 +415,9 @@ Is rendered to:
Post 2
```
+
+[`collections.Complement`]: /functions/collections/complement/
+[`date`]: /methods/page/date/
+[`lastmod`]: /methods/page/lastmod/
+[`MainSections`]: /methods/site/mainsections/
+[`time.Time`]: https://pkg.go.dev/time#Time
diff --git a/content/en/functions/compare/Default.md b/content/en/functions/compare/Default.md
index 0db4e6522..f8bd06f06 100644
--- a/content/en/functions/compare/Default.md
+++ b/content/en/functions/compare/Default.md
@@ -12,15 +12,14 @@ aliases: [/functions/default]
The `default` function returns the second argument if set, else the first argument.
-{{< note >}}
-When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset.
-
-{{% include "/_common/functions/truthy-falsy.md" %}}
-
-To set a default value based on truthiness, use the [`or`] operator instead.
-
-[`or`]: /functions/go-template/or/
-{{< /note >}}
+> [!note]
+> When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset.
+>
+> The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values.
+>
+> Everything else is truthy.
+>
+> To set a default value based on truthiness, use the [`or`] operator instead.
The `default` function returns the second argument if set:
@@ -44,3 +43,5 @@ The `default` function returns the first argument if the second argument is not
{{ default 42 slice }} → 42
{{ default 42 }} → 42
```
+
+[`or`]: /functions/go-template/or/
diff --git a/content/en/functions/css/PostCSS.md b/content/en/functions/css/PostCSS.md
index 8741f7330..9cc698248 100644
--- a/content/en/functions/css/PostCSS.md
+++ b/content/en/functions/css/PostCSS.md
@@ -22,14 +22,10 @@ params:
Follow the steps below to transform CSS using any of the available [PostCSS plugins].
-[postcss plugins]: https://postcss.org/docs/postcss-plugins
-
### Step 1
Install [Node.js].
-[node.js]: https://nodejs.org/en/download
-
### Step 2
Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
@@ -50,9 +46,8 @@ module.exports = {
};
```
-{{< note >}}
-{{% include "/_common/functions/postcss-windows-warning.md" %}}
-{{< /note >}}
+> [!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 4
@@ -126,3 +121,8 @@ module.exports = {
]
}
```
+
+[#7333]: https://github.com/gohugoio/hugo/issues/7333
+[Node.js]: https://nodejs.org/en
+[PostCSS plugins]: https://postcss.org/docs/postcss-plugins
+[this example]: https://github.com/postcss/postcss-load-config#packagejson
diff --git a/content/en/functions/data/GetCSV.md b/content/en/functions/data/GetCSV.md
index 305021639..07de1d540 100644
--- a/content/en/functions/data/GetCSV.md
+++ b/content/en/functions/data/GetCSV.md
@@ -36,11 +36,10 @@ Access the data with either of the following:
{{ $data := getCSV "," "other-files/" "pets.csv" }}
```
-{{< note >}}
-When working with local data, the file path is relative to the working directory.
-
-You must not place CSV files in the project's `data` directory.
-{{< /note >}}
+> [!note]
+> When working with local data, the file path is relative to the working directory.
+>
+> You must not place CSV files in the project's `data` directory.
Access remote data with either of the following:
diff --git a/content/en/functions/data/GetJSON.md b/content/en/functions/data/GetJSON.md
index 1965fdc6e..c6d067b65 100644
--- a/content/en/functions/data/GetJSON.md
+++ b/content/en/functions/data/GetJSON.md
@@ -36,9 +36,8 @@ Access the data with either of the following:
{{ $data := getJSON "other-files/" "books.json" }}
```
-{{< note >}}
-When working with local data, the file path is relative to the working directory.
-{{< /note >}}
+> [!note]
+> When working with local data, the file path is relative to the working directory.
Access remote data with either of the following:
diff --git a/content/en/functions/debug/Dump.md b/content/en/functions/debug/Dump.md
index 4cba6f66d..67b322b20 100644
--- a/content/en/functions/debug/Dump.md
+++ b/content/en/functions/debug/Dump.md
@@ -30,6 +30,5 @@ params:
]
```
-{{< note >}}
-Output from this function may change from one release to the next. Use for debugging only.
-{{< /note >}}
+> [!note]
+> Output from this function may change from one release to the next. Use for debugging only.
diff --git a/content/en/functions/diagrams/Goat.md b/content/en/functions/diagrams/Goat.md
index 6b7dc0019..aed0ca8fa 100644
--- a/content/en/functions/diagrams/Goat.md
+++ b/content/en/functions/diagrams/Goat.md
@@ -13,9 +13,6 @@ params:
Useful in a [code block render hook], the `diagram.Goat` function converts ASCII art to an SVG diagram, returning a [GoAT] diagram object with the following methods:
-[GoAT]: https://github.com/blampe/goat#readme
-[code block render hook]: /render-hooks/code-blocks/
-
Inner
: (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper.
@@ -30,9 +27,7 @@ Height
## GoAT Diagrams
-Hugo natively supports [GoAT](https://github.com/bep/goat) diagrams with an [embedded code block render hook].
-
-[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
+Hugo natively supports GoAT diagrams with an [embedded code block render hook].
This Markdown:
@@ -111,3 +106,7 @@ svg.foo {
font-family: "Segoe UI","Noto Sans",Helvetica,Arial,sans-serif
}
```
+
+[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/content/en/functions/global/page.md b/content/en/functions/global/page.md
index 357ad849d..0d4b8070f 100644
--- a/content/en/functions/global/page.md
+++ b/content/en/functions/global/page.md
@@ -25,9 +25,8 @@ When a `Page` object is not in context, you can use the global `page` function:
{{ page.Params.foo }}
```
-{{< note >}}
-Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below.
-{{< /note >}}
+> [!note]
+> Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below.
## Explanation
@@ -97,5 +96,5 @@ When you call the [`Summary`] method, Hugo renders the page content including sh
If Hugo renders the section page before a content page, the cached rendered shortcode will be incorrect. You cannot control the rendering sequence due to concurrency.
-[`Summary`]: /methods/page/summary/
[`partialCached`]: /functions/partials/includecached/
+[`Summary`]: /methods/page/summary/
diff --git a/content/en/functions/global/site.md b/content/en/functions/global/site.md
index 4e83c40e3..be0c6730e 100644
--- a/content/en/functions/global/site.md
+++ b/content/en/functions/global/site.md
@@ -26,6 +26,5 @@ When the `Site` object is in context you can use the `Site` property:
{{ $.Site.Params.foo }}
```
-{{< note >}}
-To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context.
-{{< /note >}}
+> [!note]
+> To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context.
diff --git a/content/en/functions/go-template/range.md b/content/en/functions/go-template/range.md
index 90f0a9efe..a06907c79 100644
--- a/content/en/functions/go-template/range.md
+++ b/content/en/functions/go-template/range.md
@@ -54,9 +54,8 @@ Hugo will throw an error:
The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template.
-{{< note >}}
-Use the `$` to get the context passed into the template.
-{{< /note >}}
+> [!note]
+> Use the `$` to get the context passed into the template.
This template will render the page title three times:
@@ -66,11 +65,8 @@ This template will render the page title three times:
{{ end }}
```
-{{< note >}}
-Gaining a thorough understanding of context is critical for anyone writing template code.
-{{< /note >}}
-
-[`seq`]: /functions/collections/seq/
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
## Array or slice of scalars
@@ -188,6 +184,7 @@ Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map
{{% include "/_common/functions/go-template/text-template.md" %}}
-[`else`]: /functions/go-template/else/
[`break`]: /functions/go-template/break/
[`continue`]: /functions/go-template/continue/
+[`else`]: /functions/go-template/else/
+[`seq`]: /functions/collections/seq/
diff --git a/content/en/functions/go-template/return.md b/content/en/functions/go-template/return.md
index 8d43d2d31..eb6ba30cd 100644
--- a/content/en/functions/go-template/return.md
+++ b/content/en/functions/go-template/return.md
@@ -16,9 +16,8 @@ The returned value may be of any data type including, but not limited to, [`bool
A `return` statement without a value returns an empty string of type `template.HTML`.
-{{< note >}}
-Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below.
-{{< /note >}}
+> [!note]
+> Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below.
## Example
@@ -63,13 +62,10 @@ Hugo renders:
See additional examples in the [partial templates] section.
-[partial templates]: /templates/partial/#returning-a-value-from-a-partial
-
## Usage
-{{< note >}}
-Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks.
-{{< /note >}}
+> [!note]
+> Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks.
A partial that returns a value must contain only one `return` statement, placed at the end of the template.
@@ -85,9 +81,8 @@ For example:
{{ return $result }}
```
-{{< note >}}
-The construct below is incorrect; it contains more than one `return` statement.
-{{< /note >}}
+> [!note]
+> The construct below is incorrect; it contains more than one `return` statement.
```go-html-template {file="layouts/partials/do-not-do-this.html"}
{{ if math.ModBool . 2 }}
@@ -96,3 +91,6 @@ The construct below is incorrect; it contains more than one `return` statement.
{{ return "odd" }}
{{ end }}
```
+
+[partial templates]: /templates/partial/#returning-a-value-from-a-partial
+[text/template package]: https://pkg.go.dev/text/template
diff --git a/content/en/functions/go-template/try.md b/content/en/functions/go-template/try.md
index 48364d520..b106abe50 100644
--- a/content/en/functions/go-template/try.md
+++ b/content/en/functions/go-template/try.md
@@ -15,8 +15,6 @@ params:
The `try` statement is a non-standard extension to Go's [text/template] package. It introduces a mechanism for handling errors within templates, mimicking the `try-catch` constructs found in other programming languages.
-[text/template]: https://pkg.go.dev/text/template
-
## Methods
The `TryValue` object encapsulates the result of evaluating the expression, and provides two methods:
@@ -90,8 +88,6 @@ Hugo renders the above to:
Error handling is essential when using the [`resources.GetRemote`] function to capture remote resources such as data or images. When calling this function, if the HTTP request fails, Hugo will fail the build.
-[`resources.GetRemote`]: /functions/resources/getremote/
-
Instead of failing the build, we can catch the error and emit a warning:
```go-html-template
@@ -108,8 +104,9 @@ Instead of failing the build, we can catch the error and emit a warning:
```
In the above, note that the [context](g) within the last conditional block is the `TryValue` object returned by the `try` statement. At this point neither the `Err` nor `Value` methods returned anything, so the current context is not useful. Use the `$` to access the [template context] if needed.
-[template context]: /templates/introduction/#template-context
+> [!note]
+> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
-{{< note >}}
-Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
-{{< /note >}}
+[`resources.GetRemote`]: /functions/resources/getremote/
+[template context]: /templates/introduction/#template-context
+[text/template]: https://pkg.go.dev/text/template
diff --git a/content/en/functions/go-template/with.md b/content/en/functions/go-template/with.md
index e18df5e78..c25ce3fba 100644
--- a/content/en/functions/go-template/with.md
+++ b/content/en/functions/go-template/with.md
@@ -73,9 +73,8 @@ Hugo will throw an error:
The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Inside of the `with` block, if we want to render the page title, we need to get the context passed into the template.
-{{< note >}}
-Use the `$` to get the context passed into the template.
-{{< /note >}}
+> [!note]
+> Use the `$` to get the context passed into the template.
This template will render the page title as desired:
@@ -85,9 +84,8 @@ This template will render the page title as desired:
{{ end }}
```
-{{< note >}}
-Gaining a thorough understanding of context is critical for anyone writing template code.
-{{< /note >}}
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
{{% include "/_common/functions/go-template/text-template.md" %}}
diff --git a/content/en/functions/images/AutoOrient.md b/content/en/functions/images/AutoOrient.md
index 5af396e59..fd8d2ed14 100644
--- a/content/en/functions/images/AutoOrient.md
+++ b/content/en/functions/images/AutoOrient.md
@@ -22,9 +22,8 @@ Create the filter:
{{% include "/_common/functions/images/apply-image-filter.md" %}}
-{{< note >}}
-When using with other filters, specify `images.AutoOrient` first.
-{{< /note >}}
+> [!note]
+> When using with other filters, specify `images.AutoOrient` first.
```go-html-template
{{ $filters := slice
diff --git a/content/en/functions/images/Config.md b/content/en/functions/images/Config.md
index f435a247c..374abfc92 100644
--- a/content/en/functions/images/Config.md
+++ b/content/en/functions/images/Config.md
@@ -14,8 +14,6 @@ aliases: [/functions/imageconfig]
See [image processing] for an overview of Hugo's image pipeline.
-[image processing]: /content-management/image-processing/
-
```go-html-template
{{ $ic := images.Config "/static/images/a.jpg" }}
@@ -25,10 +23,9 @@ See [image processing] for an overview of Hugo's image pipeline.
Supported image formats include GIF, JPEG, PNG, TIFF, and WebP.
-{{< note >}}
-This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global resources](g), [page resources](g), and [remote resources](g). See the [image processing] section for details.
+> [!note]
+> This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global resources](g), [page resources](g), and [remote resources](g). See the [image processing] section for details.
-[`Width`]: /methods/resource/width/
[`Height`]: /methods/resource/height/
+[`Width`]: /methods/resource/width/
[image processing]: /content-management/image-processing/
-{{< /note >}}
diff --git a/content/en/functions/images/Mask.md b/content/en/functions/images/Mask.md
index 66c82ae60..4f3b4aa3f 100644
--- a/content/en/functions/images/Mask.md
+++ b/content/en/functions/images/Mask.md
@@ -14,9 +14,8 @@ params:
The `images.Mask` filter applies a mask to an image. Black pixels in the mask make the corresponding areas of the base image transparent, while white pixels keep them opaque. Color images are converted to grayscale for masking purposes. The mask is automatically resized to match the dimensions of the base image.
-{{< note >}}
-Of the formats supported by Hugo's imaging pipeline, only PNG and WebP have an alpha channel to support transparency. If your source image has a different format and you require transparent masked areas, convert it to either PNG or WebP as shown in the example below.
-{{< /note >}}
+> [!note]
+> Of the formats supported by Hugo's imaging pipeline, only PNG and WebP have an alpha channel to support transparency. If your source image has a different format and you require transparent masked areas, convert it to either PNG or WebP as shown in the example below.
When applying a mask to a non-transparent image format such as JPEG, the masked areas will be filled with the color specified by the `bgColor` parameter in your [site configuration]. You can override that color with a `Process` image filter:
@@ -24,8 +23,6 @@ When applying a mask to a non-transparent image format such as JPEG, the masked
{{ $filter := images.Process "#00ff00" }}
```
-[site configuration]: /configuration/imaging/
-
## Usage
Create a slice of filters, one for WebP conversion and the other for mask application:
@@ -56,9 +53,6 @@ You can also apply the filter using the [`Filter`] method on a 'Resource' object
{{ end }}
```
-[`images.Filter`]: /functions/images/filter/
-[`Filter`]: /methods/resource/filter/
-
## Example
Mask
@@ -75,3 +69,7 @@ Mask
filterArgs="images/examples/mask.png"
example=true
>}}
+
+[`Filter`]: /methods/resource/filter/
+[`images.Filter`]: /functions/images/filter/
+[site configuration]: /configuration/imaging/
diff --git a/content/en/functions/images/QR.md b/content/en/functions/images/QR.md
index a8375b904..aac78d657 100644
--- a/content/en/functions/images/QR.md
+++ b/content/en/functions/images/QR.md
@@ -20,19 +20,17 @@ The `images.QR` function encodes the given text into a [QR code] using the speci
Although the default option values are sufficient for most applications, you should test the rendered QR code both on-screen and in print.
-[QR code]: https://en.wikipedia.org/wiki/QR_code
-
## Options
level
: (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`.
-Error correction level|Redundancy
-:--|:--|:--
-low|20%
-medium|38%
-quartile|55%
-high|65%
+ Error correction level|Redundancy
+ :--|:--|:--
+ low|20%
+ medium|38%
+ quartile|55%
+ high|65%
scale
: (`int`) The number of image pixels per QR code module. Must be greater than or equal to `2`. Default is `4`.
@@ -40,8 +38,6 @@ scale
targetDir
: (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image. Use Unix-style slashes (`/`) to separarate path segments. If empty or not provided, the image is placed directly in the `publishDir` root. Hugo automatically creates the necessary subdirectories if they don't exist.
-[`publishDir`]: /configuration/all/#publishdir
-
## Examples
To create a QR code using the default values for `level` and `scale`:
@@ -115,9 +111,8 @@ If the QR code will be printed, use the default `scale` value of `4` pixels per
Avoid using Hugo's image processing methods to resize QR codes. Resizing can introduce blurring due to anti-aliasing when a QR code module occupies a fractional number of pixels.
-{{< note >}}
-Always test the rendered QR code both on-screen and in print.
-{{< /note >}}
+> [!note]
+> Always test the rendered QR code both on-screen and in print.
## Shortcode
@@ -139,4 +134,6 @@ https://gohugo.io
The `qr` shortcode accepts several arguments including `level` and `scale`. See the [related documentation] for details.
+[`publishDir`]: /configuration/all/#publishdir
+[QR code]: https://en.wikipedia.org/wiki/QR_code
[related documentation]: /shortcodes/qr/
diff --git a/content/en/functions/js/Batch.md b/content/en/functions/js/Batch.md
index bf51c2a84..a2c8bb893 100644
--- a/content/en/functions/js/Batch.md
+++ b/content/en/functions/js/Batch.md
@@ -10,9 +10,8 @@ params:
signatures: ['js.Batch [ID]']
---
-{{< note >}}
-For a runnable example of this feature, see [this test and demo repo](https://github.com/bep/hugojsbatchdemo/).
-{{< /note >}}
+> [!note]
+> For a runnable example of this feature, see [this test and demo repo](https://github.com/bep/hugojsbatchdemo/).
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:
@@ -182,7 +181,7 @@ Setting the `Config` for a batch can be done from any template (including shortc
### Build options
format
-: (`string`) Currently only `esm` is supported in [ESBuild's code splitting].
+: (`string`) Currently only `esm` is supported in ESBuild's [code splitting].
{{% include "/_common/functions/js/options.md" %}}
@@ -243,13 +242,10 @@ 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:
-{{< 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.
-
-[`templates.Defer`]: /functions/templates/defer/
-{{< /note >}}
+> [!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.
```go-html-template
{{ $group := .group }}
@@ -272,7 +268,7 @@ See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global-
## 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 ESBuild's [code splitting], 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).
- There's a known import ordering issue.
@@ -289,28 +285,23 @@ import './lib2.js';
import './lib1.js';
console.log('entrypoints-workaround.js');
-
```
-[build options]: #build-options
[`Resource`]: /methods/resource/
-[`Resources`]: /methods/page/resources/
[`Resources.Mount`]: /methods/page/resources/#mount
+[`Resources`]: /methods/page/resources/
[`templates.Defer`]: /functions/templates/defer/
+[`templates.Defer`]: /functions/templates/defer/
+[build options]: #build-options
[code splitting]: https://esbuild.github.io/api/#splitting
[config]: #config
-[ESBuild's code splitting]: https://esbuild.github.io/api/#splitting
[ESBuild]: https://github.com/evanw/esbuild
-[group]: #group
-[instance]: #instance
[JavaScript import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
[js.Batch Demo Repo]: https://github.com/bep/hugojsbatchdemo/
-[map]: /functions/collections/dictionary/
[OptionsSetter]: #optionssetter
-[page bundles]: /content-management/page-bundles/
[params options]: #params-options
[runner]: #runner
-[script options]: #script-options
[script]: #script
+[script options]: #script-options
[SetOptions]: #optionssetter
[with]: /functions/go-template/with/
diff --git a/content/en/functions/js/Build.md b/content/en/functions/js/Build.md
index 423369bab..1bec6b16f 100644
--- a/content/en/functions/js/Build.md
+++ b/content/en/functions/js/Build.md
@@ -18,8 +18,6 @@ The `js.Build` function uses the [evanw/esbuild] package to:
- Minify
- Create source maps
-[evanw/esbuild]: https://github.com/evanw/esbuild
-
```go-html-template
{{ with resources.Get "js/main.js" }}
{{ $opts := dict
@@ -100,9 +98,8 @@ Any imports in a file outside `assets` or that does not resolve to a component i
The start directory for resolving npm packages (aka. packages that live inside a `node_modules` directory) is always the main project directory.
-{{< note >}}
-If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project.
-{{< /note >}}
+> [!note]
+> If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project.
## Examples
@@ -120,3 +117,5 @@ Or with options:
{{ $built := resources.Get "scripts/main.js" | js.Build $opts }}
```
+
+[evanw/esbuild]: https://github.com/evanw/esbuild
diff --git a/content/en/functions/lang/Translate.md b/content/en/functions/lang/Translate.md
index 9f1c2da2a..e3de608d3 100644
--- a/content/en/functions/lang/Translate.md
+++ b/content/en/functions/lang/Translate.md
@@ -16,17 +16,12 @@ The `lang.Translate` function returns the value associated with given key as def
If the key is not found in the translation table for the current language, the `lang.Translate` function falls back to the translation table for the [`defaultContentLanguage`].
-[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
-
If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string.
-{{< note >}}
-To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site.
-
-To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`] to `true` in your site configuration.
-
-[`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders
-{{< /note >}}
+> [!note]
+> To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site.
+>
+> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`] to `true` in your site configuration.
## Translation tables
@@ -46,13 +41,8 @@ i18n/art-x-hugolang.toml
i18n/hugolang.toml
```
-{{< note >}}
-Private use subtags must not exceed 8 alphanumeric characters.
-{{< /note >}}
-
-[language key]: /configuration/languages/#language-keys
-[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
-[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
+> [!note]
+> Private use subtags must not exceed 8 alphanumeric characters.
## Simple translations
@@ -78,9 +68,8 @@ privacy = 'prywatność'
security = 'bezpieczeństwo'
{{< /code-toggle >}}
-{{< note >}}
-The examples below use the `T` alias for brevity.
-{{< /note >}}
+> [!note]
+> The examples below use the `T` alias for brevity.
When viewing the English language site:
@@ -108,8 +97,6 @@ i18n/
The Unicode [CLDR Plural Rules chart] describes the pluralization categories for each language.
-[CLDR Plural Rules chart]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html
-
The English translation table:
{{< code-toggle file=i18n/en >}}
@@ -138,9 +125,8 @@ many = '{{ . }} miesięcy'
other = '{{ . }} miesiąca'
{{< /code-toggle >}}
-{{< note >}}
-The examples below use the `T` alias for brevity.
-{{< /note >}}
+> [!note]
+> The examples below use the `T` alias for brevity.
When viewing the English language site:
@@ -187,16 +173,13 @@ Template code:
{{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old.
```
-{{< note >}}
-Translation tables may contain both simple translations and translations with pluralization.
-{{< /note >}}
+> [!note]
+> Translation tables may contain both simple translations and translations with pluralization.
## Reserved keys
Hugo uses the [go-i18n] package to look up values in translation tables. This package reserves the following keys for internal use:
-[go-i18n]: https://github.com/nicksnyder/go-i18n
-
id
: (`string`) Uniquely identifies the message.
@@ -230,8 +213,6 @@ many
other
: (`string`) The content of the message for the [CLDR] plural form "other".
-[CLDR]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html
-
If you need to provide a translation for one of the reserved keys, you can prepend the word with an underscore. For example:
{{< code-toggle file=i18n/es >}}
@@ -255,3 +236,12 @@ Then in your templates:
{{ T "_zero" }} → cero
{{ T "_other" }} → otro
```
+
+[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
+[`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders
+[CLDR]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html
+[CLDR Plural Rules chart]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html
+[go-i18n]: https://github.com/nicksnyder/go-i18n
+[language key]: /configuration/languages/#language-keys
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
+[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
diff --git a/content/en/functions/math/Counter.md b/content/en/functions/math/Counter.md
index 221ae48a9..0e0c77f77 100644
--- a/content/en/functions/math/Counter.md
+++ b/content/en/functions/math/Counter.md
@@ -28,9 +28,7 @@ Use this function to:
- 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
-[`warnf`]: /functions/fmt/warnf/
-[`resources.FromString`]: /functions/resources/fromstring/
+> [!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.
-{{< 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.
-{{< /note >}}
+[`warnf`]: /functions/fmt/warnf/
diff --git a/content/en/functions/partials/IncludeCached.md b/content/en/functions/partials/IncludeCached.md
index 01dac0b99..3905ee15e 100644
--- a/content/en/functions/partials/IncludeCached.md
+++ b/content/en/functions/partials/IncludeCached.md
@@ -15,11 +15,10 @@ Without a [`return`] statement, the `partialCached` function returns a string of
The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation.
-{{< 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.
-{{< /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.
Here is the simplest usage:
diff --git a/content/en/functions/resources/ByType.md b/content/en/functions/resources/ByType.md
index e7b73a005..99e2b9771 100644
--- a/content/en/functions/resources/ByType.md
+++ b/content/en/functions/resources/ByType.md
@@ -18,12 +18,10 @@ The [media type] is typically one of `image`, `text`, `audio`, `video`, or `appl
{{ end }}
```
-{{< 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.
+> [!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.
[`Resources.ByType`]: /methods/page/resources/
-{{< /note >}}
-
[media type]: https://en.wikipedia.org/wiki/Media_type
diff --git a/content/en/functions/resources/Copy.md b/content/en/functions/resources/Copy.md
index 39500e57a..220a3db4c 100644
--- a/content/en/functions/resources/Copy.md
+++ b/content/en/functions/resources/Copy.md
@@ -23,6 +23,5 @@ The relative URL of the new published resource will be:
/img/new-image-name.jpg
```
-{{< note >}}
-Use the `resources.Copy` function with global, page, and remote resources.
-{{< /note >}}
+> [!note]
+> Use the `resources.Copy` function with global, page, and remote resources.
diff --git a/content/en/functions/resources/ExecuteAsTemplate.md b/content/en/functions/resources/ExecuteAsTemplate.md
index c1eaec44a..bff83832e 100644
--- a/content/en/functions/resources/ExecuteAsTemplate.md
+++ b/content/en/functions/resources/ExecuteAsTemplate.md
@@ -14,13 +14,8 @@ The `resources.ExecuteAsTemplate` function returns a resource created from a Go
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/
-
Let's say you have a CSS file that you wish to populate with values from your site configuration:
-
```go-html-template {file="assets/css/template.css"}
body {
background-color: {{ site.Params.style.bg_color }};
@@ -54,10 +49,13 @@ The example above:
The result is:
-
```css {file="public/css/main.css"}
body {
background-color: #fefefe;
color: #222;
}
```
+
+[`publish`]: /methods/resource/publish/
+[`permalink`]: /methods/resource/permalink/
+[`relpermalink`]: /methods/resource/relpermalink/
diff --git a/content/en/functions/resources/Get.md b/content/en/functions/resources/Get.md
index 40e38b78d..db91f0a9a 100644
--- a/content/en/functions/resources/Get.md
+++ b/content/en/functions/resources/Get.md
@@ -16,10 +16,9 @@ params:
{{ end }}
```
-{{< 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.
+> [!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.
[`Resources.Get`]: /methods/page/resources/
-{{< /note >}}
diff --git a/content/en/functions/resources/GetMatch.md b/content/en/functions/resources/GetMatch.md
index 83588378b..8f1b004fe 100644
--- a/content/en/functions/resources/GetMatch.md
+++ b/content/en/functions/resources/GetMatch.md
@@ -16,14 +16,13 @@ params:
{{ end }}
```
-{{< 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.
-
-[`Resources.GetMatch`]: /methods/page/resources/
-{{< /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.
Hugo determines a match using a case-insensitive [glob](g) pattern.
{{% include "/_common/glob-patterns.md" %}}
+
+[`Resources.GetMatch`]: /methods/page/resources/
diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md
index e62ebbe02..b83a642b1 100644
--- a/content/en/functions/resources/GetRemote.md
+++ b/content/en/functions/resources/GetRemote.md
@@ -61,11 +61,10 @@ The `resources.GetRemote` function takes an optional map of options.
## 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]: #error-handling
-{{< /note >}}
To include a header:
@@ -140,15 +139,12 @@ When retrieving remote data, use the [`transform.Unmarshal`] function to [unmars
{{ 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`.
-
-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:
-
-`{{ $data = .Content | transform.Unmarshal }}`
-
-[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
-{{< /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:
+>
+> `{{ $data = .Content | transform.Unmarshal }}`
## Error handling
@@ -156,9 +152,8 @@ Use the [`try`] statement to capture HTTP request errors. If you do not handle t
[`try`]: /functions/go-template/try
-{{< note >}}
-Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
-{{< /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
{{ $url := "https://broken-example.org/images/a.jpg" }}
diff --git a/content/en/functions/resources/Match.md b/content/en/functions/resources/Match.md
index eb6010515..6c7d83649 100644
--- a/content/en/functions/resources/Match.md
+++ b/content/en/functions/resources/Match.md
@@ -16,16 +16,14 @@ params:
{{ end }}
```
-{{< 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.
-
-[`Resources.Match`]: /methods/page/resources/
-{{< /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.
Hugo determines a match using a case-insensitive [glob pattern].
{{% include "/_common/glob-patterns.md" %}}
+[`Resources.Match`]: /methods/page/resources/
[glob pattern]: https://github.com/gobwas/glob#example
diff --git a/content/en/functions/resources/PostProcess.md b/content/en/functions/resources/PostProcess.md
index cebd7e4d9..d70437694 100644
--- a/content/en/functions/resources/PostProcess.md
+++ b/content/en/functions/resources/PostProcess.md
@@ -21,17 +21,9 @@ In this example, after the build is complete, Hugo will:
3. [Minify] the CSS
4. [Fingerprint] the CSS
-[autoprefixer]: https://github.com/postcss/autoprefixer
-[fingerprint]: /functions/resources/fingerprint/
-[minify]: /functions/resources/minify/
-[postcss]: /functions/css/postcss/
-[purgecss]: https://purgecss.com/plugins/postcss.html
-
Step 1
: Install [Node.js].
-[node.js]: https://nodejs.org/en/download
-
Step 2
: Install the required Node.js packages in the root of your project:
@@ -42,8 +34,6 @@ npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss
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`].
-[`config/production`]: /configuration/introduction/#configuration-directory
-
{{< code-toggle file=hugo >}}
[build.buildStats]
enable = true
@@ -51,8 +41,6 @@ enable = true
See the [configure build] documentation for details and options.
-[configure build]: /configuration/build/
-
Step 4
: Create a PostCSS configuration file in the root of your project.
@@ -82,9 +70,8 @@ module.exports = {
};
```
-{{< note >}}
-{{% include "/_common/functions/postcss-windows-warning.md" %}}
-{{< /note >}}
+> [!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.
@@ -148,3 +135,14 @@ You cannot manipulate the values returned from the resource's methods. For examp
{{ $css = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }}
{{ $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
diff --git a/content/en/functions/safe/CSS.md b/content/en/functions/safe/CSS.md
index c05cda87e..12ebbf8aa 100644
--- a/content/en/functions/safe/CSS.md
+++ b/content/en/functions/safe/CSS.md
@@ -28,8 +28,6 @@ Use of this type presents a security risk: the encapsulated content should come
See the [Go documentation] for details.
-[Go documentation]: https://pkg.go.dev/html/template#CSS
-
## Example
Without a safe declaration:
@@ -45,9 +43,8 @@ Hugo renders the above to:
foo
```
-{{< note >}}
-`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
-{{< /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:
@@ -61,3 +58,5 @@ Hugo renders the above to:
```html
foo
```
+
+[Go documentation]: https://pkg.go.dev/html/template#CSS
diff --git a/content/en/functions/safe/URL.md b/content/en/functions/safe/URL.md
index 798d96469..44bed8064 100644
--- a/content/en/functions/safe/URL.md
+++ b/content/en/functions/safe/URL.md
@@ -27,8 +27,6 @@ Use of this type presents a security risk: the encapsulated content should come
See the [Go documentation] for details.
-[Go documentation]: https://pkg.go.dev/html/template#URL
-
## Example
Without a safe declaration:
@@ -44,9 +42,8 @@ Hugo renders the above to:
IRC
```
-{{< note >}}
-`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime.
-{{< /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:
@@ -60,3 +57,5 @@ Hugo renders the above to:
```html
IRC
```
+
+[Go documentation]: https://pkg.go.dev/html/template#URL
diff --git a/content/en/functions/strings/FindRESubmatch.md b/content/en/functions/strings/FindRESubmatch.md
index 4bcc782b8..d039607fb 100644
--- a/content/en/functions/strings/FindRESubmatch.md
+++ b/content/en/functions/strings/FindRESubmatch.md
@@ -82,6 +82,5 @@ 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 >}}
+> [!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.
diff --git a/content/en/functions/strings/FindRe.md b/content/en/functions/strings/FindRe.md
index d2f7d3266..45129ec91 100644
--- a/content/en/functions/strings/FindRe.md
+++ b/content/en/functions/strings/FindRe.md
@@ -28,6 +28,5 @@ 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 >}}
+> [!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.
diff --git a/content/en/functions/strings/ReplaceRE.md b/content/en/functions/strings/ReplaceRE.md
index 9f40c790e..dba4bd15a 100644
--- a/content/en/functions/strings/ReplaceRE.md
+++ b/content/en/functions/strings/ReplaceRE.md
@@ -32,9 +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](https://regex101.com/). Be sure to select the Go flavor before you begin.
-{{< /note >}}
+> [!note]
+> You can write and test your regular expression using [regex101.com]. Be sure to select the Go flavor before you begin.
-[RE2]: https://github.com/google/re2/wiki/Syntax
-[string literal]: https://go.dev/ref/spec#String_literals
+[regex101.com]: https://regex101.com/
diff --git a/content/en/functions/strings/Split.md b/content/en/functions/strings/Split.md
index a077bdd00..bcab1b4d7 100644
--- a/content/en/functions/strings/Split.md
+++ b/content/en/functions/strings/Split.md
@@ -18,8 +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/
-{{< /note >}}
diff --git a/content/en/functions/strings/Truncate.md b/content/en/functions/strings/Truncate.md
index 7b7c77055..d18c7147d 100644
--- a/content/en/functions/strings/Truncate.md
+++ b/content/en/functions/strings/Truncate.md
@@ -18,8 +18,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 [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function.
[`safeHTML`]: /functions/safe/html/
-{{< /note >}}
diff --git a/content/en/functions/templates/Defer.md b/content/en/functions/templates/Defer.md
index 672c5ee8b..471f149d8 100644
--- a/content/en/functions/templates/Defer.md
+++ b/content/en/functions/templates/Defer.md
@@ -42,13 +42,10 @@ In some rare use cases, you may need to defer the execution of a template until
{{ end }}
```
-{{< note >}}
-This function only works in combination with the `with` keyword.
-{{< /note >}}
-
-{{< note >}}
-Variables defined on the outside are not visible on the inside and vice versa. To pass in data, use the `data` [option](#options).
-{{< /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).
For the above to work well when running the server (or `hugo -w`), you want to have a configuration similar to this:
diff --git a/content/en/functions/transform/Emojify.md b/content/en/functions/transform/Emojify.md
index 3e4f7ab00..3d996e366 100644
--- a/content/en/functions/transform/Emojify.md
+++ b/content/en/functions/transform/Emojify.md
@@ -18,14 +18,11 @@ 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 site's configuration. Then you can write emoji shorthand directly into your content files;
-[`enableEmoji`] :/configuration/all/#enableEmoji
-
```text
I :heart: Hugo!
```
I :heart: Hugo!
+[`enableEmoji`]: /configuration/all/#enableemoji
[emoji shortcodes]: /quick-reference/emojis/
-[sc]: /templates/shortcode/
-[scsource]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes
diff --git a/content/en/functions/transform/Markdownify.md b/content/en/functions/transform/Markdownify.md
index 0ba78eba1..c22de1efe 100644
--- a/content/en/functions/transform/Markdownify.md
+++ b/content/en/functions/transform/Markdownify.md
@@ -19,11 +19,9 @@ If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags
To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] method on the `Page` object, setting the `display` option to `block`.
-[`RenderString`]: /methods/page/renderstring/
+> [!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.
-
-[Markdown render hooks]: /render-hooks/
[#9692]: https://github.com/gohugoio/hugo/issues/9692
-{{< /note >}}
+[`RenderString`]: /methods/page/renderstring/
+[Markdown render hooks]: /render-hooks/
diff --git a/content/en/functions/transform/PortableText.md b/content/en/functions/transform/PortableText.md
index f501f6059..7baba99d4 100644
--- a/content/en/functions/transform/PortableText.md
+++ b/content/en/functions/transform/PortableText.md
@@ -19,9 +19,8 @@ params:
- `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 a [image render hook](/render-hooks/images/).
- `code` (see the [code-input](https://www.sanity.io/plugins/code-input) plugin). Code will be rendered as [fenced code blocks](/contribute/documentation/#fenced-code-blocks) with any file name provided passed on as a markdown attribute.
-{{< 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](https://gohugo.io/render-hooks/).
-{{< /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](https://gohugo.io/render-hooks/).
## Example
diff --git a/content/en/functions/transform/Remarshal.md b/content/en/functions/transform/Remarshal.md
index 30bfbf17a..ecf7fc905 100644
--- a/content/en/functions/transform/Remarshal.md
+++ b/content/en/functions/transform/Remarshal.md
@@ -13,11 +13,10 @@ 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 >}}
-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.
-{{< /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.
Example 1
: Convert a string of TOML to JSON.
diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md
index 56d9aec5b..a9f12c546 100644
--- a/content/en/functions/transform/ToMath.md
+++ b/content/en/functions/transform/ToMath.md
@@ -15,20 +15,14 @@ aliases: [/functions/tomath]
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.
-[KaTeX]: https://katex.org/
-
```go-html-template
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
```
-{{< note >}}
-By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result.
-
-[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
-
-To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet.
-
-{{< /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.
```go-html-template
{{ $opts := dict "output" "htmlAndMathml" }}
@@ -39,16 +33,12 @@ To optimize rendering quality and accessibility, use the `htmlAndMathml` output
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].
-[rendering options]: https://katex.org/docs/options.html
-
displayMode
: (`bool`) Whether to render in display mode instead of inline mode. Default is `false`.
errorColor
: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
-[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
-
fleqn
: (`bool`) Whether to render flush left with a 2em left margin. Default is `false`.
@@ -96,8 +86,6 @@ Instead of client-side JavaScript rendering of mathematical markup using MathJax
Enable and configure the Goldmark [passthrough extension] in your site 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
@@ -107,16 +95,13 @@ block = [['\[', '\]'], ['$$', '$$']]
inline = [['\(', '\)']]
{{< /code-toggle >}}
-{{< 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 will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
-{{< /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 will need to 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.
-[passthrough render hook]: /render-hooks/passthrough/
-
```go-html-template {file="layouts/_default/_markup/render-passthrough.html" copy=true}
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with try (transform.ToMath .Inner $opts) }}
@@ -164,10 +149,16 @@ $$a^*=x-b^*$$
You can also use the `transform.ToMath` function to render chemical equations, leveraging the `\ce` and `\pu` functions from the [mhchem] package.
-[mhchem]: https://mhchem.github.io/MathJax-mhchem/
-
```text
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
```
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[KaTeX]: https://katex.org/
+[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
+[mhchem]: https://mhchem.github.io/MathJax-mhchem/
+[passthrough extension]: /configuration/markup/#passthrough
+[passthrough render hook]: /render-hooks/passthrough/
+[rendering options]: https://katex.org/docs/options.html
diff --git a/content/en/functions/transform/Unmarshal.md b/content/en/functions/transform/Unmarshal.md
index b5b5800b9..d159122f5 100644
--- a/content/en/functions/transform/Unmarshal.md
+++ b/content/en/functions/transform/Unmarshal.md
@@ -107,15 +107,12 @@ 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`.
-
-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:
-
-`{{ $data = .Content | transform.Unmarshal }}`
-
-[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
-{{< /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:
+>
+> `{{ $data = .Content | transform.Unmarshal }}`
## Options
@@ -292,4 +289,5 @@ Hugo renders this to:
```
[`index`]: /functions/collections/indexfunction/
+[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
[page bundle]: /content-management/page-bundles/
diff --git a/content/en/functions/urls/AbsLangURL.md b/content/en/functions/urls/AbsLangURL.md
index 720d061b6..da45ca224 100644
--- a/content/en/functions/urls/AbsLangURL.md
+++ b/content/en/functions/urls/AbsLangURL.md
@@ -68,6 +68,5 @@ When rendering the `en` site with `baseURL = https://example.org/docs/`
{{ absLangURL "/style.css" }} → https://example.org/en/style.css
```
-{{< 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.
-{{< /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/content/en/functions/urls/AbsURL.md b/content/en/functions/urls/AbsURL.md
index fb8298d55..72613cd0b 100644
--- a/content/en/functions/urls/AbsURL.md
+++ b/content/en/functions/urls/AbsURL.md
@@ -16,8 +16,6 @@ With multilingual configurations, use the [`urls.AbsLangURL`] function instead.
- Whether the input begins with a slash (`/`)
- The `baseURL` in your site configuration
-[`urls.AbsLangURL`]: /functions/urls/abslangurl/
-
## Input does not begin with a slash
If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration.
@@ -58,6 +56,7 @@ With `baseURL = https://example.org/docs/`
{{ absURL "/style.css" }} → https://example.org/style.css
```
-{{< 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.
-{{< /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/content/en/functions/urls/RelLangURL.md b/content/en/functions/urls/RelLangURL.md
index 8a9af79d2..af8bff3d7 100644
--- a/content/en/functions/urls/RelLangURL.md
+++ b/content/en/functions/urls/RelLangURL.md
@@ -78,6 +78,5 @@ When rendering the `en` site with `baseURL = https://example.org/docs/`
{{ relLangURL "/style.css" }} → /en/style.css
```
-{{< 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.
-{{< /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/content/en/functions/urls/RelURL.md b/content/en/functions/urls/RelURL.md
index b9d117dcc..0aef4043f 100644
--- a/content/en/functions/urls/RelURL.md
+++ b/content/en/functions/urls/RelURL.md
@@ -16,8 +16,6 @@ With multilingual configurations, use the [`urls.RelLangURL`] function instead.
- Whether the input begins with a slash (`/`)
- The `baseURL` in your site configuration
-[`urls.RelLangURL`]: /functions/urls/rellangurl/
-
## Input does not begin with a slash
If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration.
@@ -68,6 +66,7 @@ With `baseURL = https://example.org/docs/`
{{ relURL "/style.css" }} → /style.css
```
-{{< 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.
-{{< /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/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md
index 240effbe6..3feecd135 100644
--- a/content/en/getting-started/directory-structure.md
+++ b/content/en/getting-started/directory-structure.md
@@ -144,11 +144,10 @@ source = '/home/user/shared-content'
target = 'content'
{{< /code-toggle >}}
-{{< note >}}
-When you overlay one directory on top of another, you must mount both directories.
-
-Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead.
-{{< /note >}}
+> [!note]
+> When you overlay one directory on top of another, you must mount both directories.
+>
+> Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead.
After mounting, the union file system has this structure:
@@ -171,9 +170,8 @@ home/
└── hugo.toml
```
-{{< note >}}
-When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's `content` directory was mounted first.
-{{< /note >}}
+> [!note]
+> When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's `content` directory was mounted first.
You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/configuration/module/#mounts).
diff --git a/content/en/getting-started/quick-start.md b/content/en/getting-started/quick-start.md
index 780d4f6f8..dfb78f42e 100644
--- a/content/en/getting-started/quick-start.md
+++ b/content/en/getting-started/quick-start.md
@@ -29,18 +29,14 @@ You must also be comfortable working from the command line.
### Commands
-{{< note >}}
-**If you are a Windows user:**
-
-- Do not use the Command Prompt
-- Do not use Windows PowerShell
-- Run these commands from [PowerShell] or a Linux terminal such as WSL or Git Bash
-
-PowerShell and Windows PowerShell [are different applications].
-
-[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
-{{< /note >}}
+> [!note]
+> **If you are a Windows user:**
+>
+> - Do not use the Command Prompt
+> - Do not use Windows PowerShell
+> - Run these commands from [PowerShell] or a Linux terminal such as WSL or Git > Bash
+>
+> PowerShell and Windows PowerShell [are different applications].
Verify that you have installed Hugo {{% param "minVersion" %}} or later.
@@ -123,8 +119,6 @@ Notice the `draft` value in the [front matter] is `true`. By default, Hugo does
Add some [Markdown] to the body of the post, but do not change the `draft` value.
-[markdown]: https://commonmark.org/help/
-
```text
+++
title = 'My First Post'
@@ -149,12 +143,8 @@ View your site at the URL displayed in your terminal. Keep the development serve
When satisfied with your new content, set the front matter `draft` parameter to `false`.
-{{< 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.
-
-[live testing tool]: https://spec.commonmark.org/dingus/
-[specification]: https://spec.commonmark.org/
-{{< /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 site
@@ -179,15 +169,10 @@ Start Hugo's development server to see your changes, remembering to include draf
hugo server -D
```
-{{< note >}}
-Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details.
-
-[The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site].
-
-[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/
-[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme
-[The New Dynamic]: https://www.thenewdynamic.com/
-{{< /note >}}
+> [!note]
+> Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details.
+>
+> [The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site].
## Publish the site
@@ -212,17 +197,22 @@ Hugo's [forum] is an active community of users and developers who answer questio
For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/external-learning-resources/) page.
[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke
+[are different applications]: https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell?view=powershell-7.3
+[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/
[directory structure]: /getting-started/directory-structure/
+[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme
[draft, future, and expired content]: /getting-started/usage/#draft-future-and-expired-content
[draft, future, or expired content]: /getting-started/usage/#draft-future-and-expired-content
-[external learning resources]:/getting-started/external-learning-resources/
-[forum]: https://discourse.gohugo.io/
[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/
-[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132
-[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132
+[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
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
[site configuration]: /configuration/
+[specification]: https://spec.commonmark.org/
+[The New Dynamic]: https://www.thenewdynamic.com/
diff --git a/content/en/getting-started/usage.md b/content/en/getting-started/usage.md
index 8ec0d8197..1259fa8d9 100644
--- a/content/en/getting-started/usage.md
+++ b/content/en/getting-started/usage.md
@@ -45,11 +45,10 @@ hugo
The [`hugo`] command builds your site, publishing the files to the `public` directory. To publish your site to a different directory, use the [`--destination`] flag or set [`publishDir`] in your site configuration.
-{{< note >}}
-Hugo does not clear the `public` directory before building your site. 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.
-{{< /note >}}
+> [!note]
+> Hugo does not clear the `public` directory before building your site. 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
@@ -62,12 +61,8 @@ Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [
{{< new-in 0.123.0 />}}
-{{< 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.
-
-[build options]: /content-management/build-options/
-[`cascade`]: /content-management/front-matter/#cascade
-{{< /note >}}
+> [!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.
You can override the default behavior when running `hugo` or `hugo server` with command line flags:
@@ -79,11 +74,10 @@ hugo --buildFuture # or -F
Although you can also set these values in your site configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.
-{{< note >}}
-As noted above, Hugo does not clear the `public` directory before building your site. 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.
-{{< /note >}}
+> [!note]
+> As noted above, Hugo does not clear the `public` directory before building your site. 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.
## Develop and test your site
@@ -117,9 +111,8 @@ hugo server --navigateToChanged
## Deploy your site
-{{< note >}}
-As noted above, Hugo does not clear the `public` directory before building your site. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
-{{< /note >}}
+> [!note]
+> As noted above, Hugo does not clear the `public` directory before building your site. 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:
@@ -156,10 +149,12 @@ 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.
[`--destination`]: /commands/hugo/#options
+[`cascade`]: /content-management/front-matter/#cascade
[`hugo server`]: /commands/hugo_server/
[`hugo`]: /commands/hugo/
[`publishDir`]: /configuration/all/#publishdir
[AWS Amplify]: https://aws.amazon.com/amplify/
+[build options]: /content-management/build-options/
[CloudCannon]: https://cloudcannon.com/
[Cloudflare Pages]: https://pages.cloudflare.com/
[front matter]: /content-management/front-matter/
diff --git a/content/en/host-and-deploy/deploy-with-hugo-deploy.md b/content/en/host-and-deploy/deploy-with-hugo-deploy.md
index 115619d28..8feeccbae 100644
--- a/content/en/host-and-deploy/deploy-with-hugo-deploy.md
+++ b/content/en/host-and-deploy/deploy-with-hugo-deploy.md
@@ -8,11 +8,8 @@ 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 Hugo extended/deploy edition. See the [installation] section for details.
-
-[installation]: /installation/
-{{< /note >}}
+> [!note]
+> This feature requires the Hugo extended/deploy edition. See the [installation] section for details.
## Assumptions
@@ -32,10 +29,6 @@ This feature requires the Hugo extended/deploy edition. See the [installation] s
- 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)
-[AWS]: https://aws.amazon.com
-[Azure]: https://azure.microsoft.com
-[Google Cloud]: https://cloud.google.com/
-
## Configuration
Create a deployment target in your [site configuration]. The only required parameters are [`name`] and [`url`]:
@@ -47,10 +40,6 @@ Create a deployment target in your [site configuration]. The only required param
url = 's3://my_bucket?region=us-west-1'
{{< /code-toggle >}}
-[`name`]: /configuration/deployment/#name
-[`url`]: /configuration/deployment/#url
-[site configuration]: /configuration/deployment/
-
## Deploy
To deploy to a target:
@@ -63,8 +52,6 @@ This command syncs the contents of your local `public` directory (the default pu
For more command-line options, see `hugo help deploy` or the [CLI documentation].
-[CLI documentation]: /commands/hugo_deploy/
-
### 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]:
@@ -72,21 +59,15 @@ For more command-line options, see `hugo help deploy` or the [CLI documentation]
- `include`: All files are skipped by default except those that match the pattern.
- `exclude`: Files matching the pattern are skipped.
-[configuration]: /configuration/deployment/#targets-1
-
-{{< 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.
-
-[`.well-known`]: https://en.wikipedia.org/wiki/Well-known_URI
-{{< /note >}}
+> [!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 >}}
-Excluded remote files (due to `include`/`exclude` configuration) won't be 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.
@@ -96,10 +77,21 @@ 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 >}}
-To prevent accidental data loss, Hugo will not delete more than 256 remote files by default. Use the `--maxDeletes` flag to override this limit.
-{{< /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/).
+
+[`.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/
+[site configuration]: /configuration/deployment/
diff --git a/content/en/host-and-deploy/host-on-firebase.md b/content/en/host-and-deploy/host-on-firebase.md
index b4c9f8bfe..f79123722 100644
--- a/content/en/host-and-deploy/host-on-firebase.md
+++ b/content/en/host-and-deploy/host-on-firebase.md
@@ -88,9 +88,8 @@ firebase login:ci
You can also set up your CI and add the token to a private variable like `$FIREBASE_DEPLOY_TOKEN`.
-{{< 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.
-{{< /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:
diff --git a/content/en/host-and-deploy/host-on-github-pages/index.md b/content/en/host-and-deploy/host-on-github-pages/index.md
index ded284b1e..a31f62e94 100644
--- a/content/en/host-and-deploy/host-on-github-pages/index.md
+++ b/content/en/host-and-deploy/host-on-github-pages/index.md
@@ -14,21 +14,12 @@ Please complete the following tasks before continuing:
1. [Install Git]
1. [Create a Hugo site] and test it locally with `hugo server`.
-[Create a GitHub account]: https://github.com/signup
-[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
-[Create a Hugo site]: /getting-started/quick-start/
-
## 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.
-
-[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
-{{< /note >}}
-
-[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
+> [!note]
+> See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming.
## Procedure
@@ -194,10 +185,14 @@ The example workflow above includes this step, which typically takes 10‑15
You may remove this step if your site, themes, and modules do not transpile Sass to CSS using the [Dart Sass] transpiler.
-[Dart Sass]: /functions/css/sass/#dart-sass
-
## 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)
+
+[Create a GitHub account]: https://github.com/signup
+[Create a Hugo site]: /getting-started/quick-start/
+[Dart Sass]: /functions/css/sass/#dart-sass
+[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
+[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
diff --git a/content/en/host-and-deploy/host-on-keycdn/index.md b/content/en/host-and-deploy/host-on-keycdn/index.md
index 86deee4ff..828e250c6 100644
--- a/content/en/host-and-deploy/host-on-keycdn/index.md
+++ b/content/en/host-and-deploy/host-on-keycdn/index.md
@@ -58,7 +58,7 @@ pages:
- master
```
-Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section.
+Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section.
The Secret Variable for your Zone ID should look similar to:
diff --git a/content/en/hugo-modules/use-modules.md b/content/en/hugo-modules/use-modules.md
index db07225ea..86d2ad1cc 100644
--- a/content/en/hugo-modules/use-modules.md
+++ b/content/en/hugo-modules/use-modules.md
@@ -9,7 +9,7 @@ aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
## Prerequisite
-{{< gomodules-info >}}
+{{% include "/_common/gomodules-info.md" %}}
## Initialize a new module
diff --git a/content/en/installation/linux.md b/content/en/installation/linux.md
index b9c32e967..731cfce4c 100644
--- a/content/en/installation/linux.md
+++ b/content/en/installation/linux.md
@@ -44,23 +44,16 @@ sudo snap connect hugo:ssh-keys
sudo snap disconnect hugo:ssh-keys
```
-[most distributions]: https://snapcraft.io/docs/installing-snapd
-[strictly confined]: https://snapcraft.io/docs/snap-confinement
-[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].
-
-Use one of the other installation methods if your package repository does not provide the desired version.
-
-[latest version]: https://github.com/gohugoio/hugo/releases/latest
-{{< /note >}}
+> [!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
@@ -70,8 +63,6 @@ To install the extended edition of Hugo on [Alpine Linux]:
doas apk add --no-cache --repository=https://dl-cdn.alpinelinux.org/alpine/edge/community hugo
```
-[Alpine Linux]: https://alpinelinux.org/
-
### Arch Linux
Derivatives of the [Arch Linux] distribution of Linux include [EndeavourOS], [Garuda Linux], [Manjaro], and others. To install the extended edition of Hugo:
@@ -80,11 +71,6 @@ Derivatives of the [Arch Linux] distribution of Linux include [EndeavourOS], [Ga
sudo pacman -S hugo
```
-[Arch Linux]: https://archlinux.org/
-[EndeavourOS]: https://endeavouros.com/
-[Manjaro]: https://manjaro.org/
-[Garuda Linux]: https://garudalinux.org/
-
### 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:
@@ -95,17 +81,6 @@ sudo apt install hugo
You can also download Debian packages from the [latest release] page.
-[Debian]: https://www.debian.org/
-[Exherbo]: https://www.exherbolinux.org/
-[elementary OS]: https://elementary.io/
-[KDE neon]: https://neon.kde.org/
-[Linux Lite]: https://www.linuxliteos.com/
-[Linux Mint]: https://linuxmint.com/
-[MX Linux]: https://mxlinux.org/
-[Pop!_OS]: https://pop.system76.com/
-[Ubuntu]: https://ubuntu.com/
-[Zorin OS]: https://zorin.com/os/
-
### Exherbo
To install the extended edition of Hugo on [Exherbo]:
@@ -131,10 +106,6 @@ Derivatives of the [Fedora] distribution of Linux include [CentOS], [Red Hat Ent
sudo dnf install hugo
```
-[CentOS]: https://www.centos.org/
-[Fedora]: https://getfedora.org/
-[Red Hat Enterprise Linux]: https://www.redhat.com/
-
### Gentoo
Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Funtoo], and others. To install the extended edition of Hugo:
@@ -151,11 +122,6 @@ Derivatives of the [Gentoo] distribution of Linux include [Calculate Linux], [Fu
sudo emerge www-apps/hugo
```
-[Calculate Linux]: https://www.calculate-linux.org/
-[Funtoo]: https://www.funtoo.org/
-[Gentoo]: https://www.gentoo.org/
-[USE]: https://packages.gentoo.org/packages/www-apps/hugo
-
### NixOS
The NixOS distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo:
@@ -172,10 +138,6 @@ Derivatives of the [openSUSE] distribution of Linux include [GeckoLinux], [Linux
sudo zypper install hugo
```
-[GeckoLinux]: https://geckolinux.github.io/
-[Linux Karmada]: https://linuxkamarada.com/
-[openSUSE]: https://www.opensuse.org/
-
### Solus
The [Solus] distribution of Linux includes Hugo in its package repository. To install the extended edition of Hugo:
@@ -184,8 +146,6 @@ The [Solus] distribution of Linux includes Hugo in its package repository. To in
sudo eopkg install hugo
```
-[Solus]: https://getsol.us/
-
### Void Linux
To install the extended edition of Hugo on [Void Linux]:
@@ -194,8 +154,6 @@ To install the extended edition of Hugo on [Void Linux]:
sudo xbps-install -S hugo
```
-[Void Linux]: https://voidlinux.org/
-
{{% include "/_common/installation/04-build-from-source.md" %}}
## Comparison
@@ -210,3 +168,35 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|varies|:heavy_ch
[^1]: Easy if a previous version is still installed.
[^2]: Snap packages are automatically updated. Homebrew requires advanced configuration.
+
+[Alpine Linux]: https://alpinelinux.org/
+[Arch Linux]: https://archlinux.org/
+[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/
+[Funtoo]: https://www.funtoo.org/
+[Garuda Linux]: https://garudalinux.org/
+[GeckoLinux]: https://geckolinux.github.io/
+[Gentoo]: https://www.gentoo.org/
+[KDE neon]: https://neon.kde.org/
+[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/
+[most distributions]: https://snapcraft.io/docs/installing-snapd
+[MX Linux]: https://mxlinux.org/
+[openSUSE]: https://www.opensuse.org/
+[Pop!_OS]: https://pop.system76.com/
+[Red Hat Enterprise Linux]: https://www.redhat.com/
+[Snap]: https://snapcraft.io/
+[Solus]: https://getsol.us/
+[strictly confined]: https://snapcraft.io/docs/snap-confinement
+[Ubuntu]: https://ubuntu.com/
+[USE]: https://packages.gentoo.org/packages/www-apps/hugo
+[Void Linux]: https://voidlinux.org/
+[Zorin OS]: https://zorin.com/os/
diff --git a/content/en/installation/windows.md b/content/en/installation/windows.md
index a125f08b9..a5920d45f 100644
--- a/content/en/installation/windows.md
+++ b/content/en/installation/windows.md
@@ -6,9 +6,8 @@ keywords: []
weight: 30
---
-{{< note >}}
-Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016.
-{{< /note >}}
+> [!note]
+> Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016.
## Editions
@@ -30,8 +29,6 @@ Unless your specific deployment needs require the extended/deploy edition, we re
choco install hugo-extended
```
-[Chocolatey]: https://chocolatey.org/
-
### Scoop
[Scoop] is a free and open-source package manager for Windows. To install the extended edition of Hugo:
@@ -40,8 +37,6 @@ choco install hugo-extended
scoop install hugo-extended
```
-[Scoop]: https://scoop.sh/
-
### Winget
[Winget] is Microsoft's official free and open-source package manager for Windows. To install the extended edition of Hugo:
@@ -56,13 +51,10 @@ To uninstall the extended edition of Hugo:
winget uninstall --name "Hugo (Extended)"
```
-[Winget]: https://learn.microsoft.com/en-us/windows/package-manager/
-
{{% include "/_common/installation/04-build-from-source.md" %}}
-{{< note >}}
-See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
-{{< /note >}}
+> [!note]
+> See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
## Comparison
@@ -76,3 +68,7 @@ Latest version available?|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mar
[^1]: Possible but requires advanced configuration.
[^2]: Easy if a previous version is still installed.
+
+[Chocolatey]: https://chocolatey.org/
+[Scoop]: https://scoop.sh/
+[Winget]: https://learn.microsoft.com/en-us/windows/package-manager/
diff --git a/content/en/methods/menu-entry/Identifier.md b/content/en/methods/menu-entry/Identifier.md
index f4e4bda53..47442533c 100644
--- a/content/en/methods/menu-entry/Identifier.md
+++ b/content/en/methods/menu-entry/Identifier.md
@@ -12,8 +12,6 @@ params:
The `Identifier` method returns the `identifier` property of the menu entry. If you define the menu entry [automatically], it returns the page's section.
-[automatically]: /content-management/menus/#define-automatically
-
{{< code-toggle file=hugo >}}
[[menus.main]]
identifier = 'about'
@@ -38,8 +36,7 @@ This example uses the `Identifier` method when querying the translation table on
```
-{{< note >}}
-In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
+> [!note]
+> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
-[details]: /content-management/menus/#properties-front-matter
-{{< /note >}}
+[automatically]: /content-management/menus/#define-automatically
diff --git a/content/en/methods/menu-entry/PageRef.md b/content/en/methods/menu-entry/PageRef.md
index 2680324c7..979879b03 100644
--- a/content/en/methods/menu-entry/PageRef.md
+++ b/content/en/methods/menu-entry/PageRef.md
@@ -29,28 +29,15 @@ If a matching page is not found:
- The [`Page`] method returns nil
- The [`HasMenuCurrent`] and [`IsMenuCurrent`] methods on a `Page` object return `false`
-{{< note >}}
-In almost also scenarios you should use the [`URL`] method instead.
-
-[`URL`]: /methods/menu-entry/url/
-{{< /note >}}
-
-[defining a menu entry]: /content-management/menus/#define-in-site-configuration
-[`Page`]: /methods/menu-entry/page/
-[`URL`]: /methods/menu-entry/url/
-[`IsMenuCurrent`]: /methods/page/ismenucurrent/
-[`HasMenuCurrent`]: /methods/page/hasmenucurrent/
-[`RelPermalink`]: /methods/page/relpermalink/
+> [!note]
+> In almost also scenarios you should use the [`URL`] method instead.
## Example
This example is contrived.
-{{< note >}}
-In almost also scenarios you should use the [`URL`] method instead.
-
-[`URL`]: /methods/menu-entry/url/
-{{< /note >}}
+> [!note]
+> In almost also scenarios you should use the [`URL`] method instead.
Consider this content structure:
@@ -114,3 +101,9 @@ Hugo renders this HTML:
```
In the above note that Hugo populates the `href` attribute of the second `anchor` element with the `pageRef` property as defined in the site configuration because the template code falls back to the `PageRef` method.
+
+[`HasMenuCurrent`]: /methods/page/hasmenucurrent/
+[`IsMenuCurrent`]: /methods/page/ismenucurrent/
+[`Page`]: /methods/menu-entry/page/
+[`URL`]: /methods/menu-entry/url/
+[defining a menu entry]: /content-management/menus/#define-in-site-configuration
diff --git a/content/en/methods/menu/ByWeight.md b/content/en/methods/menu/ByWeight.md
index 803bf3fe4..35edd0276 100644
--- a/content/en/methods/menu/ByWeight.md
+++ b/content/en/methods/menu/ByWeight.md
@@ -54,11 +54,8 @@ Hugo renders this to:
```
-{{< note >}}
-In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
-
-[details]: /content-management/menus/#properties-front-matter
-{{< /note >}}
+> [!note]
+> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
You can also sort menu entries using the [`sort`] function. For example, to sort by `weight` in descending order:
diff --git a/content/en/methods/page/CurrentSection.md b/content/en/methods/page/CurrentSection.md
index 3f71a8054..93457f13f 100644
--- a/content/en/methods/page/CurrentSection.md
+++ b/content/en/methods/page/CurrentSection.md
@@ -11,9 +11,8 @@ params:
{{% glossary-term section %}}
-{{< note >}}
-The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself.
-{{< /note >}}
+> [!note]
+> The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself.
Consider this content structure:
diff --git a/content/en/methods/page/Data.md b/content/en/methods/page/Data.md
index 3577c13a2..f636849c3 100644
--- a/content/en/methods/page/Data.md
+++ b/content/en/methods/page/Data.md
@@ -12,15 +12,10 @@ params:
The `Data` method on a `Page` object returns a unique data object for each [page kind](g).
-{{< note >}}
-The `Data` method is only useful within [taxonomy](g) and [term](g) templates.
-
-Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`]
-
-[`Pages`]: /methods/page/pages/
-[`RegularPages`]: /methods/page/regularpages/
-[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
-{{< /note >}}
+> [!note]
+> The `Data` method is only useful within [taxonomy](g) and [term](g) templates.
+>
+> Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`]
The examples that follow are based on this site configuration:
@@ -67,11 +62,8 @@ Terms
{{ $taxonomyObject := .Data.Terms }}
```
-{{< note >}}
-Once you have captured the `Taxonomy` object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages.
-
-[taxonomy methods]: /methods/taxonomy/
-{{< /note >}}
+> [!note]
+> Once you have captured the `Taxonomy` object, use any of the [taxonomy methods] to sort, count, or capture a subset of its weighted pages.
Learn more about [taxonomy templates].
@@ -102,5 +94,9 @@ Term
Learn more about [term templates].
+[`Pages`]: /methods/page/pages/
+[`RegularPages`]: /methods/page/regularpages/
+[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
+[taxonomy methods]: /methods/taxonomy/
[taxonomy templates]: /templates/types/#taxonomy
[term templates]: /templates/types/#term
diff --git a/content/en/methods/page/Date.md b/content/en/methods/page/Date.md
index 672a0630b..b6c2042c2 100644
--- a/content/en/methods/page/Date.md
+++ b/content/en/methods/page/Date.md
@@ -16,11 +16,8 @@ title = 'Article 1'
date = 2023-10-19T00:40:04-07:00
{{< /code-toggle >}}
-{{< note >}}
-The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details].
-
-[details]: /configuration/front-matter/#dates
-{{< /note >}}
+> [!note]
+> The date field in front matter is often considered to be the creation date, You can change its meaning, and its effect on your site, in the site configuration. See [details].
The date is a [time.Time] value. Format and localize the value with the [`time.Format`] function, or use it with any of the [time methods].
@@ -32,5 +29,6 @@ In the example above we explicitly set the date in front matter. With Hugo's def
[`time.Format`]: /functions/time/format/
[details]: /configuration/front-matter/#dates
+[details]: /configuration/front-matter/#dates
[time methods]: /methods/time/
[time.Time]: https://pkg.go.dev/time#Time
diff --git a/content/en/methods/page/File.md b/content/en/methods/page/File.md
index 0cfea1c92..7353b5956 100644
--- a/content/en/methods/page/File.md
+++ b/content/en/methods/page/File.md
@@ -22,15 +22,13 @@ content/
└── book-2.md
```
-{{< note >}}
-Code defensively by verifying file existence as shown in the examples below.
-{{< /note >}}
+> [!note]
+> Code defensively by verifying file existence as shown in the examples below.
## Methods
-{{< note >}}
-The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system.
-{{< /note >}}
+> [!note]
+> The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system.
### BaseFileName
@@ -88,8 +86,6 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend
(`bool`) Reports whether the file is a [content adapter].
-[content adapter]: /content-management/content-adapters/
-
```go-html-template
{{ with .File }}
{{ .IsContentAdapter }}
@@ -195,3 +191,5 @@ Without a backing file, Hugo will throw an error if you attempt to access a `.Fi
{{ .ContentBaseName }}
{{ end }}
```
+
+[content adapter]: /content-management/content-adapters/
diff --git a/content/en/methods/page/FirstSection.md b/content/en/methods/page/FirstSection.md
index 39b3dd9b9..73ddd2d7b 100644
--- a/content/en/methods/page/FirstSection.md
+++ b/content/en/methods/page/FirstSection.md
@@ -11,9 +11,8 @@ params:
{{% glossary-term section %}}
-{{< note >}}
-When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself.
-{{< /note >}}
+> [!note]
+> When called on the home page, the `FirstSection` method returns the `Page` object of the home page itself.
Consider this content structure:
diff --git a/content/en/methods/page/Fragments.md b/content/en/methods/page/Fragments.md
index cfc482a07..2c0460def 100644
--- a/content/en/methods/page/Fragments.md
+++ b/content/en/methods/page/Fragments.md
@@ -96,16 +96,14 @@ Hugo renders this to:
```
-{{< 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.
+> [!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.
+[`TableOfContents`]: /methods/page/tableofcontents/
+[ATX]: https://spec.commonmark.org/0.30/#atx-headings
[Markdown notation]: /content-management/shortcodes/#notation
-[standard notation]: /content-management/shortcodes/#notation
-{{< /note >}}
-
-[atx]: https://spec.commonmark.org/0.30/#atx-headings
[setext]: https://spec.commonmark.org/0.30/#setext-headings
+[standard notation]: /content-management/shortcodes/#notation
[table of contents]: /methods/page/tableofcontents/
-[`tableofcontents`]: /methods/page/tableofcontents/
diff --git a/content/en/methods/page/GitInfo.md b/content/en/methods/page/GitInfo.md
index dd983254c..aa08488c4 100644
--- a/content/en/methods/page/GitInfo.md
+++ b/content/en/methods/page/GitInfo.md
@@ -11,9 +11,8 @@ params:
The `GitInfo` method on a `Page` object returns an object with additional methods.
-{{< note >}}
-Hugo's Git integration is performant, but may increase build times on large sites.
-{{< /note >}}
+> [!note]
+> Hugo's Git integration is performant, but may increase build times on large sites.
## Prerequisites
@@ -31,13 +30,10 @@ Alternatively, use the command line flag when building your site:
hugo --enableGitInfo
```
-{{< note >}}
-When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file.
-
-This is configurable. See [details].
-
-[details]: /configuration/front-matter/#dates
-{{< /note >}}
+> [!note]
+> When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file.
+>
+> This is configurable. See [details].
## Methods
@@ -127,10 +123,6 @@ By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` obj
You can change this behavior in your [site configuration].
-[git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
-[gitmailmap]: https://git-scm.com/docs/gitmailmap
-[site configuration]: /configuration/front-matter/
-
## Hosting considerations
When hosting your site in a CI/CD environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may not be accurate---it may reflect the most recent repository commit, not the commit that last modified the file.
@@ -153,3 +145,7 @@ Vercel | Shallow | No
[^2]: You can configure the GitHub Action to do a deep clone by specifying `fetch-depth: 0` in the applicable "checkout" step of your workflow file, as shown in the Hugo documentation's [example workflow file](/host-and-deploy/host-on-github-pages/#procedure).
[^3]: You can configure the GitLab Runner's clone depth [as explained in the GitLab documentation](https://docs.gitlab.com/ee/ci/large_repositories/#shallow-cloning); see also the Hugo documentation's [example workflow file](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd).
+
+[details]: /configuration/front-matter/#dates
+[gitmailmap]: https://git-scm.com/docs/gitmailmap
+[site configuration]: /configuration/front-matter/
diff --git a/content/en/methods/page/HasMenuCurrent.md b/content/en/methods/page/HasMenuCurrent.md
index ceb81a1ea..207882167 100644
--- a/content/en/methods/page/HasMenuCurrent.md
+++ b/content/en/methods/page/HasMenuCurrent.md
@@ -27,8 +27,7 @@ If the `Page` object associated with the menu entry is a section, this method al
See [menu templates] for a complete example.
-{{< note >}}
-When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration.
-{{< /note >}}
+> [!note]
+> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration.
[menu templates]: /templates/menu/#example
diff --git a/content/en/methods/page/InSection.md b/content/en/methods/page/InSection.md
index 4b4cca1ad..adca82d86 100644
--- a/content/en/methods/page/InSection.md
+++ b/content/en/methods/page/InSection.md
@@ -75,9 +75,8 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj
The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
-{{< note >}}
-Use the `$` to get the context passed into the template.
-{{< /note >}}
+> [!note]
+> Use the `$` to get the context passed into the template.
```go-html-template
{{ with .Site.GetPage "/auctions" }}
@@ -85,9 +84,8 @@ Use the `$` to get the context passed into the template.
{{ end }}
```
-{{< note >}}
-Gaining a thorough understanding of context is critical for anyone writing template code.
-{{< /note >}}
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
-[`with`]: /functions/go-template/with/
[`else`]: /functions/go-template/else/
+[`with`]: /functions/go-template/with/
diff --git a/content/en/methods/page/IsAncestor.md b/content/en/methods/page/IsAncestor.md
index 0e916b19d..fe1b78454 100644
--- a/content/en/methods/page/IsAncestor.md
+++ b/content/en/methods/page/IsAncestor.md
@@ -71,9 +71,8 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj
The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
-{{< note >}}
-Use the `$` to get the context passed into the template.
-{{< /note >}}
+> [!note]
+> Use the `$` to get the context passed into the template.
```go-html-template
{{ with .Site.GetPage "/auctions" }}
@@ -81,9 +80,8 @@ Use the `$` to get the context passed into the template.
{{ end }}
```
-{{< note >}}
-Gaining a thorough understanding of context is critical for anyone writing template code.
-{{< /note >}}
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
-[`with`]: /functions/go-template/with/
[`else`]: /functions/go-template/else/
+[`with`]: /functions/go-template/with/
diff --git a/content/en/methods/page/IsDescendant.md b/content/en/methods/page/IsDescendant.md
index 9c80fc61a..6ee8d3c4f 100644
--- a/content/en/methods/page/IsDescendant.md
+++ b/content/en/methods/page/IsDescendant.md
@@ -71,9 +71,8 @@ Inside of the `with` block, the [context](g) (the dot) is the section `Page` obj
The result would be wrong when rendering the "auction-1" page because we are comparing the section page to itself.
-{{< note >}}
-Use the `$` to get the context passed into the template.
-{{< /note >}}
+> [!note]
+> Use the `$` to get the context passed into the template.
```go-html-template
{{ with .Site.GetPage "/auctions" }}
@@ -81,9 +80,8 @@ Use the `$` to get the context passed into the template.
{{ end }}
```
-{{< note >}}
-Gaining a thorough understanding of context is critical for anyone writing template code.
-{{< /note >}}
+> [!note]
+> Gaining a thorough understanding of context is critical for anyone writing template code.
-[`with`]: /functions/go-template/with/
[`else`]: /functions/go-template/else/
+[`with`]: /functions/go-template/with/
diff --git a/content/en/methods/page/IsMenuCurrent.md b/content/en/methods/page/IsMenuCurrent.md
index 96db6101f..9bbacd018 100644
--- a/content/en/methods/page/IsMenuCurrent.md
+++ b/content/en/methods/page/IsMenuCurrent.md
@@ -25,8 +25,7 @@ aliases: [/functions/ismenucurrent]
See [menu templates] for a complete example.
-{{< note >}}
-When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration.
-{{< /note >}}
+> [!note]
+> When using this method you must either define the menu entry in front matter, or specify a `pageRef` property when defining the menu entry in your site configuration.
[menu templates]: /templates/menu/#example
diff --git a/content/en/methods/page/Page.md b/content/en/methods/page/Page.md
index bdd7b5962..adbefd247 100644
--- a/content/en/methods/page/Page.md
+++ b/content/en/methods/page/Page.md
@@ -30,8 +30,7 @@ The page title is: {{ .Page.Title }}
To handle both scenarios, the partial template must be able to access the `Page` object with `Page.Page`.
-{{< note >}}
-And yes, that means you can do `.Page.Page.Page.Page.Title` too.
-
-But don't.
-{{< /note >}}
+> [!note]
+> And yes, that means you can do `.Page.Page.Page.Page.Title` too.
+>
+> But don't.
diff --git a/content/en/methods/page/Pages.md b/content/en/methods/page/Pages.md
index 22e49986a..ba43c36a8 100644
--- a/content/en/methods/page/Pages.md
+++ b/content/en/methods/page/Pages.md
@@ -70,14 +70,13 @@ When rendering lesson-2, the `Pages` method returns:
In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section.
-{{< note >}}
-When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details].
-
-[details]: /methods/site/pages/
-{{< /note >}}
+> [!note]
+> When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details].
```go-html-template
{{ range .Site.Pages.ByTitle }}
{{ end }}
```
+
+[details]: /methods/site/pages/
diff --git a/content/en/methods/page/Paginate.md b/content/en/methods/page/Paginate.md
index fdf67ef2e..0b699d6b2 100644
--- a/content/en/methods/page/Paginate.md
+++ b/content/en/methods/page/Paginate.md
@@ -13,21 +13,13 @@ Pagination is the process of splitting a list page into two or more pagers, wher
By default, the number of elements on each pager is determined by your [site configuration]. The default is `10`. Override that value by providing a second argument, an integer, when calling the `Paginate` method.
-[site configuration]: /configuration/pagination/
-
-{{< note >}}
-There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection.
-
-The `Paginate` method is more flexible.
-{{< /note >}}
+> [!note]
+> There is also a `Paginator` method on `Page` objects, but it can neither filter nor sort the page collection.
+>
+> The `Paginate` method is more flexible.
You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates].
-[home template]: /templates/types/#home
-[section templates]: /templates/types/#section
-[taxonomy templates]: /templates/types/#taxonomy
-[term templates]: /templates/types/#term
-
```go-html-template {file="layouts/_default/list.html"}
{{ $pages := where .Site.RegularPages "Section" "articles" }}
{{ $pages = $pages.ByTitle }}
@@ -45,6 +37,11 @@ In the example above, we:
1. Range over the paginated page collection, rendering a link to each page
1. Call the embedded pagination template to create navigation links between pagers
-{{< note >}}
-Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
-{{< /note >}}
+> [!note]
+> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
+
+[home template]: /templates/types/#home
+[section templates]: /templates/types/#section
+[site configuration]: /configuration/pagination/
+[taxonomy templates]: /templates/types/#taxonomy
+[term templates]: /templates/types/#term
diff --git a/content/en/methods/page/Paginator.md b/content/en/methods/page/Paginator.md
index a97f6461c..bff7ea90c 100644
--- a/content/en/methods/page/Paginator.md
+++ b/content/en/methods/page/Paginator.md
@@ -13,15 +13,8 @@ Pagination is the process of splitting a list page into two or more pagers, wher
The number of elements on each pager is determined by your [site configuration]. The default is `10`.
-[site configuration]: /configuration/pagination/
-
You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates]. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context.
-[home template]: /templates/types/#home
-[section templates]: /templates/types/#section
-[taxonomy templates]: /templates/types/#taxonomy
-[term templates]: /templates/types/#term
-
```go-html-template {file="layouts/_default/list.html"}
{{ range .Paginator.Pages }}
@@ -31,14 +24,17 @@ You can invoke pagination on the [home template], [section templates], [taxonomy
In the example above, the embedded pagination template creates navigation links between pagers.
-{{< note >}}
-Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context.
+> [!note]
+> Although simple to invoke, with the `Paginator` method you can neither filter nor sort the page collection. It acts upon the page collection received in context.
+>
+> The [`Paginate`] method is more flexible, and strongly recommended.
-The [`Paginate`] method is more flexible, and strongly recommended.
+> [!note]
+> Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
-[`paginate`]: /methods/page/paginate/
-{{< /note >}}
-
-{{< note >}}
-Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
-{{< /note >}}
+[home template]: /templates/types/#home
+[section templates]: /templates/types/#section
+[site configuration]: /configuration/pagination/
+[taxonomy templates]: /templates/types/#taxonomy
+[term templates]: /templates/types/#term
+[`Paginate`]: /methods/page/paginate/
diff --git a/content/en/methods/page/Parent.md b/content/en/methods/page/Parent.md
index babe403b3..0946a7993 100644
--- a/content/en/methods/page/Parent.md
+++ b/content/en/methods/page/Parent.md
@@ -11,11 +11,8 @@ params:
{{% glossary-term section %}}
-{{< note >}}
-The parent section of a regular page is the [current section].
-
-[current section]: /methods/page/currentsection/
-{{< /note >}}
+> [!note]
+> The parent section of a regular page is the [current section].
Consider this content structure:
@@ -51,3 +48,5 @@ In the example above, note the parent section of the home page is nil. Code defe
{{ .LinkTitle }}
{{ end }}
```
+
+[current section]: /methods/page/currentsection/
diff --git a/content/en/methods/page/Path.md b/content/en/methods/page/Path.md
index 928a6a611..db4e7d629 100644
--- a/content/en/methods/page/Path.md
+++ b/content/en/methods/page/Path.md
@@ -19,14 +19,10 @@ The `Path` method on a `Page` object returns the logical path of the given page,
{{ .Path }} → /posts/post-1
```
-{{< note >}}
-Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release.
-
-The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024.
-
-[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0
-[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
-{{< /note >}}
+> [!note]
+> Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release.
+>
+> The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024.
The value returned by the `Path` method on a `Page` object is independent of content format, language, and URL modifiers such as the `slug` and `url` front matter fields.
@@ -96,20 +92,8 @@ Methods|Functions|Shortcodes
[`Shortcode.Ref`]|||
[`Shortcode.RelRef`]|||
-[`urls.Ref`]: /functions/urls/ref/
-[`urls.RelRef`]: /functions/urls/relref/
-[`Page.GetPage`]: /methods/page/getpage/
-[`Site.GetPage`]: /methods/site/getpage/
-[`ref`]: /shortcodes/ref/
-[`relref`]: /shortcodes/relref/
-[`Page.Ref`]: /methods/page/ref/
-[`Page.RelRef`]: /methods/page/relref/
-[`Shortcode.Ref`]: /methods/shortcode/ref
-[`Shortcode.RelRef`]: /methods/shortcode/relref
-
-{{< note >}}
-Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
-{{< /note >}}
+> [!note]
+> Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
## Logical tree
@@ -139,6 +123,18 @@ A key difference between these trees is the relative path from p1 to p2:
- In the file tree, the relative path from p1 to p2 is `../p2.md`
- In the logical tree, the relative path is `p2`
-{{< note >}}
-Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
-{{< /note >}}
+> [!note]
+> Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+
+[`Page.GetPage`]: /methods/page/getpage/
+[`Page.Ref`]: /methods/page/ref/
+[`Page.RelRef`]: /methods/page/relref/
+[`ref`]: /shortcodes/ref/
+[`relref`]: /shortcodes/relref/
+[`Shortcode.Ref`]: /methods/shortcode/ref
+[`Shortcode.RelRef`]: /methods/shortcode/relref
+[`Site.GetPage`]: /methods/site/getpage/
+[`urls.Ref`]: /functions/urls/ref/
+[`urls.RelRef`]: /functions/urls/relref/
+[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
+[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0
diff --git a/content/en/methods/page/PlainWords.md b/content/en/methods/page/PlainWords.md
index 4dcd73be4..5749a21f9 100644
--- a/content/en/methods/page/PlainWords.md
+++ b/content/en/methods/page/PlainWords.md
@@ -11,11 +11,8 @@ params:
The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words.
-{{< note >}}
-_Fields splits the string s around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only whitespace._
-
-[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace
-{{< /note >}}
+> [!note]
+> `Fields` splits the string `s` around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of `s` or an empty slice if `s` contains only whitespace.
As a result, elements within the slice may contain leading or trailing punctuation.
@@ -31,3 +28,4 @@ To determine the approximate number of unique words on a page:
[`Plain`]: /methods/page/plain/
[`strings.Fields`]: https://pkg.go.dev/strings#Fields
+[`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace
diff --git a/content/en/methods/page/RawContent.md b/content/en/methods/page/RawContent.md
index f4d23d3a9..41215ef53 100644
--- a/content/en/methods/page/RawContent.md
+++ b/content/en/methods/page/RawContent.md
@@ -17,8 +17,7 @@ The `RawContent` method on a `Page` object returns the raw content. The raw cont
This is useful when rendering a page in a plain text [output format](g).
-{{< note >}}
-[Shortcodes](g) within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object.
+> [!note]
+> [Shortcodes](g) within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object.
[`RenderShortcodes`]: /methods/page/rendershortcodes/
-{{< /note >}}
diff --git a/content/en/methods/page/RegularPages.md b/content/en/methods/page/RegularPages.md
index e50daf808..761de3af5 100644
--- a/content/en/methods/page/RegularPages.md
+++ b/content/en/methods/page/RegularPages.md
@@ -67,14 +67,13 @@ When rendering lesson-2, the `RegularPages` method returns:
In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section.
-{{< note >}}
-When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details].
-
-[details]: /methods/site/regularpages/
-{{< /note >}}
+> [!note]
+> When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details].
```go-html-template
{{ range .Site.RegularPages.ByTitle }}
{{ end }}
```
+
+[details]: /methods/site/regularpages/
diff --git a/content/en/methods/page/RegularPagesRecursive.md b/content/en/methods/page/RegularPagesRecursive.md
index 7794a511f..d85cd0b48 100644
--- a/content/en/methods/page/RegularPagesRecursive.md
+++ b/content/en/methods/page/RegularPagesRecursive.md
@@ -79,6 +79,5 @@ When rendering lesson-2, the `RegularPagesRecursive` method returns:
lessons/lesson-2/resources/task-list.md
lessons/lesson-2/resources/worksheet.md
-{{< note >}}
-The `RegularPagesRecursive` method is not available on a `Site` object.
-{{< /note >}}
+> [!note]
+> The `RegularPagesRecursive` method is not available on a `Site` object.
diff --git a/content/en/methods/page/Summary.md b/content/en/methods/page/Summary.md
index 853851f6b..9158e571d 100644
--- a/content/en/methods/page/Summary.md
+++ b/content/en/methods/page/Summary.md
@@ -16,8 +16,6 @@ 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.
-[summary]: /content-management/summaries/
-
To list the pages in a section with a summary beneath each link:
```go-html-template
@@ -29,8 +27,6 @@ To list the pages in a section with a summary beneath each link:
Depending on content length and how you define the summary, the summary may be equivalent to the content itself. To determine whether the content length exceeds the summary length, use the [`Truncated`] method on a `Page` object. This is useful for conditionally rendering a “read more” link:
-[`Truncated`]: /methods/page/truncated
-
```go-html-template
{{ range .Pages }}
@@ -41,6 +37,8 @@ Depending on content length and how you define the summary, the summary may be e
{{ end }}
```
-{{< note >}}
-The `Truncated` method returns `false` if you define the summary in front matter.
-{{< /note >}}
+> [!note]
+> The `Truncated` method returns `false` if you define the summary in front matter.
+
+[`Truncated`]: /methods/page/truncated
+[summary]: /content-management/summaries/
diff --git a/content/en/methods/page/Truncated.md b/content/en/methods/page/Truncated.md
index 1d633fcfe..8c2573069 100644
--- a/content/en/methods/page/Truncated.md
+++ b/content/en/methods/page/Truncated.md
@@ -25,6 +25,5 @@ The `Truncated` method returns `true` if the content length exceeds the summary
{{ end }}
```
-{{< note >}}
-The `Truncated` method returns `false` if you define the summary in front matter.
-{{< /note >}}
+> [!note]
+> The `Truncated` method returns `false` if you define the summary in front matter.
diff --git a/content/en/methods/page/Type.md b/content/en/methods/page/Type.md
index cf1bd247e..6f855fbe3 100644
--- a/content/en/methods/page/Type.md
+++ b/content/en/methods/page/Type.md
@@ -9,7 +9,7 @@ params:
signatures: [PAGE.Type]
---
-The `Type` method on a `Page` object returns the [content type](g) of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined.
+The `Type` method on a `Page` object returns the [content type](g) of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined.
With this content structure:
diff --git a/content/en/methods/resource/Colors.md b/content/en/methods/resource/Colors.md
index 99b9b2f39..9e7b82985 100644
--- a/content/en/methods/resource/Colors.md
+++ b/content/en/methods/resource/Colors.md
@@ -30,18 +30,10 @@ Each color is an object with the following methods:
(`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.
-{{< note >}}
-Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments.
-
-Hugo renders an `images.Color` object as a hexadecimal color value.
-
-[`images.Dither`]: /functions/images/dither/
-[`images.Padding`]: /functions/images/padding/
-[`images.Text`]: /functions/images/text/
-{{< /note >}}
-
-[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
-[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+> [!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
@@ -172,7 +164,12 @@ Calculate the contrast ratio to determine WCAG conformance:
{{ end }}
```
-[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
+[`images.Dither`]: /functions/images/dither/
+[`images.Padding`]: /functions/images/padding/
+[`images.Text`]: /functions/images/text/
[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
[minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum
+[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
diff --git a/content/en/methods/resource/Err.md b/content/en/methods/resource/Err.md
index 52c7155e9..591af8266 100644
--- a/content/en/methods/resource/Err.md
+++ b/content/en/methods/resource/Err.md
@@ -56,6 +56,5 @@ To log an error as a warning instead of an error:
{{ end }}
```
-{{< note >}}
-An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above.
-{{< /note >}}
+> [!note]
+> An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above.
diff --git a/content/en/methods/shortcode/Get.md b/content/en/methods/shortcode/Get.md
index 7bdecb78f..b9c01cfc4 100644
--- a/content/en/methods/shortcode/Get.md
+++ b/content/en/methods/shortcode/Get.md
@@ -11,9 +11,8 @@ 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 >}}
-Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details.
-{{< /note >}}
+> [!note]
+> Some shortcodes support positional arguments, some support named arguments, and others support both. Refer to the shortcode's documentation for usage details.
## Positional arguments
@@ -43,6 +42,5 @@ To retrieve arguments by name:
{{ printf "%s %s." (.Get "greeting") (.Get "firstName") }} → Hello world.
```
-{{< note >}}
-Argument names are case-sensitive.
-{{< /note >}}
+> [!note]
+> Argument names are case-sensitive.
diff --git a/content/en/methods/shortcode/Inner.md b/content/en/methods/shortcode/Inner.md
index 8df179589..cdce4c1c3 100644
--- a/content/en/methods/shortcode/Inner.md
+++ b/content/en/methods/shortcode/Inner.md
@@ -41,22 +41,16 @@ 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.
-[`strings.TrimSpace`]: /functions/strings/trimspace/
-{{< /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.
-{{< /note >}}
+> [!note]
+> In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML.
## Use RenderString
Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object:
-[`RenderString`]: /methods/page/renderstring/
-
```go-html-template {file="layouts/shortcodes/card.html"}
{{ with .Get "title" }}
@@ -81,9 +75,6 @@ Hugo renders this to:
You can use the [`markdownify`] function instead of the `RenderString` method, but the latter is more flexible. See [details].
-[details]: /methods/page/renderstring/
-[`markdownify`]: /functions/transform/markdownify/
-
## Alternative notation
Instead of calling the shortcode with the `{{}}` notation, use the `{{%/* */%}}` notation:
@@ -138,13 +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.
-[Markdown notation]: /content-management/shortcodes/#notation
-{{< /note >}}
-
-[commonmark]: https://commonmark.org/
+[`markdownify`]: /functions/transform/markdownify/
+[`RenderString`]: /methods/page/renderstring/
+[`strings.TrimSpace`]: /functions/strings/trimspace/
+[CommonMark]: https://spec.commonmark.org/current/
+[details]: /methods/page/renderstring/
[indentation]: https://spec.commonmark.org/0.30/#indented-code-blocks
-[raw html blocks]: https://spec.commonmark.org/0.30/#html-blocks
+[Markdown notation]: /content-management/shortcodes/#notation
+[raw HTML blocks]: https://spec.commonmark.org/0.31.2/#html-blocks
[security model]: /about/security/
diff --git a/content/en/methods/shortcode/Ordinal.md b/content/en/methods/shortcode/Ordinal.md
index 605494dd5..0fb4f1e64 100644
--- a/content/en/methods/shortcode/Ordinal.md
+++ b/content/en/methods/shortcode/Ordinal.md
@@ -12,9 +12,8 @@ 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 >}}
-Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page.
-{{< /note >}}
+> [!note]
+> Hugo increments the ordinal with each shortcode call, regardless of the specific shortcode type. This means that the ordinal value is tracked sequentially across all shortcodes within a given page.
This method is useful for, among other things, assigning unique element IDs when a shortcode is called two or more times from the same page. For example:
@@ -48,8 +47,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/
-{{< /note >}}
diff --git a/content/en/methods/shortcode/Position.md b/content/en/methods/shortcode/Position.md
index 5ee25ade4..24810e825 100644
--- a/content/en/methods/shortcode/Position.md
+++ b/content/en/methods/shortcode/Position.md
@@ -26,6 +26,5 @@ In the absence of a "greeting" argument, Hugo will throw an error message and fa
ERROR The "myshortcode" shortcode requires a 'greeting' argument. See "/home/user/project/content/about.md:11:1"
```
-{{< note >}}
-The position can be expensive to calculate. Limit its use to error reporting.
-{{< /note >}}
+> [!note]
+> The position can be expensive to calculate. Limit its use to error reporting.
diff --git a/content/en/methods/shortcode/Store.md b/content/en/methods/shortcode/Store.md
index d1ed76da8..76cb9237d 100644
--- a/content/en/methods/shortcode/Store.md
+++ b/content/en/methods/shortcode/Store.md
@@ -13,13 +13,12 @@ params:
Use the `Store` method to create a [scratch pad](g) to store and manipulate data, scoped to the current shortcode. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
-{{< note >}}
-With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete.
-
-[assign values to template variables]: https://go.dev/doc/go1.11#texttemplatepkgtexttemplate
-[`newScratch`]: /functions/collections/newScratch/
-{{< /note >}}
+> [!note]
+> With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete.
{{% include "_common/store-methods.md" %}}
{{% include "_common/scratch-pad-scope.md" %}}
+
+[`newScratch`]: /functions/collections/newScratch/
+[assign values to template variables]: https://go.dev/doc/go1.11#texttemplatepkgtexttemplate
diff --git a/content/en/methods/site/BaseURL.md b/content/en/methods/site/BaseURL.md
index cf97d677c..3644443cb 100644
--- a/content/en/methods/site/BaseURL.md
+++ b/content/en/methods/site/BaseURL.md
@@ -21,13 +21,12 @@ Template:
{{ .Site.BaseURL }} → https://example.org/docs/
```
-{{< note >}}
-There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration.
+> [!note]
+> There is almost never a good reason to use this method in your templates. Its usage tends to be fragile due to misconfiguration.
+>
+> Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead.
-Use the [`absURL`], [`absLangURL`], [`relURL`], or [`relLangURL`] functions instead.
-
-[`absURL`]: /functions/urls/absURL/
[`absLangURL`]: /functions/urls/absLangURL/
-[`relURL`]: /functions/urls/relURL/
+[`absURL`]: /functions/urls/absURL/
[`relLangURL`]: /functions/urls/relLangURL/
-{{< /note >}}
+[`relURL`]: /functions/urls/relURL/
diff --git a/content/en/methods/site/Data.md b/content/en/methods/site/Data.md
index e720d14e7..296851874 100644
--- a/content/en/methods/site/Data.md
+++ b/content/en/methods/site/Data.md
@@ -11,13 +11,8 @@ params:
Use the `Data` method on a `Site` object to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML.
-[mounted]: /configuration/module/#mounts
-
-{{< note >}}
-Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method.
-
-[`transform.Unmarshal`]: /functions/transform/unmarshal/
-{{< /note >}}
+> [!note]
+> Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method.
Consider this `data` directory:
@@ -104,3 +99,5 @@ In the template examples above, each of the keys is a valid identifier. For exam
```
[`index`]: /functions/collections/indexfunction/
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[mounted]: /configuration/module/#mounts
diff --git a/content/en/methods/site/Menus.md b/content/en/methods/site/Menus.md
index 76b63befb..398a9b022 100644
--- a/content/en/methods/site/Menus.md
+++ b/content/en/methods/site/Menus.md
@@ -11,11 +11,8 @@ params:
The `Menus` method on a `Site` object returns a collection of menus, where each menu contains one or more entries, either flat or nested. Each entry points to a page within the site, or to an external resource.
-{{< note >}}
-Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples.
-
-[menus]: /content-management/menus/
-{{< /note >}}
+> [!note]
+> Menus can be defined and localized in several ways. Please see the [menus] section for a complete explanation and examples.
A site can have multiple menus. For example, a main menu and a footer menu:
@@ -86,7 +83,7 @@ You will typically render a menu using a partial template. As the active menu en
The example above is simplistic. Please see the [menu templates] section for more information.
-[menu templates]: /templates/menu/
-
[`partial`]: /functions/partials/include/
[`partialCached`]: /functions/partials/includecached/
+[menu templates]: /templates/menu/
+[menus]: /content-management/menus/
diff --git a/content/en/methods/site/Taxonomies.md b/content/en/methods/site/Taxonomies.md
index bb8a2d228..3beb76b92 100644
--- a/content/en/methods/site/Taxonomies.md
+++ b/content/en/methods/site/Taxonomies.md
@@ -90,13 +90,10 @@ Hugo renders this to:
```
-{{< note >}}
-Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages.
-
-Please see the [taxonomies] section for a complete explanation and examples.
-
-[taxonomies]: /content-management/taxonomies/
-{{< /note >}}
+> [!note]
+> Hugo's taxonomy system is powerful, allowing you to classify content and create relationships between pages.
+>
+> Please see the [taxonomies] section for a complete explanation and examples.
## Examples
@@ -176,3 +173,5 @@ This example will list all taxonomies and their terms, as well as all the conten
{{ end }}
{{ end }}
```
+
+[taxonomies]: /content-management/taxonomies/
diff --git a/content/en/methods/time/AddDate.md b/content/en/methods/time/AddDate.md
index c7d534ecd..7b40e1da9 100644
--- a/content/en/methods/time/AddDate.md
+++ b/content/en/methods/time/AddDate.md
@@ -21,11 +21,10 @@ aliases: [/functions/adddate]
{{ $d.AddDate -1 -1 -1 | time.Format "2006-01-02" }} → 2020-11-30
```
-{{< note >}}
-When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year.
-
-See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team.
-{{< /note >}}
+> [!note]
+> When adding months or years, Hugo normalizes the final `time.Time` value if the resulting day does not exist. For example, adding one month to 31 January produces 2 March or 3 March, depending on the year.
+>
+> See [this explanation](https://github.com/golang/go/issues/31145#issuecomment-479067967) from the Go team.
```go-html-template
{{ $d := "2023-01-31" | time.AsTime }}
diff --git a/content/en/methods/time/Format.md b/content/en/methods/time/Format.md
index 719f8f128..8a484b74e 100644
--- a/content/en/methods/time/Format.md
+++ b/content/en/methods/time/Format.md
@@ -18,11 +18,8 @@ aliases: [/methods/time/format]
{{ $t.Format $format }} → 27 Jan 2023
```
-{{< note >}}
-To [localize](g) the return value, use the [`time.Format`] function instead.
-
-[`time.Format`]: /functions/time/format/
-{{< /note >}}
+> [!note]
+> To [localize](g) the return value, use the [`time.Format`] function instead.
Use the `Format` method with any `time.Time` value, including the four predefined front matter dates:
@@ -35,11 +32,8 @@ Use the `Format` method with any `time.Time` value, including the four predefine
{{ .Lastmod.Format $format }}
```
-{{< note >}}
-Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset.
-
-[`time.Format`]: /functions/time/format/
-{{< /note >}}
+> [!note]
+> Use the [`time.Format`] function to format string representations of dates, and to format raw TOML dates that exclude time and time zone offset.
## Layout string
@@ -90,3 +84,5 @@ Use the [`humanize`](/functions/inflect/humanize) function to render the day of
{{ humanize $t.Day }} of {{ $t.Format "January 2006" }} → 27th of January 2023
```
+
+[`time.Format`]: /functions/time/format/
diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md
index cb8d71f8b..7ba282a0a 100755
--- a/content/en/render-hooks/blockquotes.md
+++ b/content/en/render-hooks/blockquotes.md
@@ -49,15 +49,10 @@ Text
Type
: (`string`) The blockquote type. Returns `alert` if the blockquote has an alert designator, else `regular`. See the [alerts](#alerts) section below.
-[Markdown attributes]: /content-management/markdown-attributes/
-[`RenderShortcodes`]: /methods/page/rendershortcodes
-
## Examples
In its default configuration, Hugo renders Markdown blockquotes according to the [CommonMark specification]. To create a render hook that does the same thing:
-[CommonMark specification]: https://spec.commonmark.org/current/
-
```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
{{ .Text }}
@@ -113,10 +108,6 @@ With the basic Markdown syntax, the first line of each alert is an alert designa
The basic syntax is compatible with [GitHub], [Obsidian], and [Typora].
-[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
-[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts
-[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts
-
### Extended syntax
With the extended Markdown syntax, you may optionally include an alert sign and/or an alert title. The alert sign is one of `+` or `-`, typically used to indicate whether an alert is graphically foldable. For example:
@@ -128,9 +119,8 @@ With the extended Markdown syntax, you may optionally include an alert sign and/
The extended syntax is compatible with [Obsidian].
-{{< note >}}
-The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote.
-{{< /note >}}
+> [!note]
+> The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote.
### Example
@@ -185,3 +175,10 @@ layouts/
```
{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[CommonMark specification]: https://spec.commonmark.org/current/
+[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
+[Markdown attributes]: /content-management/markdown-attributes/
+[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts
+[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts
diff --git a/content/en/render-hooks/code-blocks.md b/content/en/render-hooks/code-blocks.md
index 5de9e7ab7..d1a01e9b0 100755
--- a/content/en/render-hooks/code-blocks.md
+++ b/content/en/render-hooks/code-blocks.md
@@ -25,9 +25,6 @@ A fenced code block consists of:
- A code sample
- A trailing code fence
-[code fence]: https://spec.commonmark.org/0.31.2/#code-fence
-[info string]: https://spec.commonmark.org/0.31.2/#info-string
-
In the previous example, the info string contains:
- The language of the code sample (the first word)
@@ -39,12 +36,8 @@ In the example above, the _generic attributes_ are `class` and `id`. In the abse
In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. Hugo uses the [Chroma] syntax highlighter to render the code sample. You can control the appearance of the rendered code by specifying one or more [highlighting options].
-[Chroma]: https://github.com/alecthomas/chroma/
-[highlighting options]: /functions/transform/highlight/#options
-
-{{< note >}}
-Although `style` is a global HTML attribute, when used in an info string it is a highlighting option.
-{{< /note >}}
+> [!note]
+> Although `style` is a global HTML attribute, when used in an info string it is a highlighting option.
## Context
@@ -75,14 +68,10 @@ Position
Type
: (`string`) The first word of the info string, typically the code language.
-[`RenderShortcodes`]: /methods/page/rendershortcodes
-
## Examples
In its default configuration, Hugo renders fenced code blocks by passing the code sample through the Chroma syntax highlighter and wrapping the result. To create a render hook that does the same thing:
-[CommonMark specification]: https://spec.commonmark.org/current/
-
```go-html-template {file="layouts/_default/_markup/render-codeblock.html" copy=true}
{{ $result := transform.HighlightCodeBlock . }}
{{ $result.Wrapped }}
@@ -101,8 +90,6 @@ layouts/
For example, to create a code block render hook to render [Mermaid] diagrams:
-[Mermaid]: https://mermaid.js.org/
-
```go-html-template {file="layouts/_default/_markup/render-codeblock-mermaid.html" copy=true}
{{ .Inner | htmlEscape | safeHTML }}
@@ -123,13 +110,18 @@ Then include this snippet at the _bottom_ of your base template, before the clos
See the [diagrams] page for details.
-[diagrams]: /content-management/diagrams/#mermaid-diagrams
-
## Embedded
Hugo includes an [embedded code block render hook] to render [GoAT diagrams].
+{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[Chroma]: https://github.com/alecthomas/chroma/
+[code fence]: https://spec.commonmark.org/0.31.2/#code-fence
+[diagrams]: /content-management/diagrams/#mermaid-diagrams
[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
[GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii
-
-{{% include "/_common/render-hooks/pageinner.md" %}}
+[highlighting options]: /functions/transform/highlight/#options
+[info string]: https://spec.commonmark.org/0.31.2/#info-string
+[Mermaid]: https://mermaid.js.org/
diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md
index bfa51c567..a4faac672 100755
--- a/content/en/render-hooks/images.md
+++ b/content/en/render-hooks/images.md
@@ -57,19 +57,13 @@ Text
Title
: (`string`) The image title.
-[Markdown attributes]: /content-management/markdown-attributes/
-[`RenderShortcodes`]: /methods/page/rendershortcodes
-
## Examples
-{{< note >}}
-With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
-{{< /note >}}
+> [!note]
+> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing:
-[CommonMark specification]: https://spec.commonmark.org/current/
-
```go-html-template {file="layouts/_default/_markup/render-image.html" copy=true}
}}
[markup.goldmark.renderHooks.image]
enableDefault = true
@@ -118,11 +110,8 @@ enableDefault = true
A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.
-{{< note >}}
-The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
-
-[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
-{{< /note >}}
+> [!note]
+> The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
@@ -141,3 +130,9 @@ target = 'assets'
Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations.
{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[CommonMark specification]: https://spec.commonmark.org/current/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded image render hook]: {{% eturl render-image %}}
+[Markdown attributes]: /content-management/markdown-attributes/
diff --git a/content/en/render-hooks/introduction.md b/content/en/render-hooks/introduction.md
index 4325294e3..045d25c3d 100755
--- a/content/en/render-hooks/introduction.md
+++ b/content/en/render-hooks/introduction.md
@@ -16,13 +16,10 @@ When rendering Markdown to HTML, render hooks override the conversion. Each rend
- [Passthrough elements](/render-hooks/passthrough)
- [Tables](/render-hooks/tables)
-{{< note >}}
-Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
-
-The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats.
-
-[content formats]: /content-management/formats/
-{{< /note >}}
+> [!note]
+> Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
+>
+> The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats.
For example, consider this Markdown:
@@ -80,3 +77,5 @@ layouts/
```
The remaining pages in this section describe each type of render hook, including examples and the context received by each template.
+
+[content formats]: /content-management/formats/
diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md
index 63fcae567..23f725eb7 100755
--- a/content/en/render-hooks/links.md
+++ b/content/en/render-hooks/links.md
@@ -41,18 +41,13 @@ Text
Title
: (`string`) The link title.
-[`RenderShortcodes`]: /methods/page/rendershortcodes
-
## Examples
-{{< note >}}
-With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
-{{< /note >}}
+> [!note]
+> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
-[CommonMark specification]: https://spec.commonmark.org/current/
-
```go-html-template {file="layouts/_default/_markup/render-link.html" copy=true}
}}
[markup.goldmark.renderHooks.link]
enableDefault = true
@@ -90,11 +83,8 @@ enableDefault = true
A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.
-{{< note >}}
-The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
-
-[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
-{{< /note >}}
+> [!note]
+> The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource](g), then falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
@@ -111,3 +101,8 @@ target = 'assets'
{{< /code-toggle >}}
{{% include "/_common/render-hooks/pageinner.md" %}}
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
+[CommonMark specification]: https://spec.commonmark.org/current/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded link render hook]: {{% eturl render-link %}}
diff --git a/content/en/shortcodes/comment.md b/content/en/shortcodes/comment.md
deleted file mode 100755
index 233d2ed37..000000000
--- a/content/en/shortcodes/comment.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-title: Comment shortcode
-linkTitle: Comment
-description: Include hidden comments in your content with the comment shortcode.
-categories: []
-keywords: []
-expiryDate: 2025-01-22 # deprecated 2025-02-01 in v0.143.0 and immediately removed from the documentation
----
-
-{{< note >}}
-To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl comment %}}
-{{< /note >}}
-
-{{< new-in 0.137.1 />}}
-
-Use the `comment` shortcode to include comments in your content. Hugo will ignore the text within these comments when rendering your site.
-
-Use it inline:
-
-```text
-{{%/* comment */%}} rewrite the paragraph below {{%/* /comment */%}}
-```
-
-Or as a block comment:
-
-```text
-{{%/* comment */%}}
-rewrite the paragraph below
-{{%/* /comment */%}}
-```
-
-Although you can call this shortcode using the `{{}}` notation, computationally it is more efficient to call it using the `{{%/* */%}}` notation as shown above.
diff --git a/content/en/shortcodes/details.md b/content/en/shortcodes/details.md
index 8d89a161d..94502ac1c 100755
--- a/content/en/shortcodes/details.md
+++ b/content/en/shortcodes/details.md
@@ -8,11 +8,8 @@ keywords: []
{{< new-in 0.140.0 />}}
-{{< note >}}
-To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl details %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
## Example
@@ -73,3 +70,5 @@ details > summary > * { }
/* target the content */
details > :not(summary) { }
```
+
+[source code]: {{% eturl details %}}
diff --git a/content/en/shortcodes/figure.md b/content/en/shortcodes/figure.md
index cdd199299..74af52fe7 100755
--- a/content/en/shortcodes/figure.md
+++ b/content/en/shortcodes/figure.md
@@ -6,11 +6,8 @@ categories: []
keywords: []
---
-{{< note >}}
-To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl figure %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
## Example
@@ -108,3 +105,5 @@ target = 'assets'
source = 'static'
target = 'assets'
{{< /code-toggle >}}
+
+[source code]: {{% eturl figure %}}
diff --git a/content/en/shortcodes/gist.md b/content/en/shortcodes/gist.md
index 5bf8618ad..fd2b468ab 100755
--- a/content/en/shortcodes/gist.md
+++ b/content/en/shortcodes/gist.md
@@ -11,11 +11,9 @@ expiryDate: 2027-02-01 # deprecated 2025-02-01 in v0.143.0
The `gist` shortcode was deprecated in version 0.143.0 and will be removed in a future release. To continue embedding GitHub Gists in your content, you'll need to create a custom shortcode:
1. Create a new file: Create a file named `gist.html` within the `layouts/shortcodes` directory.
-1. Copy the source code: Paste the [original source code] of the gist shortcode into the newly created `gist.html` file.
+1. Copy the source code: Paste the [original source code]({{% eturl gist %}}) of the gist shortcode into the newly created `gist.html` file.
This will allow you to maintain the functionality of embedding GitHub Gists in your content after the deprecation of the original shortcode.
-
-[original source code]: {{% eturl gist %}}
{{< /deprecated-in >}}
To display a GitHub gist with this URL:
diff --git a/content/en/shortcodes/highlight.md b/content/en/shortcodes/highlight.md
index 9cc70af94..371a3d46e 100755
--- a/content/en/shortcodes/highlight.md
+++ b/content/en/shortcodes/highlight.md
@@ -6,26 +6,16 @@ categories: []
keywords: [highlight]
---
-{{< note >}}
-To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
+> [!note]
+> To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-[source code]: {{% eturl highlight %}}
-{{< /note >}}
-
-{{< note >}}
-With the Markdown [content format], the `highlight` shortcode is rarely needed because, by default, Hugo automatically applies syntax highlighting to fenced code blocks.
-
-The primary use case for the `highlight` shortcode in Markdown is to apply syntax highlighting to inline code snippets.
-
-[content format]: /content-management/formats/
-{{< /note >}}
+> [!note]
+> With the Markdown [content format], the `highlight` shortcode is rarely needed because, by default, Hugo automatically applies syntax highlighting to fenced code blocks.
+>
+> The primary use case for the `highlight` shortcode in Markdown is to apply syntax highlighting to inline code snippets.
The `highlight` shortcode calls the [`transform.Highlight`] function which uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [highlighting styles].
-[chroma]: https://github.com/alecthomas/chroma
-[highlighting styles]: /quick-reference/syntax-highlighting-styles/
-[`transform.Highlight`]: /functions/transform/highlight/
-
## Arguments
The `highlight` shortcode takes three arguments.
@@ -45,9 +35,6 @@ LANG
OPTIONS
: (`string`) Zero or more space-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive.
-[site configuration]: /configuration/markup/#highlight
-[supported languages]: /content-management/syntax-highlighting/#languages
-
## Example
```text
@@ -110,3 +97,11 @@ This is some {{< hl >}}fmt.Println("inline"){{< /hl >}} code.
Pass the options when calling the shortcode. You can set their default values in your [site configuration].
{{% include "_common/syntax-highlighting-options.md" %}}
+
+[`transform.Highlight`]: /functions/transform/highlight/
+[Chroma]: https://github.com/alecthomas/chroma
+[content format]: /content-management/formats/
+[highlighting styles]: /quick-reference/syntax-highlighting-styles/
+[site configuration]: /configuration/markup/#highlight
+[source code]: {{% eturl highlight %}}
+[supported languages]: /content-management/syntax-highlighting/#languages
diff --git a/content/en/shortcodes/instagram.md b/content/en/shortcodes/instagram.md
index 9b8ff158a..3256790c6 100755
--- a/content/en/shortcodes/instagram.md
+++ b/content/en/shortcodes/instagram.md
@@ -6,11 +6,8 @@ categories: []
keywords: []
---
-{{< note >}}
-To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl instagram %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
## Example
@@ -41,3 +38,5 @@ disable
simple
: (`bool`) Whether to enable simple mode for image card generation. If `true`, Hugo creates a static card without JavaScript. This mode only supports image cards, and the image is fetched directly from Instagram's servers. Default is `false`.
+
+[source code]: {{% eturl instagram %}}
diff --git a/content/en/shortcodes/param.md b/content/en/shortcodes/param.md
index b2f839731..133b2322a 100755
--- a/content/en/shortcodes/param.md
+++ b/content/en/shortcodes/param.md
@@ -6,11 +6,8 @@ categories: []
keywords: []
---
-{{< note >}}
-To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl param %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
The `param` shortcode renders a parameter from front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist.
@@ -37,3 +34,5 @@ Access nested values by [chaining](g) the [identifiers](g):
```text
{{%/* param my.nested.param */%}}
```
+
+[source code]: {{% eturl param %}}
diff --git a/content/en/shortcodes/qr.md b/content/en/shortcodes/qr.md
index 205bb4a67..98d6cee4c 100755
--- a/content/en/shortcodes/qr.md
+++ b/content/en/shortcodes/qr.md
@@ -8,19 +8,13 @@ keywords: []
{{< new-in 0.141.0 />}}
-{{< note >}}
-To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl qr %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
The `qr` shortcode encodes the given text into a [QR code] using the specified options and renders the resulting image.
Internally this shortcode calls the `images.QR` function. Please read the [related documentation] for implementation details and guidance.
-[QR code]: https://en.wikipedia.org/wiki/QR_code
-[related documentation]: /functions/images/qr/
-
## Examples
Use the self-closing syntax to pass the text as an argument:
@@ -51,8 +45,6 @@ To create a QR code for a phone number:
To create a QR code containing contact information in the [vCard] format:
-[vCard]: https://en.wikipedia.org/wiki/VCard
-
```text
{{}}
BEGIN:VCARD
@@ -93,8 +85,6 @@ scale
targetDir
: (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image.
-[`publishDir`]: /configuration/all/#publishdir
-
alt
: (`string`) The `alt` attribute of the `img` element.
@@ -109,3 +99,9 @@ loading
title
: (`string`) The `title` attribute of the `img` element.
+
+[`publishDir`]: /configuration/all/#publishdir
+[QR code]: https://en.wikipedia.org/wiki/QR_code
+[related documentation]: /functions/images/qr/
+[source code]: {{% eturl qr %}}
+[vCard]: https://en.wikipedia.org/wiki/VCard
diff --git a/content/en/shortcodes/ref.md b/content/en/shortcodes/ref.md
index 3bfad3c32..2f821254c 100755
--- a/content/en/shortcodes/ref.md
+++ b/content/en/shortcodes/ref.md
@@ -6,18 +6,11 @@ categories: []
keywords: []
---
-{{< note >}}
-To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
+> [!note]
+> To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-[source code]: {{% eturl ref %}}
-{{< /note >}}
-
-{{< note >}}
-When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
-
-[content format]: /content-management/formats/
-[link render hooks]: /render-hooks/images/#default
-{{< /note >}}
+> [!note]
+> When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
## Usage
@@ -31,11 +24,8 @@ The `ref` shortcode accepts either a single positional argument (the path) or on
The `ref` shortcode typically provides the destination for a Markdown link.
-{{< note >}}
-Always use [Markdown notation] notation when calling this shortcode.
-
-[Markdown notation]: /content-management/shortcodes/#notation
-{{< /note >}}
+> [!note]
+> Always use [Markdown notation] notation when calling this shortcode.
The following examples show the rendered output for a page on the English version of the site:
@@ -64,3 +54,8 @@ Rendered:
## Error handling
{{% include "_common/ref-and-relref-error-handling.md" %}}
+
+[content format]: /content-management/formats/
+[link render hooks]: /render-hooks/images/#default
+[Markdown notation]: /content-management/shortcodes/#notation
+[source code]: {{% eturl ref %}}
diff --git a/content/en/shortcodes/relref.md b/content/en/shortcodes/relref.md
index 5b28e1ff2..5b413b87e 100755
--- a/content/en/shortcodes/relref.md
+++ b/content/en/shortcodes/relref.md
@@ -6,18 +6,11 @@ categories: []
keywords: []
---
-{{< note >}}
-To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
+> [!note]
+> To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-[source code]: {{% eturl relref %}}
-{{< /note >}}
-
-{{< note >}}
-When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
-
-[content format]: /content-management/formats/
-[link render hooks]: /render-hooks/links/
-{{< /note >}}
+> [!note]
+> When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
## Usage
@@ -31,11 +24,8 @@ The `relref` shortcode accepts either a single positional argument (the path) or
The `relref` shortcode typically provides the destination for a Markdown link.
-{{< note >}}
-Always use [Markdown notation] notation when calling this shortcode.
-
-[Markdown notation]: /content-management/shortcodes/#notation
-{{< /note >}}
+> [!note]
+> Always use [Markdown notation] notation when calling this shortcode.
The following examples show the rendered output for a page on the English version of the site:
@@ -64,3 +54,8 @@ Rendered:
## Error handling
{{% include "_common/ref-and-relref-error-handling.md" %}}
+
+[content format]: /content-management/formats/
+[link render hooks]: /render-hooks/links/
+[Markdown notation]: /content-management/shortcodes/#notation
+[source code]: {{% eturl relref %}}
diff --git a/content/en/shortcodes/vimeo.md b/content/en/shortcodes/vimeo.md
index c4ba59c54..c354eefe0 100755
--- a/content/en/shortcodes/vimeo.md
+++ b/content/en/shortcodes/vimeo.md
@@ -6,11 +6,8 @@ categories: []
keywords: []
---
-{{< note >}}
-To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl vimeo %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
## Example
@@ -65,3 +62,4 @@ simple
The source code for the simple version of the shortcode is available [here].
[here]: {{% eturl vimeo_simple %}}
+[source code]: {{% eturl vimeo %}}
diff --git a/content/en/shortcodes/x.md b/content/en/shortcodes/x.md
index 49f2894e7..f1eebdaf2 100755
--- a/content/en/shortcodes/x.md
+++ b/content/en/shortcodes/x.md
@@ -8,11 +8,8 @@ keywords: []
{{< new-in 0.141.0 />}}
-{{< note >}}
-To override Hugo's embedded `x` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl x %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded `x` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
## Example
@@ -49,8 +46,9 @@ simple
The source code for the simple version of the shortcode is available [here].
-[here]: {{% eturl x_simple %}}
-
If you enable simple mode you may want to disable the hardcoded inline styles by setting `disableInlineCSS` to `true` in your site configuration. The default value for this setting is `false`.
{{< code-toggle config=services.x />}}
+
+[here]: {{% eturl x_simple %}}
+[source code]: {{% eturl x %}}
diff --git a/content/en/shortcodes/youtube.md b/content/en/shortcodes/youtube.md
index 73ba21bfd..18c5ae6c2 100755
--- a/content/en/shortcodes/youtube.md
+++ b/content/en/shortcodes/youtube.md
@@ -6,11 +6,8 @@ categories: []
keywords: []
---
-{{< note >}}
-To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl youtube %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
## Example
@@ -90,3 +87,5 @@ disable
privacyEnhanced
: (`bool`) Whether to block YouTube from storing information about visitors on your website unless the user plays the embedded video. Default is `false`.
+
+[source code]: {{% eturl youtube %}}
diff --git a/content/en/templates/base.md b/content/en/templates/base.md
index bf861fbab..84ed1b94b 100644
--- a/content/en/templates/base.md
+++ b/content/en/templates/base.md
@@ -59,21 +59,21 @@ The default list template will inherit all of the code defined above and can the
{{ end }}
```
-This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists.
+This replaces the contents of our (basically empty) `main` block with something useful for the list template. In this case, we didn't define a `title` block, so the contents from our base template remain unchanged in lists.
-{{< note >}}
-Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example:
+> [!caution]
+> Only [template comments] are allowed outside a block's `define` and `end` statements. Avoid placing any other text, including HTML comments, outside these boundaries. Doing so will cause rendering issues, potentially resulting in a blank page. See the example below.
-```go-html-template
-
+```go-html-template {file="layouts/default/single.html"}
+This div element broke your template.
{{ define "main" }}
-...your code here
+ {{ .Title }}
+ {{ .Content }}
{{ end }}
+
```
-[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6)
-{{< /note >}}
-The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your default [single template]:
+The following shows how you can override both the `main` and `title` block areas from the base template with code unique to your default [single template]:
```go-html-template {file="layouts/_default/single.html"}
{{ define "title" }}
@@ -87,3 +87,4 @@ The following shows how you can override both the `"main"` and `"title"` block a
```
[single template]: /templates/types/#single
+[template comments]: /templates/introduction/#comments
diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md
index c17fb2930..9fe2bb68d 100644
--- a/content/en/templates/embedded.md
+++ b/content/en/templates/embedded.md
@@ -9,20 +9,13 @@ aliases: [/templates/internal]
## Disqus
-{{< note >}}
-To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
-
-`{{ partial "disqus.html" . }}`
-
-[`partial`]: /functions/partials/include/
-[source code]: {{% eturl disqus %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "disqus.html" . }}`
Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service.
-[Disqus]: https://disqus.com
-[signing up]: https://disqus.com/profile/signup/
-
To include the embedded template:
```go-html-template
@@ -61,19 +54,13 @@ disable
## Google Analytics
-{{< note >}}
-To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
-
-`{{ partial "google_analytics.html" . }}`
-
-[`partial`]: /functions/partials/include/
-[source code]: {{% eturl google_analytics %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "google_analytics.html" . }}`
Hugo includes an embedded template supporting [Google Analytics 4].
-[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
-
To include the embedded template:
```go-html-template
@@ -105,14 +92,10 @@ respectDoNotTrack
## Open Graph
-{{< note >}}
-To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
-
-`{{ partial "opengraph.html" . }}`
-
-[`partial`]: /functions/partials/include/
-[source code]: {{% eturl opengraph %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "opengraph.html" . }}`
Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph.
This format is used for Facebook and some other sites.
@@ -164,19 +147,13 @@ If using YouTube this will produce a og:video tag like `}}
+> [!note]
+> To override Hugo's embedded Schema template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "schema.html" . }}`
Hugo includes an embedded template to render [microdata] `meta` elements within the `head` element of your templates.
-[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
-
To include the embedded template:
```go-html-template
@@ -185,14 +162,10 @@ To include the embedded template:
## X (Twitter) Cards
-{{< note >}}
-To override Hugo's embedded Twitter Cards template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
-
-`{{ partial "twitter_cards.html" . }}`
-
-[`partial`]: /functions/partials/include/
-[source code]: {{% eturl twitter_cards %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded Twitter Cards template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "twitter_cards.html" . }}`
Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards),
metadata used to attach rich media to Tweets linking to your site.
@@ -237,3 +210,14 @@ NOTE: The `@` will be added for you
```html
```
+
+[`partial`]: /functions/partials/include/
+[Disqus]: https://disqus.com
+[Google Analytics 4]: https://support.google.com/analytics/answer/10089681
+[microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
+[signing up]: https://disqus.com/profile/signup/
+[source code]: {{% eturl disqus %}}
+[source code]: {{% eturl google_analytics %}}
+[source code]: {{% eturl opengraph %}}
+[source code]: {{% eturl schema %}}
+[source code]: {{% eturl twitter_cards %}}
diff --git a/content/en/templates/home.md b/content/en/templates/home.md
index cbb47d4aa..937a4a5a8 100644
--- a/content/en/templates/home.md
+++ b/content/en/templates/home.md
@@ -26,11 +26,8 @@ A home page template is used to render your site's home page, and is the only te
Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page.
-[template lookup order]: /templates/lookup-order/#home-templates
-
-{{< note >}}
-You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format.
-{{< /note >}}
+> [!note]
+> You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format.
## Content and front matter
@@ -57,3 +54,5 @@ The home page template below inherits the site's shell from the base template, r
{{ end }}
{{ end }}
```
+
+[template lookup order]: /templates/lookup-order/#home-templates
diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md
index 4f4081729..706e709e4 100644
--- a/content/en/templates/introduction.md
+++ b/content/en/templates/introduction.md
@@ -11,20 +11,12 @@ weight: 10
Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page.
-[functions]: /functions/
-[methods]: /methods/
-[variables]: #variables
-
-{{< note >}}
-Hugo uses Go's [text/template] and [html/template] packages.
-
-The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
-
-By default, Hugo uses the html/template package when rendering HTML files.
-
-[text/template]: https://pkg.go.dev/text/template
-[html/template]: https://pkg.go.dev/html/template
-{{< /note >}}
+> [!note]
+> Hugo uses Go's [text/template] and [html/template] packages.
+>
+> The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
+>
+> By default, Hugo uses the html/template package when rendering HTML files.
For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph.
@@ -52,14 +44,8 @@ Within a template, the dot (`.`) represents the current context.
In the example above the dot represents the `Page` object, and we call its [`Title`] method to return the title as defined in [front matter].
-[front matter]: /content-management/front-matter/
-[`Title`]: /methods/page/title
-
The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we rebind the context to another value or object within [`range`] or [`with`] blocks.
-[`range`]: /functions/go-template/range/
-[`with`]: /functions/go-template/with/
-
```go-html-template {file="layouts/_default/single.html"}
{{ .Title }}
@@ -97,9 +83,8 @@ Hugo renders this to:
My Page Title - foo
```
-{{< note >}}
-Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context.
-{{< /note >}}
+> [!note]
+> Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context.
## Actions
@@ -172,9 +157,8 @@ These are also equivalent:
{{ 5 | add 2 | mul 6 }} → 42
```
-{{< note >}}
-Remember that the piped value becomes the final argument to the function or method to which you are piping.
-{{< /note >}}
+> [!note]
+> Remember that the piped value becomes the final argument to the function or method to which you are piping.
### Line splitting
@@ -219,8 +203,6 @@ Variables initialized inside of an `if`, `range`, or `with` block are scoped to
With variables that represent a slice or map, use the [`index`] function to return the desired value.
-[`index`]: /functions/collections/indexfunction/
-
```go-html-template
{{ $slice := slice "foo" "bar" "baz" }}
{{ index $slice 2 }} → baz
@@ -229,9 +211,8 @@ With variables that represent a slice or map, use the [`index`] function to retu
{{ index $map "c" }} → baz
```
-{{< note >}}
-Slices and arrays are zero-based; element 0 is the first element.
-{{< /note >}}
+> [!note]
+> Slices and arrays are zero-based; element 0 is the first element.
With variables that represent a map or object, [chain](g) identifiers to return the desired value or to access the desired method.
@@ -243,9 +224,8 @@ With variables that represent a map or object, [chain](g) identifiers to return
{{ $homePage.Title }} → My Homepage
```
-{{< note >}}
-As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore.
-{{< /note >}}
+> [!note]
+> As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore.
## Functions
@@ -253,12 +233,8 @@ Used within a template action, a function takes one or more arguments and return
Go's text/template and html/template packages provide a small set of functions, operators, and statements for general use. See the [go-templates] section of the function documentation for details.
-[go-templates]: /functions/go-template/
-
Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other functions:
-[functions]: /functions
-
Function|Alias
:--|:--
[`strings.ToLower`](/functions/strings/tolower)|`lower`
@@ -279,10 +255,6 @@ Used within a template action and associated with an object, a method takes zero
The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object.
-[`Site`]: /methods/site/
-[`Page`]: /methods/page/
-[methods]: /methods/
-
Object|Method|Description
:--|:--|:--
`Page`|[`Date`](methods/page/date/)|Returns the date of the given page.
@@ -294,8 +266,6 @@ Object|Method|Description
Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context].
-[current context]: #current-context
-
```go-html-template {file="layouts/_default/single.html"}
{{ .Site.Title }} → My Site Title
{{ .Page.Title }} → My Page Title
@@ -317,11 +287,10 @@ Some methods take an argument. Separate the argument from the method with a spac
## Comments
-{{< note >}}
-Do not attempt to use HTML comment delimiters to comment out template code.
-
-Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build.
-{{< /note >}}
+> [!note]
+> Do not attempt to use HTML comment delimiters to comment out template code.
+>
+> Hugo strips HTML comments when rendering a page, but first evaluates any template code within the HTML comment delimiters. Depending on the template code within the HTML comment delimiters, this could cause unexpected results or fail the build.
Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example:
@@ -347,8 +316,6 @@ You may not nest one comment inside of another.
To render an HTML comment, pass a string through the [`safeHTML`] template function. For example:
-[`safeHTML`]: /functions/safe/html
-
```go-html-template
{{ "" | safeHTML }}
{{ printf "" .Site.Title | safeHTML }}
@@ -358,8 +325,6 @@ To render an HTML comment, pass a string through the [`safeHTML`] template funct
Use the [`template`] function to include one or more of Hugo's [embedded templates]:
-[embedded templates]: /templates/embedded/
-
```go-html-template
{{ template "_internal/google_analytics.html" . }}
{{ template "_internal/opengraph" . }}
@@ -368,14 +333,8 @@ Use the [`template`] function to include one or more of Hugo's [embedded templat
{{ template "_internal/twitter_cards.html" . }}
```
-[`partial`]: /functions/partials/include/
-[`partialCached`]: /functions/partials/includecached/
-[`template`]: /functions/go-template/template/
-
Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
-[partial templates]: /templates/partial
-
```go-html-template
{{ partial "breadcrumbs.html" . }}
{{ partialCached "css.html" . }}
@@ -383,24 +342,17 @@ Use the [`partial`] or [`partialCached`] function to include one or more [partia
Create your partial templates in the layouts/partials directory.
-{{< note >}}
-In the examples above, note that we are passing the current context (the dot) to each of the templates.
-{{< /note >}}
+> [!note]
+> In the examples above, note that we are passing the current context (the dot) to each of the templates.
## Examples
This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions], [methods], and [templates] documentation for specific examples.
-[templates]: /templates/
-
### Conditional blocks
See documentation for [`if`], [`else`], and [`end`].
-[`if`]: /functions/go-template/if/
-[`else`]: /functions/go-template/else/
-[`end`]: /functions/go-template/end/
-
```go-html-template
{{ $var := 42 }}
{{ if eq $var 6 }}
@@ -418,9 +370,6 @@ See documentation for [`if`], [`else`], and [`end`].
See documentation for [`and`] and [`or`].
-[`and`]: /functions/go-template/and
-[`or`]: /functions/go-template/or
-
```go-html-template
{{ $v1 := true }}
{{ $v2 := false }}
@@ -442,8 +391,6 @@ See documentation for [`and`] and [`or`].
See documentation for [`range`], [`else`], and [`end`].
-[`range`]: /functions/go-template/range/
-
```go-html-template
{{ $s := slice "foo" "bar" "baz" }}
{{ range $s }}
@@ -455,8 +402,6 @@ See documentation for [`range`], [`else`], and [`end`].
Use the [`seq`] function to loop a specified number of times:
-[`seq`]: /functions/collections/seq
-
```go-html-template
{{ $total := 0 }}
{{ range seq 4 }}
@@ -469,8 +414,6 @@ Use the [`seq`] function to loop a specified number of times:
See documentation for [`with`], [`else`], and [`end`].
-[`with`]: /functions/go-template/with/
-
```go-html-template
{{ $var := "foo" }}
{{ with $var }}
@@ -546,3 +489,35 @@ Access the custom page parameters by chaining the identifiers:
{{ .Params.display_related }} → true
{{ .Params.author.name }} → John Smith
```
+
+[`and`]: /functions/go-template/and
+[`else`]: /functions/go-template/else/
+[`end`]: /functions/go-template/end/
+[`if`]: /functions/go-template/if/
+[`index`]: /functions/collections/indexfunction/
+[`or`]: /functions/go-template/or
+[`Page`]: /methods/page/
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
+[`range`]: /functions/go-template/range/
+[`range`]: /functions/go-template/range/
+[`safeHTML`]: /functions/safe/html
+[`seq`]: /functions/collections/seq
+[`Site`]: /methods/site/
+[`template`]: /functions/go-template/template/
+[`Title`]: /methods/page/title
+[`with`]: /functions/go-template/with/
+[`with`]: /functions/go-template/with/
+[current context]: #current-context
+[embedded templates]: /templates/embedded/
+[front matter]: /content-management/front-matter/
+[functions]: /functions/
+[functions]: /functions
+[go-templates]: /functions/go-template/
+[html/template]: https://pkg.go.dev/html/template
+[methods]: /methods/
+[methods]: /methods/
+[partial templates]: /templates/partial
+[templates]: /templates/
+[text/template]: https://pkg.go.dev/text/template
+[variables]: #variables
diff --git a/content/en/templates/lookup-order.md b/content/en/templates/lookup-order.md
index 19635bbd9..b7b366b3e 100644
--- a/content/en/templates/lookup-order.md
+++ b/content/en/templates/lookup-order.md
@@ -31,9 +31,8 @@ Type
Section
: Is relevant for `section`, `taxonomy` and `term` types.
-{{< note >}}
-Templates can live in either the project's or the themes' `layout` directories, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
-{{< /note >}}
+> [!note]
+> Templates can live in either the project's or the themes' `layout` directories, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
## Target a template
diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md
index fe93ef42a..c755b2521 100644
--- a/content/en/templates/pagination.md
+++ b/content/en/templates/pagination.md
@@ -15,9 +15,8 @@ Displaying a large page collection on a list page is not user-friendly:
Improve usability by paginating `home`, `section`, `taxonomy`, and `term` pages.
-{{< note >}}
-The most common templating mistake related to pagination is invoking pagination more than once for a given list page. See the [caching](#caching) section below.
-{{< /note >}}
+> [!note]
+> The most common templating mistake related to pagination is invoking pagination more than once for a given list page. See the [caching](#caching) section below.
## Terminology
@@ -52,9 +51,6 @@ The `Paginate` method is more flexible, allowing you to:
By comparison, the `Paginator` method paginates the page collection passed into the template, and you cannot override the number of pages per pager.
-[`Paginate`]: /methods/page/paginate/
-[`Paginator`]: /methods/page/paginator/
-
## Examples
To paginate a list page using the `Paginate` method:
@@ -96,22 +92,17 @@ In the example above, we:
## Caching
-{{< note >}}
-The most common templating mistake related to pagination is invoking pagination more than once for a given list page.
-{{< /note >}}
+> [!note]
+> The most common templating mistake related to pagination is invoking pagination more than once for a given list page.
Regardless of pagination method, the initial invocation is cached and cannot be changed. If you invoke pagination more than once for a given list page, subsequent invocations use the cached result. This means that subsequent invocations will not behave as written.
When paginating conditionally, do not use the `compare.Conditional` function due to its eager evaluation of arguments. Use an `if-else` construct instead.
-[`compare.Conditional`]: /functions/compare/conditional/
-
## Grouping
Use pagination with any of the [grouping methods]. For example:
-[grouping methods]: /quick-reference/page-collections/#group
-
```go-html-template
{{ $pages := where site.RegularPages "Type" "posts" }}
{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }}
@@ -126,8 +117,6 @@ Use pagination with any of the [grouping methods]. For example:
{{ template "_internal/pagination.html" . }}
```
-[grouping methods]: /quick-reference/page-collections/#group
-
## Navigation
As shown in the examples above, the easiest way to add navigation between pagers is with Hugo's embedded pagination template:
@@ -148,14 +137,10 @@ The `terse` format has fewer controls and page slots, consuming less space when
{{ template "_internal/pagination.html" (dict "page" . "format" "terse") }}
```
-{{< note >}}
-To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
-
-`{{ partial "pagination.html" . }}`
-
-[`partial`]: /functions/partials/include/
-[source code]: {{% eturl pagination %}}
-{{< /note >}}
+> [!note]
+> To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
+>
+> `{{ partial "pagination.html" . }}`
Create custom navigation components using any of the `Pager` methods:
@@ -247,3 +232,10 @@ public/
│ └── index.html
└── index.html
```
+
+[`Paginate`]: /methods/page/paginate/
+[`Paginator`]: /methods/page/paginator/
+[`partial`]: /functions/partials/include/
+[grouping methods]: /quick-reference/page-collections/#group
+[grouping methods]: /quick-reference/page-collections/#group
+[source code]: {{% eturl pagination %}}
diff --git a/content/en/templates/partial.md b/content/en/templates/partial.md
index ba63ae37f..8493a4674 100644
--- a/content/en/templates/partial.md
+++ b/content/en/templates/partial.md
@@ -34,13 +34,11 @@ All partials are called within your templates using the following pattern:
{{ partial "/.html" . }}
```
-{{< note >}}
-One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/#context).
-{{< /note >}}
+> [!note]
+> One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/#context).
-{{< note >}}
-`` including `baseof` is reserved. ([#5373](https://github.com/gohugoio/hugo/issues/5373))
-{{< /note >}}
+> [!note]
+> Do not include the word "baseof" when naming partial templates. The word "baseof" is reserved for base templates.
As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory:
@@ -94,9 +92,8 @@ In addition to outputting markup, partials can be used to return a value of any
{{ end }}
```
-{{< note >}}
-Only one `return` statement is allowed per partial file.
-{{< /note >}}
+> [!note]
+> Only one `return` statement is allowed per partial file.
## Inline partials
@@ -138,9 +135,8 @@ The following `header.html` partial template is used for [spf13.com](https://spf
```
-{{< note >}}
-The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility.
-{{< /note >}}
+> [!note]
+> The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility.
### `footer.html`
@@ -159,7 +155,4 @@ The following `footer.html` partial template is used for [spf13.com](https://spf
```
[context]: /templates/introduction/
-[customize]: /hugo-modules/theme-components/
-[lookup order]: /templates/lookup-order/
[partialcached]: /functions/partials/includecached/
-[themes]: /themes/
diff --git a/content/en/templates/robots.md b/content/en/templates/robots.md
index 72ddf81b6..21e467ab8 100644
--- a/content/en/templates/robots.md
+++ b/content/en/templates/robots.md
@@ -16,8 +16,6 @@ enableRobotsTXT = true
By default, Hugo generates robots.txt using an [embedded template].
-[embedded template]: {{% eturl robots %}}
-
```text
User-agent: *
```
@@ -42,15 +40,14 @@ Disallow: {{ .RelPermalink }}
This template creates a robots.txt file with a `Disallow` directive for each page on the site. Search engines that honor the Robots Exclusion Protocol will not crawl any page on the site.
-{{< note >}}
-To create a robots.txt file without using a template:
-
-1. Set `enableRobotsTXT` to `false` in the site configuration.
-1. Create a robots.txt file in the `static` directory.
-
-Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site.
-
-[static]: /getting-started/directory-structure/
-{{< /note >}}
+> [!note]
+> To create a robots.txt file without using a template:
+>
+> 1. Set `enableRobotsTXT` to `false` in the site configuration.
+> 1. Create a robots.txt file in the `static` directory.
+>
+> Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site.
+[embedded template]: {{% eturl robots %}}
[site configuration]: /configuration/
+[static]: /getting-started/directory-structure/
diff --git a/content/en/templates/rss.md b/content/en/templates/rss.md
index d005f5aa8..f387a71e3 100644
--- a/content/en/templates/rss.md
+++ b/content/en/templates/rss.md
@@ -62,9 +62,6 @@ Hugo will render this to:
Override Hugo's [embedded RSS template] by creating one or more of your own, following the naming conventions as shown in the [template lookup order].
-[embedded RSS template]: {{% eturl rss %}}
-[template lookup order]: /templates/lookup-order/#rss-templates
-
For example, to use different templates for home, section, taxonomy, and term pages:
```text
@@ -77,3 +74,6 @@ layouts/
```
RSS templates receive the `.Page` and `.Site` objects in context.
+
+[embedded RSS template]: {{% eturl rss %}}
+[template lookup order]: /templates/lookup-order/#rss-templates
diff --git a/content/en/templates/shortcode.md b/content/en/templates/shortcode.md
index dc91c4992..cca4f215c 100644
--- a/content/en/templates/shortcode.md
+++ b/content/en/templates/shortcode.md
@@ -7,12 +7,8 @@ weight: 120
aliases: [/templates/shortcode-templates/]
---
-{{< note >}}
-Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates.
-
-[shortcodes]: /content-management/shortcodes/
-[content management]: /content-management/shortcodes/
-{{< /note >}}
+> [!note]
+> Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates.
## Introduction
@@ -26,8 +22,6 @@ Hugo provides [embedded shortcodes] for many common tasks, but you'll likely nee
- Tables
- And many other custom elements
-[embedded shortcodes]: /shortcodes/
-
## Directory structure
Create shortcode templates within the `layouts/shortcodes` directory, either at its root or organized into subdirectories.
@@ -98,8 +92,6 @@ This is {{}}, and look at how far we've come.
This shortcode can be used inline or as a block on its own line. If a shortcode might be used inline, remove the surrounding [whitespace] by using [template action](g) delimiters with hyphens.
-[whitespace]: /templates/introduction/#whitespace
-
### Insert image
This example assumes the following content structure, where `content/example/index.md` is a [page bundle](g) containing one or more [page resources](g).
@@ -134,16 +126,10 @@ The example above uses:
- The [`Get`] method to retrieve arguments by name
- The `$` to access the template context
-[`get`]: /methods/shortcode/get/
-[`with`]: /functions/go-template/with/
-
-{{< note >}}
-Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context.
-
-Read more about context in the [introduction to templating].
-
-[introduction to templating]: /templates/introduction/
-{{< /note >}}
+> [!note]
+> Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context.
+>
+> Read more about context in the [introduction to templating].
### Insert image with error handling
@@ -172,9 +158,6 @@ This template throws an error and gracefully fails the build if the author negle
The [`Name`] and [`Position`] methods provide helpful context for errors and warnings. For example, a missing `width` argument causes the shortcode to throw this error:
-[`name`]: /methods/shortcode/name/
-[`position`]: /methods/shortcode/position/
-
```text
ERROR The "image" shortcode requires a 'width' argument: see "/home/user/project/content/example/index.md:7:1"
```
@@ -183,8 +166,6 @@ ERROR The "image" shortcode requires a 'width' argument: see "/home/user/project
Shortcode arguments can be [named or positional]. We used named arguments previously; let's explore positional arguments. Here's the named argument version of our example:
-[named or positional]: /content-management/shortcodes/#arguments
-
```text {file="content/example/index.md"}
{{}}
```
@@ -203,9 +184,8 @@ Using the `Get` method with zero-indexed keys, we'll initialize variables with d
{{ $alt := .Get 2 }}
```
-{{< note >}}
-Positional arguments work well for frequently used shortcodes with one or two arguments. Since you'll use them often, the argument order will be easy to remember. For less frequently used shortcodes, or those with more than two arguments, named arguments improve readability and reduce the chance of errors.
-{{< /note >}}
+> [!note]
+> Positional arguments work well for frequently used shortcodes with one or two arguments. Since you'll use them often, the argument order will be easy to remember. For less frequently used shortcodes, or those with more than two arguments, named arguments improve readability and reduce the chance of errors.
### Named and positional arguments
@@ -219,15 +199,10 @@ You can create a shortcode that will accept both named and positional arguments,
This example uses the `cond` alias for the [`compare.Conditional`] function to get the argument by name if `IsNamedParams` returns `true`, otherwise get the argument by position.
-[`compare.Conditional`]: /functions/compare/conditional/
-[`IsNamedParams`]: /methods/shortcode/isnamedparams/
-
### Argument collection
Use the [`Params`] method to access the arguments as a collection.
-[`Params`]: /methods/shortcode/params/
-
When using named arguments, the `Params` method returns a map:
```text {file="content/example/index.md"}
@@ -254,14 +229,10 @@ When using named arguments, the `Params` method returns a map:
Combine the `Params` method with the [`collections.IsSet`] function to determine if a parameter is set, even if its value is falsy.
-[`collections.IsSet`]: /functions/collections/isset/
-
### Inner content
Extract the content enclosed within shortcode tags using the [`Inner`] method. This example demonstrates how to pass both content and a title to a shortcode. The shortcode then generates a `div` element containing an `h2` element (displaying the title) and the provided content.
-[`Inner`]: /methods/shortcode/inner/
-
```text {file="content/example.md"}
{{}}
This is a **bold** word, and this is an _emphasized_ word.
@@ -277,16 +248,10 @@ This is a **bold** word, and this is an _emphasized_ word.
The preceding example called the shortcode using [standard notation], requiring us to process the inner content with the [`RenderString`] method to convert the Markdown to HTML. This conversion is unnecessary when calling a shortcode using [Markdown notation].
-[`RenderString`]: /methods/page/renderstring/
-[markdown notation]: /content-management/shortcodes/#markdown-notation
-[standard notation]: /content-management/shortcodes/#standard-notation
-
### Nesting
The [`Parent`] method provides access to the parent shortcode context when the shortcode in question is called within the context of a parent shortcode. This provides an inheritance model.
-[`Parent`]: /methods/shortcode/parent/
-
The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` argument:
```go-html-template {file="layouts/shortcodes/gallery.html"}
@@ -330,8 +295,6 @@ This will output the following HTML. Note how the first two `img` shortcodes inh
For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub], can provide a useful model.
-[GitHub]: https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates/shortcodes
-
## Detection
The [`HasShortcode`] method allows you to check if a specific shortcode has been called on a page. For example, consider a custom audio shortcode:
@@ -352,4 +315,24 @@ You can use the `HasShortcode` method in your base template to conditionally loa
```
+[`collections.IsSet`]: /functions/collections/isset/
+[`compare.Conditional`]: /functions/compare/conditional/
+[`Get`]: /methods/shortcode/get/
[`HasShortcode`]: /methods/page/hasshortcode/
+[`Inner`]: /methods/shortcode/inner/
+[`IsNamedParams`]: /methods/shortcode/isnamedparams/
+[`Name`]: /methods/shortcode/name/
+[`Params`]: /methods/shortcode/params/
+[`Parent`]: /methods/shortcode/parent/
+[`Position`]: /methods/shortcode/position/
+[`RenderString`]: /methods/page/renderstring/
+[`with`]: /functions/go-template/with/
+[content management]: /content-management/shortcodes/
+[embedded shortcodes]: /shortcodes/
+[GitHub]: https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates/shortcodes
+[introduction to templating]: /templates/introduction/
+[Markdown notation]: /content-management/shortcodes/#markdown-notation
+[named or positional]: /content-management/shortcodes/#arguments
+[shortcodes]: /content-management/shortcodes/
+[standard notation]: /content-management/shortcodes/#standard-notation
+[whitespace]: /templates/introduction/#whitespace
diff --git a/content/en/templates/sitemap.md b/content/en/templates/sitemap.md
index f7af32323..bf0850eef 100644
--- a/content/en/templates/sitemap.md
+++ b/content/en/templates/sitemap.md
@@ -18,9 +18,6 @@ With a multilingual project, Hugo generates:
- A sitemap.xml file in the root of each site (language) using the [embedded sitemap template]
- A sitemap.xml file in the root of the [`publishDir`] using the [embedded sitemapindex template]
-[embedded sitemap template]: {{% eturl sitemap %}}
-[embedded sitemapindex template]: {{% eturl sitemapindex %}}
-
## Configuration
See [configure sitemap](/configuration/sitemap).
@@ -60,4 +57,6 @@ disableKinds = ['sitemap']
{{}}
[`publishDir`]: /configuration/all/#publishdir
+[embedded sitemap template]: {{% eturl sitemap %}}
+[embedded sitemapindex template]: {{% eturl sitemapindex %}}
[sitemap protocol]: https://www.sitemaps.org/protocol.html
diff --git a/content/en/templates/types.md b/content/en/templates/types.md
index e623b8be2..b44d3eb47 100644
--- a/content/en/templates/types.md
+++ b/content/en/templates/types.md
@@ -37,11 +37,8 @@ layouts/
Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page.
-[template lookup order]: /templates/lookup-order/
-
-{{< note >}}
-You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format.
-{{< /note >}}
+> [!note]
+> You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format.
The purpose of each template type is described below.
@@ -51,9 +48,6 @@ Base templates reduce duplicate code by wrapping other templates within a shell.
For example, the base template below calls the [partial] function to include partial templates for the `head`, `header`, and `footer` elements of each page, and it uses the [block] function to include `home`, `single`, `section`, `taxonomy`, and `term` templates within the `main` element of each page.
-[block]: /functions/go-template/block/
-[partial]: /functions/partials/include/
-
```go-html-template {file="layouts/_default/baseof.html"}
@@ -172,11 +166,8 @@ Learn more about [term templates](/templates/term/).
A partial template is typically used to render a component of your site, though you may also create partial templates that return values.
-{{< note >}}
-Unlike other template types, you cannot create partial templates to target a particular page kind, content type, section, language, or output format. Partial templates do not follow Hugo's [template lookup order].
-
-[template lookup order]: /templates/lookup-order/
-{{< /note >}}
+> [!note]
+> Unlike other template types, you cannot create partial templates to target a particular page kind, content type, section, language, or output format. Partial templates do not follow Hugo's [template lookup order].
For example, the partial template below renders copyright information.
@@ -193,8 +184,6 @@ A content view template is similar to a partial template, invoked by calling the
- Automatically inherit the context of the current page
- Follow a lookup order allowing you to target a given content type or section
-[`Render`]: /methods/page/render/
-
For example, the home template below inherits the site's shell from the base template, and renders a card component for each page within the "articles" section of your site.
```go-html-template {file="layouts/_default/home.html"}
@@ -264,3 +253,9 @@ Use other specialized templates to create:
- [RSS feeds](/templates/rss/)
- [404 error pages](/templates/404/)
- [robots.txt files](/templates/robots/)
+
+[`Render`]: /methods/page/render/
+[block]: /functions/go-template/block/
+[partial]: /functions/partials/include/
+[template lookup order]: /templates/lookup-order/
+[template lookup order]: /templates/lookup-order/
diff --git a/content/en/troubleshooting/faq.md b/content/en/troubleshooting/faq.md
index 9336a735b..6992af5d3 100644
--- a/content/en/troubleshooting/faq.md
+++ b/content/en/troubleshooting/faq.md
@@ -96,20 +96,18 @@ Why is my page Scratch or Store missing a value?
You can trigger content rendering with other methods as well. See next FAQ.
-2025-02-18T22:07:09-08:00Which page methods trigger content rendering?
+Which page methods trigger content rendering?
: The following methods on a `Page` object trigger content rendering: `Content`, `ContentWithoutSummary`, `FuzzyWordCount`, `Len`, `Plain`, `PlainWords`, `ReadingTime`, `Summary`, `Truncated`, and `WordCount`.
-{{< note >}}
-For other questions please visit the [forum]. 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.
-
-[forum]: https://discourse.gohugo.io
-[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
-{{< /note >}}
+> [!note]
+> For other questions please visit the [forum]. 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.
[`Paginate`]: /methods/page/paginate/
[`Paginator`]: /methods/page/paginator/
+[`Scratch`]: /methods/page/scratch
+[`Store`]: /methods/page/store
+[forum]: https://discourse.gohugo.io
[forum]: https://discourse.gohugo.io
[installation]: /installation/
[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
-[`Scratch`]: /methods/page/scratch
-[`Store`]: /methods/page/store
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
diff --git a/content/en/troubleshooting/logging.md b/content/en/troubleshooting/logging.md
index d6e8affeb..aa658cd12 100644
--- a/content/en/troubleshooting/logging.md
+++ b/content/en/troubleshooting/logging.md
@@ -39,9 +39,8 @@ debug
hugo --logLevel debug
```
-{{< note >}}
-If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed.
-{{< /note >}}
+> [!note]
+> If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed.
## Template functions
diff --git a/content/en/troubleshooting/performance.md b/content/en/troubleshooting/performance.md
index 1889cd7d1..e366eba81 100644
--- a/content/en/troubleshooting/performance.md
+++ b/content/en/troubleshooting/performance.md
@@ -18,9 +18,8 @@ For example, with Microsoft Defender Antivirus:
Then type `hugo.exe` add press the **Add** button.
-{{< note >}}
-Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation](https://support.microsoft.com/en-us/topic/how-to-add-a-file-type-or-process-exclusion-to-windows-security-e524cbc2-3975-63c2-f9d1-7c2eb5331e53) for details.
-{{< /note >}}
+> [!note]
+> Virus scanning exclusions are common, but use caution when changing these settings. See the [Microsoft Defender Antivirus documentation] for details.
Other virus scanners have similar exclusion mechanisms. See their respective documentation.
@@ -86,21 +85,20 @@ total count
template
: The path to the template, relative to the `layouts` directory.
-[`partial`]: /functions/partials/include/
-[`partialCached`]: /functions/partials/includecached/
-
-{{< note >}}
-Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site.
-{{< /note >}}
+> [!note]
+> Hugo builds pages in parallel where multiple pages are generated simultaneously. Because of this parallelism, the sum of "cumulative duration" values is usually greater than the actual time it takes to build a site.
## Caching
Some partial templates such as sidebars or menus are executed many times during a site build. Depending on the content within the partial template and the desired output, the template may benefit from caching to reduce the number of executions. The [`partialCached`] template function provides caching capabilities for partial templates.
-{{< note >}}
-Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
-{{< /note >}}
+> [!note]
+> Note that you can create cached variants of each partial by passing additional arguments to `partialCached` beyond the initial context. See the `partialCached` documentation for more details.
## Timers
Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottlenecks in templates. See [details](/functions/debug/timer/).
+
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includecached/
+[Microsoft Defender Antivirus documentation]: https://support.microsoft.com/en-us/topic/how-to-add-a-file-type-or-process-exclusion-to-windows-security-e524cbc2-3975-63c2-f9d1-7c2eb5331e53
diff --git a/layouts/_default/_markup/render-blockquote.html b/layouts/_default/_markup/render-blockquote.html
index 26876ab5d..98019e12d 100644
--- a/layouts/_default/_markup/render-blockquote.html
+++ b/layouts/_default/_markup/render-blockquote.html
@@ -4,7 +4,7 @@
"important" (dict "color" "blue" "icon" "exclamation-circle")
"note" (dict "color" "blue" "icon" "information-circle")
"tip" (dict "color" "green" "icon" "light-bulb")
- "warning" (dict "color" "yellow" "icon" "exclamation-triangle")
+ "warning" (dict "color" "orange" "icon" "exclamation-triangle")
}}
{{- $alertTypes := slice }}
diff --git a/layouts/shortcodes/gomodules-info.html b/layouts/shortcodes/gomodules-info.html
deleted file mode 100644
index f9cd9d765..000000000
--- a/layouts/shortcodes/gomodules-info.html
+++ /dev/null
@@ -1,18 +0,0 @@
-{{- $text := `
- Most of the commands for **Hugo Modules** require a newer version (>= 1.18) of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ).
- If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.19 or newer in your Environment settings.
-
- For more information about Go Modules, see:
-
- - https://go.dev/wiki/Modules
- - https://blog.golang.org/using-go-modules
- `
-}}
-{{- $text = $text | strings.TrimSpace | .Page.RenderString (dict "display" "block") }}
-{{- partial "layouts/blocks/alert.html" (dict
- "color" "orange"
- "icon" "exclamation"
- "text" $text
- "title" "Go Modules"
- )
-}}
diff --git a/layouts/shortcodes/note.html b/layouts/shortcodes/note.html
deleted file mode 100644
index 526a57e10..000000000
--- a/layouts/shortcodes/note.html
+++ /dev/null
@@ -1,16 +0,0 @@
-{{/* prettier-ignore-start */ -}}
-{{- /*
-Renders a callout.
-
-@example {{< note >}}
- Some descriptive text here.
- {{< /note >}}
-*/ -}}
-{{/* prettier-ignore-end */ -}}
-{{- $text := .Inner | strings.TrimSpace | .Page.RenderString (dict "display" "block") }}
-{{- partial "layouts/blocks/alert.html" (dict
- "color" "blue"
- "icon" "exclamation-triangle"
- "text" $text
- )
-}}