mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-16 12:34:40 -04:00
Joe Mooring
parent
60dd993a65
commit
09f8e0c31d
@ -60,25 +60,33 @@ The default front matter configuration includes these aliases.
|
||||
|
||||
## Tokens
|
||||
|
||||
Hugo provides several [tokens](g) to assist with front matter configuration.
|
||||
Hugo provides the following [tokens](g) to help you configure your front matter:
|
||||
|
||||
Token|Description
|
||||
:--|:--
|
||||
`:default`|The default ordered sequence of date fields.
|
||||
`:fileModTime`|The file's last modification timestamp.
|
||||
`:filename`|The date from the file name, if present.
|
||||
`:git`|The Git author date for the file's last revision.
|
||||
`:default`
|
||||
: The default ordered sequence of date fields.
|
||||
|
||||
When Hugo extracts a date from a file name, it uses the rest of the file name to generate the page's [`slug`], but only if a slug isn't already specified in the page's front matter. For example, given the name `2025-02-01-article.md`, Hugo will set the `date` to `2025-02-01` and the `slug` to `article`.
|
||||
`:fileModTime`
|
||||
: The file's last modification timestamp.
|
||||
|
||||
[`slug`]: /content-management/front-matter/#slug
|
||||
`:filename`
|
||||
: Extracts the date from the file name, provided the file name begins with a date in one of the following formats:
|
||||
|
||||
To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use\
|
||||
the `--enableGitInfo` flag when building your site.
|
||||
- `YYYY-MM-DD`
|
||||
- `YYYY-MM-DD-HH-MM-SS` {{< new-in 0.148.0 />}}
|
||||
|
||||
[`enableGitInfo`]: /configuration/all/#enablegitinfo
|
||||
|
||||
Consider this example:
|
||||
Within the `YYYY-MM-DD-HH-MM-SS` format, the date and time values may be separated by any character including a space (e.g., `2025-02-01T14-30-00`).
|
||||
|
||||
Hugo resolves the extracted date to the [`timeZone`] defined in your site configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`], but only if you haven't already specified a slug in the page's front matter.
|
||||
|
||||
For example, if you name your file `2025-02-01-article.md`, Hugo will set the date to `2025-02-01` and the slug to `article`.
|
||||
|
||||
`:git`
|
||||
: The Git author date for the file's last revision. To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use the `--enableGitInfo` flag when building your site.
|
||||
|
||||
## Example
|
||||
|
||||
Consider this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[frontmatter]
|
||||
@ -89,3 +97,7 @@ lastmod = ['lastmod', ':fileModTime']
|
||||
To determine `date`, Hugo tries to extract the date from the file name, falling back to the default ordered sequence of date fields.
|
||||
|
||||
To determine `lastmod`, Hugo looks for a `lastmod` field in front matter, falling back to the file's last modification timestamp.
|
||||
|
||||
[`enableGitInfo`]: /configuration/all/#enablegitinfo
|
||||
[`slug`]: /content-management/front-matter/#slug
|
||||
[`timeZone`]: /configuration/all/#timezone
|
||||
|
||||
@ -133,13 +133,13 @@ parser.autoHeadingID
|
||||
: (`bool`) Whether to automatically add `id` attributes to headings (i.e., `h1`, `h2`, `h3`, `h4`, `h5`, and `h6` elements).
|
||||
|
||||
parser.autoIDType
|
||||
: (`string`) The strategy used to automatically generate `id` attributes, one of `github`, `github-ascii` or `blackfriday`.
|
||||
: (`string`) The strategy used to automatically generate `id` attributes, one of `github`, `github-ascii` or `blackfriday`. Default is `github`.
|
||||
|
||||
- `github` produces GitHub-compatible `id` attributes
|
||||
- `github-ascii` drops any non-ASCII characters after accent normalization
|
||||
- `blackfriday` produces `id` attributes compatible with the Blackfriday Markdown renderer
|
||||
- `github`: Generate GitHub-compatible `id` attributes
|
||||
- `github-ascii`: Drop any non-ASCII characters after accent normalization
|
||||
- `blackfriday`: Generate `id` attributes compatible with the Blackfriday Markdown renderer
|
||||
|
||||
This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function. Default is `github`.
|
||||
This is also the strategy used by the [anchorize](/functions/urls/anchorize) template function.
|
||||
|
||||
parser.attribute.block
|
||||
: (`bool`) Whether to enable [Markdown attributes] for block elements. Default is `false`.
|
||||
@ -147,19 +147,35 @@ parser.attribute.block
|
||||
parser.attribute.title
|
||||
: (`bool`) Whether to enable [Markdown attributes] for headings. Default is `true`.
|
||||
|
||||
<!-- TODO: delete this on or after July 1, 2027. -->
|
||||
renderHooks.image.enableDefault
|
||||
: {{< new-in 0.123.0 />}}
|
||||
: (`bool`) Whether to enable the [embedded image render hook]. Default is `false`.
|
||||
: Deprecated in v0.148.0. Use `renderHooks.image.useEmbedded` instead.
|
||||
|
||||
> [!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.image.useEmbedded
|
||||
: {{< new-in 0.148.0 />}}
|
||||
: (`string`) When to use the [embedded image render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
|
||||
|
||||
- `auto`: Automatically use the embedded image render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites.
|
||||
If a custom image render hook is defined by your project, modules, or themes, it will be utilized instead.
|
||||
- `never`: Never use the embedded image render hook. If a custom image render hook is defined by your project, modules, or themes, it will be utilized instead.
|
||||
- `always`: Always use the embedded image render hook, even if a custom image render hook is provided by your project, modules, or themes. In this case, the embedded hook takes precedence.
|
||||
- `fallback`: Use the embedded image render hook only if no custom image render hook is provided by your project, modules, or themes. If a custom hook exists, it will be used instead.
|
||||
|
||||
<!-- TODO: delete this on or after July 1, 2027. -->
|
||||
renderHooks.link.enableDefault
|
||||
: {{< new-in 0.123.0 />}}
|
||||
: (`bool`) Whether to enable the [embedded link render hook]. Default is `false`.
|
||||
: Deprecated in v0.148.0. Use `renderHooks.link.useEmbedded` instead.
|
||||
|
||||
> [!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.
|
||||
renderHooks.link.useEmbedded
|
||||
: {{< new-in 0.148.0 />}}
|
||||
: (`string`) When to use the [embedded link render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
|
||||
|
||||
- `auto`: Automatically use the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites.
|
||||
If a custom link render hook is defined by your project, modules, or themes, it will be utilized instead.
|
||||
- `never`: Never use the embedded link render hook. If a custom link render hook is defined by your project, modules, or themes, it will be utilized instead.
|
||||
- `always`: Always use the embedded link render hook, even if a custom link render hook is provided by your project, modules, or themes. In this case, the embedded hook takes precedence.
|
||||
- `fallback`: Use the embedded link render hook only if no custom link render hook is provided by your project, modules, or themes. If a custom hook exists, it will be used instead.
|
||||
|
||||
renderer.hardWraps
|
||||
: (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`.
|
||||
@ -301,26 +317,26 @@ 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/
|
||||
[AsciiDoc]: https://asciidoc.org/
|
||||
[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/
|
||||
[Emacs Org Mode]: https://orgmode.org/
|
||||
[embedded image render hook]: /render-hooks/images/#embedded
|
||||
[embedded link render hook]: /render-hooks/links/#embedded
|
||||
[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/
|
||||
[GitHub Flavored Markdown]: https://github.github.com/gfm/
|
||||
[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
|
||||
[Goldmark]: https://github.com/yuin/goldmark/
|
||||
[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/
|
||||
@ -330,12 +346,10 @@ ordered
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
[mathematics in Markdown]: content-management/mathematics/
|
||||
[multilingual page resources]: /content-management/page-resources/#multilingual
|
||||
[Pandoc]: https://pandoc.org/
|
||||
[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
|
||||
[reStructuredText]: https://docutils.sourceforge.io/rst.html
|
||||
[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
|
||||
[AsciiDoc]: https://asciidoc.org/
|
||||
[Emacs Org Mode]: https://orgmode.org/
|
||||
[Pandoc]: https://pandoc.org/
|
||||
[reStructuredText]: https://docutils.sourceforge.io/rst.html
|
||||
|
||||
@ -56,7 +56,7 @@ noUgly
|
||||
: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`] are enabled in your site configuration. Default is `false`.
|
||||
|
||||
path
|
||||
: (`string`) The published file's directory path, relative to the root of the publish directory. If not specified, the file will be published using its content path.
|
||||
: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`]. If omitted, Hugo will use the file's original content path for publishing.
|
||||
|
||||
permalinkable
|
||||
: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`] and [`RelPermalink`] methods on a `Page` object. See [details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`.
|
||||
@ -193,11 +193,12 @@ Output format|Template path
|
||||
`rss`|`layouts/section.rss.xml`
|
||||
|
||||
[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
|
||||
[`baseURL`]: /configuration/all/#baseurl
|
||||
[`OutputFormats`]: /methods/page/outputformats/
|
||||
[`Permalink`]: /methods/page/permalink/
|
||||
[`RelPermalink`]: /methods/page/relpermalink/
|
||||
[`baseURL`]: /configuration/all/#baseurl
|
||||
[`permalinkable`]: #permalinkable
|
||||
[`publishDir`]: /configuration/all/#publishdir
|
||||
[`RelPermalink`]: /methods/page/relpermalink/
|
||||
[`uglyURLs`]: /configuration/ugly-urls/
|
||||
[configure media types]: /configuration/media-types/
|
||||
[configure outputs]: /configuration/outputs/
|
||||
|
||||
@ -271,12 +271,12 @@ public/
|
||||
|
||||
This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.
|
||||
|
||||
> [!note]
|
||||
> [!important]
|
||||
> 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.
|
||||
> In its default configuration, Hugo automatically uses the [embedded link render hook] and the [embedded image render hook] for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites.
|
||||
>
|
||||
> You may override the embedded render hooks as needed, provided they capture the resource as described above.
|
||||
> The embedded render hooks will not override any custom link or image render hooks that are provided by your project, modules, or themes. You can change this behavior in your site configuration by setting and [`markup.goldmark.renderHooks.link.useEmbedded`] and [`markup.goldmark.renderHooks.image.useEmbedded`] .
|
||||
|
||||
Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired:
|
||||
|
||||
@ -285,13 +285,16 @@ Although duplicating shared page resources is inefficient, you can enable this f
|
||||
duplicateResourceFiles = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[`markup.goldmark.renderHooks.image.useEmbedded`]: /configuration/markup/#renderhooksimageuseembedded
|
||||
[`markup.goldmark.renderHooks.link.useEmbedded`]: /configuration/markup/#renderhookslinkenabledefault
|
||||
[`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.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
|
||||
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
|
||||
[embedded image render hook]: /render-hooks/images/#embedded
|
||||
[embedded link render hook]: /render-hooks/links/#embedded
|
||||
|
||||
@ -97,21 +97,14 @@ Note that the above requires the following site configuration:
|
||||
wrapStandAloneImageWithinParagraph = false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
## Default
|
||||
## Embedded
|
||||
|
||||
{{< new-in 0.123.0 />}}
|
||||
|
||||
Hugo includes an [embedded image render hook] to resolve Markdown image destinations. Disabled by default, you can enable it in your site configuration:
|
||||
Hugo includes an [embedded image render hook] to resolve Markdown image destinations.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.renderHooks.image]
|
||||
enableDefault = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
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.
|
||||
> [!important]
|
||||
> In its default configuration, Hugo automatically uses the embedded image render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. The default behavior will not override any custom image render hooks that are provided by your project, modules, or themes. You can change this behavior in your site configuration. See [details](/configuration/markup/#renderhooksimageuseembedded).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@ -70,21 +70,14 @@ To include a `rel` attribute set to `external` for external links:
|
||||
{{- /* chomp trailing newline */ -}}
|
||||
```
|
||||
|
||||
## Default
|
||||
## Embedded
|
||||
|
||||
{{< new-in 0.123.0 />}}
|
||||
|
||||
Hugo includes an [embedded link render hook] to resolve Markdown link destinations. Disabled by default, you can enable it in your site configuration:
|
||||
Hugo includes an [embedded link render hook] to resolve Markdown link destinations.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.renderHooks.link]
|
||||
enableDefault = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
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.
|
||||
> [!important]
|
||||
> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. The default behavior will not override any custom link render hooks that are provided by your project, modules, or themes. You can change this behavior in your site configuration. See [details](/configuration/markup/#renderhookslinkuseembedded).
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@ -10,7 +10,9 @@ keywords: []
|
||||
> To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
|
||||
|
||||
> [!note]
|
||||
> When working with Markdown, this shortcode is obsolete. Instead, use a [link render hook] that resolves the link destination using the `GetPage` method on the `Page` object. You can either create your own, or simply enable the [embedded link render hook]. The embedded link render hook is automatically enabled for multilingual single-host projects.
|
||||
> When working with Markdown this shortcode is obsolete. Instead, to properly resolve Markdown link destinations, use the [embedded link render hook] or create your own.
|
||||
>
|
||||
> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. The default behavior will not override any custom link render hooks that are provided by your project, modules, or themes. You can change this behavior in your site configuration. See [details](/configuration/markup/#renderhookslinkuseembedded).
|
||||
|
||||
## Usage
|
||||
|
||||
@ -56,7 +58,7 @@ Rendered:
|
||||
{{% include "_common/ref-and-relref-error-handling.md" %}}
|
||||
|
||||
[content format]: /content-management/formats/
|
||||
[embedded link render hook]: /render-hooks/links/#default
|
||||
[link render hook]: /render-hooks/links/
|
||||
[duplication of shared page resources]: http://localhost:1313/configuration/markup/#duplicateresourcefiles
|
||||
[embedded link render hook]: /render-hooks/links/#embedded
|
||||
[Markdown notation]: /content-management/shortcodes/#notation
|
||||
[source code]: {{% eturl relref %}}
|
||||
|
||||
@ -10,7 +10,9 @@ keywords: []
|
||||
> To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/_shortcodes` directory.
|
||||
|
||||
> [!note]
|
||||
> When working with Markdown, this shortcode is obsolete. Instead, use a [link render hook] that resolves the link destination using the `GetPage` method on the `Page` object. You can either create your own, or simply enable the [embedded link render hook]. The embedded link render hook is automatically enabled for multilingual single-host projects.
|
||||
> When working with Markdown this shortcode is obsolete. Instead, to properly resolve Markdown link destinations, use the [embedded link render hook] or create your own.
|
||||
>
|
||||
> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. The default behavior will not override any custom link render hooks that are provided by your project, modules, or themes. You can change this behavior in your site configuration. See [details](/configuration/markup/#renderhookslinkuseembedded).
|
||||
|
||||
## Usage
|
||||
|
||||
@ -56,7 +58,7 @@ Rendered:
|
||||
{{% include "_common/ref-and-relref-error-handling.md" %}}
|
||||
|
||||
[content format]: /content-management/formats/
|
||||
[embedded link render hook]: /render-hooks/links/#default
|
||||
[link render hook]: /render-hooks/links/
|
||||
[duplication of shared page resources]: http://localhost:1313/configuration/markup/#duplicateresourcefiles
|
||||
[embedded link render hook]: /render-hooks/links/#embedded
|
||||
[Markdown notation]: /content-management/shortcodes/#notation
|
||||
[source code]: {{% eturl relref %}}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user