--- /dev/null
- ignore-words-list = abl,edn,januar,te,trys,ue,womens
+# Config file for codespell.
+# https://github.com/codespell-project/codespell#using-a-config-file
+
+[codespell]
+
+# Comma separated list of dirs to be skipped.
+skip = *.ai,chroma.css,chroma_dark.css,.cspell.json,./data/docs.yaml
+
+# Comma separated list of words to be ignored. Words must be lowercased.
++ignore-words-list = abl,edn,ist,januar,te,trys,ue,womens
+
+# Check file names as well.
+check-filenames = true
--- /dev/null
- "# cspell: ignore fenced code blocks",
+{
+ "version": "0.2",
+ "allowCompoundWords": true,
+ "overrides": [
+ {
+ "filename": "**/*",
+ "enabled": false
+ },
+ {
+ "filename": "**/*.md",
+ "enabled": true
+ }
+ ],
+ "flagWords": [
+ "alot",
+ "hte",
+ "langauge",
+ "reccommend",
+ "seperate",
+ "teh"
+ ],
+ "ignorePaths": [
+ "**/emojis.md",
+ "**/commands/*",
+ "**/showcase/*",
+ "**/tools/*"
+ ],
+ "ignoreRegExpList": [
- "# cspell: ignore words joined with dot",
++ // cspell: ignore fenced code blocks
+ "^(\\s*`{3,}).*[\\s\\S]*?^\\1$",
- "# cspell: ignore strings within backticks",
++ // cspell: ignore words joined with dot
+ "\\w+\\.\\w+",
- "# cspell: ignore strings within double quotes",
++ // cspell: ignore strings within backticks
+ "`.+`",
- "# cspell: ignore strings within brackets",
++ // cspell: ignore strings within double quotes
+ "\".+\"",
- "# cspell: ignore strings within parentheses",
++ // cspell: ignore strings within brackets
+ "\\[.+\\]",
- "# cspell: ignore words that begin with a slash",
++ // cspell: ignore strings within parentheses
+ "\\(.+\\)",
- "# cspell: ignore everything within action delimiters",
++ // cspell: ignore words that begin with a slash
+ "/\\w+",
- "# cspell: ignore everything after a right arrow",
- "\\s+→\\s+.+"
++ // cspell: ignore everything within action delimiters
+ "\\{\\{.+\\}\\}",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore hugo terminology",
- "# ----------------------------------------------------------------------",
++ // cspell: ignore everything after a right arrow
++ "\\s+→\\s+.+",
+ ],
+ "language": "en",
+ "words": [
+ "composability",
+ "configurators",
+ "defang",
+ "deindent",
+ "downscale",
+ "downscaling",
+ "exif",
+ "geolocalized",
+ "grayscale",
+ "marshal",
+ "marshaling",
+ "multihost",
+ "multiplatform",
+ "performantly",
+ "preconfigured",
+ "prerendering",
+ "redirection",
+ "redirections",
+ "slugified",
+ "slugify",
+ "subexpression",
+ "suppressible",
+ "synchronisation",
+ "templating",
+ "transpile",
+ "unmarshal",
+ "unmarshaled",
+ "unmarshaling",
+ "unmarshals",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore foreign language words",
- "# ----------------------------------------------------------------------",
++ // ------------------------------------------------------------------------
++ // cspell: ignore hugo terminology",
++ // ------------------------------------------------------------------------
+ "alignx",
+ "aligny",
+ "attrlink",
+ "canonify",
+ "codeowners",
+ "dynacache",
+ "eturl",
+ "getenv",
+ "gohugo",
+ "gohugoio",
+ "keyvals",
+ "leftdelim",
+ "linkify",
+ "numworkermultiplier",
+ "rightdelim",
+ "shortcode",
+ "stringifier",
+ "struct",
+ "toclevels",
+ "unmarshal",
+ "unpublishdate",
+ "zgotmplz",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore names",
- "# ----------------------------------------------------------------------",
++ // ------------------------------------------------------------------------
++ // cspell: ignore foreign language words",
++ // ------------------------------------------------------------------------
+ "bezpieczeństwo",
+ "blatt",
+ "buch",
+ "descripción",
+ "dokumentation",
+ "erklärungen",
+ "español",
+ "français",
+ "libros",
+ "mercredi",
+ "miesiąc",
+ "miesiąca",
+ "miesiące",
+ "miesięcy",
+ "misérables",
+ "mittwoch",
+ "muchos",
+ "novembre",
+ "otro",
+ "pocos",
+ "produkte",
+ "projekt",
+ "prywatność",
+ "referenz",
+ "régime",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore operating systems and software packages",
- "# ----------------------------------------------------------------------",
++ // ------------------------------------------------------------------------
++ // cspell: ignore names",
++ // ------------------------------------------------------------------------
+ "Atishay",
+ "Cosette",
+ "Eliott",
+ "Furet",
+ "Gregor",
+ "Jaco",
+ "Lanczos",
+ "Ninke",
+ "Noll",
+ "Pastorius",
++ "Pontmercy",
+ "Samsa",
+ "Stucki",
+ "Thénardier",
+ "Vitter",
+ "WASI",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore miscellaneous",
- "# ----------------------------------------------------------------------",
++ // ------------------------------------------------------------------------
++ // cspell: ignore operating systems and software packages",
++ // ------------------------------------------------------------------------
+ "asciidoctor",
+ "brotli",
+ "cifs",
+ "corejs",
+ "disqus",
+ "docutils",
+ "dpkg",
+ "doas",
+ "eopkg",
+ "forgejo",
+ "gitee",
+ "goldmark",
+ "katex",
+ "kubuntu",
+ "lubuntu",
+ "mathjax",
+ "nosql",
+ "pandoc",
+ "pkgin",
+ "rclone",
+ "xubuntu",
++ // ------------------------------------------------------------------------
++ // cspell: ignore miscellaneous",
++ // ------------------------------------------------------------------------
+ "achristie",
+ "ccpa",
+ "cpra",
+ "ddmaurier",
+ "dring",
+ "fleqn",
+ "inor",
+ "iptc",
+ "jausten",
+ "jdoe",
+ "jsmith",
+ "leqno",
+ "milli",
+ "monokai",
+ "mysanityprojectid",
+ "rgba",
+ "rsmith",
+ "tdewolff",
+ "tjones",
+ "vcard",
+ "wcag",
+ "xfeff"
+ ]
+}
--- /dev/null
- Hugo uses Go's [text/template] and [html/template] packages.
+---
+_comment: Do not remove front matter.
+---
+
- 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.
++Hugo uses Go's [`text/template`][] and [`html/template`][] packages.
+
- By default, Hugo uses the html/template package when rendering HTML files.
++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.
+
- To generate HTML output that is safe against code injection, the html/template package escapes strings in certain contexts.
++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
++To generate HTML output that is safe against code injection, the `html/template` package escapes strings in certain contexts.
+
++[`text/template`]: https://pkg.go.dev/text/template
++[`html/template`]: https://pkg.go.dev/html/template
--- /dev/null
- See Go's [text/template] documentation for more information.
+---
+_comment: Do not remove front matter.
+---
+
- [text/template]: https://pkg.go.dev/text/template
++See Go's [`text/template`][] documentation for more information.
+
++[`text/template`]: https://pkg.go.dev/text/template
--- /dev/null
- : (`bool`) Whether to let `js.Build` handle the minification.
+---
+_comment: Do not remove front matter.
+---
+
+params
+: (`map` or `slice`) Params that can be imported as JSON in your JS files, e.g.
+
+ ```go-html-template
+ {{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+ ```
+
+ And then in your JS file:
+
+ ```js
+ import * as params from '@params';
+ ```
+
+ Note that this is meant for small data sets, e.g., configuration settings. For larger data sets, please put/mount the files into `assets` and import them directly.
+
+minify
- : (`string`) Whether to generate `inline`, `linked`, or `external` source maps from esbuild. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file. By default, source maps are not created. Note that the `linked` option was added in Hugo 0.140.0.
++: (`bool`) Whether to minify the generated CSS code. Default is `false`.
+
+loaders
+: {{< new-in 0.140.0 />}}
+: (`map`) Configuring a loader for a given file type lets you load that file type with an `import` statement or a `require` call. For example, configuring the `.png` file extension to use the data URL loader means importing a `.png` file gives you a data URL containing the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`, `css`, `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`, `text`, `ts`, `tsx`. See <https://esbuild.github.io/api/#loader>.
+
+inject
+: (`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See <https://esbuild.github.io/api/#inject>.
+
+shims
+: (`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development:
+
+ ```go-html-template
+ {{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }}
+ {{ $js = $js | js.Build dict "shims" $shims }}
+ ```
+
+ The _shim_ files may look like these:
+
+ ```js
+ // js/shims/react.js
+ module.exports = window.React;
+ ```
+
+ ```js
+ // js/shims/react-dom.js
+ module.exports = window.ReactDOM;
+ ```
+
+ With the above, these imports should work in both scenarios:
+
+ ```js
+ import * as React from 'react';
+ import * as ReactDOM from 'react-dom/client';
+ ```
+
+target
+: (`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, or `esnext`. Default is `esnext`.
+
+platform
+: {{< new-in 0.140.0 />}}
+: (`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See <https://esbuild.github.io/api/#platform>.
+
+externals
+: (`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See <https://esbuild.github.io/api/#external>.
+
+defines
+: (`map`) This option allows you to define a set of string replacements to be performed when building. It must be a map where each key will be replaced by its value.
+
+ ```go-html-template
+ {{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+ ```
+
+drop
+: {{< new-in 0.144.0 />}}
+: (`string`) Edit your source code before building to drop certain constructs: One of `debugger` or `console`.
+: See <https://esbuild.github.io/api/#drop>
+
+sourceMap
- : (`bool`) Whether to include the content of the source files in the source map. By default, this is `true`.
++: (`string`) The type of source map to generate. One of `external`, `inline`, `linked`, or `none`. Default is `none`. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file.
+
+sourcesContent
+: {{< new-in 0.140.0 />}}
++: (`bool`) Whether to include the content of the source files in the source map. Default is `true`.
+
+JSX
+: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See <https://esbuild.github.io/api/#jsx>.
+
+JSXImportSource
+: (`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See <https://esbuild.github.io/api/#jsx-import-source>.
+
+ The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.:
+
+ ```go-html-template
+ {{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }}
+ ```
+
+ With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time:
+
+ ```jsx
+ import { render } from 'preact';
+
+ const App = () => <>Hello world!</>;
+
+ const container = document.getElementById('app');
+ if (container) render(<App />, container);
+ ```
--- /dev/null
--- /dev/null
++---
++_comment: Do not remove front matter.
++---
++
++## Image operations
++
++Use these functions to determine which operations Hugo supports for a given resource. While Hugo classifies a variety of file types as image resources, its ability to process them or extract metadata varies by format.
++
++- [`reflect.IsImageResource`][]: {{% get-page-desc "/functions/reflect/isimageresource" %}}
++- [`reflect.IsImageResourceProcessable`][]: {{% get-page-desc "/functions/reflect/isimageresourceprocessable" %}}
++- [`reflect.IsImageResourceWithMeta`][]: {{% get-page-desc "/functions/reflect/isimageresourcewithmeta" %}}
++
++The table below shows the values these functions return for various file formats. Use it to determine which checks are required before calling specific methods in your templates.
++
++|Format|IsImageResource|IsImageResourceProcessable|IsImageResourceWithMeta|
++|:-----|:--------------|:-------------------------|:----------------------|
++|AVIF |true |**false** |true |
++|BMP |true |true |true |
++|GIF |true |true |true |
++|HEIC |true |**false** |true |
++|HEIF |true |**false** |true |
++|ICO |true |**false** |**false** |
++|JPEG |true |true |true |
++|PNG |true |true |true |
++|SVG |true |**false** |**false** |
++|TIFF |true |true |true |
++|WebP |true |true |true |
++
++This contrived example demonstrates how to iterate through resources and use these functions to apply the appropriate handling for each image format.
++
++```go-html-template
++{{ range resources.Match "**" }}
++ {{ if reflect.IsImageResource . }}
++ {{ if reflect.IsImageResourceProcessable . }}
++ {{ with .Process "resize 300x webp" }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
++ {{ end }}
++ {{ else if reflect.IsImageResourceWithMeta . }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
++ {{ else }}
++ <img src="{{ .RelPermalink }}" alt="">
++ {{ end }}
++ {{ end }}
++{{ end }}
++```
++
++[`reflect.IsImageResource`]: /functions/reflect/isimageresource/
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
++[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
--- /dev/null
- 1. Install [Go] version 1.24.0 or later
+---
+_comment: Do not remove front matter.
+---
+
+## Build from source
+
+To build the extended or extended/deploy edition from source you must:
+
+1. Install [Git]
++1. Install [Go] version 1.25.0 or later
+1. Install a C compiler, either [GCC] or [Clang]
+1. Update your `PATH` environment variable as described in the [Go documentation]
+
+> The install directory is controlled by the `GOPATH` and `GOBIN` environment variables. If `GOBIN` is set, binaries are installed to that directory. If `GOPATH` is set, binaries are installed to the bin subdirectory of the first directory in the `GOPATH` list. Otherwise, binaries are installed to the bin subdirectory of the default `GOPATH` (`$HOME/go` or `%USERPROFILE%\go`).
+
+To build the standard edition:
+
+```sh
+go install github.com/gohugoio/hugo@latest
+```
+
+To build the extended edition:
+
+```sh
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
+```
+
+To build the extended/deploy edition:
+
+```sh
+CGO_ENABLED=1 go install -tags extended,withdeploy github.com/gohugoio/hugo@latest
+```
+
+[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
--- /dev/null
- : The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`smartcrop.js`][] library to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your project configuration.
+---
+_comment: Do not remove front matter.
+---
+
+## Processing specification
+
+The processing specification is a space-delimited, case-insensitive list containing one or more of the following options in any sequence:
+
+action
+: Specify one of `crop`, `fill`, `fit`, or `resize`. This is applicable to the [`Process`][] method and the [`images.Process`][] filter. If you specify an action, you must also provide dimensions.
+
+anchor
- [`smartcrop.js`]: https://github.com/jwagner/smartcrop.js
++: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`muesli/smartcrop`][] package to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your project configuration.
+
+background color
+: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the [`bgColor`][] parameter in your project configuration.
+
+compression
+: {{< new-in 0.153.5 />}}
+: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. This defaults to the [`compression`][] parameter in your project configuration.
+
+dimensions
+: The dimensions of the resulting image, in pixels. The format is `WIDTHxHEIGHT` where `WIDTH` and `HEIGHT` are whole numbers. When resizing an image, you may specify only the width (such as `600x`) or only the height (such as `x400`) for proportional scaling. Specifying both width and height when resizing an image may result in non-proportional scaling. When cropping, fitting, or filling, you must provide both width and height such as `600x400`.
+
+format
+: The format of the resulting image. Valid options include `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image.
+
+hint
+: The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your project configuration.
+
+ Value|Example
+ :--|:--
+ `drawing`|Hand or line drawing with high-contrast details
+ `icon`|Small colorful image
+ `photo`|Outdoor photograph with natural lighting
+ `picture`|Indoor photograph such as a portrait
+ `text`|Image that is primarily text
+
+quality
+: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your project configuration.
+
+resampling filter
+: The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the [`resampleFilter`][] parameter in your project configuration.
+
+ Filter|Description
+ :--|:--
+ `box`|Simple and fast averaging filter appropriate for downscaling
+ `lanczos`|High-quality resampling filter for photographic images yielding sharp results
+ `catmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results
+ `mitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom
+ `linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters
+ `nearestNeighbor`|Fastest resampling filter, no antialiasing
+
+ Refer to the [source documentation][] for a complete list of available resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.
+
+rotation
+: The number of whole degrees to rotate an image counter-clockwise. The format is `rDEGREES` where `DEGREES` is a whole number. Hugo performs rotation before any other transformations, so your [target dimensions](#dimensions) and any [anchor](#anchor) should refer to the image orientation after rotation. Use `r90`, `r180`, or `r270` for orthogonal rotations, or arbitrary angles such as `r45`. To rotate clockwise, use a negative number such as `r-45`. To automatically rotate an image based on its Exif orientation tag, use the [`images.AutoOrient`][] filter instead of manual rotation.
+
+ Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as PNG or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your project configuration.
+
+[`anchor`]: /configuration/imaging/#anchor
+[`bgcolor`]: /configuration/imaging/#bgcolor
+[`compression`]: /configuration/imaging/#compression
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
++[`muesli/smartcrop`]: https://github.com/muesli/smartcrop
+[`hint`]: /configuration/imaging/#hint
+[`images.AutoOrient`]: /functions/images/autoorient/
+[`images.Process`]: /functions/images/process/
+[`Process`]: /methods/resource/process
+[`quality`]: /configuration/imaging/#quality
+[`resampleFilter`]: /configuration/imaging/#resamplefilter
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[source documentation]: https://github.com/disintegration/imaging#image-resizing
--- /dev/null
- : The content's file name without extension, applicable to the `page` page kind.
-
- {{< deprecated-in v0.144.0 >}}
- The `:filename` token has been deprecated. Use `:contentbasename` instead.
- {{< /deprecated-in >}}
+---
+_comment: Do not remove front matter.
+---
+
+`:year`
+: The 4-digit year as defined in the front matter `date` field.
+
+`:month`
+: The 2-digit month as defined in the front matter `date` field.
+
+`:monthname`
+: The name of the month as defined in the front matter `date` field.
+
+`:day`
+: The 2-digit day as defined in the front matter `date` field.
+
+`:weekday`
+: The 1-digit day of the week as defined in the front matter `date` field (Sunday = `0`).
+
+`:weekdayname`
+: The name of the day of the week as defined in the front matter `date` field.
+
+`:yearday`
+: The 1- to 3-digit day of the year as defined in the front matter `date` field.
+
+`:section`
+: The content's section.
+
+`:sectionslug`
+: {{< new-in 0.149.0 />}}
+: The content's section using slugified section name. The slugified section name is the `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title.
+
+`:sections`
+: The content's sections hierarchy. You can use a selection of the sections using _slice syntax_: `:sections[1:]` includes all but the first, `:sections[:last]` includes all but the last, `:sections[last]` includes only the last, `:sections[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
+
+`:sectionslugs`
+: {{< new-in 0.149.0 />}}
+: The content's sections hierarchy using slugified section names. The slugified section name is the `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title. You can use a selection of the sections using _slice syntax_: `:sectionslugs[1:]` includes all but the first, `:sectionslugs[:last]` includes all but the last, `:sectionslugs[last]` includes only the last, `:sectionslugs[1:2]` includes section 2 and 3. Note that this slice access will not throw any out-of-bounds errors, so you don't have to be exact.
+
+`:title`
+: The `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
+
+`:slug`
+: The `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
+
+`:filename`
- : The `slug` as defined in front matter, else the content's file name without extension, applicable to the `page` page kind.
-
- {{< deprecated-in v0.144.0 >}}
- The `:slugorfilename` token has been deprecated. Use `:slugorcontentbasename` instead.
- {{< /deprecated-in >}}
++: {{< deprecated-in v0.144.0 />}}
++: Use `:contentbasename` instead.
+
+`:slugorfilename`
++: {{< deprecated-in v0.144.0 />}}
++: Use `:slugorcontentbasename` instead.
+
+`:contentbasename`
+: {{< new-in 0.144.0 />}}
+: The [content base name].
+
+[content base name]: /methods/page/file/#contentbasename
+
+`:slugorcontentbasename`
+: {{< new-in 0.144.0 />}}
+: The `slug` as defined in front matter, else the [content base name].
+
+For time-related values, you can also use the layout string components defined in Go's [time package]. For example:
+
+[time package]: https://pkg.go.dev/time#pkg-constants
+
+{{< code-toggle file=hugo >}}
+permalinks:
+ posts: /:06/:1/:2/:title/
+{{< /code-toggle >}}
--- /dev/null
- : Render each page of your site to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
+---
+title: Features
+description: Hugo's rich and powerful feature set provides the framework and tools to create static sites that build in seconds, often less.
+categories: []
+keywords: []
+weight: 20
+---
+
+## Framework
+
+[Multiplatform]
+: Install Hugo's single executable on Linux, macOS, Windows, and more.
+
+[Multilingual]
+: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations.
+
+[Output formats]
- : Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site.
++: Render each page of your project to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
+
+[Templates]
+: Create templates using variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format.
+
+[Themes]
+: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more.
+
+[Modules]
- : Configure your site to help comply with regional privacy regulations.
++: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new project, or to augment an existing project.
+
+[Privacy]
- : Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire site once a week.
++: Configure your project to help comply with regional privacy regulations.
+
+[Security]
+: Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more.
+
+## Content authoring
+
+[Content formats]
+: Create your content using Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, or reStructuredText. Markdown is the default content format, conforming to the [CommonMark] and [GitHub Flavored Markdown] specifications.
+
+[Markdown attributes]
+: Apply HTML attributes such as `class` and `id` to Markdown images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+[Markdown extensions]
+: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
+
+[Markdown render hooks]
+: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, links, and tables. For example, render every standalone image as an HTML `figure` element.
+
+[Diagrams]
+: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
+
+[Mathematics]
+: Include mathematical equations and expressions in Markdown using LaTeX markup.
+
+[Syntax highlighting]
+: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles.
+
+[Shortcodes]
+: Use Hugo's embedded shortcodes, or create your own, to insert complex content. For example, use shortcodes to include `audio` and `video` elements, render tables from local or remote data sources, insert snippets from other pages, and more.
+
+## Content management
+
+[Multidimensional content model]
+: Generate pages across any combination of language, version, and role from a single source. This allows a single piece of content to be published to multiple [sites](g) within your project, removing the need to duplicate files for different audiences or versions.
+
+[Content adapters]
+: Create content adapters to dynamically add content when building your project. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
+
+[Taxonomies]
+: Classify content to establish simple or complex logical relationships between pages. For example, create an authors taxonomy, and assign one or more authors to each page. Among other uses, the taxonomy system provides an inverted, weighted index to render a list of related pages, ordered by relevance.
+
+[Data]
+: Augment your content using local or remote data sources including CSV, JSON, TOML, YAML, and XML. For example, create a shortcode to render an HTML table from a remote CSV file.
+
+[Menus]
+: Provide rapid access to content via Hugo's menu system, configured automatically, globally, or on a page-by-page basis. The menu system is a key component of Hugo's multilingual architecture.
+
+[URL management]
+: Serve any page from any path via global configuration or on a page-by-page basis.
+
+## Asset pipelines
+
+[Image processing]
+: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract metadata.
+
+[JavaScript bundling]
+: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
+
+[Sass processing]
+: Transpile Sass to CSS, bundle, tree shake, minify, create source maps, perform SRI hashing, and integrate with PostCSS.
+
+[Tailwind CSS processing]
+: Compile Tailwind CSS utility classes into standard CSS, bundle, tree shake, optimize, minify, perform SRI hashing, and integrate with PostCSS.
+
+## Performance
+
+[Caching]
+: Reduce build time and cost by rendering a _partial_ template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
+
+[Segmentation]
++: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire project once a week.
+
+[Minification]
+: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times.
+
+[Multilingual]: /content-management/multilingual/
+[Multiplatform]: /installation/
+[Output formats]: /configuration/output-formats/
+[Templates]: /templates/introduction/
+[Themes]: https://themes.gohugo.io/
+[Modules]: /hugo-modules/
+[Privacy]: /configuration/privacy/
+[Security]: /about/security/
+
+[Content formats]: /content-management/formats/
+[CommonMark]: https://spec.commonmark.org/current/
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Markdown attributes]: /content-management/markdown-attributes/
+[Markdown extensions]: /configuration/markup/#extensions
+[Markdown render hooks]: /render-hooks/introduction/
+[Diagrams]: /content-management/diagrams/
+[Mathematics]: /content-management/mathematics/
+[Syntax highlighting]: /content-management/syntax-highlighting/
+[Shortcodes]: /content-management/shortcodes/
+
+[Multidimensional content model]: /quick-reference/glossary/#sites-matrix
+[Content adapters]: /content-management/content-adapters/
+[Taxonomies]: /content-management/taxonomies/
+[Data]: /content-management/data-sources/
+[Menus]: /content-management/menus/
+[URL management]: /content-management/urls/
+
+[Image processing]: /content-management/image-processing/
+[JavaScript bundling]: /functions/js/build/
+[Sass processing]: /functions/css/Sass/
+[Tailwind CSS processing]: /functions/css/tailwindcss/
+
+[Caching]: /functions/partials/includecached/
+[Segmentation]: /configuration/segments/
+[Minification]: /configuration/minify/
--- /dev/null
- description: Use the command line interface (CLI) to manage your site.
+---
+title: Command line interface
+linkTitle: CLI
++description: Use the command line interface (CLI) to manage your project.
+categories: []
+keywords: []
+weight: 10
+---
--- /dev/null
- See https://xyproto.github.io/splash/docs/all.html for a preview of the available styles
+---
+title: "hugo gen chromastyles"
+slug: hugo_gen_chromastyles
+url: /commands/hugo_gen_chromastyles/
+---
+## hugo gen chromastyles
+
+Generate CSS stylesheet for the Chroma code highlighter
+
+### Synopsis
+
+Generate CSS stylesheet for the Chroma code highlighter for a given style. This stylesheet is needed if markup.highlight.noClasses is disabled in config.
+
- --style string highlighter style (see https://xyproto.github.io/splash/docs/) (default "friendly")
++See https://gohugo.io/quick-reference/syntax-highlighting-styles/ for a preview of the available styles.
+
+```
+hugo gen chromastyles [flags] [args]
+```
+
+### Options
+
+```
+ -h, --help help for chromastyles
+ --highlightStyle string foreground and background colors for highlighted lines, e.g. --highlightStyle "#fff000 bg:#000fff"
+ --lineNumbersInlineStyle string foreground and background colors for inline line numbers, e.g. --lineNumbersInlineStyle "#fff000 bg:#000fff"
+ --lineNumbersTableStyle string foreground and background colors for table line numbers, e.g. --lineNumbersTableStyle "#fff000 bg:#000fff"
+ --omitClassComments omit CSS class comment prefixes in the generated CSS
+ --omitEmpty omit empty CSS rules (deprecated, no longer needed)
++ --style string highlighter style (default "friendly")
+```
+
+### Options inherited from parent commands
+
+```
+ --clock string set the clock used by Hugo, e.g. --clock 2021-11-06T22:30:00.00+09:00
+ --config string config file (default is hugo.yaml|json|toml)
+ --configDir string config dir (default "config")
+ -d, --destination string filesystem path to write files to
+ -e, --environment string build environment
+ --ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
+ --logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
+ --quiet build in quiet mode
+ -M, --renderToMemory render to memory (mostly useful when running the server)
+ -s, --source string filesystem path to read files relative from
+ --themesDir string filesystem path to themes directory
+```
+
+### SEE ALSO
+
+* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
--- /dev/null
- : (`bool`) For sites under Git version control, whether to enable the [`GitInfo`][] object for each page. With the [default front matter configuration][], the `Lastmod` method on a `Page` object will return the Git author date. Default is `false`.
+---
+title: All settings
+description: The complete list of Hugo configuration settings.
+categories: []
+keywords: []
+weight: 20
+aliases: [/getting-started/configuration/]
+---
+
+## Settings
+
+archetypeDir
+: (`string`) The designated directory for [archetypes](g). Default is `archetypes`. {{% module-mounts-note %}}
+
+assetDir
+: (`string`) The designated directory for [global resources](g). Default is `assets`. {{% module-mounts-note %}}
+
+baseURL
+: (`string`) The absolute URL of your published site including the protocol, host, path, and a trailing slash.
+
+build
+: See [configure build][].
+
+buildDrafts
+: (`bool`) Whether to include draft content when building a site. Default is `false`.
+
+buildExpired
+: (`bool`) Whether to include expired content when building a site. Default is `false`.
+
+buildFuture
+: (`bool`) Whether to include future content when building a site. Default is `false`.
+
+cacheDir
+: (`string`) The designated cache directory. See [details](#cache-directory).
+
+caches
+: See [configure file caches][].
+
+canonifyURLs
+: (`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
+
+capitalizeListTitles
+: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Use the [`titleCaseStyle`][] setting to configure capitalization rules. Default is `true`.
+
+cascade
+: See [configure cascade][].
+
+cleanDestinationDir
+: (`bool`) Whether to remove files from the [`publishDir`][] that do not exist in the [`staticDir`][] when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`.
+
+contentDir
+: (`string`) The designated directory for content files. Default is `content`. {{% module-mounts-note %}}
+
+copyright
+: (`string`) The copyright notice for a site, typically displayed in the footer.
+
+dataDir
+: (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}}
+
+defaultContentLanguage
+: (`string`) The projects's [default language](g), conforming to the syntax described in [RFC 5646][].
+
+defaultContentLanguageInSubdir
+: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`.
+
+defaultContentRole
+: {{< new-in 0.153.0 />}}
+: (`string`) The project's [default role](g).
+
+defaultContentRoleInSubdir
+: {{< new-in 0.153.0 />}}
+: (`bool`) Whether to publish the default content [role](g) to a subdirectory matching the [`defaultContentRole`][]. Default is `false`.
+
+defaultContentVersion
+: {{< new-in 0.153.0 />}}
+: (`string`) The project's [default version](g).
+
+defaultContentVersionInSubdir
+: {{< new-in 0.153.0 />}}
+: (`bool`) Whether to publish the default content version to a subdirectory matching the [`defaultContentVersion`][]. Default is `false`.
+
+defaultOutputFormat
+: (`string`) The default output format for the site. If unspecified, the first available format in the defined order (by weight, then alphabetically) will be used.
+
+deployment
+: See [configure deployment][].
+
+disableAliases
+: (`bool`) Whether to disable the generation of HTML redirect files for each path defined in the [`aliases`][aliases_front_matter] front matter field. When `true`, Hugo will not create physical files for [client-side redirection][], but the alias data remains available via the [`Aliases`][aliases_page_method] method on a `Page` object. Default is `false`.
+
+disableDefaultLanguageRedirect
+: {{< new-in 0.140.0 />}}
+: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`][] is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`.
+
+disableDefaultSiteRedirect
+: {{< new-in 0.154.5 />}}
+: (bool) Whether to disable generation of the alias redirect to the [default site](g). When [`defaultContentLanguageInSubdir`][], [`defaultContentRoleInSubdir`][], or [`defaultContentVersionInSubdir`][] is `true`, this prevents the root directory from redirecting to the default site's subdirectory. Conversely, when these are `false`, it prevents the subdirectories from redirecting back to the root. Default is `false`.
+
+disableHugoGeneratorInject
+: (`bool`) Whether to disable injection of a `<meta name="generator">` tag into the home page. Default is `false`.
+
+disableKinds
+: (`[]string`) A slice of page [kinds](g) to disable during the build process, any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
+
+disableLanguages
+: (`[]string`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`][] key under each language instead.
+
+disableLiveReload
+: (`bool`) Whether to disable automatic live reloading of the browser window. Default is `false`.
+
+disablePathToLower
+: (`bool`) Whether to disable transformation of page URLs to lower case. Default is `false`.
+
+enableEmoji
+: (`bool`) Whether to allow emoji in Markdown. Default is `false`.
+
+enableGitInfo
- languageCode
++: (`bool`) Whether to retrieve commit metadata from the Git history of your local project and any [modules](g). This enables the [`GitInfo`][] method on a `Page` object. With the default front matter configuration, the [`Lastmod`][] method on a `Page` object returns the Git author date of the last commit for that file. Default is `false`.
+
+enableMissingTranslationPlaceholders
+: (`bool`) Whether to show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`.
+
+enableRobotsTXT
+: (`bool`) Whether to enable generation of a `robots.txt` file. Default is `false`.
+
+environment
+: (`string`) The build environment. Default is `production` when running `hugo build` and `development` when running `hugo server`.
+
+frontmatter
+: See [configure front matter][].
+
+hasCJKLanguage
+: (`bool`) Whether to automatically detect [CJK](g) languages in content. Affects the values returned by the [`WordCount`][] and [`FuzzyWordCount`][] methods. Default is `false`.
+
+HTTPCache
+: See [configure HTTP cache][].
+
+i18nDir
+: (`string`) The designated directory for translation tables. Default is `i18n`. {{% module-mounts-note %}}
+
+ignoreCache
+: (`bool`) Whether to ignore the cache directory. Default is `false`.
+
+ignoreFiles
+: (`[]string`) A slice of [regular expressions](g) used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts][].
+
+ignoreLogs
+: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`][] and [`warnidf`][].
+
+ignoreVendorPaths
+: (`string`) A [glob pattern](g) matching the module paths to exclude from the `_vendor` directory.
+
+imaging
+: See [configure imaging][].
+
- [`defaultContentLanguage`]: #defaultcontentlanguage
++locale
+: (`string`) The site's language tag, conforming to the syntax described in [RFC 5646][]. This value does not affect translations or localization. Hugo uses this value to populate:
+
+ - The `language` element in the [embedded RSS template][]
+ - The `lang` attribute of the `html` element in the [embedded alias template][]
+ - The `og:locale` `meta` element in the [embedded Open Graph template][]
+
+ When present in the root of the configuration, this value is ignored if one or more language keys exists. Please specify this value independently for each language key.
+
+languages
+: See [configure languages][].
+
+layoutDir
+: (`string`) The designated directory for templates. Default is `layouts`. {{% module-mounts-note %}}
+
+mainSections
+: (`string` or `[]string`) The main sections of a site. If set, the [`MainSections`][] method on the `Site` object returns the given sections, otherwise it returns the section with the most pages.
+
+markup
+: See [configure markup][].
+
+mediaTypes
+: See [configure media types][].
+
+menus
+: See [configure menus][].
+
+minify
+: See [configure minify][].
+
+module
+: See [configure modules][].
+
+newContentEditor
+: (`string`) The editor to use when creating new content.
+
+noBuildLock
+: (`bool`) Whether to disable creation of the `.hugo_build.lock` file. Default is `false`.
+
+noChmod
+: (`bool`) Whether to disable synchronization of file permission modes. Default is `false`.
+
+noTimes
+: (`bool`) Whether to disable synchronization of file modification times. Default is `false`.
+
+outputFormats
+: See [configure output formats][].
+
+outputs
+: See [configure outputs][].
+
+page
+: See [configure page][].
+
+pagination
+: See [configure pagination][].
+
+panicOnWarning
+: (`bool`) Whether to panic on the first WARNING. Default is `false`.
+
+params
+: See [configure params][].
+
+permalinks
+: See [configure permalinks][].
+
+pluralizeListTitles
+: (`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`.
+
+printI18nWarnings
+: (`bool`) Whether to log WARNINGs for each missing translation. Default is `false`.
+
+printPathWarnings
+: (`bool`) Whether to log WARNINGs when Hugo publishes two or more files to the same path. Default is `false`.
+
+printUnusedTemplates
+: (`bool`) Whether to log WARNINGs for each unused template. Default is `false`.
+
+privacy
+: See [configure privacy][].
+
+publishDir
+: (`string`) The designated directory for publishing the site. Default is `public`.
+
+refLinksErrorLevel
+: (`string`) The logging error level to use when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page. Either `ERROR` or `WARNING`. Any `ERROR` will fail the build. Default is `ERROR`.
+
+refLinksNotFoundURL
+: (`string`) The URL to return when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page.
+
+related
+: See [configure related content][].
+
+relativeURLs
+: (`bool`) See [details](/content-management/urls/#relative-urls) before enabling this feature. Default is `false`.
+
+removePathAccents
+: (`bool`) Whether to remove [non-spacing marks][] from [composite characters][] in content paths. Default is `false`.
+
+renderSegments
+: (`[]string`) A slice of [segments](g) to render. If omitted, all segments are rendered. This option is typically set via a command-line flag, such as `hugo build --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`][] configuration.
+
+resourceDir
+: (`string`) The designated directory for caching output from [asset pipelines](g). Default is `resources`.
+
+roles
+: See [configure roles][].
+
+security
+: See [configure security][].
+
+sectionPagesMenu
+: (`string`) When set, each top-level section will be added to the menu identified by the provided value. See [details](/content-management/menus/#define-automatically).
+
+segments
+: See [configure segments][].
+
+server
+: See [configure server][].
+
+services
+: See [configure services][].
+
+sitemap
+: See [configure sitemap][].
+
+staticDir
+: (`string`) The designated directory for static files. Default is `static`. {{% module-mounts-note %}}
+
+summaryLength
+: (`int`) Applicable to [automatic summaries][], the minimum number of words returned by the [`Summary`][] method on a `Page` object. The `Summary` method will return content truncated at the paragraph boundary closest to the specified `summaryLength`, but at least this minimum number of words. Default is `70`.
+
+taxonomies
+: See [configure taxonomies][].
+
+templateMetrics
+: (`bool`) Whether to print template execution metrics to the console. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
+
+templateMetricsHints
+: (`bool`) Whether to print template execution improvement hints to the console. Applicable when `templateMetrics` is `true`. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
+
+theme
+: (`string` or `[]string`) The [theme](g) to use. Multiple themes can be listed, with precedence given from left to right. See [details](/hugo-modules/theme-components/).
+
+themesDir
+: (`string`) The designated directory for themes. Default is `themes`.
+
+timeout
+: (`string`) The timeout for generating page content, either as a [duration][] or in seconds. This timeout is used to prevent infinite recursion during content generation. You may need to increase this value if your pages take a long time to generate, for example, due to extensive image processing or reliance on remote content. Default is `60s`.
+
+timeZone
+: (`string`) The time zone used to parse dates without time zone offsets, including front matter date fields and values passed to the [`time.AsTime`][] and [`time.Format`][] template functions. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone Database][]. For example, `America/Los_Angeles` and `Europe/Oslo` are valid time zones.
+
+title
+: (`string`) The site title.
+
+titleCaseStyle
+: (`string`) The capitalization rules to follow when Hugo automatically generates a section title, or when using the [`strings.Title`][] function. One of `ap`, `chicago`, `go`, `firstupper`, or `none`. Default is `ap`. See [details](#title-case-style).
+
+uglyurls
+: See [configure ugly URLs][].
+
+versions
+: See [configure versions][].
+
+## 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:
+
+1. If running on Netlify: `/opt/build/cache/hugo_cache/`. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other [CI/CD](g) platforms, please read their documentation. For a CircleCI example, see [this configuration][].
+1. In a `hugo_cache` directory below the OS user cache directory as defined by Go's [os.UserCacheDir][] function. On Unix systems, per the [XDG base directory specification][], this is `$XDG_CACHE_HOME` if non-empty, else `$HOME/.cache`. On MacOS, this is `$HOME/Library/Caches`. On Windows, this is`%LocalAppData%`. On Plan 9, this is `$home/lib/cache`.
+1. In a `hugo_cache_$USER` directory below the OS temp dir.
+
+To determine the current `cacheDir`:
+
+```sh
+hugo config | grep cachedir
+```
+
+## 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.
+
+ap
+: Use the capitalization rules published in the [Associated Press Stylebook][]. This is the default.
+
+chicago
+: Use the capitalization rules published in the [Chicago Manual of Style][].
+
+go
+: Capitalize the first letter of every word.
+
+firstupper
+: Capitalize the first letter of the first word.
+
+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.
+
+## Localized settings
+
+Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages][].
+
++[Associated Press Stylebook]: https://www.apstylebook.com/
++[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
++[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
++[XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/
++[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
++[`GitInfo`]: /methods/page/gitinfo/
++[`Lastmod`]: /methods/page/lastmod/
++[`MainSections`]: /methods/site/mainsections/
++[`Summary`]: /methods/page/summary/
++[`WordCount`]: /methods/page/wordcount/
+[`cacheDir`]: #cachedir
- [`defaultContentRole`]: #defaultcontentrole
+[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
- [`defaultContentVersion`]: #defaultcontentversion
++[`defaultContentLanguage`]: #defaultcontentlanguage
+[`defaultContentRoleInSubdir`]: #defaultcontentroleinsubdir
- [`disabled`]: /configuration/languages/#disabled
++[`defaultContentRole`]: #defaultcontentrole
+[`defaultContentVersionInSubdir`]: #defaultcontentversioninsubdir
- [`FuzzyWordCount`]: /methods/page/fuzzywordcount/
- [`GitInfo`]: /methods/page/gitinfo/
- [`MainSections`]: /methods/site/mainsections/
++[`defaultContentVersion`]: #defaultcontentversion
+[`disableDefaultSiteRedirect`]: #disabledefaultsiteredirect
++[`disabled`]: /configuration/languages/#disabled
+[`erroridf`]: /functions/fmt/erroridf/
- [`Summary`]: /methods/page/summary/
+[`publishDir`]: #publishdir
+[`segments`]: /configuration/segments/
+[`staticDir`]: #staticdir
+[`strings.Title`]: /functions/strings/title/
- [`WordCount`]: /methods/page/wordcount/
+[`time.AsTime`]: /functions/time/astime/
+[`time.Format`]: /functions/time/format/
+[`titleCaseStyle`]: #titlecasestyle
+[`warnidf`]: /functions/fmt/warnidf/
- [Associated Press Stylebook]: https://www.apstylebook.com/
+[aliases_front_matter]: /content-management/front-matter/#aliases
+[aliases_page_method]: /methods/page/aliases/
- [Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
+[automatic summaries]: /content-management/summaries/#automatic-summary
- [configure HTTP cache]: /configuration/http-cache/
+[client-side redirection]: /content-management/urls/#client-side-redirection
+[composite characters]: https://en.wikipedia.org/wiki/Precomposed_character
++[configure HTTP cache]: /configuration/http-cache/
+[configure build]: /configuration/build/
+[configure cascade]: /configuration/cascade/
+[configure deployment]: /configuration/deployment/
+[configure file caches]: /configuration/caches/
+[configure front matter]: /configuration/front-matter/
- [default front matter configuration]: /configuration/front-matter/
+[configure imaging]: /configuration/imaging/
+[configure languages]: /configuration/languages/
+[configure markup]: /configuration/markup/
+[configure media types]: /configuration/media-types/
+[configure menus]: /configuration/menus/
+[configure minify]: /configuration/minify/
+[configure modules]: /configuration/module/
+[configure output formats]: /configuration/output-formats/
+[configure outputs]: /configuration/outputs/
+[configure page]: /configuration/page/
+[configure pagination]: /configuration/pagination/
+[configure params]: /configuration/params/
+[configure permalinks]: /configuration/permalinks/
+[configure privacy]: /configuration/privacy/
+[configure related content]: /configuration/related-content
+[configure roles]: /configuration/roles/
+[configure security]: /configuration/security/
+[configure segments]: /configuration/segments/
+[configure server]: /configuration/server/
+[configure services]: /configuration/services/
+[configure sitemap]: /configuration/sitemap/
+[configure taxonomies]: /configuration/taxonomies/
+[configure ugly URLs]: /configuration/ugly-urls/
+[configure versions]: /configuration/versions/
- [embedded alias template]: <{{% eturl alias %}}>
+[duration]: https://pkg.go.dev/time#Duration
- [IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+[embedded Open Graph template]: <{{% eturl opengraph %}}>
+[embedded RSS template]: <{{% eturl rss %}}>
- [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
++[embedded alias template]: <{{% eturl alias %}}>
+[module mounts]: /configuration/module/#mounts
+[non-spacing marks]: https://www.compart.com/en/unicode/category/Mn
+[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir
- [XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/
+[this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml
--- /dev/null
- source = "assets/watching/hugo_stats\\.json"
- target = "styles\\.css"
+---
+title: Configure build
+linkTitle: Build
+description: Configure global build options.
+categories: []
+keywords: []
+aliases: [/getting-started/configuration-build/]
+---
+
+The `build` configuration section contains global build-related configuration options.
+
+{{< code-toggle config=build />}}
+
+buildStats
+: See the [build stats](#build-stats) section below.
+
+cachebusters
+: See the [cache busters](#cache-busters) section below.
+
+noJSConfigInAssets
+: (`bool`) Whether to disable writing a `jsconfig.json` in your `assets` directory with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
+
+useResourceCacheWhen
+: (`string`) When to use the resource file cache, one of `never`, `fallback`, or `always`. Applicable when transpiling Sass to CSS. Default is `fallback`.
+
+## Cache busters
+
+The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:
+
+<!-- markdownlint-disable MD049 -->
+{{< code-toggle file=hugo >}}
+[build]
+ [build.buildStats]
+ enable = true
+ [[build.cachebusters]]
- source = "(postcss|tailwind)\\.config\\.js"
- target = "css"
++ source = 'assets/watching/hugo_stats\.json'
++ target = 'styles\.css'
+ [[build.cachebusters]]
- source = "assets/.*\\.(js|ts|jsx|tsx)"
- target = "js"
++ source = '(postcss|tailwind)\.config\.js'
++ target = 'css'
+ [[build.cachebusters]]
- source = "assets/.*\\.(.*)$"
- target = "$1"
++ source = 'assets/.*\.(js|ts|jsx|tsx)'
++ target = 'js'
+ [[build.cachebusters]]
++ source = 'assets/.*\.(.*)$'
++ target = '$1'
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD049 -->
+
+When `buildStats` is enabled, Hugo writes a `hugo_stats.json` file on each build with HTML classes etc. that's used in the rendered output. Changes to this file will trigger a rebuild of the `styles.css` file. You also need to add `hugo_stats.json` to Hugo's server watcher. See [Hugo Starter Tailwind Basic](https://github.com/bep/hugo-starter-tailwind-basic) for a running example.
+
+source
+: (`string`) A [regular expression](g) matching file(s) relative to one of the virtual component directories in Hugo, typically `assets/...`.
+
+target
+: (`string`) A [regular expression](g) matching the keys in the resource cache that should be expired when `source` changes. You can use the matching regexp groups from `source` in the expression, e.g. `$1`.
+
+## Build stats
+
+{{< code-toggle config=build.buildStats />}}
+
+enable
+: (`bool`) Whether to create a `hugo_stats.json` file in the root of your project. This file contains arrays of the `class` attributes, `id` attributes, and tags of every HTML element within your published site. Use this file as data source when [removing unused CSS] from your site. This process is also known as pruning, purging, or tree shaking. Default is `false`.
+
+[removing unused CSS]: /functions/resources/postprocess/
+
+disableIDs
+: (`bool`) Whether to exclude `id` attributes. Default is `false`.
+
+disableTags
+: (`bool`) Whether to exclude element tags. Default is `false`.
+
+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`].
+>
+> 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 `hugo build`.
+
+[`config/production`]: /configuration/introduction/#configuration-directory
--- /dev/null
+---
+title: Configure file caches
+linkTitle: Caches
+description: Configure file caches.
+categories: []
+keywords: []
+---
+
+This is the default configuration:
+
+{{< code-toggle config=caches />}}
+
+## Purpose
+
+Hugo uses file caches to store data on disk, avoiding repeated operations within the same build and persisting data from one build to the next.
+
+assets
+: Caches processed CSS and Sass resources.
+
+getresource
+: Caches files fetched from remote URLs via the [`resources.GetRemote`][] function.
+
+images
+: Caches processed images.
+
+misc
+: Caches miscellaneous data.
+
++modulegitinfo
++: Caches Git information for modules.
++
+modulequeries
+: Caches the results of module resolution queries.
+
+modules
+: Caches downloaded modules.
+
+## Keys
+
+dir
+: (`string`) The absolute file system path where Hugo stores the cached files. You can begin the path with the `:cacheDir` or `:resourceDir` [tokens](#tokens) to anchor the cache to specific system or project locations.
+
+maxAge
+: (`string`) The duration a cached entry remains valid before being evicted, expressed as a [duration](g). A value of `0` disables the cache for that key, and a value of `-1` means the cache entry never expires. Default is `-1`.
+
+## Tokens
+
+`:cacheDir`
+: (`string`) The designated cache directory. See [details](/configuration/all/#cachedir).
+
+`:project`
+: (`string`) The base directory name of the current Hugo project. This ensures isolated file caches for each project, preventing the `hugo build --gc` command from affecting other projects on the same machine.
+
+`:resourceDir`
+: (`string`) The designated directory for caching output from [asset pipelines](g). See [details](/configuration/all/#resourcedir).
+
+## Garbage collection
+
+As you modify your site or change your configuration, cached files from previous builds may remain on disk, consuming unnecessary space. Use the `hugo build --gc` command to remove these expired or unused entries from the file cache.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
--- /dev/null
- [`Date`]|Returns the date of the given page.
- [`ExpiryDate`]|Returns the expiry date of the given page.
- [`Lastmod`]|Returns the last modification date of the given page.
- [`PublishDate`]|Returns the publish date of the given page.
+---
+title: Configure front matter
+linkTitle: Front matter
+description: Configure front matter.
+categories: []
+keywords: []
+---
+
+## Dates
+
+There are four methods on a `Page` object that return a date.
+
+Method|Description
+:--|:--
- Hugo resolves the extracted date to the [`timeZone`] defined in your project 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.
++[`Date`][]|Returns the date of the given page.
++[`ExpiryDate`][]|Returns the expiry date of the given page.
++[`Lastmod`][]|Returns the last modification date of the given page.
++[`PublishDate`][]|Returns the publish date of the given page.
+
+[`Date`]: /methods/page/date
+[`ExpiryDate`]: /methods/page/expirydate
+[`Lastmod`]: /methods/page/lastmod
+[`PublishDate`]: /methods/page/publishdate
+
+Hugo determines the values to return based on this configuration:
+
+{{< code-toggle config=frontmatter />}}
+
+The `ExpiryDate` method, for example, returns the `expirydate` value if it exists, otherwise it returns `unpublishdate`.
+
+You can also use custom date parameters:
+
+{{< code-toggle file=hugo >}}
+[frontmatter]
+date = ["myDate", "date"]
+{{< /code-toggle >}}
+
+In the example above, the `Date` method returns the `myDate` value if it exists, otherwise it returns `date`.
+
+To fall back to the default sequence of dates, use the `:default` token:
+
+{{< code-toggle file=hugo >}}
+[frontmatter]
+date = ["myDate", ":default"]
+{{< /code-toggle >}}
+
+In the example above, the `Date` method returns the `myDate` value if it exists, otherwise it returns the first valid date from `date`, `publishdate`, `pubdate`, `published`, `lastmod`, and `modified`.
+
+## Aliases
+
+Some of the front matter fields have aliases.
+
+Front matter field|Aliases
+:--|:--
+`expiryDate`|`unpublishdate`
+`lastmod`|`modified`
+`publishDate`|`pubdate`, `published`
+
+The default front matter configuration includes these aliases.
+
+## Tokens
+
+Hugo provides the following [tokens](g) to help you configure your front matter:
+
+`:default`
+: The default ordered sequence of date fields.
+
+`:fileModTime`
+: The file's last modification timestamp.
+
+`:filename`
+: Extracts the date from the file name, provided the file name begins with a date in one of the following formats:
+
+ - `YYYY-MM-DD`
+ - `YYYY-MM-DD-HH-MM-SS` {{< new-in 0.148.0 />}}
+
+ 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`).
+
- : 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 project.
++ Hugo resolves the extracted date to the [`timeZone`][] defined in your project 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`.
+
+## Example
+
+Consider this project configuration:
+
+{{< code-toggle file=hugo >}}
+[frontmatter]
+date = [':filename', ':default']
+publishDate = [':filename', ':default']
+lastmod = ['lastmod', ':fileModTime']
+{{< /code-toggle >}}
+
+To determine `date` and `publishDate`, Hugo tries to extract the value 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
--- /dev/null
- ## Processing options
-
+---
+title: Configure imaging
+linkTitle: Imaging
+description: Configure imaging.
+categories: []
+keywords: []
+---
+
- {{< code-toggle file=hugo >}}
- [imaging]
- anchor = 'Smart'
- bgColor = '#ffffff'
- compression = 'lossy'
- quality = 75
- resampleFilter = 'box'
- {{< /code-toggle >}}
+These are the default settings for processing images:
+
- : (`string`) The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`smartcrop.js`][] library to identify the most interesting area of the image. Default is `Smart`.
++{{< code-toggle config=imaging />}}
++
++## Top-level options
++
++These global settings define how Hugo handles the fundamental aspects of image manipulation, such as cropping logic, background colors, and general output quality.
+
+anchor
- ## WebP images
++: (`string`) The focal point used when cropping or filling an image. Valid case-insensitive options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`muesli/smartcrop`][] package to identify the most interesting area of the image. Default is `smart`.
+
+bgColor
+: (string) The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. Default is `#ffffff`.
+
+compression
+: {{< new-in 0.153.5 />}}
+: (`string`) The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. Default is `lossy`.
+
+quality
+: (`int`) The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. Expressed as a whole number from `1` to `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is `75`.
+
+resampleFilter
+: (`string`) The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. Default is `box`.
+
+ Filter|Description
+ :--|:--
+ `box`|Simple and fast averaging filter appropriate for downscaling
+ `lanczos`|High-quality resampling filter for photographic images yielding sharp results
+ `catmullRom`|Sharp cubic filter that is faster than the Lanczos filter while providing similar results
+ `mitchellNetravali`|Cubic filter that produces smoother results with less ringing artifacts than CatmullRom
+ `linear`|Bilinear resampling filter, produces smooth output, faster than cubic filters
+ `nearestNeighbor`|Fastest resampling filter, no antialiasing
+
+ Refer to the [source documentation][] for a complete list of available resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.
+
- These are the default settings specific to processing WebP images:
++## Exif method
++
++{{< deprecated-in 0.155.0 >}}
++Use [`Meta`](/methods/resource/meta/) instead.
++{{< /deprecated-in >}}
++
++## Meta method
+
+{{< new-in 0.155.0 />}}
+
- {{< code-toggle file=hugo >}}
- [imaging.webp]
- hint = 'photo'
- method = 4
- useSharpYuv = true
- {{< /code-toggle >}}
++The following parameters allow you to control how Hugo extracts and filters metadata when using the [`Meta`][] method, helping you balance data granularity with build performance.
++
++fields
++: (`[]string`) A [glob slice](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `['**']` to include all fields.
++
++ > [!note]
++ > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
++
++sources
++: (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance.
++
++## WebP images
++
++{{< new-in 0.155.0 />}}
+
- : (`int`) The effort level of the compression algorithm. Expressed as a whole number from `0` to `6`, inclusive, equivalent to the `-m` flag for the [`cwebp`][] CLI. Lower numbers prioritize processing speed, while higher numbers prioritize compression efficiency. Default is `4`.
++These specialized settings provide granular control over the WebP encoding process, allowing you to optimize compression based on the specific visual characteristics of your imagery.
+
+hint
+: (`string`) The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`.
+
+ Value|Example
+ :--|:--
+ `drawing`|Hand or line drawing with high-contrast details
+ `icon`|Small colorful image
+ `photo`|Outdoor photograph with natural lighting
+ `picture`|Indoor photograph such as a portrait
+ `text`|Image that is primarily text
+
+method
- : (`bool`) The conversion method used for RGB-to-YUV encoding, equivalent to the `-sharp_yuv` flag for the [`cwebp`][] CLI. Enabling this prioritizes image sharpness at the expense of processing speed. Default is `true`.
-
- ## Exif method
-
- These are the default settings for the [`Exif`] method on an image `Resource` object:
-
- {{< code-toggle file=hugo >}}
- [imaging.exif]
- disableDate = false
- disableLatLong = false
- excludeFields = ""
- includeFields = ""
- {{< /code-toggle >}}
-
- disableDate
- : (`bool`) Whether to disable the [`Date`][] method by returning its zero value. Default is `false`.
-
- disableLatLong
- : (`bool`) Whether to disable the [`Lat`][] and [`Long`][] methods by returning their zero values. Default is `false`.
-
- excludeFields
- : (`string`) A [regular expression](g) matching the fields to exclude when extracting metadata.
-
- > [!note]
- > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
-
- includeFields
- : (`string`) A [regular expression](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `'.*'` to include all fields.
-
- ## Meta method
-
- {{< new-in 0.155.0 />}}
-
- These are the default settings for the [`Meta`] method on an image `Resource` object:
-
- {{< code-toggle file=hugo >}}
- [imaging.meta]
- fields = []
- sources = ['exif', 'iptc']
- {{< /code-toggle >}}
-
- fields
- : (`[]string`) A [glob slice](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `['**']` to include all fields.
-
- > [!note]
- > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
-
- sources
- : (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance.
++: (`int`) The effort level of the compression algorithm. Expressed as a whole number from `0` to `6`, inclusive, equivalent to the `-m` flag for the [`cwebp`][] CLI. Lower numbers prioritize processing speed, while higher numbers prioritize compression efficiency. Default is `2`.
+
+useSharpYuv
- [`Exif`]: /methods/resource/exif/
- [`Meta`]: /methods/resource/meta/
- [`smartcrop.js`]: https://github.com/jwagner/smartcrop.js
++: (`bool`) The conversion method used for RGB-to-YUV encoding, equivalent to the `-sharp_yuv` flag for the [`cwebp`][] CLI. Enabling this prioritizes image sharpness at the expense of processing speed. Default is `false`.
+
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
++[`muesli/smartcrop`]: https://github.com/muesli/smartcrop
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[source documentation]: https://github.com/disintegration/imaging#image-resizing
--- /dev/null
- Hugo offers many configuration options, but its defaults are often sufficient. A new site requires only these settings:
+---
+title: Introduction
+description: Configure your site using files, directories, and environment variables.
+categories: []
+keywords: []
+weight: 10
+---
+
+## Sensible defaults
+
- languageCode = 'en-us'
++Hugo offers many configuration options, but its defaults are often sufficient. A new project requires only these settings:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
- languageCode = 'en-us'
++locale = 'en-us'
+title = 'My New Hugo Site'
+{{< /code-toggle >}}
+
+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.
+
+## Configuration file
+
+Create a project configuration file in the root of your project directory, naming it `hugo.toml`, `hugo.yaml`, or `hugo.json`, with that order of precedence.
+
+```text
+my-project/
+└── hugo.toml
+```
+
+> [!note]
+> For versions v0.109.0 and earlier, the project 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:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
- languageCode = 'en-us'
++locale = 'en-us'
+title = 'ABC Widgets, Inc.'
+[params]
+subtitle = 'The Best Widgets on Earth'
+[params.contact]
+email = 'info@example.org'
+phone = '+1 202-555-1212'
+{{< /code-toggle >}}
+
+To use a different configuration file when building your project, use the `--config` flag:
+
+```sh
+hugo build --config other.toml
+```
+
+Combine two or more configuration files, with left-to-right precedence:
+
+```sh
+hugo build --config a.toml,b.yaml,c.json
+```
+
+> [!note]
+> See the specifications for each file format: [TOML], [YAML], and [JSON].
+
+## Configuration directory
+
+Instead of a single project configuration file, split your configuration by [environment](g), root configuration key, and language. For example:
+
+```text
+my-project/
+└── config/
+ ├── _default/
+ │ ├── hugo.toml
+ │ ├── menus.en.toml
+ │ ├── menus.de.toml
+ │ └── params.toml
+ └── production/
+ └── params.toml
+```
+
+The root configuration keys are {{< root-configuration-keys >}}.
+
+> [!note]
+> You must define `cascade` tables in the root configuration file. You cannot define `cascade` tables in a dedicated file. See issue [#12899] for details.
+
+[#12899]: https://github.com/gohugoio/hugo/issues/12899
+
+### Omit the root key
+
+When splitting the configuration by root key, omit the root key in the component file. For example, these are equivalent:
+
+{{< code-toggle file=config/_default/hugo >}}
+[params]
+foo = 'bar'
+{{< /code-toggle >}}
+
+{{< code-toggle file=config/_default/params >}}
+foo = 'bar'
+{{< /code-toggle >}}
+
+### Recursive parsing
+
+Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example:
+
+```text
+my-project/
+└── config/
+ └── _default/
+ ├── navigation/
+ │ ├── menus.de.toml
+ │ └── menus.en.toml
+ └── hugo.toml
+```
+
+### Example
+
+```text
+my-project/
+└── config/
+ ├── _default/
+ │ ├── hugo.toml
+ │ ├── menus.en.toml
+ │ ├── menus.de.toml
+ │ └── params.toml
+ ├── production/
+ │ ├── hugo.toml
+ │ └── params.toml
+ └── staging/
+ ├── hugo.toml
+ └── params.toml
+```
+
+Considering the structure above, when running `hugo build --environment staging`, Hugo will use every setting from `config/_default` and merge `staging`'s on top of those.
+
+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 project configuration:
+
+{{< code-toggle file=hugo >}}
+[services.googleAnalytics]
+ID = 'G-XXXXXXXXX'
+{{< /code-toggle >}}
+
+Now consider the following scenario:
+
+1. You don't want to load the analytics code when running `hugo server`.
+1. You want to use different Google tag IDs for your production and staging environments. For example:
+ - `G-PPPPPPPPP` for production
+ - `G-SSSSSSSSS` for staging
+
+To satisfy these requirements, configure your site as follows:
+
+1. `config/_default/hugo.toml`
+ - Exclude the `services.googleAnalytics` section. This will prevent loading of the analytics code when you run `hugo server`.
+ - By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory.
+1. `config/production/hugo.toml`
+ - Include this section only:
+
+ {{< code-toggle file=hugo >}}
+ [services.googleAnalytics]
+ ID = 'G-PPPPPPPPP'
+ {{< /code-toggle >}}
+
+ - You do not need to include other parameters in this file. Include only those parameters that are specific to your production environment. Hugo will merge these parameters with the default configuration.
+ - By default, Hugo sets its `environment` to `production` when running `hugo build`. The analytics code will use the `G-PPPPPPPPP` tag ID.
+
+1. `config/staging/hugo.toml`
+
+ - Include this section only:
+
+ {{< code-toggle file=hugo >}}
+ [services.googleAnalytics]
+ ID = 'G-SSSSSSSSS'
+ {{< /code-toggle >}}
+
+ - You do not need to include other parameters in this file. Include only those parameters that are specific to your staging environment. Hugo will merge these parameters with the default configuration.
+ - To build your staging site, run `hugo build --environment staging`. The analytics code will use the `G-SSSSSSSSS` tag ID.
+
+## Merge configuration settings
+
+Hugo merges configuration settings from themes and modules, prioritizing the project's own settings. Given this simplified project structure with two themes:
+
+```text
+project/
+├── themes/
+│ ├── theme-a/
+│ │ └── hugo.toml
+│ └── theme-b/
+│ └── hugo.toml
+└── hugo.toml
+```
+
+and this project-level configuration:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
++locale = 'en-us'
+title = 'My New Hugo Site'
+theme = ['theme-a','theme-b']
+{{< /code-toggle >}}
+
+Hugo merges settings in this order:
+
+1. Project configuration (`hugo.toml` in the project root)
+1. `theme-a` configuration
+1. `theme-b` configuration
+
+The `_merge` setting within each top-level configuration key controls _which_ settings are merged and _how_ they are merged.
+
+The value for `_merge` can be one of:
+
+none
+: No merge.
+
+shallow
+: Only add values for new keys.
+
+deep
+: Add values for new keys, merge existing.
+
+Note that you don't need to be so verbose as in the default setup below; a `_merge` value higher up will be inherited if not set.
+
+{{< code-toggle file=hugo dataKey="config_helpers.mergeStrategy" skipHeader=true />}}
+
+## Environment variables
+
+You can also configure settings using operating system environment variables:
+
+```sh
+export HUGO_BASEURL=https://example.org/
+export HUGO_ENABLEGITINFO=true
+export HUGO_ENVIRONMENT=staging
+hugo
+```
+
+The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configuration options and then builds your site.
+
+> [!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](g) platforms by allowing you to set values directly within their respective configuration and workflow files.
+
+> [!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].
+
+In addition to configuring standard settings, environment variables may be used to override default values for certain internal settings:
+
+DART_SASS_BINARY
+: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable.
+
+HUGO_FILE_LOG_FORMAT
+: (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`.
+
+HUGO_MEMORYLIMIT
+: (`int`) The maximum amount of system memory, in gigabytes, that Hugo can use while rendering your site. Default is 25% of total system memory. Note that `HUGO_MEMORYLIMIT` is a "best effort" setting. Don't expect Hugo to build a million pages with only 1 GB of memory. You can get more information about how this behaves during the build by running `hugo build --logLevel info` and look for the `dynacache` label.
+
+HUGO_NUMWORKERMULTIPLIER
+: (`int`) The number of workers used in parallel processing. Default is the number of logical CPUs.
+
+## Current configuration
+
+Display the complete project configuration with:
+
+```sh
+hugo config
+```
+
+Display a specific configuration setting with:
+
+```sh
+hugo config | grep [key]
+```
+
+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/
--- /dev/null
- description: Configure the languages in your multilingual site.
+---
+title: Configure languages
+linkTitle: Languages
- Configure the following base settings within the site's root configuration:
++description: Configure the languages in your multilingual project.
+categories: []
+keywords: []
+---
+
+## Base settings
+
- Access this value from a template using the [`Language.LanguageCode`][] method on a `Site` or `Page` object.
-
- languageDirection
- : (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`][] method on a `Site` or `Page` object. Default is `ltr`.
-
- languageName
- : (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.LanguageName`][] method on a `Site` or `Page` object.
++Configure the following base settings:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = false
+disableDefaultLanguageRedirect = false
+disableLanguages = []
+{{< /code-toggle >}}
+
+defaultContentLanguage
+: (`string`) The projects's default content language, conforming to the syntax described in [RFC 5646][]. This value must match one of the defined [language keys][]. Default is `en`.
+
+defaultContentLanguageInSubdir
+: (`bool`) Whether to publish the default content language to a subdirectory matching the [`defaultContentLanguage`][]. Default is `false`.
+
+disableDefaultLanguageRedirect
+: {{< new-in 0.140.0 />}}
+: (`bool`) Whether to disable generation of the alias redirect for the default content language. When [`defaultContentLanguageInSubdir`][] is `true`, this setting prevents the root directory from redirecting to the language subdirectory. Conversely, when `defaultContentLanguageInSubdir` is `false`, this setting prevents the language subdirectory from redirecting to the root directory. This is superseded by the more general [`disableDefaultSiteRedirect`][] setting. Default is `false`.
+
+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.
+
+## Language settings
+
+Configure each language under the `languages` key:
+
+{{< code-toggle config=languages />}}
+
+In the above, `en` is the [language key](#language-keys).
+
++direction
++: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.Direction`][] method on a `Site` or `Page` object. Default is `ltr`.
++
+disabled
+: (`bool`) Whether to disable this language when building the site. Default is `false`.
+
++label
++: (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.Label`][] method on a `Site` or `Page` object.
++
+languageCode
++: {{<deprecated-in 0.158.0 />}}
++: Use [`locale`](#locale) instead.
++
++languageDirection
++: {{<deprecated-in 0.158.0 />}}
++: Use [`direction`](#direction) instead.
++
++languageName
++: {{<deprecated-in 0.158.0 />}}
++: Use [`label`](#label) instead.
++
++locale
+: (`string`) The language tag as described in [RFC 5646][]. This is the primary value used by the [`language.Translate`][] function to select a translation table, falling back to the language key if a matching translation table does not exist.
+
+ Hugo also uses this value to populate:
+
+ - The `lang` attribute of the `html` element in the [embedded alias template][]
+ - The `language` element in the [embedded RSS template][]
+ - The `locale` property in the [embedded OpenGraph template][]
+
+ > [!note]
+ > This value does not affect localization of dates, numbers, and currencies, nor does it affect the site's URL structure. These are controlled by the [language key](#language-keys).
+
- : (`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.
++ Access this value from a template using the [`Language.Locale`][] method on a `Site` or `Page` object.
+
+title
+: (`string`) The site title for this language. Access this value from a template using the [`Title`][] method on a `Site` object.
+
+weight
- languageCode = 'en-US'
- languageName = 'English'
- weight = 1
- title = 'Project Documentation'
++: (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language.
+
+## Sort order
+
+Hugo sorts languages by weight in ascending order, then lexicographically in ascending order. This affects build order and complement selection.
+
+## Localized settings
+
+Some configuration settings can be defined separately for each language. For example:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
- weight = 1
++label = 'English'
++locale = 'en-US'
+timeZone = 'America/New_York'
++title = 'Project Documentation'
++weight = 1
+[languages.en.pagination]
+path = 'page'
+[languages.en.params]
+subtitle = 'Reference, Tutorials, and Explanations'
+{{< /code-toggle >}}
+
+The following configuration keys can be defined separately for each language:
+
+{{< per-lang-config-keys >}}
+
+Any key not defined in a `languages` object will fall back to the global value in the root of your project configuration.
+
+## Language keys
+
+Language keys must conform to the syntax described in [RFC 5646][]. For example:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+[languages.de]
- weight = 2
++weight = 1
+[languages.en-US]
- weight = 3
++weight = 2
+[languages.pt-BR]
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
++weight = 3
+{{< /code-toggle >}}
+
+Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7][] are also supported. Omit the `art-x-` prefix from the language key. For example:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+[languages.en]
+weight = 1
+[languages.hugolang]
+weight = 2
+{{< /code-toggle >}}
+
+> [!note]
+> Private use subtags must not exceed 8 alphanumeric characters.
+
+## Example
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+disableDefaultLanguageRedirect = false
+
+[languages.de]
+contentDir = 'content/de'
++direction = 'ltr'
+disabled = false
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
++label = 'Deutsch'
++locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.de.params]
+subtitle = 'Referenz, Tutorials und Erklärungen'
+
+[languages.en]
+contentDir = 'content/en'
++direction = 'ltr'
+disabled = false
- [languages]
- [languages.en]
- baseURL = 'https://en.example.org/'
- languageName = 'English'
- title = 'In English'
- weight = 2
- [languages.fr]
- baseURL = 'https://fr.example.org'
- languageName = 'Français'
- title = 'En Français'
- weight = 1
++label = 'English'
++locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+
+[languages.en.params]
+subtitle = 'Reference, Tutorials, and Explanations'
+{{< /code-toggle >}}
+
+> [!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.
+
+For example:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'fr'
- [`defaultContentLanguage`]: #defaultcontentlanguage
++[languages.en]
++baseURL = 'https://en.example.org/'
++label = 'English'
++title = 'In English'
++weight = 2
++[languages.fr]
++baseURL = 'https://fr.example.org'
++label = 'Français'
++title = 'En Français'
++weight = 1
+{{</ code-toggle >}}
+
+With the above, Hugo publishes two sites, each with their own root:
+
+```text
+public
+├── en
+└── fr
+```
+
- [`Language.LanguageCode`]: /methods/site/language/#languagecode
- [`Language.LanguageDirection`]: /methods/site/language/#languagedirection
- [`Language.LanguageName`]: /methods/site/language/#languagename
++[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
++[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
++[`Language.Direction`]: /methods/site/language/#direction
++[`Language.Label`]: /methods/site/language/#label
++[`Language.Locale`]: /methods/site/language/#locale
++[`Title`]: /methods/site/title/
+[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
++[`defaultContentLanguage`]: #defaultcontentlanguage
+[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
+[`disableDefaultSiteRedirect`]: /configuration/all/#disabledefaultsiteredirect
- [`Language.Weight`]: /methods/site/language/#weight
- [`Title`]: /methods/site/title/
- [embedded alias template]: <{{% eturl alias %}}>
+[`language.Translate`]: /functions/lang/translate/
- [RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
- [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[embedded OpenGraph template]: <{{% eturl opengraph %}}>
+[embedded RSS template]: <{{% eturl rss %}}>
++[embedded alias template]: <{{% eturl alias %}}>
+[language keys]: #language-keys
+[translating by file name]: /content-management/multilingual/#translation-by-file-name
--- /dev/null
- : (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host sites. See [multilingual page resources] for details. Default is `false`.
+---
+title: Configure markup
+linkTitle: Markup
+description: Configure markup.
+categories: []
+keywords: []
+aliases: [/getting-started/configuration-markup/]
+---
+
+## Default handler
+
+In its default configuration, Hugo uses [Goldmark] to render Markdown to HTML.
+
+{{< code-toggle file=hugo >}}
+[markup]
+defaultMarkdownHandler = 'goldmark'
+{{< /code-toggle >}}
+
+Files with ending with `.md`, `.mdown`, or `.markdown` are processed as Markdown, unless you've explicitly set a different format using the `markup` field in your front matter.
+
+To use a different renderer for Markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your project configuration.
+
+`defaultMarkdownHandler`|Renderer
+:--|:--
+`asciidocext`|[AsciiDoc]
+`goldmark`|[Goldmark]
+`org`|[Emacs Org Mode]
+`pandoc`|[Pandoc]
+`rst`|[reStructuredText]
+
+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).
+
+## Goldmark
+
+This is the default configuration for the Goldmark Markdown renderer:
+
+{{< code-toggle config=markup.goldmark />}}
+
+### Extensions
+
+The extensions below, excluding Extras and Passthrough, are enabled by default.
+
+Extension|Documentation|Enabled
+:--|:--|:-:
+`cjk`|[Goldmark Extensions: CJK]|:heavy_check_mark:
+`definitionList`|[PHP Markdown Extra: Definition lists]|:heavy_check_mark:
+`extras`|[Hugo Goldmark Extensions: Extras]|
+`footnote`|[PHP Markdown Extra: Footnotes]|:heavy_check_mark:
+`linkify`|[GitHub Flavored Markdown: Autolinks]|:heavy_check_mark:
+`passthrough`|[Hugo Goldmark Extensions: Passthrough]|
+`strikethrough`|[GitHub Flavored Markdown: Strikethrough]|:heavy_check_mark:
+`table`|[GitHub Flavored Markdown: Tables]|:heavy_check_mark:
+`taskList`|[GitHub Flavored Markdown: Task list items]|:heavy_check_mark:
+`typographer`|[Goldmark Extensions: Typographer]|:heavy_check_mark:
+
+#### Extras
+
+Enable [deleted text], [inserted text], [mark text], [subscript], and [superscript] elements in Markdown.
+
+Element|Markdown|Rendered
+:--|:--|:--
+Deleted text|`~~foo~~`|`<del>foo</del>`
+Inserted text|`++bar++`|`<ins>bar</ins>`
+Mark text|`==baz==`|`<mark>baz</mark>`
+Subscript|`H~2~O`|`H<sub>2</sub>O`
+Superscript|`1^st^`|`1<sup>st</sup>`
+
+To avoid a conflict[^1], if you enable the "subscript" feature of the Extras extension, you must disable the Strikethrough extension:
+
+[^1]: See [details](https://github.com/gohugoio/hugo-goldmark-extensions/commit/4d4fcd022fe45a9b51483df001c9e5f4e632d5a9).
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions]
+strikethrough = false
+
+[markup.goldmark.extensions.extras.subscript]
+enable = true
+{{< /code-toggle >}}
+
+If you still need to show deleted text after disabling the Strikethrough extension, enable the "deleted text" feature of the Extras extension:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions]
+strikethrough = false
+
+[markup.goldmark.extensions.extras.delete]
+enable = true
+{{< /code-toggle >}}
+
+With this configuration, to format text as deleted, wrap it with double-tildes.
+
+#### Footnote
+
+Enabled by default, the Footnote extension enables inclusion of footnotes in Markdown.
+
+enable
+: {{< new-in 0.151.0 />}}
+: (`bool`) Whether to enable the Footnotes extension. Default is `true`.
+
+backlinkHTML
+: {{< new-in 0.151.0 />}}
+: (`string`) The HTML to be displayed at the end of a footnote that links the user back to the corresponding reference in the main text. The default is ↩︎ (a return arrow symbol).
+
+enableAutoIDPrefix
+: {{< new-in 0.151.0 />}}
+: (`bool`) Whether to prepend a unique prefix to footnote IDs, preventing clashes when multiple documents are rendered together. This prefix is unique to each logical path, which means that the prefix is not unique across content dimensions such as language. Default is `false`.
+
+#### Passthrough
+
+Enable the Passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details.
+
+#### Typographer
+
+The Typographer extension replaces certain character combinations with HTML entities as specified below:
+
+Markdown|Replaced by|Description
+:--|:--|:--
+`...`|`…`|horizontal ellipsis
+`'`|`’`|apostrophe
+`--`|`–`|en dash
+`---`|`—`|em dash
+`«`|`«`|left angle quote
+`“`|`“`|left double quote
+`‘`|`‘`|left single quote
+`»`|`»`|right angle quote
+`”`|`”`|right double quote
+`’`|`’`|right single quote
+
+### Goldmark settings explained
+
+Most of the Goldmark settings above are self-explanatory, but some require explanation.
+
+duplicateResourceFiles
- > 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.
++: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host projects. See [multilingual page resources] for details. Default is `false`.
+
+ > [!note]
- extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
- workingFolderCurrent = true
- [markup.asciidocExt.attributes]
- my-base-url = "https://example.com/"
- my-attribute-name = "my value"
++ > With multilingual single-host projects, 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 projects.
+
+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`.
+
+parser.autoDefinitionTermID
+: {{< new-in 0.144.0 />}}
+: (`bool`) Whether to automatically add `id` attributes to description list terms (i.e., `dt` elements). When `true`, the `id` attribute of each `dt` element is accessible through the [`Fragments.Identifiers`] method on a `Page` object.
+
+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`. Default is `github`.
+
+ - `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] template function.
+
+parser.attribute.block
+: (`bool`) Whether to enable [Markdown attributes] for block elements. Default is `false`.
+
+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
+: Deprecated in v0.148.0. Use `renderHooks.image.useEmbedded` instead.
+
+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`: Use the embedded image render hook only for multilingual single-host projects where the [duplication of shared page resources] feature is disabled. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `never`: Never use the embedded image render hook. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `always`: Always use the embedded image render hook, even if custom image render hooks are provided by your project, modules, or themes.
+ - `fallback`: Use the embedded image render hook only if custom image render hooks are not provided by your project, modules, or themes. If custom image render hooks exist, these will be used instead.
+
+<!-- TODO: delete this on or after July 1, 2027. -->
+renderHooks.link.enableDefault
+: Deprecated in v0.148.0. Use `renderHooks.link.useEmbedded` instead.
+
+renderHooks.link.useEmbedded
+: (`string`) When to use the [embedded link render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
+
+ - `auto`: Use the embedded link render hook only for multilingual single-host projects where the [duplication of shared page resources] feature is disabled. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `never`: Never use the embedded link render hook. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `always`: Always use the embedded link render hook, even if custom link render hooks are provided by your project, modules, or themes.
+ - `fallback`: Use the embedded link render hook only if custom link render hooks are not provided by your project, modules, or themes. If custom link render hooks exist, these will be used instead.
+
+renderer.hardWraps
+: (`bool`) Whether to replace newline characters within a paragraph with `br` elements. Default is `false`.
+
+renderer.unsafe
+: (`bool`) Whether to render raw HTML mixed within Markdown. This is unsafe unless the content is under your control. Default is `false`.
+
+## AsciiDoc
+
+This is the default configuration for the AsciiDoc renderer:
+
+{{< code-toggle config=markup.asciidocExt />}}
+
+### AsciiDoc settings explained
+
+attributes
+: (`map`) A map of key-value pairs, each a document attribute. See Asciidoctor's [attributes].
+
+backend
+: (`string`) The backend output file format. Default is `html5`.
+
+extensions
+: (`[]string`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`.
+
+ > [!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`.
+
+noHeaderOrFooter
+: (`bool`) Whether to output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is `true`.
+
+preserveTOC
+: (`bool`) Whether to preserve the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the [`TableOfContents`] method on a `Page` object in your templates. Default is `false`.
+
+safeMode
+: (`string`) The safe mode level, one of `unsafe`, `safe`, `server`, or `secure`. Default is `unsafe`.
+
+sectionNumbers
+: (`bool`) Whether to number each section title. Default is `false`.
+
+trace
+: (`bool`) Whether to include backtrace information on errors. Default is `false`.
+
+verbose
+: (`bool`) Whether to verbosely print processing information and configuration file checks to stderr. Default is `false`.
+
+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`.
+
+### Configuration example
+
+{{< code-toggle file=hugo >}}
+[markup.asciidocExt]
++extensions = ['asciidoctor-html5s','asciidoctor-diagram']
++workingFolderCurrent = true
++[markup.asciidocExt.attributes]
++my-base-url = 'https://example.com/'
++my-attribute-name = 'my value'
+{{< /code-toggle >}}
+
+### Syntax highlighting
+
+Follow the steps below to enable syntax highlighting.
+
+Step 1
+: Set the `source-highlighter` attribute in your project configuration. For example:
+
+ {{< code-toggle file=hugo >}}
+ [markup.asciidocExt.attributes]
+ source-highlighter = 'rouge'
+ {{< /code-toggle >}}
+
+Step 2
+: Generate the highlighter CSS. For example:
+
+ ```text
+ rougify style monokai.sublime > assets/css/syntax.css
+ ```
+
+Step 3
+: In your base template add a link to the CSS file:
+
+ ```go-html-template {file="layouts/baseof.html"}
+ <head>
+ ...
+ {{ with resources.Get "css/syntax.css" }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ ...
+ </head>
+ ```
+
+Step 4
+: Add the code to be highlighted to your markup:
+
+ ```text
+ [#hello,ruby]
+ ----
+ require 'sinatra'
+
+ get '/hi' do
+ "Hello World!"
+ end
+ ----
+ ```
+
+### Troubleshooting
+
+Run `hugo build --logLevel debug` to examine Hugo's call to the Asciidoctor executable:
+
+```txt
+INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
+```
+
+## Highlight
+
+This is the default configuration.
+
+{{< code-toggle config=markup.highlight />}}
+
+{{% include "/_common/syntax-highlighting-options.md" %}}
+
+## Table of contents
+
+This is the default configuration for the table of contents, applicable to Goldmark and Asciidoctor:
+
+{{< code-toggle config=markup.tableOfContents />}}
+
+startLevel
+: (`int`) Heading levels less than this value will be excluded from the table of contents. For example, to exclude `h1` elements from the table of contents, set this value to `2`. Default is `2`.
+
+endLevel
+: (`int`) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude `h4`, `h5`, and `h6` elements from the table of contents, set this value to `3`. Default is `3`.
+
+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/
+[anchorize]: /functions/urls/anchorize
+[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
+[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-
+[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/
+[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
+[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
--- /dev/null
- [mediaTypes."text/netlify"]
- delimiter = ""
+---
+title: Configure media types
+linkTitle: Media types
+description: Configure media types.
+categories: []
+keywords: []
+---
+
+{{% glossary-term "media type" %}}
+
+Configured media types serve multiple purposes in Hugo, including the definition of [output formats](g). This is the default media type configuration in tabular form:
+
+{{< datatable "config" "mediaTypes" "_key" "suffixes" >}}
+
+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.
+
+## Default configuration
+
+The following is the default configuration that matches the table above:
+
+{{< code-toggle file=hugo config=mediaTypes />}}
+
+delimiter
+: (`string`) The delimiter between the file name and the suffix. The delimiter, in conjunction with the suffix, forms the file extension. Default is `"."`.
+
+suffixes
+: (`[]string`) The suffixes associated with this media type. The first suffix is the primary suffix.
+
+## Modify a media type
+
+You can modify any of the default media types. For example, to switch the primary suffix for `text/html` from `html` to `htm`:
+
+{{< code-toggle file=hugo >}}
+[mediaTypes.'text/html']
+suffixes = ['htm','html']
+{{< /code-toggle >}}
+
+If you alter a default media type, you must also explicitly redefine all output formats that utilize that media type. For example, to ensure the changes above affect the `html` output format, redefine the `html` output format:
+
+{{< code-toggle file=hugo >}}
+[outputFormats.html]
+mediaType = 'text/html'
+{{< /code-toggle >}}
+
+## Create a media type
+
+You can create new media types as needed. For example, to create a media type for an Atom feed:
+
+{{< code-toggle file=hugo >}}
+[mediaTypes.'application/atom+xml']
+suffixes = ['atom']
+{{< /code-toggle >}}
+
+## Media types without suffixes
+
+Occasionally, you may need to create a media type without a suffix or delimiter. For example, [Netlify] recognizes configuration files named `_redirects` and `_headers`, which Hugo can generate using custom [output formats](g).
+
+To support these custom output formats, register a custom media type with no suffix or delimiter:
+
+{{< code-toggle file=hugo >}}
- baseName = "_redirects"
++[mediaTypes.'text/netlify']
++delimiter = ''
+{{< /code-toggle >}}
+
+The custom output format definitions would look something like this:
+
+{{< code-toggle file=hugo >}}
+[outputFormats.redir]
- mediatype = "text/netlify"
++baseName = '_redirects'
+isPlainText = true
- baseName = "_headers"
++mediatype = 'text/netlify'
+[outputFormats.headers]
- mediatype = "text/netlify"
++baseName = '_headers'
+isPlainText = true
++mediatype = 'text/netlify'
+notAlternative = true
+{{< /code-toggle >}}
+
+[Netlify]: https://www.netlify.com/
--- /dev/null
- See the [tdewolff/minify] project page for details, but note the following:
+---
+title: Configure minify
+linkTitle: Minify
+description: Configure minify.
+categories: []
+keywords: []
+---
+
+This is the default configuration:
+
+{{< code-toggle config=minify />}}
+
- [tdewolff/minify]: https://github.com/tdewolff/minify
++See the [`tdewolff/minify`][] project page for details, but note the following:
+
+- `css.inline` is for internal use. Changing this setting has no effect.
+- `html.keepConditionalComments` has been deprecated. Use `html.keepSpecialComments` instead.
+
++[`tdewolff/minify`]: https://github.com/tdewolff/minify
--- /dev/null
- : (`string`) A comma-separated list of [glob patterns](g),s matching paths that should not use the [configured proxy server](#proxy).
+---
+title: Configure modules
+linkTitle: Modules
+description: Configure modules.
+categories: []
+keywords: []
+aliases: [/hugo-modules/configuration/]
+---
+
+{{% include "/_common/gomodules-info.md" %}}
+
+## Top-level options
+
+This is the default configuration:
+
+<!-- markdownlint-disable MD049 -->
+{{< code-toggle file=hugo >}}
+[module]
+noProxy = 'none'
+noVendor = ''
+private = '*.*'
+proxy = 'direct'
+vendorClosest = false
+workspace = 'off'
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD049 -->
+
+auth
+: {{< new-in 0.144.0 />}}
+: (`string`) Configures `GOAUTH` when running the Go command for module operations. This is a semicolon-separated list of authentication commands for go-import and HTTPS module mirror interactions. This is useful for private repositories. See `go help goauth` for more information.
+
+noProxy
- : (`string`) A comma-separated list of [glob patterns](g),s matching paths that should be treated as private.
++: (`string`) A comma-separated list of [glob patterns](g), matching paths that should not use the [configured proxy server](#proxy).
+
+noVendor
+: (`string`) A [glob pattern](g) matching module paths to skip when vendoring.
+
+private
- path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
++: (`string`) A comma-separated list of [glob patterns](g), matching paths that should be treated as private.
+
+proxy
+: (`string`) The proxy server to use to download remote modules. Default is `direct`, which means `git clone` and similar.
+
+replacements
+: (`string`) Primarily useful for local module development, a comma-separated list of mappings from module paths to directories. Paths may be absolute or relative to the [`themesDir`][].
+
+ {{< code-toggle file=hugo >}}
+ [module]
+ replacements = 'github.com/bep/my-theme -> ../..,github.com/bep/shortcodes -> /some/path'
+ {{< /code-toggle >}}
+
+vendorClosest
+: (`bool`) Whether to pick the vendored module closest to the module using it. The default behavior is to pick the first. Note that there can still be only one dependency of a given module path, so once it is in use it cannot be redefined. Default is `false`.
+
+workspace
+: (`string`) The Go workspace file to use, either as an absolute path or a path relative to the current working directory. Enabling this activates Go workspace mode and requires Go 1.18 or later. The default is `off`.
+
+You may also use environment variables to set any of the above. For example:
+
+```sh
+export HUGO_MODULE_PROXY="https://proxy.example.org"
+export HUGO_MODULE_REPLACEMENTS="github.com/bep/my-theme -> ../.."
+export HUGO_MODULE_WORKSPACE="/my/hugo.work"
+```
+
+## Hugo version
+
+You can specify a required Hugo version for your module in the `module` section. Users will then receive a warning if their Hugo version is incompatible.
+
+This is the default configuration:
+
+{{< code-toggle config=module.hugoVersion />}}
+
+You can omit any of the settings above.
+
+extended
+: (`bool`) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition.
+
+ > [!note]
+ > The extended version check is disabled in v0.153.2 and later.
+ >
+ > Historically, certain features—specifically WebP encoding and LibSass—required the Hugo Extended binary. However, as of v0.153.0:
+ >
+ > - WebP encoding is now supported in all Hugo editions.
+ > - LibSass has been deprecated in favor of [Dart Sass][], which is compatible with any Hugo edition.
+ >
+ > Because these dependencies no longer require a specialized binary, the internal enforcement check for the extended version has been removed. Site and theme authors are encouraged to use Dart Sass to ensure cross-edition compatibility.
+
+max
+: (`string`) The maximum Hugo version supported, for example `0.153.0`.
+
+min
+: (`string`) The minimum Hugo version supported, for example `0.102.0`.
+
+## Imports
+
+{{< code-toggle file=hugo >}}
+[[module.imports]]
+disable = false
+ignoreConfig = false
+ignoreImports = false
- path = "my-shortcodes"
++path = 'github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v'
+[[module.imports]]
- : {{< new-in 0.128.0 />}}
++path = 'my-shortcodes'
+{{< /code-toggle >}}
+
+disable
+: (`bool`) Whether to disable the module but keep version information in the `go.*` files. Default is `false`.
+
+ignoreConfig
+: (`bool`) Whether to ignore module configuration files, for example, `hugo.toml`. This will also prevent loading of any transitive module dependencies. Default is `false`.
+
+ignoreImports
+: (`bool`) Whether to ignore module imports. Default is `false`.
+
+noMounts
+: (`bool`) Whether to disable directory mounting for this import. Default is `false`.
+
+noVendor
+: (`bool`) Whether to disable vendoring for this import. This setting is restricted to the main project. Default is `false`.
+
+path
+: (`string`) The module path, either a valid Go module path (e.g., `github.com/gohugoio/myShortcodes`) or the directory name if stored in the [`themesDir`][].
+
+version
+: {{< new-in 0.150.0 />}}
+: If set to a [version query](https://go.dev/ref/mod#version-queries), this import becomes a direct dependency, in contrast to dependencies managed by Go Modules. See [this issue](https://github.com/gohugoio/hugo/pull/13966) for more information.
+
+## Mounts
+
+{{% glossary-term mount %}}
+
+> [!important]
+> If you define one or more mounts to map a file system path to a component path, do not use these legacy configuration settings: [`archetypeDir`][], [`assetDir`][], [`contentDir`][], [`dataDir`][], [`i18nDir`][], [`layoutDir`][], or [`staticDir`][].
+
+### Default mounts
+
+Within a project, if you define a mount to map a file system path to a component path, the corresponding default mount for that component will be removed. This action essentially overwrites the standard, automatic mapping for that specific component with your custom one.
+
+Within a module, if you define a mount to map a file system path to a component path, all of the default mounts will be removed. Defining a mount at the module level is a more sweeping change, causing all default mappings within that module to be discarded.
+
+In either case, if you still need one of the default mounts, you must explicitly add it along with the new mount. Because custom mounts override defaults, any necessary default mappings must be re-added manually after you introduce your custom configuration.
+
+These are the default mounts:
+
+{{< code-toggle config=module.mounts />}}
+
+source
+: (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative.
+
+target
+: (`string`) Where the mount will reside within Hugo's [unified file system](g). It must begin with one of Hugo's [component](g) directories: archetypes, assets, content, data, i18n, layouts, or static. For example, content/blog.
+
+disableWatch
- source="content"
- target="content"
- files=["! docs/*"]
+: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`.
+
+files
+: {{< new-in 0.153.0 />}}
+: (`[]string`) A [glob slice](g) defining the files to include or exclude.
+
+sites
+: {{< new-in 0.153.0 />}}
+: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the mount. Relevant for `content` and `layouts` mounts, and `static` mounts when in multihost mode. For `static` and `layouts`, only the `matrix` keyword is supported.
+
+### Example
+
+{{< code-toggle file=hugo >}}
+[module]
+[[module.mounts]]
- source="node_modules"
- target="assets"
++source = 'content'
++target = 'content'
++files = ['! docs/*']
+[[module.mounts]]
- source="assets"
- target="assets"
++source = 'node_modules'
++target = 'assets'
+[[module.mounts]]
++source = 'assets'
++target = 'assets'
+{{< /code-toggle >}}
+
+[`archetypeDir`]: /configuration/all/#archetypedir
+[`assetDir`]: /configuration/all/#assetdir
+[`contentDir`]: /configuration/all/#contentdir
+[`dataDir`]: /configuration/all/#datadir
+[`i18nDir`]: /configuration/all/#i18ndir
+[`layoutDir`]: /configuration/all/#layoutdir
+[`staticDir`]: /configuration/all/#staticdir
+[`themesDir`]: /configuration/all/#themesdir
+[Dart Sass]: /functions/css/sass/#dart-sass
--- /dev/null
- : (`bool`) Whether to parse templates for this output format with Go's [text/template][] package instead of the [html/template][] package. Default is `false`.
+---
+title: Configure output formats
+linkTitle: Output formats
+description: Configure output formats.
+categories: []
+keywords: []
+---
+
+{{% glossary-term "output format" %}}
+
+You can output a page in as many formats as you want. Define an infinite number of output formats, provided they each resolve to a unique file system path.
+
+This is the default output format configuration in tabular form:
+
+{{< datatable
+ "config"
+ "outputFormats"
+ "_key"
+ "mediaType"
+ "weight"
+ "baseName"
+ "isHTML"
+ "isPlainText"
+ "noUgly"
+ "notAlternative"
+ "path"
+ "permalinkable"
+ "protocol"
+ "rel"
+ "root"
+ "ugly"
+>}}
+
+## Default configuration
+
+The following is the default configuration that matches the table above:
+
+{{< code-toggle config=outputFormats />}}
+
+baseName
+: (`string`) The base name of the published file. Default is `index`.
+
+isHTML
+: (`bool`) Whether to classify the output format as HTML. This value determines when the LiveReload script is injected and, in conjunction with [`permalinkable`](#permalinkable), whether [alias redirects][] are generated. Default is `false`.
+
+isPlainText
- : Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path:
++: (`bool`) Whether to parse templates for this output format with Go's [`text/template`][] package instead of the [`html/template`][] package. Default is `false`.
+
+mediaType
+: (`string`) The [media type](g) of the published file. This must match one of the [configured media types][].
+
+notAlternative
+: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`][] method on a `Page` object. Default is `false`.
+
+noUgly
+: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your project configuration. Default is `false`.
+
+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 the main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. Along with [`isHTML`](#ishtml), this must be `true` to create [alias redirects][]. Enabled by default for the `html` and `amp` output formats. Default is `false`.
+
+protocol
+: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your project configuration, typically `https://`.
+
+rel
+: (`string`) The relationship of the output format to the current page. Hugo uses this property to determine the [canonical output format](g) of the current page. For the predefined `html` output format, the default value is `canonical`; for all other predefined output formats, the default value is `alternate`.
+
+root
+: (`bool`) Whether to publish files to the root of the publish directory. Default is `false`.
+
+ugly
+: (`bool`) Whether to enable uglyURLs for this output format when `uglyURLs` is `false` in your project configuration. Default is `false`.
+
+weight
+: (`int`) When set to a non-zero value, Hugo uses the `weight` as the first criteria when sorting output formats, falling back to the name of the output format. Lighter items float to the top, while heavier items sink to the bottom. Hugo renders output formats sequentially based on the sort order. Default is `0`, except for the `html` output format, which has a default weight of `10`.
+
+## Modify an output format
+
+You can modify any of the default output formats. For example, to prioritize `json` rendering over `html` rendering, when both are generated, adjust the [`weight`](#weight):
+
+{{< code-toggle file=hugo >}}
+[outputFormats.json]
+weight = 1
+[outputFormats.html]
+weight = 2
+{{< /code-toggle >}}
+
+The example above shows that when you modify a default content format, you only need to define the properties that differ from their default values.
+
+## Create an output format
+
+You can create new output formats as needed. For example, you may wish to create an output format to support Atom feeds.
+
+Step 1
+: Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types][], you must create it first.
+
+ {{< code-toggle file=hugo >}}
+ [mediaTypes.'application/atom+xml']
+ suffixes = ['atom']
+ {{< /code-toggle >}}
+
+ See [configure media types][] for more information.
+
+Step 2
+: Create a new output format:
+
+ {{< code-toggle file=hugo >}}
+ [outputFormats.atom]
+ mediaType = 'application/atom+xml'
+ noUgly = true
+ {{< /code-toggle >}}
+
+ Note that we use the default settings for all other output format properties.
+
+Step 3
+: Specify the page [kinds](g) for which to render this output format:
+
+ {{< code-toggle file=hugo >}}
+ [outputs]
+ home = ['html', 'rss', 'atom']
+ section = ['html', 'rss', 'atom']
+ taxonomy = ['html', 'rss', 'atom']
+ term = ['html', 'rss', 'atom']
+ {{< /code-toggle >}}
+
+ See [configure outputs][] for more information.
+
+Step 4
- [html/template]: https://pkg.go.dev/html/template
++: Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order][] to find the correct template path:
+
+ ```text
+ layouts/list.atom.atom
+ ```
+
+ We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template][].
+
+## List output formats
+
+To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within a `head` element, as shown below:
+
+```go-html-template
+{{ range .AlternativeOutputFormats }}
+ <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
+{{ end }}
+```
+
+## Link to output formats
+
+By default, a `Page` object's [`Permalink`][] and [`RelPermalink`][] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used.
+
+For example, in `page.json.json`, you'll see:
+
+```go-html-template
+{{ .RelPermalink }} → /that-page/
+{{ with .OutputFormats.Get "json" }}
+ {{ .RelPermalink }} → /that-page/index.json
+{{ end }}
+```
+
+To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`][] setting to `true` for that format.
+
+With `permalinkable` set to true for `json` in the same `page.json.json` template:
+
+```go-html-template
+{{ .RelPermalink }} → /that-page/index.json
+{{ with .OutputFormats.Get "html" }}
+ {{ .RelPermalink }} → /that-page/
+{{ end }}
+```
+
+## Template lookup order
+
+Each output format requires a template conforming to the [template lookup order][].
+
+For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name:
+
+```text
+[page kind].[output format].[suffix]
+```
+
+For example, for section pages:
+
+Output format|Template path
+:--|:--
+`html`|`layouts/section.html.html`
+`json`|`layouts/section.json.json`
+`rss`|`layouts/section.rss.xml`
+
+[`AlternativeOutputFormats`]: /methods/page/alternativeoutputformats/
+[`baseURL`]: /configuration/all/#baseurl
+[`OutputFormats`]: /methods/page/outputformats/
+[`Permalink`]: /methods/page/permalink/
+[`permalinkable`]: #permalinkable
+[`publishDir`]: /configuration/all/#publishdir
+[`RelPermalink`]: /methods/page/relpermalink/
+[`uglyURLs`]: /configuration/ugly-urls/
+[alias redirects]: /content-management/urls/#aliases
+[configure media types]: /configuration/media-types/
+[configure outputs]: /configuration/outputs/
+[configured media types]: /configuration/media-types/
+[default media types]: /configuration/media-types/
+[embedded RSS template]: <{{% eturl rss %}}>
- [text/template]: https://pkg.go.dev/text/template
++[`html/template`]: https://pkg.go.dev/html/template
+[template lookup order]: /templates/lookup-order/
++[`text/template`]: https://pkg.go.dev/text/template
--- /dev/null
- With multilingual sites you can define the pagination behavior for each language:
+---
+title: Configure pagination
+linkTitle: Pagination
+description: Configure pagination.
+categories: []
+keywords: []
+---
+
+This is the default configuration:
+
+{{< code-toggle config=pagination />}}
+
+disableAliases
+: (`bool`) Whether to disable alias generation for the first pager. Default is `false`.
+
+pagerSize
+: (`int`) The number of pages per pager. Default is `10`.
+
+path
+: (`string`) The segment of each pager URL indicating that the target page is a pager. Default is `page`.
+
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
++With multilingual projects you can define the pagination behavior for each language:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+contentDir = 'content/en'
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
++direction = 'ltr'
++label = 'English'
++locale = 'en-US'
+weight = 1
+[languages.en.pagination]
+disableAliases = true
+pagerSize = 10
+path = 'page'
+[languages.de]
+contentDir = 'content/de'
++direction = 'ltr'
++label = 'Deutsch'
++locale = 'de-DE'
+weight = 2
+[languages.de.pagination]
+disableAliases = true
+pagerSize = 20
+path = 'blatt'
+{{< /code-toggle >}}
--- /dev/null
- languageCode = 'en-US'
+---
+title: Configure params
+linkTitle: Params
+description: Create custom site parameters.
+categories: []
+keywords: []
+---
+
+Use the `params` key for custom parameters:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
++locale = 'en-US'
+title = 'Project Documentation'
- ## Multilingual sites
+[params]
+subtitle = 'Reference, Tutorials, and Explanations'
+[params.contact]
+email = 'info@example.org'
+phone = '+1 206-555-1212'
+{{< /code-toggle >}}
+
+Access the custom parameters from your templates using the [`Params`] method on a `Site` object:
+
+[`Params`]: /methods/site/params/
+
+```go-html-template
+{{ .Site.Params.subtitle }} → Reference, Tutorials, and Explanations
+{{ .Site.Params.contact.email }} → info@example.org
+```
+
+Key names should use camelCase or snake_case. While TOML, YAML, and JSON allow kebab-case keys, they are not valid [identifiers](g) and cannot be used when [chaining](g) identifiers.
+
+For example, you can do either of these:
+
+```go-html-template
+{{ .Site.params.camelCase.foo }}
+{{ .Site.params.snake_case.foo }}
+```
+
+But you cannot do this:
+
+```go-html-template
+{{ .Site.params.kebab-case.foo }}
+```
+
- For multilingual sites, create a `params` key under each language:
++## Multilingual projects
+
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
++For multilingual projects, create a `params` key under each language:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+defaultContentLanguage = 'en'
+
+[languages.de]
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
++direction = 'ltr'
++label = 'Deutsch'
++locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.de.params]
+subtitle = 'Referenz, Tutorials und Erklärungen'
+
+[languages.de.params.contact]
+email = 'info@de.example.org'
+phone = '+49 30 1234567'
+
+[languages.en]
++direction = 'ltr'
++label = 'English'
++locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+
+[languages.en.params]
+subtitle = 'Reference, Tutorials, and Explanations'
+
+[languages.en.params.contact]
+email = 'info@example.org'
+phone = '+1 206-555-1212'
+{{< /code-toggle >}}
+
+## Namespacing
+
+To prevent naming conflicts, module and theme developers should namespace any custom parameters specific to their module or theme.
+
+{{< code-toggle file=hugo >}}
+[params.modules.myModule.colors]
+background = '#efefef'
+font = '#222222'
+{{< /code-toggle >}}
+
+To access the module/theme settings:
+
+```go-html-template
+{{ $cfg := .Site.Params.module.mymodule }}
+
+{{ $cfg.colors.background }} → #efefef
+{{ $cfg.colors.font }} → #222222
+```
--- /dev/null
- "/" = "/:year/:month/:slug/"
+---
+title: Configure permalinks
+linkTitle: Permalinks
+description: Configure permalinks.
+categories: []
+keywords: []
+---
+
+This is the default configuration:
+
+{{< code-toggle config=permalinks />}}
+
+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.
+
+## Monolingual example
+
+With this content structure:
+
+```text
+content/
+├── posts/
+│ ├── bash-in-slow-motion.md
+│ └── tls-in-a-nutshell.md
+├── tutorials/
+│ ├── git-for-beginners.md
+│ └── javascript-bundling-with-hugo.md
+└── _index.md
+```
+
+Render tutorials under "training", and render the posts under "articles" with a date-base hierarchy:
+
+{{< code-toggle file=hugo >}}
+[permalinks.page]
+posts = '/articles/:year/:month/:slug/'
+tutorials = '/training/:slug/'
+[permalinks.section]
+posts = '/articles/'
+tutorials = '/training/'
+{{< /code-toggle >}}
+
+The structure of the published site will be:
+
+```text
+public/
+├── articles/
+│ ├── 2023/
+│ │ ├── 04/
+│ │ │ └── bash-in-slow-motion/
+│ │ │ └── index.html
+│ │ └── 06/
+│ │ └── tls-in-a-nutshell/
+│ │ └── index.html
+│ └── index.html
+├── training/
+│ ├── git-for-beginners/
+│ │ └── index.html
+│ ├── javascript-bundling-with-hugo/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+To create a date-based hierarchy for regular pages in the content root:
+
+{{< code-toggle file=hugo >}}
+[permalinks.page]
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
++'/' = '/:year/:month/:slug/'
+{{< /code-toggle >}}
+
+Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL:
+
+{{< code-toggle file=hugo >}}
+[permalinks.term]
+'tags' = '/:slug/'
+{{< /code-toggle >}}
+
+## Multilingual example
+
+Use the `permalinks` configuration as a component of your localization strategy.
+
+With this content structure:
+
+```text
+content/
+├── en/
+│ ├── books/
+│ │ ├── les-miserables.md
+│ │ └── the-hunchback-of-notre-dame.md
+│ └── _index.md
+└── es/
+ ├── books/
+ │ ├── les-miserables.md
+ │ └── the-hunchback-of-notre-dame.md
+ └── _index.md
+```
+
+And this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+
+[languages.en]
+contentDir = 'content/en'
- books = "/books/:slug/"
++direction = 'ltr'
++label = 'English'
++locale = 'en-US'
+weight = 1
+
+[languages.en.permalinks.page]
- books = "/books/"
++books = '/books/:slug/'
+
+[languages.en.permalinks.section]
- languageCode = 'es-ES'
- languageDirection = 'ltr'
- languageName = 'Español'
++books = '/books/'
+
+[languages.es]
+contentDir = 'content/es'
- books = "/libros/:slug/"
++direction = 'ltr'
++label = 'Español'
++locale = 'es-ES'
+weight = 2
+
+[languages.es.permalinks.page]
- books = "/libros/"
++books = '/libros/:slug/'
+
+[languages.es.permalinks.section]
++books = '/libros/'
+{{< /code-toggle >}}
+
+The structure of the published site will be:
+
+```text
+public/
+├── en/
+│ ├── books/
+│ │ ├── les-miserables/
+│ │ │ └── index.html
+│ │ ├── the-hunchback-of-notre-dame/
+│ │ │ └── index.html
+│ │ └── index.html
+│ └── index.html
+├── es/
+│ ├── libros/
+│ │ ├── les-miserables/
+│ │ │ └── index.html
+│ │ ├── the-hunchback-of-notre-dame/
+│ │ │ └── index.html
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+## Tokens
+
+Use these tokens when defining a URL pattern.
+
+{{% include "/_common/permalink-tokens.md" %}}
+
+[`url`]: /content-management/front-matter/#url
--- /dev/null
- Hugo provides [embedded templates](g) to simplify site and content creation. Some of these templates interact with external services. For example, the `youtube` shortcode connects with YouTube's servers to embed videos on your site.
+---
+title: Configure privacy
+linkTitle: Privacy
+description: Configure your site to help comply with regional privacy regulations.
+categories: []
+keywords: []
+aliases: [/about/privacy/]
+---
+
+## Responsibility
+
+Site authors are responsible for ensuring compliance with regional privacy regulations, including but not limited to:
+
+- GDPR (General Data Protection Regulation): Applies to individuals within the European Union and the European Economic Area.
+- CCPA (California Consumer Privacy Act): Applies to California residents.
+- CPRA (California Privacy Rights Act): Expands upon the CCPA with stronger consumer privacy protections.
+- Virginia Consumer Data Protection Act (CDPA): Applies to businesses that collect, process, or sell the personal data of Virginia residents.
+
+Hugo's privacy settings can assist in compliance efforts.
+
+## Embedded templates
+
++Hugo provides [embedded templates](g) to simplify project and content creation. Some of these templates interact with external services. For example, the `youtube` shortcode connects with YouTube's servers to embed videos.
+
+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.
+
+These are the default privacy settings for Hugo's embedded templates:
+
+{{< code-toggle config=privacy />}}
+
+See each template's documentation for a description of its privacy settings:
+
+- [Disqus partial](/templates/embedded/#privacy-disqus)
+- [Google Analytics partial](/templates/embedded/#privacy-google-analytics)
+- [Instagram shortcode](/shortcodes/instagram/#privacy)
+- [Vimeo shortcode](/shortcodes/vimeo/#privacy)
+- [X shortcode](/shortcodes/x/#privacy)
+- [YouTube shortcode](/shortcodes/youtube/#privacy)
--- /dev/null
- lang = "n*"
+---
+title: Configure segments
+linkTitle: Segments
+description: Configure your site for segmented rendering.
+categories: []
+keywords: []
+---
+
+> [!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:
+
+- Faster builds: Process large sites more efficiently.
+- Rapid development: Render only a subset of your site for quicker iteration.
+- Scheduled rebuilds: Rebuild specific sections at different frequencies (e.g., home page and news hourly, full site weekly).
+- Targeted output: Generate specific output formats (like JSON for search indexes).
+
+## Segment definition
+
+Each segment is defined by include and exclude filters:
+
+- Filters: Each segment has zero or more exclude filters and zero or more include filters.
+- Matchers: Each filter contains one or more field [glob pattern](g) matchers.
+- Logic: Matchers within a filter use AND logic. Filters within a section (include or exclude) use OR logic.
+
+## Filter fields
+
+Available fields for filtering:
+
+kind
+: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
+
+sites
+: {{< new-in 0.153.0 />}}
+: (`map`) A map to define [sites matrix](g).
+
+output
+: (`string`) A [glob pattern](g) matching the [output format](g) of the page. For example: `{html,json}`.
+
+path
+: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
+
+## Example
+
+Place broad filters, such as those for language or output format, in the excludes section. For example:
+
+{{< code-toggle file=hugo >}}
+[segments.segment1]
+ [[segments.segment1.excludes]]
- lang = "en"
- output = "rss"
++ lang = 'n*'
+ [[segments.segment1.excludes]]
- kind = "{home,term,taxonomy}"
++ lang = 'en'
++ output = 'rss'
+ [[segments.segment1.includes]]
- path = "{/docs,/docs/**}"
++ kind = '{home,term,taxonomy}'
+ [[segments.segment1.includes]]
++ path = '{/docs,/docs/**}'
+{{< /code-toggle >}}
+
+## Rendering segments
+
+Render specific segments using the [`renderSegments`] configuration or the `--renderSegments` flag:
+
+```sh
+hugo build --renderSegments segment1
+```
+
+You can configure multiple segments and use a comma-separated list with `--renderSegments` to render them all.
+
+```sh
+hugo build --renderSegments segment1,segment2
+```
+
+[`renderSegments`]: /configuration/all/#rendersegments
--- /dev/null
- for = "/**"
+---
+title: Configure server
+linkTitle: Server
+description: Configure the development server.
+categories: []
+keywords: []
+---
+
+These settings are exclusive to Hugo's development server, so a dedicated [configuration directory] for development, where the server is configured accordingly, is the recommended approach.
+
+[configuration directory]: /configuration/introduction/#configuration-directory
+
+```text
+project/
+└── config/
+ ├── _default/
+ │ └── hugo.toml
+ └── development/
+ └── server.toml
+```
+
+## Default settings
+
+The development server defaults to redirecting to `/404.html` for any requests to URLs that don't exist. See the [404 errors](#404-errors) section below for details.
+
+{{< code-toggle config=server />}}
+
+force
+: (`bool`) Whether to force a redirect even if there is existing content in the path.
+
+from
+: (`string`) A [glob pattern](g) matching the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns.
+
+fromHeaders
+: {{< new-in 0.144.0 />}}
+: (`map[string][string]`) Headers to match for the redirect. This maps the HTTP header name to a [glob pattern](g) with values to match. If the map is empty, the redirect will always be triggered.
+
+fromRe
+: {{< new-in 0.144.0 />}}
+: (`string`) A [regular expression](g) used to match the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns. Capture groups from the regular expression are accessible in the `to` field as `$1`, `$2`, and so on.
+
+status
+: (`string`) The HTTP status code to use for the redirect. A status code of 200 will trigger a URL rewrite.
+
+to
+: (`string`) The URL to forward the request to.
+
+## Headers
+
+Include headers in every server response to facilitate testing, particularly for features like [Content Security Policies].
+
+[Content Security Policies]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+
+{{< code-toggle file=config/development/server >}}
+[[headers]]
- X-Frame-Options = "DENY"
- X-XSS-Protection = "1; mode=block"
- X-Content-Type-Options = "nosniff"
- Referrer-Policy = "strict-origin-when-cross-origin"
- Content-Security-Policy = "script-src localhost:1313"
++for = '/**'
+
+[headers.values]
- from = "/myspa/**"
- to = "/myspa/"
++X-Frame-Options = 'DENY'
++X-XSS-Protection = '1; mode=block'
++X-Content-Type-Options = 'nosniff'
++Referrer-Policy = 'strict-origin-when-cross-origin'
++Content-Security-Policy = 'script-src localhost:1313'
+{{< /code-toggle >}}
+
+## Redirects
+
+You can define simple redirect rules.
+
+{{< code-toggle file=config/development/server >}}
+[[redirects]]
- from = "/**"
- to = "/404.html"
++from = '/myspa/**'
++to = '/myspa/'
+status = 200
+force = false
+{{< /code-toggle >}}
+
+The `200` status code in this example triggers a URL rewrite, which is typically the desired behavior for [single-page applications].
+
+[single-page applications]: https://en.wikipedia.org/wiki/Single-page_application
+
+## 404 errors
+
+The development server defaults to redirecting to /404.html for any requests to URLs that don't exist.
+
+{{< code-toggle config=server />}}
+
+If you've already defined other redirects, you must explicitly add the 404 redirect.
+
+{{< code-toggle file=config/development/server >}}
+[[redirects]]
+force = false
- For multilingual sites, ensure the default language 404 redirect is defined last:
++from = '/**'
++to = '/404.html'
+status = 404
+{{< /code-toggle >}}
+
++For multilingual projects, ensure the default language 404 redirect is defined last:
+
+{{< code-toggle file=config/development/server >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = false
+[[redirects]]
+from = '/fr/**'
+to = '/fr/404.html'
+status = 404
+
+[[redirects]] # Default language must be last.
+from = '/**'
+to = '/404.html'
+status = 404
+{{< /code-toggle >}}
+
+When the default language is served from a subdirectory:
+
+{{< code-toggle file=config/development/server >}}
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+[[redirects]]
+from = '/fr/**'
+to = '/fr/404.html'
+status = 404
+
+[[redirects]] # Default language must be last.
+from = '/**'
+to = '/en/404.html'
+status = 404
+{{< /code-toggle >}}
--- /dev/null
- ## Multilingual sites
+---
+title: Content adapters
+description: Create content adapters to dynamically add content when building your project.
+categories: []
+keywords: []
+---
+
+## Overview
+
+A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
+
+Unlike templates that reside in the `layouts` directory, content adapters reside in the `content` directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path](g) will be relative to the content adapter.
+
+```text
+content/
+├── articles/
+│ ├── _index.md
+│ ├── article-1.md
+│ └── article-2.md
+├── books/
+│ ├── _content.gotmpl <-- content adapter
+│ └── _index.md
+└── films/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+```
+
+Each content adapter is named `_content.gotmpl` and uses the same [syntax] as templates in the `layouts` directory. You can use any of the [template functions] within a content adapter, as well as the methods described below.
+
+## Methods
+
+Use these methods within a content adapter.
+
+### AddPage
+
+Adds a page to the site.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+```
+
+### AddResource
+
+Adds a page resource to the site.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ with resources.Get "images/a.jpg" }}
+ {{ $content := dict
+ "mediaType" .MediaType.Type
+ "value" .
+ }}
+ {{ $resource := dict
+ "content" $content
+ "path" "the-hunchback-of-notre-dame/cover.jpg"
+ }}
+ {{ $.AddResource $resource }}
+{{ end }}
+```
+
+Then retrieve the new page resource with something like:
+
+```go-html-template {file="layouts/page.html"}
+{{ with .Resources.Get "cover.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+### Site
+
+Returns the `Site` to which the pages will be added.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ .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".
+
+### Store
+
+Returns a persistent "scratch pad" to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/).
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ .Store.Set "key" "value" }}
+{{ .Store.Get "key" }}
+```
+
+### EnableAllLanguages
+
+By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to all languages while maintaining the current role and version.
+
+For more fine-grained control, define a `sites.matrix` in front matter or in a content mount.
+
+```go-html-template {file="content/books/_content.gotmpl"}
+{{ .EnableAllLanguages }}
+{{ $content := dict
+ "mediaType" "text/markdown"
+ "value" "The _Hunchback of Notre Dame_ was written by Victor Hugo."
+}}
+{{ $page := dict
+ "content" $content
+ "kind" "page"
+ "path" "the-hunchback-of-notre-dame"
+ "title" "The Hunchback of Notre Dame"
+}}
+{{ .AddPage $page }}
+```
+
+### EnableAllDimensions
+
+By default, Hugo executes the content adapter only once for the first matching site in the [sites matrix](g). Use this method to expand execution to every possible combination of language, version, and role.
+
+For more fine-grained control, define a `sites.matrix` in front matter or in a content mount.
+
+{{< new-in v0.153.0 />}}
+
+## Page map
+
+Set any [front matter field] in the map passed to the [`AddPage`](#addpage) method, excluding `markup`. Instead of setting the `markup` field, specify the `content.mediaType` as described below.
+
+This table describes the fields most commonly passed to the `AddPage` method.
+
+Key|Description|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|
+`content.value`|The content value as a string.|
+`dates.date`|The page creation date as a `time.Time` value.|
+`dates.expiryDate`|The page expiry date as a `time.Time` value.|
+`dates.lastmod`|The page last modification date as a `time.Time` value.|
+`dates.publishDate`|The page publication date as a `time.Time` value.|
+`params`|A map of page parameters.|
+`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`.
+
+## Resource map
+
+Construct the map passed to the [`AddResource`](#addresource) method using the fields below.
+
+Key|Description|Required
+:--|:--|:-:
+`content.mediaType`|The content [media type].|:heavy_check_mark:
+`content.value`|The content value as a string or resource.|:heavy_check_mark:
+`name`|The resource name.|
+`params`|A map of resource parameters.|
+`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]
+> When `content.value` is a string, Hugo generates a new resource with a publication path relative to the page. However, if `content.value` is already a resource, Hugo directly uses its value and publishes it relative to the site root. This latter method is more efficient.
+>
+> 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
+
+Create pages from remote data, where each page represents a book review.
+
+Step 1
+: Create the content structure.
+
+ ```text
+ content/
+ └── books/
+ ├── _content.gotmpl <-- content adapter
+ └── _index.md
+ ```
+
+Step 2
+: Inspect the remote data to determine how to map key-value pairs to front matter fields.\
+ <https://gohugo.io/shared/examples/data/books.json>
+
+Step 3
+: Create the content adapter.
+
+ ```go-html-template {file="content/books/_content.gotmpl" copy=true}
+ {{/* Get remote data. */}}
+ {{ $data := dict }}
+ {{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
+ {{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
+ {{ end }}
+
+ {{/* Add pages and page resources. */}}
+ {{ range $data }}
+
+ {{/* Add page. */}}
+ {{ $content := dict "mediaType" "text/markdown" "value" .summary }}
+ {{ $dates := dict "date" (time.AsTime .date) }}
+ {{ $params := dict "author" .author "isbn" .isbn "rating" .rating "tags" .tags }}
+ {{ $page := dict
+ "content" $content
+ "dates" $dates
+ "kind" "page"
+ "params" $params
+ "path" .title
+ "title" .title
+ }}
+ {{ $.AddPage $page }}
+
+ {{/* Add page resource. */}}
+ {{ $item := . }}
+ {{ with $url := $item.cover }}
+ {{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "Unable to get remote resource %s: %s" $url . }}
+ {{ else with .Value }}
+ {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
+ {{ $params := dict "alt" $item.title }}
+ {{ $resource := dict
+ "content" $content
+ "params" $params
+ "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
+ }}
+ {{ $.AddResource $resource }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
+ {{ end }}
+ {{ end }}
+ {{ end }}
+
+ {{ end }}
+ ```
+
+Step 4
+: Create a _page_ template to render each book review.
+
+ ```go-html-template {file="layouts/books/page.html" copy=true}
+ {{ define "main" }}
+ <h1>{{ .Title }}</h1>
+
+ {{ with .Resources.GetMatch "cover.*" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ .Params.alt }}">
+ {{ end }}
+
+ <p>Author: {{ .Params.author }}</p>
+
+ <p>
+ ISBN: {{ .Params.isbn }}<br>
+ Rating: {{ .Params.rating }}<br>
+ Review date: {{ .Date | time.Format ":date_long" }}
+ </p>
+
+ {{ with .GetTerms "tags" }}
+ <p>Tags:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+ {{ end }}
+
+ {{ .Content }}
+ {{ end }}
+ ```
+
- With multilingual sites you can:
++## Multilingual projects
+
++With multilingual projects you can:
+
+1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above.
+1. Create content adapters unique to each language. See the examples below.
+
+### Translations by file name
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+weight = 1
+
+[languages.de]
+weight = 2
+{{< /code-toggle >}}
+
+Include a language designator in the content adapter's file name.
+
+```text
+content/
+└── books/
+ ├── _content.de.gotmpl
+ ├── _content.en.gotmpl
+ ├── _index.de.md
+ └── _index.en.md
+```
+
+### Translations by content directory
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[languages.en]
+contentDir = 'content/en'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
+weight = 2
+{{< /code-toggle >}}
+
+Create a single content adapter in each directory:
+
+```text
+content/
+├── de/
+│ └── books/
+│ ├── _content.gotmpl
+│ └── _index.md
+└── en/
+ └── books/
+ ├── _content.gotmpl
+ └── _index.md
+```
+
+## Page collisions
+
+Two or more pages collide when they have the same publication path. Due to concurrency, the content of the published page is indeterminate. Consider this example:
+
+```text
+content/
+└── books/
+ ├── _content.gotmpl <-- content adapter
+ ├── _index.md
+ └── the-hunchback-of-notre-dame.md
+```
+
+If the content adapter also creates `books/the-hunchback-of-notre-dame`, the content of the published page is indeterminate. You can not define the processing order.
+
+To detect page collisions, use the `--printPathWarnings` flag when building your project.
+
+[content formats]: /content-management/formats/#classification
+[front matter field]: /content-management/front-matter/#fields
+[media type]: https://en.wikipedia.org/wiki/Media_type
+[syntax]: /templates/introduction/
+[template functions]: /functions/
--- /dev/null
- > For multilingual sites, defining cascade values in your project 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/).
+---
+title: Front matter
+description: Use front matter to add metadata to your content.
+categories: []
+keywords: []
+aliases: [/content/front-matter/]
+---
+
+## Overview
+
+The front matter at the top of each content file is metadata that:
+
+- Describes the content
+- Augments the content
+- Establishes relationships with other content
+- Controls the published structure of your site
+- Determines template selection
+
+Provide front matter using a serialization format, one of [JSON], [TOML], or [YAML]. Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content.
+
+See examples of front matter delimiters by toggling between the serialization formats below.
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+Front matter fields may be [boolean](g), [integer](g), [float](g), [string](g), [arrays](g), or [maps](g). Note that the TOML format also supports unquoted date/time values.
+
+## Fields
+
+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.
+
+[parameters]: #parameters
+
+aliases
+: (`[]string`) An array of one or more [page-relative](g) or [site-relative](g) paths that should redirect to the current page. Hugo resolves these to [server-relative](g) URLs during the build process. Access these values from a template using the [`Aliases`] method on a `Page` object. See the [aliases] section for details.
+
+build
+: (`map`) A map of [build options].
+
+cascade
+: (`map`) A map (or a slice of maps) of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See the [cascade] section for details.
+
+date
+: (`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Date`] method on a `Page` object.
+
+description
+: (`string`) Conceptually different than the page `summary`, the description is typically rendered within a `meta` element within the `head` element of the published HTML file. Access this value from a template using the [`Description`] method on a `Page` object.
+
+draft
+: (`bool`) Whether to disable rendering unless you pass the `--buildDrafts` flag to the `hugo` command. Access this value from a template using the [`Draft`] method on a `Page` object.
+
+expiryDate
+: (`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`ExpiryDate`] method on a `Page` object.
+
+headless
+: (`bool`) Applicable to [leaf bundles], whether to set the `render` and `list` [build options] to `never`, creating a headless bundle of [page resources].
+
+isCJKLanguage
+: (`bool`) Whether the content language is in the [CJK](g) family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object.
+
+keywords
+: (`[]string`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object.
+
+lastmod
+: (`string`) The date that the page was last modified. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Lastmod`] method on a `Page` object.
+
+layout
+: (`string`) Provide a template name to [target a specific template], overriding the default [template lookup order]. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the [`Layout`] method on a `Page` object.
+
+linkTitle
+: (`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`] method on a `Page` object.
+
+markup
+: (`string`) An identifier corresponding to one of the supported [content formats]. If not provided, Hugo determines the content renderer based on the file extension.
+
+menus
+: (`string`, `[]string`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
+
+modified
+: Alias to [lastmod](#lastmod).
+
+outputs
+: (`[]string`) The [output formats] to render. See [configure outputs] for more information.
+
+params
+: (`map`) A map of custom [page parameters].
+
+pubdate
+: Alias to [publishDate](#publishdate).
+
+publishDate
+: (`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`PublishDate`] method on a `Page` object.
+
+published
+: Alias to [publishDate](#publishdate).
+
+resources
+: (`map array`) An array of maps to provide metadata for [page resources].
+
+sitemap
+: (`map`) A map of sitemap options. See the [sitemap templates] page for details. Access these values from a template using the [`Sitemap`] method on a `Page` object.
+
+sites
+: {{< new-in 0.153.0 />}}
+: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the page.
+
+ <!-- markdownlint-disable MD049 -->
+
+ {{< code-toggle file=content/_index.md fm=true >}}
+ title = 'Home'
+ [sites.matrix]
+ languages = ["en","fr"]
+ versions = ["v1.2.*","v2.*.*"]
+ roles = ["**"]
+ [sites.complements]
+ versions = ["v3.*.*"]
+ {{< /code-toggle >}}
+
+ <!-- markdownlint-enable MD049 -->
+
+slug
+: (`string`) Overrides the last segment of the URL path. Not applicable to `home`, `section`, `taxonomy`, or `term` pages. See the [URL management] page for details. Access this value from a template using the [`Slug`] method on a `Page` object.
+
+summary
+: (`string`) Conceptually different than the page `description`, the summary either summarizes the content or serves as a teaser to encourage readers to visit the page. Access this value from a template using the [`Summary`] method on a `Page` object.
+
+title
+: (`string`) The page title. Access this value from a template using the [`Title`] method on a `Page` object.
+
+translationKey
+: (`string`) An arbitrary value used to relate two or more translations of the same page, useful when the translated pages do not share a common path. Access this value from a template using the [`TranslationKey`] method on a `Page` object.
+
+type
+: (`string`) The [content type](g), overriding the value derived from the top-level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object.
+
+unpublishdate
+: Alias to [expirydate](#expirydate).
+
+url
+: (`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details.
+
+weight
+: (`int`) The page [weight](g), used to order the page within a [page collection](g). Access this value from a template using the [`Weight`] method on a `Page` object.
+
+## Parameters
+
+Specify custom page parameters under the `params` key in front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object.
+
+Hugo provides [embedded templates] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
+
+Parameter|Data type|Used by these embedded templates
+:--|:--|:--
+`audio`|`[]string`|[`opengraph.html`]
+`images`|`[]string`|[`opengraph.html`], [`schema.html`], [`twitter_cards.html`]
+`videos`|`[]string`|[`opengraph.html`]
+
+The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
+
+## Taxonomies
+
+Classify content by adding taxonomy terms to front matter. For example, with this project configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+tag = 'tags'
+genre = 'genres'
+{{< /code-toggle >}}
+
+Add taxonomy terms as shown below:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+tags = ['red','blue']
+genres = ['mystery','romance']
+[params]
+author = 'John Smith'
+{{< /code-toggle >}}
+
+You can add taxonomy terms to the front matter of any these [page kinds](g):
+
+- `home`
+- `page`
+- `section`
+- `taxonomy`
+- `term`
+
+Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object. For example:
+
+```go-html-template {file="layouts/page.html"}
+{{ with .GetTerms "tags" }}
+ <p>Tags</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+[`GetTerms`]: /methods/page/getterms/
+
+## Cascade
+
+A [node](g) can cascade front matter values to its descendants. However, this cascading will be prevented if the descendant already defines the field, or if a closer ancestor node has already cascaded a value for that same field.
+
+For example, to cascade a "color" parameter from the home page to all its descendants:
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title = 'Home'
+[cascade.params]
+color = 'red'
+{{< /code-toggle >}}
+
+{{< new-in 0.153.0 />}}
+From Hugo 0.153.0, you can also set the [sites](#sites) front matter as cascade front matter values, which means that you can e.g. apply one or more languages to the `target` pages.
+
+### Target
+
+<!-- TODO
+We deprecated the `_target` front matter key in favor of `target` in v0.156.0 on 2026-02-17. Remove footnote #1 on or after 2027-05-17 (15 months after deprecation).
+-->
+
+The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter from the home page only to pages within the "articles" section, including the "articles" section page itself:
+
+[^1]: The `_target` alias for `target` is deprecated and will be removed in a future release.
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title = 'Home'
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '{/articles,/articles/**}'
+[cascade.target.sites.matrix]
+languages = ['en','fr']
+{{< /code-toggle >}}
+
+Use any combination of these keywords to target pages and/or environments:
+
+environment
+: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`.
+
+kind
+: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
+
+path
+: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
+
+sites
+: {{< new-in 0.153.0 />}}
+: (`map`) A map to define [sites matrix](g) for the target, as in: Which sites should receive the cascaded values.
+
+### Array
+
+Define an array of cascade parameters to apply different values to different targets. For example:
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title = 'Home'
+[[cascade]]
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '{/books/**}'
+kind = 'page'
+[[cascade]]
+[cascade.params]
+color = 'blue'
+[cascade.target]
+path = '{/films/**}'
+kind = 'page'
+{{< /code-toggle >}}
+
+> [!note]
- > 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.
++> For multilingual projects, defining cascade values in your project 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 project, you must create a corresponding home, section, taxonomy, or term page for every language.
+
+## Emacs Org Mode
+
+If your [content format] is [Emacs Org Mode], you may provide front matter using Org Mode keywords. For example:
+
+```text {file="content/example.org"}
+#+TITLE: Example
+#+DATE: 2024-02-02T04:14:54-08:00
+#+DRAFT: false
+#+AUTHOR: John Smith
+#+GENRES: mystery
+#+GENRES: romance
+#+TAGS: red
+#+TAGS: blue
+#+WEIGHT: 10
+```
+
+Note that you can also specify array elements on a single line:
+
+```text {file="content/example.org"}
+#+TAGS[]: red blue
+```
+
+[content format]: /content-management/formats/
+[emacs org mode]: https://orgmode.org/
+
+## Dates
+
+When populating a date field, whether a [custom page parameter](#parameters) or one of the four predefined fields ([`date`](#date), [`expiryDate`](#expirydate), [`lastmod`](#lastmod), [`publishDate`](#publishdate)), use one of these parsable formats:
+
+{{% include "/_common/parsable-date-time-strings.md" %}}
+
+To override the default time zone, set the [`timeZone`](/configuration/all/#timezone) in your project configuration. The order of precedence for determining the time zone is:
+
+1. The time zone offset in the date/time string
+1. The time zone specified in your project configuration
+1. The `Etc/UTC` time zone
+
+[`aliases`]: /methods/page/aliases/
+[`date`]: /methods/page/date/
+[`description`]: /methods/page/description/
+[`draft`]: /methods/page/draft/
+[`expirydate`]: /methods/page/expirydate/
+[`fuzzywordcount`]: /methods/page/wordcount/
+[`keywords`]: /methods/page/keywords/
+[`lastmod`]: /methods/page/date/
+[`layout`]: /methods/page/layout/
+[`linktitle`]: /methods/page/linktitle/
+[`opengraph.html`]: <{{% eturl opengraph %}}>
+[`Param`]: /methods/page/param/
+[`Params`]: /methods/page/params/
+[`publishdate`]: /methods/page/publishdate/
+[`readingtime`]: /methods/page/readingtime/
+[`schema.html`]: <{{% eturl schema %}}>
+[`sitemap`]: /methods/page/sitemap/
+[`slug`]: /methods/page/slug/
+[`Summary`]: /methods/page/summary/
+[`title`]: /methods/page/title/
+[`translationkey`]: /methods/page/translationkey/
+[`twitter_cards.html`]: <{{% eturl twitter_cards %}}>
+[`type`]: /methods/page/type/
+[`weight`]: /methods/page/weight/
+[`wordcount`]: /methods/page/wordcount/
+[aliases]: /content-management/urls/#aliases
+[build options]: /content-management/build-options/
+[cascade]: #cascade-1
+[configure outputs]: /configuration/outputs/#outputs-per-page
+[content formats]: /content-management/formats/#classification
+[embedded templates]: /templates/embedded/
+[json]: https://www.json.org/
+[leaf bundles]: /content-management/page-bundles/#leaf-bundles
+[menus]: /content-management/menus/#define-in-front-matter
+[output formats]: /configuration/output-formats/
+[page parameters]: #parameters
+[page resources]: /content-management/page-resources/#metadata
+[sitemap templates]: /templates/sitemap/
+[target a specific template]: /templates/lookup-order/#target-a-template
+[template lookup order]: /templates/lookup-order/
+[toml]: https://toml.io/
+[URL management]: /content-management/urls/#slug
+[yaml]: https://yaml.org/
--- /dev/null
- description: Process, transform, and analyze images.
+---
+title: Image processing
- Hugo provides methods to transform and analyze images during the build process. The results are cached to ensure subsequent builds remain fast.
++description: Transform images to change their size, shape, and appearance.
+categories: []
+keywords: []
+---
+
- > Metadata is not preserved during image transformation. Use the `Exif` or `Meta` methods with the _original_ image resource to extract metadata from JPEG, PNG, TIFF, and WebP images.
-
- Each method serves a specific transformation or metadata requirement:
++Hugo provides methods to transform and analyze images during the build process. While Hugo can manage any image format as a resource, only [processable images](g) can be transformed using the methods below. The results are cached to ensure subsequent builds remain fast.
++
++> [!note]
++> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Resources
+
+To process an image you must capture the file as a page resource, a global resource, or a remote resource.
+
+### Page
+
+{{% glossary-term "page resource" %}}
+
+```text
+content/
+└── posts/
+ └── post-1/ <-- page bundle
+ ├── index.md
+ └── sunset.jpg <-- page resource
+```
+
+To capture an image as a page resource:
+
+```go-html-template
+{{ $image := .Resources.Get "sunset.jpg" }}
+```
+
+### Global
+
+{{% glossary-term "global resource" %}}
+
+```text
+assets/
+└── images/
+ └── sunset.jpg <-- global resource
+```
+
+To capture an image as a global resource:
+
+```go-html-template
+{{ $image := resources.Get "images/sunset.jpg" }}
+```
+
+### Remote
+
+{{% glossary-term "remote resource" %}}
+
+To capture an image as a remote resource:
+
+```go-html-template
+{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
+```
+
+## Rendering
+
+Once you have captured an image as a resource, render it in your templates using the [`Permalink`][], [`RelPermalink`][], [`Width`][], and [`Height`][] methods.
+
+Example 1: Throw an error if the resource is not found.
+
+```go-html-template
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+<img src="{{ $image.RelPermalink }}" width="{{ $image.Width }}" height="{{ $image.Height }}">
+```
+
+Example 2: Skip image rendering if the resource is not found.
+
+```go-html-template
+{{ $image := .Resources.GetMatch "sunset.jpg" }}
+{{ with $image }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
+```
+
+Example 3: A more concise way to skip image rendering if the resource is not found.
+
+```go-html-template
+{{ with .Resources.GetMatch "sunset.jpg" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ end }}
+```
+
+Example 4: Skip rendering if there's problem accessing a remote resource.
+
+```go-html-template
+{{ $url := "https://gohugo.io/img/hugo-logo.png" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
++{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
++
+## Processing
+
+To transform an image, apply a processing method to the image resource. Hugo generates the processed image on demand, caches the result, and returns a new resource object.
+
+```go-html-template
+{{ with .Resources.Get "sunset.jpg" }}
+ {{ with .Resize "400x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ end }}
+{{ end }}
+```
+
+> [!note]
- Method|Description
- :--|:--
- [`Colors`]|Returns a slice of the most dominant colors using a simple histogram method.
- [`Crop`]|Returns a new image resource cropped according to the given processing specification.
- [`Exif`]|Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif metadata.
- [`Fill`]|Returns a new image resource cropped and resized according to the given processing specification.
- [`Filter`]|Applies one or more image filters to the given image resource.
- [`Fit`]|Returns a new image resource downscaled to fit according to the given processing specification.
- [`Meta`]|Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif, IPTC, and XMP metadata.
- [`Process`]|Returns a new image resource processed according to the given processing specification.
- [`Resize`]|Returns a new image resource resized according to the given processing specification.
- {class="!mt-0"}
++> Metadata is not preserved during image transformation. Use the [`Meta`][] method with the original image resource to extract metadata from supported formats.
+
- Select a method from the table above for syntax and usage examples.
++Select a method from the table below for syntax and usage examples, depending on your specific transformation or metadata requirements:
+
- [`Colors`]: /methods/resource/colors/
- [`Crop`]: /methods/resource/crop/
- [`Exif`]: /methods/resource/exif/
- [`Fill`]: /methods/resource/fill/
- [`Filter`]: /methods/resource/filter/
- [`Fit`]: /methods/resource/fit/
++{{% render-table-of-pages-in-section
++ path=/methods/resource
++ filter=methods_resource_image_processing
++ filterType=include
++ headingColumn1=Method
++ headingColumn2=Description
++%}}{class="!mt-0"}
+
+## Performance
+
+### Caching
+
+Hugo processes images on demand and returns a new resource object. To ensure subsequent builds remain fast, Hugo caches the results in the directory specified in the [file cache][] section of your project configuration.
+
+If you host your site with Netlify, include the following in your project configuration to persist the image cache between builds:
+
+```toml
+[caches]
+ [caches.images]
+ dir = ':cacheDir/images'
+```
+
+### Garbage collection
+
+If you change image processing methods, or rename/remove images, the cache will eventually contain unused files. To remove them and reclaim disk space, run Hugo's garbage collection:
+
+```text
+hugo build --gc
+```
+
+### Resource usage
+
+The time and memory required to process an image increase with the image's dimensions. For example, a `4032x2268` image requires significantly more memory and processing time than a `1920x1080` image.
+
+If your source images are much larger than the maximum size you intend to publish, consider scaling them down before the build to optimize performance.
+
+## Configuration
+
+See [configure imaging](/configuration/imaging).
+
- [`Process`]: /methods/resource/process/
+[`Height`]: /methods/resource/height/
+[`Meta`]: /methods/resource/meta/
+[`Permalink`]: /methods/resource/permalink/
- [`Resize`]: /methods/resource/resize/
+[`RelPermalink`]: /methods/resource/relpermalink/
+[`Width`]: /methods/resource/width/
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[file cache]: /configuration/caches/
--- /dev/null
- sectionPagesMenu = "main"
+---
+title: Menus
+description: Create menus by defining entries, localizing each entry, and rendering the resulting data structure.
+categories: []
+keywords: []
+aliases: [/extras/menus/]
+---
+
+## Overview
+
+To create a menu for your site:
+
+1. Define the menu entries
+1. [Localize](multilingual/#menus) each entry
+1. Render the menu with a [template]
+
+Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
+
+There are three ways to define menu entries:
+
+1. Automatically
+1. In front matter
+1. In your project 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.
+
+## Define automatically
+
+To automatically define a menu entry for each top-level [section](g) of your site, enable the section pages menu in your project configuration.
+
+{{< code-toggle file=hugo >}}
++sectionPagesMenu = 'main'
+{{< /code-toggle >}}
+
+This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
+
+## Define in front matter
+
+To add a page to the "main" menu:
+
+{{< code-toggle file=content/about.md fm=true >}}
+title = 'About'
+menus = 'main'
+{{< /code-toggle >}}
+
+Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
+
+To add a page to the "main" and "footer" menus:
+
+{{< code-toggle file=content/contact.md fm=true >}}
+title = 'Contact'
+menus = ['main','footer']
+{{< /code-toggle >}}
+
+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`.
+
+### Properties
+
+Use these properties when defining menu entries in front matter:
+
+{{% include "/_common/menu-entry-properties.md" %}}
+
+### Example
+
+This front matter menu entry demonstrates some of the available properties:
+
+<!-- markdownlint-disable MD033 -->
+{{< code-toggle file=content/products/software.md fm=true >}}
+title = 'Software'
+[menus.main]
+parent = 'Products'
+weight = 20
+pre = '<i class="fa-solid fa-code"></i>'
+[menus.main.params]
+class = 'center'
+{{< /code-toggle >}}
+<!-- markdownlint-enable MD033 -->
+
+Access the entry with `site.Menus.main` in your templates. See [menu templates] for details.
+
+## Define in project configuration
+
+See [configure menus](/configuration/menus/).
+
+## Localize
+
+Hugo provides two methods to localize your menu entries. See [multilingual].
+
+## Render
+
+See [menu templates].
+
+[menu templates]: /templates/menu/
+[multilingual]: /content-management/multilingual/#menus
+[template]: /templates/menu/
--- /dev/null
- languages:
- en:
- weight: 10
- languageName: "English"
- contentDir: "content/english"
- fr:
- weight: 20
- languageName: "Français"
- contentDir: "content/french"
+---
+title: Multilingual mode
+linkTitle: Multilingual
+description: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations.
+categories: []
+keywords: []
+aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/]
+---
+
+## Configuration
+
+See [configure languages](/configuration/languages/).
+
+## Translate your content
+
+There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations.
+
+### Translation by file name
+
+Considering the following example:
+
+1. `/content/about.en.md`
+1. `/content/about.fr.md`
+
+The first file is assigned the English language and is linked to the second.
+The second file is assigned the French language and is linked to the first.
+
+Their language is assigned according to the language code added as a suffix to the file name.
+
+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.
+
+### Translation by content directory
+
+This system uses different content directories for each of the languages. Each language's `content` directory is set using the `contentDir` parameter.
+
+{{< code-toggle file=hugo >}}
- ## Reference translated content
-
- To create a list of links to translated content, use a template similar to the following:
-
- ```go-html-template {file="layouts/_partials/i18nlist.html"}
- {{ if .IsTranslated }}
- <h4>{{ i18n "translations" }}</h4>
- <ul>
- {{ range .Translations }}
- <li>
- <a href="{{ .RelPermalink }}">{{ .Language.Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
- </li>
- {{ end }}
- </ul>
- {{ end }}
- ```
-
- The above can be put in a _partial_ template then included in any template. It will not print anything if there are no translations for a given page.
-
- The above also uses the [`i18n` function][i18func] described in the next section.
-
- ### List all available languages
-
- `.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator:
-
- ```go-html-template {file="layouts/_partials/allLanguages.html"}
- <ul>
- {{ range $.Site.Home.AllTranslations }}
- <li><a href="{{ .RelPermalink }}">{{ .Language.LanguageName }}</a></li>
- {{ end }}
- </ul>
- ```
-
++[languages.en]
++contentDir = 'content/english'
++label = "English"
++weight = 10
++
++[languages.fr]
++contentDir = 'content/french'
++label = "Français"
++weight = 20
+{{< /code-toggle >}}
+
+The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap.
+
+Considering the following example in conjunction with the configuration above:
+
+1. `/content/english/about.md`
+1. `/content/french/about.md`
+
+The first file is assigned the English language and is linked to the second.
+The second file is assigned the French language and is linked to the first.
+
+Their language is assigned according to the `content` directory they are placed in.
+
+By having the same path and basename (relative to their language `content` directory), the content pieces are linked together as translated pages.
+
+### Bypassing default linking
+
+Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location.
+
+Considering the following example:
+
+1. `/content/about-us.en.md`
+1. `/content/om.nn.md`
+1. `/content/presentation/a-propos.fr.md`
+
+{{< code-toggle file=hugo >}}
+translationKey: "about"
+{{< /code-toggle >}}
+
+By setting the `translationKey` front matter parameter to `about` in all three pages, they will be linked as translated pages.
+
+### Localizing permalinks
+
+Because paths and file names are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory).
+
+To localize URLs:
+
+- For a regular page, set either [`slug`] or [`url`] in front matter
+- For a section page, set [`url`] in front matter
+
+For example, a French translation can have its own localized slug.
+
+{{< code-toggle file=content/about.fr.md fm=true >}}
+title: A Propos
+slug: "a-propos"
+{{< /code-toggle >}}
+
+At render, Hugo will build both `/about/` and `/fr/a-propos/` without affecting the translation link.
+
+### Page bundles
+
+To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (Markdown files, HTML files etc.).
+
+Therefore, from within a template, the page will have access to the files from all linked pages' bundles.
+
+If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows:
+
+- 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`).
+
- The following localization examples assume your site's primary language is English, with translations to French and German.
+## Translation of strings
+
+See the [`lang.Translate`] template function.
+
+## Localization
+
- languageName = 'English'
++The following localization examples assume your project's primary language is English, with translations to French and German.
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages]
+[languages.en]
+contentDir = 'content/en'
- languageName = 'Français'
++label = 'English'
+weight = 1
+[languages.fr]
+contentDir = 'content/fr'
- languageName = 'Deutsch'
++label = 'Français'
+weight = 2
+[languages.de]
+contentDir = 'content/de'
- languageCode = 'de-DE'
- languageName = 'Deutsch'
++label = 'Deutsch'
+weight = 3
+
+{{< /code-toggle >}}
+
+### Dates
+
+With this front matter:
+
+{{< code-toggle file=hugo >}}
+date = 2021-11-03T12:34:56+01:00
+{{< /code-toggle >}}
+
+And this template code:
+
+```go-html-template
+{{ .Date | time.Format ":date_full" }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|Wednesday, November 3, 2021
+Français|mercredi 3 novembre 2021
+Deutsch|Mittwoch, 3. November 2021
+
+See [`time.Format`] for details.
+
+### Currency
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatCurrency 2 "USD" }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|$512.50
+Français|512,50 $US
+Deutsch|512,50 $
+
+See [lang.FormatCurrency] and [lang.FormatAccounting] for details.
+
+### Numbers
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatNumber 2 }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|512.50
+Français|512,50
+Deutsch|512,50
+
+See [lang.FormatNumber] and [lang.FormatNumberCustom] for details.
+
+### Percentages
+
+With this template code:
+
+```go-html-template
+{{ 512.5032 | lang.FormatPercent 2 }}
+```
+
+The rendered page displays:
+
+Language|Value
+:--|:--
+English|512.50%
+Français|512,50 %
+Deutsch|512,50 %
+
+See [lang.FormatPercent] for details.
+
+## Menus
+
+Localization of menu entries depends on how you define them:
+
+- When you define menu entries [automatically] using the section pages menu, you must use translation tables to localize each entry.
+- When you define menu entries in [front matter], they are already localized based on the front matter itself. If the front matter values are insufficient, use translation tables to localize each entry.
+- When you define menu entries in your [project configuration], you must create language-specific menu entries under each language key. If the names of the menu entries are insufficient, use translation tables to localize each entry.
+
+### Create language-specific menu entries
+
+#### Method 1 -- Use a single configuration file
+
+For a simple menu with a small number of entries, use a single configuration file. For example:
+
+{{< code-toggle file=hugo >}}
+[languages.de]
- languageCode = 'en-US'
- languageName = 'English'
++label = 'Deutsch'
++locale = 'de-DE'
+weight = 1
+
+[[languages.de.menus.main]]
+name = 'Produkte'
+pageRef = '/products'
+weight = 10
+
+[[languages.de.menus.main]]
+name = 'Leistungen'
+pageRef = '/services'
+weight = 20
+
+[languages.en]
- [i18func]: /functions/lang/translate/
++label = 'English'
++locale = 'en-US'
+weight = 2
+
+[[languages.en.menus.main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+
+[[languages.en.menus.main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+#### Method 2 -- Use a configuration directory
+
+With a more complex menu structure, create a [configuration directory] and split the menu entries into multiple files, one file per language. For example:
+
+```text
+config/
+└── _default/
+ ├── menus.de.toml
+ ├── menus.en.toml
+ └── hugo.toml
+```
+
+{{< code-toggle file=config/_default/menus.de >}}
+[[main]]
+name = 'Produkte'
+pageRef = '/products'
+weight = 10
+[[main]]
+name = 'Leistungen'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+{{< code-toggle file=config/_default/menus.en >}}
+[[main]]
+name = 'Products'
+pageRef = '/products'
+weight = 10
+[[main]]
+name = 'Services'
+pageRef = '/services'
+weight = 20
+{{< /code-toggle >}}
+
+### Use translation tables
+
+When rendering the text that appears in menu each entry, the [example menu template] does this:
+
+```go-html-template
+{{ or (T .Identifier) .Name | safeHTML }}
+```
+
+It queries the translation table for the current language using the menu entry's `identifier` and returns the translated string. If the translation table does not exist, or if the `identifier` key is not present in the translation table, it falls back to `name`.
+
+The `identifier` depends on how you define menu entries:
+
+- If you define the menu entry [automatically] using the section pages menu, the `identifier` is the page's `.Section`.
+- If you define the menu entry in your [project configuration] or in [front matter], set the `identifier` property to the desired value.
+
+For example, if you define menu entries in project configuration:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+ identifier = 'products'
+ name = 'Products'
+ pageRef = '/products'
+ weight = 10
+[[menus.main]]
+ identifier = 'services'
+ name = 'Services'
+ pageRef = '/services'
+ weight = 20
+{{< / code-toggle >}}
+
+Create corresponding entries in the translation tables:
+
+{{< code-toggle file=i18n/de >}}
+products = 'Produkte'
+services = 'Leistungen'
+{{< / code-toggle >}}
+
+## 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.
+
+For merging of content from other languages (i.e. missing content translations), see [lang.Merge].
+
+To track down missing translation strings, run Hugo with the `--printI18nWarnings` flag:
+
+```sh
+hugo build --printI18nWarnings | grep i18n
+i18n|MISSING_TRANSLATION|en|wordCount
+```
+
+## Multilingual themes support
+
+To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria:
+
+- Come from the built-in `.Permalink` or `.RelPermalink`
+- Be constructed with the [`relLangURL`] or [`absLangURL`] template function, or be prefixed with `{{ .LanguagePrefix }}`
+
+If there is more than one language defined, the `LanguagePrefix` method will return `/en` (or whatever the current language is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites).
+
+## Generate multilingual content with `hugo new content`
+
+If you organize content with translations in the same directory:
+
+```sh
+hugo new content post/test.en.md
+hugo new content post/test.de.md
+```
+
+If you organize content with translations in different directories:
+
+```sh
+hugo new content content/en/post/test.md
+hugo new content content/de/post/test.md
+```
+
+[`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/
+[configuration directory]: /configuration/introduction/#configuration-directory
+[example menu template]: /templates/menu/#example
+[front matter]: /content-management/menus/#define-in-front-matter
- [lang.FormatNumber]: /functions/lang/formatnumber/
+[lang.FormatAccounting]: /functions/lang/formataccounting/
+[lang.FormatCurrency]: /functions/lang/formatcurrency/
+[lang.FormatNumberCustom]: /functions/lang/formatnumbercustom/
++[lang.FormatNumber]: /functions/lang/formatnumber/
+[lang.FormatPercent]: /functions/lang/formatpercent/
+[lang.Merge]: /functions/lang/merge/
+[project configuration]: /content-management/menus/#define-in-project-configuration
--- /dev/null
- src = "*specs.pdf"
- title = "Specification #:counter"
+---
+title: Page resources
+description: Use page resources to logically associate assets with a page.
+categories: []
+keywords: []
+---
+
+Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
+`_index.md` files at their root. Page resources are only available to the
+page with which they are bundled.
+
+In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`.
+
+```text
+content
+└── post
+ ├── first-post
+ │ ├── images
+ │ │ ├── a.jpg
+ │ │ ├── b.jpg
+ │ │ └── c.jpg
+ │ ├── index.md (root of page bundle)
+ │ ├── latest.html
+ │ ├── manual.json
+ │ ├── notice.md
+ │ ├── office.mp3
+ │ ├── pocket.mp4
+ │ ├── rating.pdf
+ │ └── safety.txt
+ └── second-post
+ └── index.md (root of page bundle)
+```
+
+## Examples
+
+Use any of these methods on a `Page` object to capture page resources:
+
+- [`Resources.ByType`]
+- [`Resources.Get`]
+- [`Resources.GetMatch`]
+- [`Resources.Match`]
+
+ Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action.
+
+The following examples assume this content structure:
+
+```text
+content/
+└── example/
+ ├── data/
+ │ └── books.json <-- page resource
+ ├── images/
+ │ ├── a.jpg <-- page resource
+ │ └── b.jpg <-- page resource
+ ├── snippets/
+ │ └── text.md <-- page resource
+ └── index.md
+```
+
+Render a single image, and throw an error if the file does not exist:
+
+```go-html-template
+{{ $path := "images/a.jpg" }}
+{{ with .Resources.Get $path }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ else }}
+ {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
+```
+
+Render all images, resized to 300 px wide:
+
+```go-html-template
+{{ range .Resources.ByType "image" }}
+ {{ with .Resize "300x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+Render the markdown snippet:
+
+```go-html-template
+{{ with .Resources.Get "snippets/text.md" }}
+ {{ .Content }}
+{{ end }}
+```
+
+List the titles in the data file, and throw an error if the file does not exist.
+
+```go-html-template
+{{ $path := "data/books.json" }}
+{{ with .Resources.Get $path }}
+ {{ with . | transform.Unmarshal }}
+ <p>Books:</p>
+ <ul>
+ {{ range . }}
+ <li>{{ .title }}</li>
+ {{ end }}
+ </ul>
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
+```
+
+## Metadata
+
+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.
+
+name
+: (`string`) Sets the value returned in `Name`.
+
+> [!note]
+> The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
+
+title
+: (`string`) Sets the value returned in `Title`
+
+params
+: (`map`) A map of custom key-value pairs.
+
+### Resources metadata example
+
+<!-- markdownlint-disable MD007 MD032 -->
+{{< code-toggle file=content/example.md fm=true >}}
+title: Application
+date: 2018-01-25
+resources:
+ - src: images/sunset.jpg
+ name: header
+ - src: documents/photo_specs.pdf
+ title: Photo Specifications
+ params:
+ icon: photo
+ - src: documents/guide.pdf
+ title: Instruction Guide
+ - src: documents/checklist.pdf
+ title: Document Checklist
+ - src: documents/payment.docx
+ title: Proof of Payment
+ - src: "**.pdf"
+ name: pdf-file-:counter
+ params:
+ icon: pdf
+ - src: "**.docx"
+ params:
+ icon: word
+{{</ code-toggle >}}
+<!-- markdownlint-enable MD007 MD032 -->
+
+From the example above:
+
+- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`.
+- `documents/photo_specs.pdf` will get the `photo` icon.
+- `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`.
+- Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon.
+- 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.
+
+### The `:counter` placeholder in `name` and `title`
+
+The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`.
+
+The counter starts at 1 the first time they are used in either `name` or `title`.
+
+For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
+
+{{< code-toggle file=content/inspections/engine/index.md fm=true >}}
+title = 'Engine inspections'
+[[resources]]
- src = "**.pdf"
- name = "pdf-file-:counter"
++ src = '*specs.pdf'
++ title = 'Specification #:counter'
+[[resources]]
- By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site.
++ src = '**.pdf'
++ name = 'pdf-file-:counter'
+{{</ code-toggle >}}
+
+the `Name` and `Title` will be assigned to the resource files as follows:
+
+| Resource file | `Name` | `Title` |
+|-------------------|-------------------|-----------------------|
+| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` |
+| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` |
+| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
+| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |
+
+## Multilingual
+
- languageCode = 'de-DE'
- languageName = 'Deutsch'
++By default, with a multilingual single-host project, Hugo does not duplicate shared page during the build.
+
+> [!note]
+> This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle.
+
+Consider this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+
+[languages.de]
- languageCode = 'en-US'
- languageName = 'English'
++label = 'Deutsch'
++locale = 'de-DE'
+weight = 1
+
+[languages.en]
- > 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. If custom link or image render hooks are defined by your project, modules, or themes, these will be used instead.
++label = 'English'
++locale = 'en-US'
+weight = 2
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+└── my-bundle/
+ ├── a.jpg <-- shared page resource
+ ├── b.jpg <-- shared page resource
+ ├── c.de.jpg
+ ├── c.en.jpg
+ ├── index.de.md
+ └── index.en.md
+```
+
+With v0.122.0 and earlier, Hugo duplicated the shared page resources, creating copies for each language:
+
+```text
+public/
+├── de/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource
+│ │ ├── b.jpg <-- shared page resource
+│ │ ├── c.de.jpg
+│ │ └── index.html
+│ └── index.html
+├── en/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource (duplicate)
+│ │ ├── b.jpg <-- shared page resource (duplicate)
+│ │ ├── c.en.jpg
+│ │ └── index.html
+│ └── index.html
+└── index.html
+
+```
+
+With v0.123.0 and later, Hugo places the shared resources in the page bundle for the default content language:
+
+```text
+public/
+├── de/
+│ ├── my-bundle/
+│ │ ├── a.jpg <-- shared page resource
+│ │ ├── b.jpg <-- shared page resource
+│ │ ├── c.de.jpg
+│ │ └── index.html
+│ └── index.html
+├── en/
+│ ├── my-bundle/
+│ │ ├── c.en.jpg
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.
+
+> [!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.
+>
++> In its default configuration, Hugo automatically uses the [embedded link render hook] and the [embedded image render hook] for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link or image render hooks are defined by your project, modules, or themes, these will be used instead.
+>
+> You can also configure Hugo to `always` use the embedded link or image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
+
+Although duplicating shared page resources is inefficient, you can enable this feature in your project configuration if desired:
+
+{{< code-toggle file=hugo >}}
+[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.GetMatch`]: /methods/page/resources#getmatch
+[`Resources.Match`]: /methods/page/resources#match
+[content formats]: /content-management/formats/
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded image render hook]: /render-hooks/images/#embedded
+[embedded link render hook]: /render-hooks/links/#embedded
--- /dev/null
- name = "fragmentrefs"
- type = "fragments"
+---
+title: Related content
+description: List related content in "See Also" sections.
+categories: []
+keywords: []
+aliases: [/content/related/,/related/,/content-management/related/]
+---
+
+Hugo uses a set of factors to identify a page's related content based on front matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [related content configuration](/configuration/related-content/).
+
+## List related content
+
+To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your template:
+
+```go-html-template {file="layouts/_partials/related.html" copy=true}
+{{ with site.RegularPages.Related . | first 5 }}
+ <p>Related content:</p>
+ <ul>
+ {{ range . }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+The `Related` method takes one argument which may be a `Page` or an options map. The options map has these options:
+
+indices
+: (`slice`) The indices to search within.
+
+document
+: (`page`) The page for which to find related content. Required when specifying an options map.
+
+namedSlices
+: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function.
+
+fragments
+: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment](g) identifiers of the documents.
+
+A fictional example using all of the above options:
+
+```go-html-template
+{{ $page := . }}
+{{ $opts := dict
+ "indices" (slice "tags" "keywords")
+ "document" $page
+ "namedSlices" (slice (keyVals "tags" "hugo" "rocks") (keyVals "date" $page.Date))
+ "fragments" (slice "heading-1" "heading-2")
+}}
+```
+
+> [!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
+
+Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration:
+
+{{< code-toggle file=hugo >}}
+[related]
+threshold = 20
+includeNewer = true
+toLower = false
+[[related.indices]]
++name = 'fragmentrefs'
++type = 'fragments'
+applyFilter = true
+weight = 80
+{{< /code-toggle >}}
+
+- The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level.
+- If `applyFilter` is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing:
+
+```go-html-template
+{{ $related := .Site.RegularPages.Related . | first 5 }}
+{{ with $related }}
+ <h2>See Also</h2>
+ <ul>
+ {{ range $i, $p := . }}
+ <li>
+ <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
+ {{ with .HeadingsFiltered }}
+ <ul>
+ {{ range . }}
+ {{ $link := printf "%s#%s" $p.RelPermalink .ID | safeURL }}
+ <li>
+ <a href="{{ $link }}">{{ .Title }}</a>
+ </li>
+ {{ end }}
+ </ul>
+ {{ end }}
+ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+## Configuration
+
+See [configure related content](/configuration/related-content/).
+
+[`keyVals`]: /functions/collections/keyvals/
--- /dev/null
- {{% list-pages-in-section path=/shortcodes %}}
+---
+title: Shortcodes
+description: Use embedded, custom, or inline shortcodes to insert elements such as videos, images, and social media embeds into your content.
+categories: []
+keywords: []
+aliases: [/extras/shortcodes/]
+---
+
+## Introduction
+
+{{% glossary-term shortcode %}}
+
+There are three types of shortcodes: embedded, custom, and inline.
+
+## Embedded
+
+Hugo's embedded shortcodes are pre-defined templates within the application. Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
- Learn more about creating shortcodes in the [shortcode templates] section.
++{{% render-list-of-pages-in-section path=/shortcodes %}}
+
+## Custom
+
+Create custom shortcodes to simplify and standardize content creation. For example, the following _shortcode_ template generates an audio player using a [global resource](g):
+
+```go-html-template {file="layouts/_shortcodes/audio.html"}
+{{ with resources.Get (.Get "src") }}
+ <audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
+{{ end }}
+```
+
+Then call the shortcode from within markup:
+
+```text {file="content/example.md"}
+{{</* audio src=/audio/test.mp3 */>}}
+```
+
- The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string].
++Learn more about creating shortcodes in the [shortcode templates][] section.
+
+## Inline
+
+An inline shortcode is a _shortcode_ template defined within content.
+
+Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.
+
+To conform with this security model, creating _shortcode_ templates within content is disabled by default. If you trust your content authors, you can enable this functionality in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[security]
+enableInlineShortcodes = true
+{{< /code-toggle >}}
+
+For more information see [configure security](/configuration/security).
+
- Inline shortcodes process their inner content within the same context as regular _shortcode_ templates, allowing you to use any available [shortcode method].
++The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string][].
+
+```text {file="content/example.md"}
+Today is
+{{</* date.inline ":date_medium" */>}}
+ {{- now | time.Format (.Get 0) -}}
+{{</* /date.inline */>}}.
+
+Today is {{</* date.inline ":date_full" /*/>}}.
+```
+
+In the example above, the inline shortcode is executed twice: once upon definition and again when subsequently called. Hugo renders this to:
+
+```html
+<p>Today is Jan 30, 2025.</p>
+<p>Today is Thursday, January 30, 2025</p>
+```
+
- Learn more about creating shortcodes in the [shortcode templates] section.
++Inline shortcodes process their inner content within the same context as regular _shortcode_ templates, allowing you to use any available [shortcode method][].
+
+> [!note]
+> You cannot [nest](#nesting) inline shortcodes.
+
- Some shortcodes expect content between opening and closing tags. For example, the embedded [`details`] shortcode requires an opening and closing tag:
++Learn more about creating shortcodes in the [shortcode templates][] section.
+
+## Calling
+
+Shortcode calls involve three syntactical elements: tags, arguments, and notation.
+
+### Tags
+
- Some shortcodes do not accept content. For example, the embedded [`instagram`] shortcode requires a single _positional_ argument:
++Some shortcodes expect content between opening and closing tags. For example, the embedded [`details`][] shortcode requires an opening and closing tag:
+
+```text
+{{</* details summary="See the details" */>}}
+This is a **bold** word.
+{{</* /details */>}}
+```
+
- Some shortcodes optionally accept content. For example, you can call the embedded [`qr`] shortcode with content:
++Some shortcodes do not accept content. For example, the embedded [`instagram`][] shortcode requires a single _positional_ argument:
+
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
+
- 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.
++Some shortcodes optionally accept content. For example, you can call the embedded [`qr`][] shortcode with content:
+
+```text
+{{</* qr */>}}
+https://gohugo.io
+{{</* /qr */>}}
+```
+
+Or use the self-closing syntax with a trailing slash to pass the text as an argument:
+
+```text
+{{</* qr text=https://gohugo.io /*/>}}
+```
+
+Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+### Arguments
+
+Shortcode arguments can be either _named_ or _positional_.
+
- 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.
++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.
+
+```text
+{{</* figure src=/images/kitten.jpg */>}}
+```
+
+Positional arguments, on the other hand, are determined by their position. The embedded `instagram` shortcode, for example, expects the first argument to be the Instagram post ID.
+
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
+
+Shortcode arguments are space-delimited, and arguments with internal spaces must be quoted.
+
+```text
+{{</* figure src=/images/kitten.jpg alt="A white kitten" */>}}
+```
+
+Shortcodes accept [scalar](g) arguments, one of [string](g), [integer](g), [floating point](g), or [boolean](g).
+
+```text
+{{</* my-shortcode name="John Smith" age=24 married=false */>}}
+```
+
+You can optionally use multiple lines when providing several arguments to a shortcode for better readability:
+
+```text
+{{</* figure
+ src=/images/kitten.jpg
+ alt="A white kitten"
+ caption="This is a white kitten"
+ loading=lazy
+*/>}}
+```
+
+Use a [raw string literal](g) if you need to pass a multiline string:
+
+```text
+{{</* myshortcode `This is some <b>HTML</b>,
+and a new line with a "quoted string".` */>}}
+```
+
+Shortcodes can accept named arguments, positional arguments, or both, but you must use either named or positional arguments exclusively within a single shortcode call; mixing them is not allowed.
+
+Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+### Notation
+
+Shortcodes can be called using two different notations, distinguished by their tag delimiters.
+
+Notation|Example
+:--|:--
+Markdown|`{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}`
+Standard|`{{</* foo */>}} ## Section 2 {{</* /foo */>}}`
+
+#### Markdown notation
+
++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.
+
+#### 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.
+
+By way of example, with this _shortcode_ template:
+
+```go-html-template {file="layouts/_shortcodes/foo.html"}
+{{ .Inner }}
+```
+
+And this markdown:
+
+```text {file="content/example.md"}
+{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}
+
+{{</* foo */>}} ## Section 2 {{</* /foo */>}}
+```
+
+Hugo renders this HTML:
+
+```html
+<h2 id="heading">Section 1</h2>
+
+## Section 2
+```
+
+In the above, "Section 1" will be included when invoking the `TableOfContents` method, while "Section 2" will not.
+
+> [!note]
+> The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments.
+
+## Nesting
+
+Shortcodes (excluding [inline](#inline) shortcodes) can be nested, creating parent-child relationships. For example, a gallery shortcode might contain several image shortcodes:
+
+```text {file="content/example.md"}
+{{</* gallery class="content-gallery" */>}}
+ {{</* image src="/images/a.jpg" */>}}
+ {{</* image src="/images/b.jpg" */>}}
+ {{</* image src="/images/c.jpg" */>}}
+{{</* /gallery */>}}
+```
+
+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/
--- /dev/null
- title = "John Smith"
- affiliation = "University of Chicago"
+---
+title: Taxonomies
+description: Hugo includes support for user-defined taxonomies.
+categories: []
+keywords: []
+aliases: [/taxonomies/overview/,/taxonomies/usage/,/indexes/overview/,/doc/indexes/,/extras/indexes]
+---
+
+## What is a taxonomy?
+
+Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications of logical relationships between content.
+
+### Definitions
+
+Taxonomy
+: A categorization that can be used to classify content
+
+Term
+: A key within the taxonomy
+
+Value
+: A piece of content assigned to a term
+
+## Example taxonomy: movie website
+
+Let's assume you are making a website about movies. You may want to include the following taxonomies:
+
+- Actors
+- Directors
+- Studios
+- Genre
+- Year
+- Awards
+
+Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the front matter of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.
+
+### Movie taxonomy organization
+
+To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:
+
+```txt
+Actor <- Taxonomy
+ Bruce Willis <- Term
+ The Sixth Sense <- Value
+ Unbreakable <- Value
+ Moonrise Kingdom <- Value
+ Samuel L. Jackson <- Term
+ Unbreakable <- Value
+ The Avengers <- Value
+ xXx <- Value
+```
+
+From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:
+
+```txt
+Unbreakable <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Samuel L. Jackson <- Term
+ Director <- Taxonomy
+ M. Night Shyamalan <- Term
+ ...
+Moonrise Kingdom <- Value
+ Actors <- Taxonomy
+ Bruce Willis <- Term
+ Bill Murray <- Term
+ Director <- Taxonomy
+ Wes Anderson <- Term
+ ...
+```
+
+### Default destinations
+
+When taxonomies are used Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your configuration and used in your content front matter will create the following pages:
+
+- A single page at `example.com/categories/` that lists all the terms within the taxonomy
+- Individual taxonomy list pages (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's front matter
+
+## Configuration
+
+See [configure taxonomies](/configuration/taxonomies/).
+
+## Assign terms to content
+
+To assign one or more terms to a page, create a front matter field using the plural name of the taxonomy, then add terms to the corresponding array. For example:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title = 'Example'
+tags = ['Tag A','Tag B']
+categories = ['Category A','Category B']
+{{< /code-toggle >}}
+
+## Taxonomic weight
+
+{{% glossary-term "taxonomic weight" %}}
+
+Assign a taxonomic weight using a front matter key named `[taxonomy_name]_weight`.
+
+{{< code-toggle file="content/courses/organic-chemistry.md" fm=true >}}
+title = 'Organic Chemistry'
+weight = 10
+tags_weight = 1000
+tags = ['chemistry','science']
+{{</ code-toggle >}}
+
+With the front matter above, the "Organic Chemistry" page will float towards the top of the list on section and home pages, and it will sink towards the bottom of the list on the "chemistry" and "science" term pages.
+
+## Metadata
+
+Display metadata about each term by creating a corresponding branch bundle in the `content` directory.
+
+For example, create an "authors" taxonomy:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+author = 'authors'
+{{< /code-toggle >}}
+
+Then create content with one [branch bundle](g) for each term:
+
+```text
+content/
+└── authors/
+ ├── jsmith/
+ │ ├── _index.md
+ │ └── portrait.jpg
+ └── rjones/
+ ├── _index.md
+ └── portrait.jpg
+```
+
+Then add front matter to each term page:
+
+{{< code-toggle file=content/authors/jsmith/_index.md fm=true >}}
++title = 'John Smith'
++affiliation = 'University of Chicago'
+{{< /code-toggle >}}
+
+Then create a _taxonomy_ template specific to the "authors" taxonomy:
+
+```go-html-template {file="layouts/authors/taxonomy.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Data.Terms.Alphabetical }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2>
+ <p>Affiliation: {{ .Page.Params.Affiliation }}</p>
+ {{ with .Page.Resources.Get "portrait.jpg" }}
+ {{ with .Fill "100x100" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="portrait">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+In the example above we list each author including their affiliation and portrait.
+
+Or create a _term_ template specific to the "authors" taxonomy:
+
+```go-html-template {file="layouts/authors/term.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ <p>Affiliation: {{ .Params.affiliation }}</p>
+ {{ with .Resources.Get "portrait.jpg" }}
+ {{ with .Fill "100x100" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="portrait">
+ {{ end }}
+ {{ end }}
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+In the example above we display the author including their affiliation and portrait, then a list of associated content.
--- /dev/null
- 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.
+---
+title: URL management
+description: Control the structure and appearance of URLs through front matter entries and settings in your project configuration.
+categories: []
+keywords: []
+aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/]
+---
+
+## Overview
+
+By default, when Hugo renders a page, the resulting URL matches the file path within the `content` directory. For example:
+
+```text
+content/posts/post-1.md → https://example.org/posts/post-1/
+```
+
+You can change the structure and appearance of URLs with front matter values and project configuration options.
+
+## Front matter
+
+### `slug`
+
+Set the `slug` in front matter to override the last segment of the path. This front matter field is not applicable to `home`, `section`, `taxonomy`, or `term` pages.
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Post'
+slug = 'my-first-post'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/posts/my-first-post/
+```
+
+### `url`
+
+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.
+
+If you set both `slug` and `url` in front matter, the `url` value takes precedence.
+
+#### Include a colon
+
+{{< new-in 0.136.0 />}}
+
+If you need to include a colon in the `url` front matter field, escape it with backslash characters. Use one backslash if you wrap the string within single quotes, or use two backslashes if you wrap the string within double quotes. With YAML front matter, use a single backslash if you omit quotation marks.
+
+For example, with this front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title: Example
+url: "my\\:example"
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/my:example/
+```
+
+As described above, this will fail on Windows because the colon (`:`) is a reserved character.
+
+#### File extensions
+
+With this front matter:
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Article'
+url = 'articles/my-first-article'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/articles/my-first-article/
+```
+
+If you include a file extension:
+
+{{< code-toggle file=content/posts/post-1.md fm=true >}}
+title = 'My First Article'
+url = 'articles/my-first-article.html'
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/articles/my-first-article.html
+```
+
+#### Leading slashes
+
- title ="Bar"
++With monolingual projects, `url` values with or without a leading slash are relative to the [`baseURL`][]. With multilingual projects, `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.
+
+Site type|Front matter `url`|Resulting URL
+:--|:--|:--
+monolingual|`/about`|`https://example.org/about/`
+monolingual|`about`|`https://example.org/about/`
+multilingual|`/about`|`https://example.org/about/`
+multilingual|`about`|`https://example.org/de/about/`
+
+#### Permalinks tokens in front matter
+
+{{< new-in 0.131.0 />}}
+
+You can also use tokens when setting the `url` value. This is typically used in `cascade` sections:
+
+{{< code-toggle file=content/foo/bar/_index.md fm=true >}}
- url = "/:sections[last]/:slug"
++title ='Bar'
+[[cascade]]
- <html lang="{{ site.Language.LanguageCode }}">
++ url = '/:sections[last]/:slug'
+{{< /code-toggle >}}
+
+Use any of these tokens:
+
+{{% include "/_common/permalink-tokens.md" %}}
+
+## Project configuration
+
+### Permalinks
+
+See [configure permalinks](/configuration/permalinks).
+
+### Appearance
+
+See [configure ugly URLs](/configuration/ugly-urls/).
+
+### Post-processing
+
+Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.
+
+#### Canonical URLs
+
+> [!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.
+
+```html
+<a href="/about"> → <a href="https://example.org/about/">
+<img src="/a.gif"> → <img src="https://example.org/a.gif">
+```
+
+This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, this is a legacy configuration option that will likely be removed in a future release.
+
+To enable:
+
+{{< code-toggle file=hugo >}}
+canonifyURLs = true
+{{< /code-toggle >}}
+
+#### Relative URLs
+
+> [!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.
+
+For example, when rendering `content/posts/post-1`:
+
+```html
+<a href="/about"> → <a href="../../about">
+<img src="/a.gif"> → <img src="../../a.gif">
+```
+
+This is an imperfect, brute force approach that can affect content as well as HTML attributes. As noted above, do not enable this option unless you are creating a serverless site.
+
+To enable:
+
+{{< code-toggle file=hugo >}}
+relativeURLs = true
+{{< /code-toggle >}}
+
+## Aliases
+
+Aliases allow you to redirect old URLs to new URLs. This is essential for preventing broken links and ensuring that existing bookmarks or external links continue to function when you rename or move content.
+
+### Defining aliases
+
+To add redirects to a page, list the previous paths in the [`aliases`][aliases_field] field in your front matter. Hugo resolves these to [server-relative](g) paths during the build process, accounting for the [`baseURL`][] and [content dimension](g) prefixes such as language, version, or role.
+
+{{< code-toggle file=content/examples/example-1.en.md fm=true >}}
+title = 'Example 1'
+date = 2025-02-02
+aliases = ['/old-url', 'old-name', '../old/path']
+{{< /code-toggle >}}
+
+As shown in the example above, you can use [site-relative](g) paths or [page-relative](g) paths. Page-relative paths can also include directory traversal. Using the file `content/examples/example-1.en.md` as a reference point, here is how Hugo interprets those different path types:
+
+Path type|Alias|Server-relative path
+:--|:--|:--
+site-relative|`/old-url`|`/en/old-url/`
+page-relative|`old-name`|`/en/examples/old-name/`
+page-relative|`../old/path`|`/en/old/path/`
+
+### Redirection methods
+
+There are two ways to implement aliases depending on your hosting environment and preferences: client-side redirection and server-side redirection.
+
+> [!note]
+> Alias data is only generated for [output formats](g) where both [`isHTML`][] and [`permalinkable`][] are `true`. This affects both the creation of client-side redirect files and the results returned by the [`Aliases`][aliases_method] method used in server-side redirection.
+
+#### Client-side redirection
+
+By default, Hugo uses client-side redirection, generating a small HTML file for every alias. This file contains a `meta http-equiv="refresh"` tag that instructs the browser to navigate to the new URL. This approach is portable across all hosting providers.
+
+When using this method, Hugo creates a physical directory and an `index.html` file at each alias location. For example, if a page at `content/posts/new.md` has a page-relative alias of `old-path`, a file is generated at `public/posts/old-path/index.html`.
+
+Unless you provide a custom layout, Hugo uses its [embedded alias template][] to generate the redirect files:
+
+```go-html-template
+<!DOCTYPE html>
++<html lang="{{ site.Language.Locale }}">
+ <head>
+ <title>{{ .Permalink }}</title>
+ {{ with .OutputFormats.Canonical }}<link rel="{{ .Rel }}" href="{{ .Permalink }}">{{ end }}
+ <meta charset="utf-8">
+ <meta http-equiv="refresh" content="0; url={{ .Permalink }}">
+ </head>
+</html>
+```
+
+To override this, create a file named `alias.html` in your `layouts` directory. This custom template has access to the following context:
+
+`Permalink`
+: (`string`) The absolute URL of the destination page.
+
+`Page`
+: (`page.Page`) The full `Page` object of the destination.
+
+#### Server-side redirection
+
+Alternatively, you can implement server-side redirection by using the [`Aliases`][aliases_method] method on a `Page` object to generate a single configuration file that the web server processes. This method is more efficient because the redirect happens at the HTTP header level before any page content is processed, whereas a meta refresh requires the browser to download and parse the HTML body before acting. Additionally, server-side redirection improves build and deployment times because Hugo doesn't need to write a physical directory and HTML file for every alias.
+
+To implement this, you typically create a single template to generate the necessary rules for your specific host or server. Common examples include:
+
+- A `_redirects` file for hosting services such as Cloudflare, GitLab Pages, and Netlify.
+- An `.htaccess` file for web servers such as Apache and LiteSpeed.
+
+See the [`Aliases`][aliases_method] method page for a complete example of how to iterate through pages to generate these rules.
+
+If you implement server-side redirects, you should disable the generation of individual HTML files by setting [`disableAliases`][] to `true` in your project configuration. This setting only prevents the generation of the physical HTML files; the `Aliases` method on a `Page` object remains available for use in your configuration templates.
+
+[`baseURL`]: /configuration/all/#baseurl
+[`disableAliases`]: /configuration/all/#disablealiases
+[`isHTML`]: /configuration/output-formats/#ishtml
+[`permalinkable`]: /configuration/output-formats/#permalinkable
+[aliases_field]: /content-management/front-matter/#aliases
+[aliases_method]: /methods/page/aliases/
+[embedded alias template]: <{{% eturl alias %}}>
+[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
--- /dev/null
- 1. Install [Go] version 1.24.0 or later
+---
+title: Development
+description: Contribute to the development of Hugo.
+categories: []
+keywords: []
+---
+
+## Introduction
+
+You can contribute to the Hugo project by:
+
+- Answering questions on the [forum]
+- Improving the [documentation]
+- Monitoring the [issue queue]
+- Creating or improving [themes]
+- Squashing [bugs]
+
+Please submit documentation issues and pull requests to the [documentation repository].
+
+If you have an idea for an enhancement or new feature, create a new topic on the [forum] in the "Feature" category. This will help you to:
+
+- Determine if the capability already exists
+- Measure interest
+- Refine the concept
+
+If there is sufficient interest, [create a proposal]. Do not submit a pull request until the project lead accepts the proposal.
+
+For a complete guide to contributing to Hugo, see the [Contribution Guide].
+
+## Prerequisites
+
+To build the extended or extended/deploy edition from source you must:
+
+1. Install [Git]
- CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.156.0
++1. Install [Go] version 1.25.0 or later
+1. Install a C compiler, either [GCC] or [Clang]
+1. Update your `PATH` environment variable as described in the [Go documentation]
+
+> [!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.
+
+Use this workflow to create and submit pull requests.
+
+Step 1
+: Fork the [project repository].
+
+Step 2
+: Clone your fork.
+
+Step 3
+: Create a new branch with a descriptive name that includes the corresponding issue number.
+
+ For a new feature:
+
+ ```sh
+ git checkout -b feat/implement-some-feature-99999
+ ```
+
+ For a bug fix:
+
+ ```sh
+ git checkout -b fix/fix-some-bug-99999
+ ```
+
+Step 4
+: Make changes.
+
+Step 5
+: Compile and install.
+
+ To compile and install the standard edition:
+
+ ```text
+ go install
+ ```
+
+ To compile and install the extended edition:
+
+ ```text
+ CGO_ENABLED=1 go install -tags extended
+ ```
+
+ To compile and install the extended/deploy edition:
+
+ ```text
+ CGO_ENABLED=1 go install -tags extended,withdeploy
+ ```
+
+Step 6
+: Test your changes:
+
+ ```text
+ go test ./...
+ ```
+
+Step 7
+: Commit your changes with a descriptive commit message:
+
+ - Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
+ - Begin the summary with the name of the package, followed by a colon, a space, and a brief description of the change beginning with a capital letter
+ - Use imperative present tense
+ - See the [commit message guidelines] for requirements
+ - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
+ - Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+
+ For example:
+
+ ```sh
+ git commit -m "tpl/strings: Create wrap function
+
+ The strings.Wrap function wraps a string into one or more lines,
+ splitting the string after the given number of characters, but not
+ splitting in the middle of a word.
+
+ Fixes #99998
+ Closes #99999"
+ ```
+
+Step 8
+: Push the new branch to your fork of the documentation repository.
+
+Step 9
+: Visit the [project repository] and create a pull request (PR).
+
+Step 10
+: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
+
+## 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.
+
+To build and install the latest release:
+
+```sh
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
+```
+
+To build and install a specific release:
+
+```sh
++CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.158.0
+```
+
+To build and install at the latest commit on the master branch:
+
+```sh
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@master
+```
+
+To build and install at a specific commit:
+
+```sh
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@c0d9beb
+```
+
+[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/
--- /dev/null
- title = "Long descriptive title"
- linkTitle = "Short title"
+---
+title: Documentation
+description: Help us to improve the documentation by identifying issues and suggesting changes.
+categories: []
+keywords: []
+aliases: [/contribute/docs/]
+---
+
+## Introduction
+
+We welcome corrections and improvements to the documentation. The documentation lives in a separate repository from the main project. To contribute:
+
+- For corrections and improvements to existing documentation, submit issues and pull requests to the [documentation repository].
+- For documentation of new features, include the documentation changes in your pull request to the [project repository].
+
+## Guidelines
+
+### Style
+
+Follow Google's [developer documentation style guide].
+
+### Markdown
+
+Adhere to these Markdown conventions:
+
+- Use [ATX] headings (levels 2-4), not [setext] headings.
+- Use [collapsed link references][] instead of full or shortcut references. For example:
+
+ ```text
+ This is a [link][].
+
+ [link]: https://example.org
+ ```
+
+- Use [fenced code blocks] instead of [indented code blocks].
+- Use hyphens, not asterisks, for unordered [list items].
+- Use [callouts](#callouts) instead of 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.
+- Remove trailing spaces.
+
+### Glossary
+
+[Glossary] terms are defined on individual pages, providing a central repository for definitions, though these pages are not directly linked from the site.
+
+Definitions must be complete sentences, with the first sentence defining the term. Italicize the first occurrence of the term and any referenced glossary terms for consistency.
+
+Link to glossary terms using this syntax: `[term](g)`
+
+Term lookups are case-insensitive, ignore formatting, and support singular and plural forms. For example, all of these variations will link to the same glossary term:
+
+```text
+[global resource](g)
+[Global Resource](g)
+[Global Resources](g)
+[`Global Resources`](g)
+```
+
+Use the [glossary-term shortcode](#glossary-term) to insert a term definition:
+
+```text
+{{%/* glossary-term "global resource" */%}}
+```
+
+### Terminology
+
+Link to the [glossary] as needed and use terms consistently. Pay particular attention to:
+
+- "front matter" (two words, except when referring to the configuration key)
+- "home page" (two words)
+- "website" (one word)
+- "standalone" (one word, no hyphen)
+- "map" (instead of "dictionary")
+- "flag" (instead of "option" for command-line flags)
+- "client side" (noun), "client-side" (adjective)
+- "server side" (noun), "server-side" (adjective)
+- "Markdown" (capitalized)
+- "open-source" (hyphenated adjective)
++- "Node.js" (first mention per page), "Node" (subsequent mentions), "node" (for the executable), "npm" (always lowercase)
+
+### Template types
+
+When you refer to a template type, italicize it:
+
+```text
+When creating a _taxonomy_ template, do this...
+```
+
+However, if the template type is also a link, do not italicize it to avoid distracting formatting:
+
+```text
+When creating a [taxonomy] template, do this...
+```
+
+Do not italicize the template type in a title, heading, or front matter description.
+
+### Titles and headings
+
+- Use sentence-style capitalization.
+- Avoid formatted strings.
+- Keep them concise.
+
+### Page descriptions
+
+When writing the page `description` use imperative present tense when possible. For example:
+
+{{< code-toggle file=content/en/functions/data/_index.md" fm=true >}}
+title: Data functions
+linkTitle: data
+description: Use these functions to read local or remote data files.
+{{< /code-toggle >}}
+
+### Writing style
+
+Use active voice and present tense wherever possible.
+
+No → With Hugo you can build a static site.\
+Yes → Build a static site with Hugo.
+
+No → This will cause Hugo to generate HTML files in the `public` directory.\
+Yes → Hugo generates HTML files in the `public` directory.
+
+Use second person instead of third person.
+
+No → Users should exercise caution when deleting files.\
+Better → You must be cautious when deleting files.\
+Best → Be cautious when deleting files.
+
+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).
+
+### Function and method descriptions
+
+Start descriptions in the functions and methods sections with "Returns", or for boolean values, "Reports whether".
+
+### File paths and names
+
+Enclose directory names, file names, and file paths in backticks, except when used in:
+
+- Page titles
+- Section headings (h1-h6)
+- Definition list terms
+- The `description` field in front matter
+
+### Miscellaneous
+
+Other best practices:
+
+- Introduce lists with a sentence or phrase, not directly under a heading.
+- 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.
+
+## Front matter fields
+
+This site uses the front matter fields listed in the table below.
+
+Of the four required fields, only `title` and `description` require data.
+
+```text
+title: The title
+description: The description
+categories: []
+keywords: []
+```
+
+This example demonstrates the minimum required front matter fields.
+
+If quotation marks are required, prefer single quotes to double quotes when possible.
+
+Field|Description|Required
+:--|:--|:--
+`title`|The page title|:heavy_check_mark:
+`linkTitle`|A short version of the page title|
+`description`|A complete sentence describing the page|:heavy_check_mark:
+`categories`|An array of terms in the categories taxonomy|:heavy_check_mark: [^1]
+`keywords`|An array of keywords used to identify related content|:heavy_check_mark: [^1]
+`publishDate`|Applicable to news items: the publication date|
+`params.alt_title`|An alternate title: used in the "see also" panel if provided|
+`params.functions_and_methods.aliases`|Applicable to function and method pages: an array of alias names|
+`params.functions_and_methods.returnType`|Applicable to function and method pages: the data type returned|
+`params.functions_and_methods.signatures`|Applicable to function and method pages: an array of signatures|
+`params.hide_in_this_section`|Whether to hide the "in this section" panel|
+`params.minversion`|Applicable to the quick start page: the minimum Hugo version required|
+`params.permalink`|Reserved for use by the news content adapter|
+`params.reference (used in glossary term)`|Applicable to glossary entries: a URL for additional information|
+`params.searchable`|Whether to add the content of this page to the search index. The default value is cascaded down from the project configuration; `true` if the page kind is `page`, and `false` if the page kind is one of `home`, `section`, `taxonomy`, or `term`. Add this field to override the default value.|
+`params.show_publish_date`|Whether to show the `publishDate` when rendering the page|
+`weight`|The page weight|
+`aliases`|Previous URLs used to access this page|
+`expirydate`|The expiration date|
+
+[^1]: The field is required, but its data is not.
+
+## Related content
+
+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.
+
+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 >}}
- alt_title = "Whatever you want"
++title = 'Long descriptive title'
++linkTitle = 'Short title'
+[params]
- languageCode = 'en-US'
++alt_title = 'Whatever you want'
+{{< /code-toggle >}}
+
+Use of the alternate title is limited to the "See also" sidebar.
+
+> [!note]
+> Think carefully before setting the `alt_title`. Use it only when absolutely necessary.
+
+## Code examples
+
+With examples of template code:
+
+- Indent with two spaces.
+- Insert a space after an opening action delimiter.
+- Insert a space before a closing action delimiter.
+- Do not add white space removal syntax to action delimiters unless required. For example, inline elements like `img` and `a` require whitespace removal on both sides.
+
+```go-html-template
+{{ if eq $foo $bar }}
+ {{ fmt.Printf "%s is %s" $foo $bar }}
+{{ end }}
+```
+
+### Fenced code blocks
+
+Always specify the language.
+
+When providing a Mardown example, set the code language to "text" to prevent
+erroneous lexing/highlighting of shortcode calls.
+
+````text
+```go-html-template
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+````
+
+To include a file name header and copy-to-clipboard button:
+
+````text
+```go-html-template {file="layouts/_partials/foo.html" copy=true}
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+````
+
+To wrap the code block within an initially-opened `details` element using a non-default summary:
+
+````text
+```go-html-template {details=true open=true summary="layouts/_partials/foo.html" copy=true}
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+````
+
+Whitespace trimming is enabled by default. To override this behavior and preserve leading and trailing spaces:
+
+````text
+```go-html-template {trim=false}
+
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+
+```
+````
+
+### Shortcode calls
+
+Use this syntax :
+
+````text
+```text
+{{</*/* foo */*/>}}
+{{%/*/* foo */*/%}}
+```
+````
+
+### Project configuration
+
+Use the [code-toggle shortcode](#code-toggle) to include project configuration examples:
+
+```text
+{{</* code-toggle file=hugo */>}}
+baseURL = 'https://example.org/'
- languageCode = 'en-US'
++locale = 'en-US'
+title = 'My Site'
+{{</* /code-toggle */>}}
+```
+
+### Front matter
+
+Use the [code-toggle shortcode](#code-toggle) to include front matter examples:
+
+```text
+{{</* code-toggle file=content/posts/my-first-post.md fm=true */>}}
+title = 'My first post'
+date = 2023-11-09T12:56:07-08:00
+draft = false
+{{</* /code-toggle */>}}
+```
+
+## Callouts
+
+To visually emphasize important information, use callouts (admonitions). Callout types are case-insensitive. Effective March 8, 2025, we utilize only three of the five available types.
+
+- note (272 instances)
+- warning (2 instances)
+- caution (1 instance)
+
+Limiting the number of callout types helps us to use them consistently.
+
+```text
+> [!note]
+> Useful information that users should know, even when skimming content.
+```
+
+> [!note]
+> Useful information that users should know, even when skimming content.
+
+```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.
+
+```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.
+
+## Shortcodes
+
+These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
+
+### code-toggle
+
+Use the `code-toggle` shortcode to display examples of project configuration, front matter, or data files. This shortcode takes these arguments:
+
+config
+: (`string`) The section of `hugo.Data.docs.config` to render.
+
+copy
+: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+
+datakey:
+: (`string`) The section of `hugo.Data.docs` to render.
+
+file
+: (`string`) The file name to display above the rendered code. Omit the file extension for project configuration examples.
+
+fm
+: (`bool`) Whether to render the code as front matter. Default is `false`.
+
+skipHeader
+: (`bool`) Whether to omit top-level key(s) when rendering a section of `hugo.Data.docs.config`.
+
+```text
+{{</* code-toggle file=hugo copy=true */>}}
+baseURL = 'https://example.org/'
- {{</* deprecated-in 0.144.0 */>}}
++locale = 'en-US'
+title = 'My Site'
+{{</* /code-toggle */>}}
+```
+
+### deprecated-in
+
+Use the `deprecated-in` shortcode to indicate that a feature is deprecated:
+
+```text
- Use [`hugo.IsServer`] instead.
++{{</* deprecated-in 0.144.0 /*/>}}
++```
+
- [`hugo.IsServer`]: /functions/hugo/isserver/
++You can also include details:
+
- Use the [new-in shortcode](#new-in) to indicate a new feature:
-
- ```text
- {{</* new-in 0.144.0 */>}}
- ```
++```text
++{{</* deprecated-in 0.144.0 */>}}
++Use [`hugo.IsServer`](/functions/hugo/isserver/) instead.
+{{</* /deprecated-in */>}}
+```
+
+### eturl
+
+Use the embedded template URL (`eturl`) shortcode to insert an absolute URL to the source code for an embedded template. The shortcode takes a single argument, the base file name of the template (omit the file extension).
+
+```text
+This is a link to the [embedded alias template].
+
+[embedded alias template]: <{{%/* eturl alias */%}}>
+```
+
+### glossary-term
+
+Use the `glossary-term` shortcode to insert the definition of the given glossary term.
+
+```text
+{{%/* glossary-term scalar */%}}
+```
+
+### include
+
+Use the `include` shortcode to include content from another page.
+
+```text
+{{%/* include "_common/glob-patterns.md" */%}}
+```
+
+### new-in
+
+Use the `new-in` shortcode to indicate a new feature:
+
+```text
+{{</* new-in 0.144.0 /*/>}}
+```
+
+You can also include details:
+
+```text
+{{</* new-in 0.144.0 */>}}
+This is a new feature.
+{{</* /new-in */>}}
+```
+
+## New features
+
- The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_shortcodes/new-in.html).
++Use the [new-in](#new-in) shortcode to indicate a new feature.
+
- Use the [deprecated-in shorcode](#deprecated-in) shortcode to indicate that a feature is deprecated:
++The new-in shortcode will trigger a build warning if the specified version is older than a predefined threshold, based on differences in major and minor versions. This serves as a reminder to remove this shortcode call. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/_partials/layouts/blocks/feature-state.html).
+
+## Deprecated features
+
- ```text
- {{</* deprecated-in 0.144.0 */>}}
- Use [`hugo.IsServer`] instead.
-
- [`hugo.IsServer`]: /functions/hugo/isserver/
- {{</* /deprecated-in */>}}
- ```
-
- When deprecating a function or method, add something like this to front matter:
++Use the [deprecated-in](#deprecated-in) shortcode to indicate that a feature is deprecated.
+
- {{< code-toggle file=content/something/foo.md fm=true >}}
- expiryDate: 2027-02-17 # deprecated 2025-02-17 in v0.144.0
- {{< /code-toggle >}}
++The deprecated-in shortcode will trigger a build warning if the specified version is older than a predefined threshold, based on differences in major and minor versions. This serves as a reminder to remove this shortcode call and the associated content. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/_partials/layouts/blocks/feature-state.html).
+
- Set the `expiryDate` to two years from the date of deprecation, and add a brief front matter comment to explain the setting.
++When deprecating a feature that has its own page, also set the `expiryDate` in front matter to two years from the date of deprecation. Include a brief comment to explain the setting:
+
++```yaml
++expiryDate: 2028-03-03 # deprecated 2026-03-03 in v0.157.0
++```
+
+## GitHub workflow
+
+> [!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.
+
+Step 1
+: Fork the [documentation repository].
+
+Step 2
+: Clone your fork.
+
+Step 3
+: Create a new branch with a descriptive name that includes the corresponding issue number, if any:
+
+ ```sh
+ git checkout -b restructure-foo-page-99999
+ ```
+
+Step 4
+: Make changes.
+
+Step 5
+: Build the site locally to preview your changes.
+
+Step 6
+: Commit your changes with a descriptive commit message:
+
+ - Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
+ - Begin the summary with one of `content`, `theme`, `config`, `all`, or `misc`, followed by a colon, a space, and a brief description of the change beginning with a capital letter
+ - Use imperative present tense
+ - Optionally, provide a detailed description where each line is 72 characters or less, followed by a blank line.
+ - Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+
+ For example:
+
+ ```text
+ git commit -m "content: Restructure the taxonomy page
+
+ This restructures the taxonomy page by splitting topics into logical
+ sections, each with one or more examples.
+
+ Fixes #9999
+ Closes #9998"
+ ```
+
+Step 7
+: Push the new branch to your fork of the documentation repository.
+
+Step 8
+: Visit the [documentation repository] and create a pull request (PR).
+
+Step 9
+: 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/current/#atx-headings
+[basic english]: https://simple.wikipedia.org/wiki/Basic_English
+[collapsed link references]: https://discourse.gohugo.io/t/55714
+[developer documentation style guide]: https://developers.google.com/style
+[documentation repository]: https://github.com/gohugoio/hugoDocs/
+[fenced code blocks]: https://spec.commonmark.org/current/#fenced-code-blocks
+[glossary]: /quick-reference/glossary/
+[indented code blocks]: https://spec.commonmark.org/current/#indented-code-blocks
+[issues]: https://github.com/gohugoio/hugoDocs/issues
+[list items]: https://spec.commonmark.org/current/#list-items
+[project repository]: https://github.com/gohugoio/hugo
+[raw HTML]: https://spec.commonmark.org/current/#raw-html
+[related content]: /content-management/related-content/
+[setext]: https://spec.commonmark.org/current/#setext-heading
--- /dev/null
- firstName = "Marius"
- lastName = "Pontmercy"
+---
+title: collections.Sort
+description: Returns a sorted map or slice by reordering the given collection by a key and order.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [sort]
+ returnType: any
+ signatures: ['collections.Sort MAP|SLICE [KEY] [ORDER]']
+aliases: [/functions/sort]
+---
+
+The `KEY` is optional when sorting slices in ascending order, otherwise it is required. When sorting slices, use the literal `value` in place of the `KEY`. See examples below.
+
+The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default sort order is ascending.
+
+## Sort a slice
+
+The examples below assume this project configuration:
+
+{{< code-toggle file=hugo >}}
+[params]
+grades = ['b','a','c']
+{{< /code-toggle >}}
+
+### Ascending order {#slice-ascending-order}
+
+Sort slice elements in ascending order using either of these constructs:
+
+```go-html-template
+{{ sort site.Params.grades }} → [a b c]
+{{ sort site.Params.grades "value" "asc" }} → [a b c]
+```
+
+In the examples above, `value` is the `KEY` representing the value of the slice element.
+
+### Descending order {#slice-descending-order}
+
+Sort slice elements in descending order:
+
+```go-html-template
+{{ sort site.Params.grades "value" "desc" }} → [c b a]
+```
+
+In the example above, `value` is the `KEY` representing the value of the slice element.
+
+## Sort a map
+
+The examples below assume this project configuration:
+
+{{< code-toggle file=hugo >}}
+[params.authors.a]
- firstName = "Victor"
- lastName = "Hugo"
++firstName = 'Marius'
++lastName = 'Pontmercy'
+[params.authors.b]
- firstName = "Jean"
- lastName = "Valjean"
++firstName = 'Victor'
++lastName = 'Hugo'
+[params.authors.c]
++firstName = 'Jean'
++lastName = 'Valjean'
+{{< /code-toggle >}}
+
+> [!note]
+> When sorting maps, the `KEY` argument must be lowercase.
+
+### Ascending order {#map-ascending-order}
+
+Sort map objects in ascending order using either of these constructs:
+
+```go-html-template
+{{ range sort site.Params.authors "firstname" }}
+ {{ .firstName }}
+{{ end }}
+
+{{ range sort site.Params.authors "firstname" "asc" }}
+ {{ .firstName }}
+{{ end }}
+```
+
+These produce:
+
+```text
+Jean Marius Victor
+```
+
+### Descending order {#map-descending-order}
+
+Sort map objects in descending order:
+
+```go-html-template
+{{ range sort site.Params.authors "firstname" "desc" }}
+ {{ .firstName }}
+{{ end }}
+```
+
+This produces:
+
+```text
+Victor Marius Jean
+```
+
+### First level key removal
+
+Hugo removes the first level keys when sorting a map.
+
+Original map:
+
+```json
+{
+ "felix": {
+ "breed": "malicious",
+ "type": "cat"
+ },
+ "spot": {
+ "breed": "boxer",
+ "type": "dog"
+ }
+}
+```
+
+After sorting:
+
+```json
+[
+ {
+ "breed": "malicious",
+ "type": "cat"
+ },
+ {
+ "breed": "boxer",
+ "type": "dog"
+ }
+]
+```
+
+## 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.
+
+In this contrived example, sort the site's regular pages by `.Type` in descending order:
+
+```go-html-template
+{{ range sort site.RegularPages "Type" "desc" }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+```
+
+[sorting and grouping methods]: /methods/pages/
--- /dev/null
- Consider this site content:
+---
+title: collections.Where
+description: Returns a slice by filtering the given slice based on a key, operator, and value.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [where]
+ returnType: '[]any'
+ signatures: ['collections.Where SLICE KEY [OPERATOR] VALUE']
+aliases: [/functions/where]
+---
+
+The `where` function returns the given slice, removing elements that do not satisfy the comparison condition. The comparison condition is composed of the `KEY`, `OPERATOR`, and `VALUE` arguments:
+
+```text
+collections.Where SLICE KEY [OPERATOR] VALUE
+ --------------------
+ comparison condition
+```
+
+Hugo will test for equality if you do not provide an `OPERATOR` argument. For example:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "books" }}
+{{ $books := where hugo.Data.books "genres" "suspense" }}
+```
+
+## Arguments
+
+The where function takes three or four arguments. The `OPERATOR` argument is optional.
+
+SLICE
+: (`[]any`) A [page collection](g) or a [slice](g) of [maps](g).
+
+KEY
+: (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain](g) the subkey as shown below:
+
+ ```go-html-template
+ {{ $result := where .Site.RegularPages "Params.foo" "bar" }}
+ ```
+
+OPERATOR
+: (`string`) The logical comparison [operator](#operators).
+
+VALUE
+: (`any`) The value with which to compare. The values to compare must have comparable data types. For example:
+
+Comparison|Result
+:--|:--
+`"123" "eq" "123"`|`true`
+`"123" "eq" 123`|`false`
+`false "eq" "false"`|`false`
+`false "eq" false`|`true`
+
+When one or both of the values to compare is a slice, use the `in`, `not in`, or `intersect` operators as described below.
+
+## Operators
+
+Use any of the following logical operators:
+
+`=`, `==`, `eq`
+: (`bool`) Reports whether the given field value is equal to `VALUE`.
+
+`!=`, `<>`, `ne`
+: (`bool`) Reports whether the given field value is not equal to `VALUE`.
+
+`>=`, `ge`
+: (`bool`) Reports whether the given field value is greater than or equal to `VALUE`.
+
+`>`, `gt`
+: `true` Reports whether the given field value is greater than `VALUE`.
+
+`<=`, `le`
+: (`bool`) Reports whether the given field value is less than or equal to `VALUE`.
+
+`<`, `lt`
+: (`bool`) Reports whether the given field value is less than `VALUE`.
+
+`in`
+: (`bool`) Reports whether the given field value is a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
+
+`not in`
+: (`bool`) Reports whether the given field value is not a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
+
+`intersect`
+: (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect).
+
+`like`
+: (`bool`) Reports whether the given field value matches the [regular expression](g) 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.
+
+## String comparison
+
+Compare the value of the given field to a [`string`](g):
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "eq" "books" }}
+{{ $pages := where .Site.RegularPages "Section" "ne" "books" }}
+```
+
+## Numeric comparison
+
+Compare the value of the given field to an [`int`](g) or [`float`](g):
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $pages := where $books "Params.price" "eq" 42 }}
+{{ $pages := where $books "Params.price" "ne" 42.67 }}
+{{ $pages := where $books "Params.price" "ge" 42 }}
+{{ $pages := where $books "Params.price" "gt" 42.67 }}
+{{ $pages := where $books "Params.price" "le" 42 }}
+{{ $pages := where $books "Params.price" "lt" 42.67 }}
+```
+
+## Boolean comparison
+
+Compare the value of the given field to a [`bool`](g):
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $pages := where $books "Params.fiction" "eq" true }}
+{{ $pages := where $books "Params.fiction" "eq" false }}
+{{ $pages := where $books "Params.fiction" "ne" true }}
+{{ $pages := where $books "Params.fiction" "ne" false }}
+```
+
+## Member comparison
+
+Compare a [`scalar`](g) to a [`slice`](g).
+
+For example, to return a slice of pages where the `color` page parameter is either "red" or "yellow":
+
+```go-html-template
+{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
+
+{{ $colors := slice "red" "yellow" }}
+{{ $pages := where $fruit "Params.color" "in" $colors }}
+```
+
+To return a slice of pages where the "color" page parameter is neither "red" nor "yellow":
+
+```go-html-template
+{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
+
+{{ $colors := slice "red" "yellow" }}
+{{ $pages := where $fruit "Params.color" "not in" $colors }}
+```
+
+## Intersection comparison
+
+Compare a `slice` to a `slice`, returning elements with common values. This is frequently used when comparing taxonomy terms.
+
+For example, to return a slice of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance":
+
+```go-html-template
+{{ $books := where site.RegularPages "Section" "eq" "books" }}
+
+{{ $genres := slice "suspense" "romance" }}
+{{ $pages := where $books "Params.genres" "intersect" $genres }}
+```
+
+## Regular expression comparison
+
+To return a slice of pages where the "author" page parameter begins with either "victor" or "Victor":
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }}
+```
+
+{{% include "/_common/functions/regular-expressions.md" %}}
+
+> [!note]
+> Use the `like` operator to compare string values. Comparing other data types will result in an empty slice.
+
+## Date comparison
+
+### Predefined dates
+
+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.
+
+For example, to return a slice of pages that were created before the current year:
+
+```go-html-template
+{{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }}
+{{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }}
+```
+
+### Custom dates
+
+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.
+
+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.
+
+In the TOML example below, note that the event date is not quoted.
+
+```text {file="content/events/2024-user-conference.md"}
++++
+title = '2024 User Conference"
+eventDate = 2024-04-01
++++
+```
+
+To return a slice of future events:
+
+```go-html-template
+{{ $events := where .Site.RegularPages "Type" "events" }}
+{{ $futureEvents := where $events "Params.eventDate" "gt" now }}
+```
+
+When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. To be safe, filter the pages by ranging over the slice:
+
+```go-html-template
+{{ $events := where .Site.RegularPages "Type" "events" }}
+{{ $futureEvents := slice }}
+{{ range $events }}
+ {{ if gt (time.AsTime .Params.eventDate) now }}
+ {{ $futureEvents = $futureEvents | append . }}
+ {{ end }}
+{{ end }}
+```
+
+## Nil comparison
+
+To return a slice of pages where the "color" parameter is present in front matter, compare to `nil`:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
+```
+
+To return a slice of pages where the "color" parameter is not present in front matter, compare to `nil`:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Params.color" "eq" nil }}
+```
+
+In both examples above, note that `nil` is not quoted.
+
+## Nested comparison
+
+These are equivalent:
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Type" "tutorials" }}
+{{ $pages = where $pages "Params.level" "eq" "beginner" }}
+```
+
+```go-html-template
+{{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }}
+```
+
+## Portable section comparison
+
+Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object.
+
+```go-html-template
+{{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }}
+```
+
+With this construct, a theme author can instruct users to specify their main sections in their project configuration:
+
+{{< code-toggle file=hugo >}}
+mainSections = ['blog','galleries']
+{{< /code-toggle >}}
+
+If `mainSections` is not defined in your project configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages.
+
+## Boolean/undefined comparison
+
++Consider this project structure:
+
+```text
+content/
+├── posts/
+│ ├── _index.md
+│ ├── post-1.md <-- front matter: exclude = false
+│ ├── post-2.md <-- front matter: exclude = true
+│ └── post-3.md <-- front matter: exclude not defined
+└── _index.md
+```
+
+The first two pages have an "exclude" field in front matter, but the last page does not. When testing for _equality_, the third page is _excluded_ from the result. When testing for _inequality_, the third page is _included_ in the result.
+
+### Equality test
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "eq" false }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "eq" true }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-2/">Post 2</a></li>
+</ul>
+```
+
+### Inequality test
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "ne" false }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-2/">Post 2</a></li>
+ <li><a href="/posts/post-3/">Post 3</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range where .Site.RegularPages "Params.exclude" "ne" true }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+ <li><a href="/posts/post-3/">Post 3</a></li>
+</ul>
+```
+
+To exclude a page with an undefined field from a boolean _inequality_ test:
+
+1. Create a slice using a boolean comparison
+1. Create a slice using a nil comparison
+1. Subtract the second slice from the first slice using the [`collections.Complement`] function.
+
+This template:
+
+```go-html-template
+{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }}
+{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
+<ul>
+ {{ range $p1 | complement $p2 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 1</a></li>
+</ul>
+```
+
+This template:
+
+```go-html-template
+{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }}
+{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
+<ul>
+ {{ range $p1 | complement $p2 }}
+ <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li><a href="/posts/post-1/">Post 2</a></li>
+</ul>
+```
+
+[`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
--- /dev/null
--- /dev/null
++---
++title: css.Build
++description: Bundle, transform, and minify CSS resources.
++categories: []
++keywords: []
++params:
++ functions_and_methods:
++ aliases: []
++ returnType: resource.Resource
++ signatures: ['css.Build [OPTIONS] RESOURCE']
++---
++
++{{< new-in 0.158.0 />}}
++
++Use the `css.Build` function to:
++
++- Recursively replace `@import` statements in CSS files with the content of the imported files
++- Transform syntax for browser compatibility
++- Apply vendor prefixes for browser compatibility
++- Minify the bundled CSS code
++- Create a source map
++
++If an `@import` statement includes a media query, a feature query, or a cascade layer assignment, the function wraps the imported content in the corresponding `@media`, `@supports`, or `@layer` rule.
++
++## Usage
++
++In this example, Hugo bundles the local files referenced by `@import` statements to create and publish a single resource with inline content.
++
++```text
++assets/
++└── css/
++ ├── components/
++ │ ├── a.css
++ │ └── b.css
++ └── main.css
++```
++
++```css {file="assets/css/main.css" copy=true}
++@import url('https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css');
++
++@import './components/a.css';
++@import './components/b.css';
++
++.c {color: blue; }
++```
++
++```css {file="assets/css/components/a.css" copy=true}
++.a { color: red; }
++```
++
++```css {file="assets/css/components/b.css" copy=true}
++.b { color: green; }
++```
++
++```go-html-template {file="layouts/_partials/css.html" copy=true}
++{{ with resources.Get "css/main.css" | css.Build }}
++ {{ if hugo.IsDevelopment }}
++ <link rel="stylesheet" href="{{ .RelPermalink }}">
++ {{ else }}
++ {{ with . | fingerprint }}
++ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
++ {{ end }}
++ {{ end }}
++{{ end }}
++```
++
++```go-html-template {file="layouts/baseof.html" copy=true}
++{{ partialCached "css.html" . }}
++```
++
++The generated CSS code:
++
++```css {file="public/css/main.css"}
++@import "https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css";
++
++.a {
++ color: red;
++}
++
++.b {
++ color: green;
++}
++
++.c {
++ color: blue;
++}
++```
++
++To minify the generated CSS code, use the [`minify`](#minify) option as described below.
++
++## Options
++
++The `css.Build` function takes an optional map of options based on the underlying [`esbuild`] package. Use these options to fine-tune bundling, minification, and browser compatibility.
++
++externals
++: (`[]string`) A slice of path patterns to exclude from bundling. The `@import` statements for these patterns remain as-is in the generated CSS code. See [details][esb_external].
++
++ ```go-html-template
++ {{ $opts := dict "externals" (slice "./exclude-these/*" "./exclude-these-too/*") }}
++ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
++ ```
++
++loaders
++: (`map`) A map of file extensions to loader types. This determines how files with a given extension are processed during bundling. By default, Hugo uses the `css` loader for `.css` files and the `file` loader for all others. Common loaders include:
++
++ - `css`: Processes the file as a CSS file
++ - `dataurl`: Embeds the file as a base64-encoded data URL
++ - `empty`: Excludes the file from the bundle
++ - `file`: Copies the file to the output directory and rewrites the URL
++ - `text`: Loads the file content as a string
++
++ See [details][esb_loader].
++
++ ```go-html-template
++ {{ $opts := dict "loaders" (dict ".png" "dataurl" ".svg" "dataurl") }}
++ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
++ ```
++
++mainFields
++: (`[]string`) A prioritized slice of field names in a `package.json` file that determine the CSS entry point of a Node package. The default is `["style", "main"]`. See [details][esb_mainfields].
++
++ When an `@import` statement references a Node package, Hugo consults the metadata in the `package.json` file to find the stylesheet. Use this option to support packages that define a CSS entry point using non-standard fields.
++
++ ```go-html-template
++ {{ $opts := dict "mainFields" (slice "css" "style" "main") }}
++ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
++ ```
++
++minify
++: (`bool`) Whether to minify the generated CSS code. Default is `false`. See [details][esb_minify].
++
++ ```go-html-template
++ {{ $opts := dict "minify" true }}
++ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
++ ```
++
++sourceMap
++: (`string`) The type of source map to generate. One of `external`, `inline`, `linked`, or `none`. Default is `none`. See [details][esb_sourcemap].
++
++ ```go-html-template
++ {{ $opts := dict "sourceMap" "linked" }}
++ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
++ ```
++
++sourcesContent
++: (`bool`) Whether to include the content of the source files in the source map. Default is `true`. See [details][esb_sourcesContent].
++
++ ```go-html-template
++ {{ $opts := dict "sourceMap" "linked" "sourcesContent" false }}
++ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
++ ```
++
++target
++: (`[]string`) The target environment for the generated CSS code. This determines which syntax transformations to perform and which vendor prefixes to apply. If unset, no transformations or prefixing are performed. Each element consists of a target name and a version number. Supported targets include `chrome`, `edge`, `firefox`, `ie`, `ios`, `opera`, and `safari`. See [details][esb_target].
++
++ ```go-html-template
++ {{ $target := slice "chrome115" "edge115" "firefox116" "ios16.4" "opera101" "safari16.4" }}
++ {{ $opts := dict "target" $target }}
++ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
++ ```
++
++ In the example above, the target environment is roughly equivalent to the [browserlist][] "baseline widely available" profile as of March 2026.
++
++targetPath
++: (`string`) The path to the generated CSS file, relative to the project's [`publishDir`][]. If unset, this defaults to the asset's original path with a `.css` extension.
++
++ ```go-html-template
++ {{ $opts := dict "targetPath" "css/styles.css" }}
++ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
++ ```
++
++## Example
++
++The example below uses several of the [options](#options) described above to bundle, transform, and minify CSS code.
++
++```go-html-template {file="layouts/_partials/css.html" copy=true}
++{{ with resources.Get "css/main.css" }}
++ {{ $opts := dict
++ "loaders" (dict ".png" "dataurl" ".svg" "dataurl")
++ "minify" (cond hugo.IsDevelopment false true)
++ "sourceMap" (cond hugo.IsDevelopment "linked" "none")
++ "target" (slice "chrome115" "edge115" "firefox116" "ios16.4" "opera101" "safari16.4")
++ }}
++ {{ with . | css.Build $opts }}
++ {{ if hugo.IsDevelopment }}
++ <link rel="stylesheet" href="{{ .RelPermalink }}">
++ {{ else }}
++ {{ with . | fingerprint }}
++ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
++ {{ end }}
++ {{ end }}
++ {{ end }}
++{{ end }}
++```
++
++Using the options above, Hugo does the following:
++
++- Embeds PNG and SVG images as data URLs in the generated CSS code
++- Minifies the output in production but not in development
++- Generates an external source map in development but not in production
++- Transforms syntax for compatibility with the targeted browser versions
++- Adds vendor prefixes for compatibility with the targeted browser versions
++- Publishes the generated CSS code to `css/styles.css`
++- In production, adds an SRI hash and inserts a file hash into the filename
++
++[`esbuild`]: https://github.com/evanw/esbuild
++[`publishDir`]: /configuration/all/#publishdir
++[browserlist]: https://browsersl.ist
++[esb_external]: https://esbuild.github.io/api/#external
++[esb_loader]: https://esbuild.github.io/api/#loader
++[esb_mainfields]: https://esbuild.github.io/api/#main-fields
++[esb_minify]: https://esbuild.github.io/api/#minify
++[esb_sourcemap]: https://esbuild.github.io/api/#sourcemap
++[esb_sourcesContent]: https://esbuild.github.io/api/#sources-content
++[esb_target]: https://esbuild.github.io/api/#target
++
++## Common patterns
++
++The examples below cover the most frequent use cases for referencing resources within your project or within Node packages. These patterns apply to both `@import` statements and the `url()` functional notation used for images and fonts.
++
++All resources referenced by a path, including images, fonts, and stylesheets, must reside in the `assets` directory of the [unified file system](g), or within a Node package.
++
++### Files in the assets directory
++
++To include a stylesheet from the `assets` directory, you can use a bare path, a relative path, or a root-relative path. When you use a bare path, Hugo searches relative to the current stylesheet, then relative to the `assets` directory.
++
++```css {file="/assets/css/main.css"}
++/* A bare path */
++@import "variables.css";
++
++/* A relative path */
++@import "./theme.css";
++@import "../layout.css";
++
++/* A root-relative path */
++@import "/css/grid.css";
++
++/* A url() reference using the same resolution logic */
++.logo { background: url("/images/logo.svg"); }
++```
++
++### Node packages
++
++When referencing a Node package by name, Hugo consults the `package.json` file within that package to find the entry point.
++
++```css {file="/assets/css/main.css"}
++@import "bootstrap";
++```
++
++### Files within a package
++
++To reference a specific file within a Node package, provide the path starting with the package name.
++
++```css {file="/assets/css/main.css"}
++@import "bootstrap/dist/css/bootstrap-grid.css";
++```
--- /dev/null
- {{< new-in 0.128.0 />}}
-
+---
+title: css.PostCSS
+description: Processes the given resource with PostCSS using any PostCSS plugin.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [postCSS]
+ returnType: resource.Resource
+ signatures: ['css.PostCSS [OPTIONS] RESOURCE']
++aliases: [/functions/resources/postcss/]
+---
+
- : Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
+```go-html-template
+{{ with resources.Get "css/main.css" | postCSS }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+{{ end }}
+```
+
+## Setup
+
+Follow the steps below to transform CSS using any of the available [PostCSS plugins].
+
+Step 1
+: Install [Node.js].
+
+Step 2
- : (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set this option to `true`. Default is `false`."
++: Install the required Node packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
+
+ ```sh
+ npm i -D postcss postcss-cli autoprefixer
+ ```
+
+Step 3
+: Create a PostCSS configuration file in the root of your project.
+
+ ```js {file="postcss.config.js"}
+ module.exports = {
+ plugins: [
+ require('autoprefixer')
+ ]
+ };
+ ```
+
+ > [!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
+: Place your CSS file within the `assets/css` directory.
+
+Step 5
+: Process the resource with PostCSS:
+
+ ```go-html-template
+ {{ with resources.Get "css/main.css" | postCSS }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ end }}
+ ```
+
+## Options
+
+The `css.PostCSS` method takes an optional map of options.
+
+config
+: (`string`) The directory that contains the PostCSS configuration file. Default is the root of the project directory.
+
+noMap
+: (`bool`) Whether to disable inline source maps. Default is `false`.
+
+inlineImports
+: (`bool`) Whether to enable inlining of import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. Default is `false`.
+
+skipInlineImportsNotFound
++: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set this option to `true`. Default is `false`.
+
+```go-html-template
+{{ $opts := dict "config" "config-directory" "noMap" true }}
+{{ with resources.Get "css/main.css" | postCSS $opts }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+{{ end }}
+```
+
+## No configuration file
+
+To avoid using a PostCSS configuration file, you can specify a minimal configuration using the options map.
+
+use
+: (`string`) A space-delimited list of PostCSS plugins to use.
+
+parser
+: (`string`) A custom PostCSS parser.
+
+stringifier
+: (`string`) A custom PostCSS stringifier.
+
+syntax
+: (`string`) Custom postcss syntax.
+
+```go-html-template
+{{ $opts := dict "use" "autoprefixer postcss-color-alpha" }}
+{{ with resources.Get "css/main.css" | postCSS $opts }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+{{ end }}
+```
+
+## Check environment
+
+The current Hugo environment name (set by `--environment` or in configuration or OS environment) is available in the Node context, which allows constructs like this:
+
+```js
+const autoprefixer = require('autoprefixer');
+module.exports = {
+ plugins: [
+ process.env.HUGO_ENVIRONMENT !== 'development' ? autoprefixer : null
+ ]
+}
+```
+
+[#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
--- /dev/null
+---
+title: css.Sass
+description: Transpiles Sass to CSS.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [toCSS]
+ returnType: resource.Resource
+ signatures: ['css.Sass [OPTIONS] RESOURCE']
++aliases: [/functions/resources/tocss/]
+---
+
+Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended and extended/deploy editions, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language.
+
+> [!warning]
+> The embedded LibSass transpiler was deprecated in [v0.153.0][] and will be removed in a future release. Use the Dart Sass transpiler instead.
+
+Sass has two forms of syntax: [SCSS][] and [indented][]. Hugo supports both.
+
+## Options
+
+enableSourceMap
+: (`bool`) Whether to generate a source map. Default is `false`.
+
+includePaths
+: (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements.
+
+outputStyle
+: (`string`) The output style of the resulting CSS. With LibSass, one of `nested` (default), `expanded`, `compact`, or `compressed`. With Dart Sass, either `expanded` (default) or `compressed`.
+
+precision
+: (`int`) The precision of floating point math. Applicable to LibSass. Default is `8`.
+
+silenceDeprecations
+: {{< new-in 0.139.0 />}}
+: (`slice`) A slice of deprecation IDs to silence. IDs are enclosed in brackets within Dart Sass warning messages (e.g., `import` in `WARN Dart Sass: DEPRECATED [import]`). Applicable to Dart Sass. Default is `false`.
+
+silenceDependencyDeprecations
+: {{< new-in 0.146.0 />}}
+: (`bool`) Whether to silence deprecation warnings from dependencies, where a dependency is considered any file transitively imported through a load path. This does not apply to `@warn` or `@debug` rules.Default is `false`.
+
+sourceMapIncludeSources
+: (`bool`) Whether to embed sources in the generated source map. Applicable to Dart Sass. Default is `false`.
+
+targetPath
+: (`string`) The publish path for the transformed resource, relative to the[`publishDir`][]. If unset, the target path defaults to the asset's original path with a `.css` extension.
+
+transpiler
+: (`string`) The transpiler to use, either `libsass` or `dartsass`. Hugo's extended and extended/deploy editions include the LibSass transpiler. To use the Dart Sass transpiler, see the [installation instructions](#dart-sass). Default is `libsass`.
+
+ > [!warning]
+ > The embedded LibSass transpiler was deprecated in [v0.153.0][] and will be removed in a future release. Use the Dart Sass transpiler instead.
+
+vars
+: (`map`) A map of key-value pairs that will be available in the `hugo:vars` namespace. Useful for [initializing Sass variables from Hugo templates](https://discourse.gohugo.io/t/42053/).
+
+ ```scss
+ // LibSass
+ @import "hugo:vars";
+
+ // Dart Sass
+ @use "hugo:vars" as v;
+ ```
+
+ When passing a `vars` map to the `css.Sass` function, Hugo detects common typed CSS values such as `24px` or `#FF0000` using regular expression matching. If necessary, you can bypass automatic type inference by using the [`css.Quoted`][] or [`css.Unquoted`][] function to explicitly indicate a value's type.
+
+## Example
+
+```go-html-template {copy=true}
+{{ with resources.Get "sass/main.scss" }}
+ {{ $opts := dict
+ "enableSourceMap" hugo.IsDevelopment
+ "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
+ "targetPath" "css/main.css"
+ "transpiler" "dartsass"
+ "vars" site.Params.styles
+ "includePaths" (slice "node_modules/bootstrap/scss")
+ }}
+ {{ with . | toCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Dart Sass
+
+Hugo's extended and extended/deploy editions include [LibSass][] to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of [Dart Sass][].
+
+Use the latest features of the Sass language by installing Dart Sass in your development and production environments.
+
+### Installation overview
+
+Dart Sass is compatible with Hugo v0.114.0 and later.
+
+If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.
+
+If you install Hugo as a [Snap package][] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.
+
+[^1]: In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass.
+
+### Installing in a development environment
+
+When you install Dart Sass somewhere in your PATH, Hugo will find it.
+
+OS|Package manager|Site|Installation
+:--|:--|:--|:--
+Linux|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Linux|Snap|[snapcraft.io]|`sudo snap install dart-sass`
+macOS|Homebrew|[brew.sh]|`brew install sass/sass/sass`
+Windows|Chocolatey|[chocolatey.org]|`choco install sass`
+Windows|Scoop|[scoop.sh]|`scoop install sass`
+
+You may also install [prebuilt binaries][] for Linux, macOS, and Windows. You must install the prebuilt binary outside of your project directory and ensure its path is included in your system's PATH environment variable.
+
+Run `hugo env` to list the active transpilers.
+
+> [!note]
+> If you build Hugo from source and run `mage test -v`, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package's strict confinement model.
+
+### Installing in a production environment
+
+To use Dart Sass with Hugo on a [CI/CD](g) platform, you typically must modify your build workflow to install Dart Sass before the Hugo site build begins. This is because these platforms don't have Dart Sass pre-installed, and Hugo needs it to process your Sass files.
+
+There's one key exception where you can skip this step: you have committed your `resources` directory to your repository. This is only possible if:
+
+- You have not changed Hugo's default asset cache location.
+- You have not set [`useResourceCacheWhen`][] to never in your project configuration.
+
+By committing the `resources` directory, you're providing the pre-built CSS files directly to your CI/CD platform, so it doesn't need to run the Sass compilation itself.
+
+For examples of how to install Dart Sass in a production environment, see these hosting guides:
+
+- [Cloudflare][]
+- [GitHub Pages][]
+- [GitLab Pages][]
+- [Netlify][]
+- [Render][]
+- [SourceHut][]
+- [Vercel][]
+
+[`css.Quoted`]: /functions/css/quoted/
+[`css.Unquoted`]: /functions/css/unquoted/
+[`publishDir`]: /configuration/all/#publishdir
+[`useResourceCacheWhen`]: /configuration/build/#useresourcecachewhen
+[brew.sh]: https://brew.sh/
+[chocolatey.org]: https://community.chocolatey.org/packages/sass
+[Cloudflare]: /host-and-deploy/host-on-cloudflare/
+[Dart Sass]: https://sass-lang.com/dart-sass/
+[GitHub Pages]: /host-and-deploy/host-on-github-pages/
+[GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/
+[indented]: https://sass-lang.com/documentation/syntax#the-indented-syntax
+[LibSass]: https://sass-lang.com/libsass
+[Netlify]: /host-and-deploy/host-on-netlify/
+[prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest
+[Render]: /host-and-deploy/host-on-render/
+[scoop.sh]: https://scoop.sh/#/apps?q=sass
+[SCSS]: https://sass-lang.com/documentation/syntax#scss
+[Snap package]: https://snapcraft.io/hugo
+[snapcraft.io]: https://snapcraft.io/dart-sass
+[SourceHut]: /host-and-deploy/host-on-sourcehut-pages/
+[v0.153.0]: https://github.com/gohugoio/hugo/releases/tag/v0.153.0
+[Vercel]: /host-and-deploy/host-on-vercel/
--- /dev/null
- {{< new-in 0.128.0 />}}
-
+---
+title: css.TailwindCSS
+description: Processes the given resource with the Tailwind CSS CLI.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['css.TailwindCSS [OPTIONS] RESOURCE']
+---
+
+Use the `css.TailwindCSS` function to process your Tailwind CSS files. This function uses the Tailwind CSS CLI to:
+
+1. Scan your templates for Tailwind CSS utility class usage.
+1. Compile those utility classes into standard CSS.
+1. Generate an optimized CSS output file.
+
+> [!note]
+> Use this function with Tailwind CSS v4.0 and later, which require a relatively [modern browser] to render correctly.
+
+[modern browser]: https://tailwindcss.com/docs/compatibility#browser-support
+
+## Setup
+
+Step 1
+: Install the Tailwind CSS CLI v4.0 or later:
+
+ ```sh {copy=true}
+ npm install --save-dev tailwindcss @tailwindcss/cli @tailwindcss/typography
+ ```
+
+ The Tailwind CSS CLI is also available as a [standalone executable]. You must install it outside of your project directory and ensure its path is included in your system's `PATH` environment variable.
+
+ [standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest
+
+Step 2
+: Add this to your project configuration:
+
+ {{< code-toggle file=hugo copy=true >}}
+ [build]
+ [build.buildStats]
+ enable = true
+ [[build.cachebusters]]
+ source = 'assets/notwatching/hugo_stats\.json'
+ target = 'css'
+ [[build.cachebusters]]
+ source = '(postcss|tailwind)\.config\.js'
+ target = 'css'
+ [module]
+ [[module.mounts]]
+ source = 'assets'
+ target = 'assets'
+ [[module.mounts]]
+ disableWatch = true
+ source = 'hugo_stats.json'
+ target = 'assets/notwatching/hugo_stats.json'
+ {{< /code-toggle >}}
+
+Step 3
+: Create a CSS entry file:
+
+ ```css {file="assets/css/main.css" copy=true}
+ @import "tailwindcss";
+ @plugin "@tailwindcss/typography";
+ @source "hugo_stats.json";
+ ```
+
+ Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` is listed in your `.gitignore` file, Tailwind CSS will ignore it. To make `hugo_stats.json` available to Tailwind CSS you must explicitly source it as shown in the example above.
+
+Step 4
+: Create a _partial_ template to process the CSS with the Tailwind CSS CLI:
+
+ ```go-html-template {file="layouts/_partials/css.html" copy=true}
+ {{ with resources.Get "css/main.css" }}
+ {{ $opts := dict "minify" (not hugo.IsDevelopment) }}
+ {{ with . | css.TailwindCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ ```
+
+Step 5
+: Call the _partial_ template from your base template, deferring template execution until after all sites and output formats have been rendered:
+
+ ```go-html-template {file="layouts/baseof.html" copy=true}
+ <head>
+ ...
+ {{ with (templates.Defer (dict "key" "global")) }}
+ {{ partial "css.html" . }}
+ {{ end }}
+ ...
+ </head>
+ ```
+
+## Options
+
+minify
+: (`bool`) Whether to optimize and minify the output. Default is `false`.
+
+optimize
+: (`bool`) Whether to optimize the output without minifying. Default is `false`.
+
+disableInlineImports
+: {{< new-in 0.147.4 />}}
+: (`bool`) Whether to disable inlining of `@import` statements. Inlining is performed recursively, but currently once only per file. It is not possible to import the same file in different scopes (root, media query, etc.). Note that this import routine does not care about the CSS specification, so you can have `@import` statements anywhere in the file. Default is `false`.
+
+skipInlineImportsNotFound
+: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. It is important to note that the inline importer does not process URL-based imports or those with media queries, and these will remain unaltered even when this option is disabled. Default is `false`.
--- /dev/null
- 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.
+---
+title: try
+description: Returns a TryValue object after evaluating the given expression.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: TryValue
+ signatures: ['try EXPRESSION']
+---
+
+{{< new-in 0.141.0 />}}
+
- 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.
++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.
+
+## Methods
+
+The `TryValue` object encapsulates the result of evaluating the expression, and provides two methods:
+
+### Err
+
+(`string`) Returns a string representation of the error thrown by the expression, if an error occurred, or returns `nil` if the expression evaluated without errors.
+
+### Value
+
+(`any`) Returns the result of the expression if the evaluation was successful, or returns `nil` if an error occurred while evaluating the expression.
+
+## Explanation
+
+By way of example, let's divide a number by zero:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ $result := div $x $y }}
+{{ printf "%v divided by %v equals %v" $x $y .Value }}
+```
+
+As expected, the example above throws an error and fails the build:
+
+```terminfo
+Error: error calling div: can't divide the value by 0
+```
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ with try (div $x $y) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else }}
+ {{ printf "%v divided by %v equals %v" $x $y .Value }}
+ {{ end }}
+{{ end }}
+```
+
+The error thrown by the expression is logged to the console as a warning:
+
+```terminfo
+WARN error calling div: can't divide the value by 0
+```
+
+Now let's change the arguments to avoid dividing by zero:
+
+```go-html-template
+{{ $x := 42 }}
+{{ $y := 6 }}
+{{ with try (div $x $y) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else }}
+ {{ printf "%v divided by %v equals %v" $x $y .Value }}
+ {{ end }}
+{{ end }}
+```
+
+Hugo renders the above to:
+
+```html
+42 divided by 6 equals 7
+```
+
+## Example
+
- 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.
++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.
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ warnf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
- [text/template]: https://pkg.go.dev/text/template
++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.
+
+> [!note]
+> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
+[template context]: /templates/introduction/#template-context
++[`text/template`]: https://pkg.go.dev/text/template
--- /dev/null
- {{ hugo.Generator }} → <meta name="generator" content="Hugo 0.156.0">
+---
+title: hugo.Generator
+description: Renders an HTML meta element identifying the software that generated the site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: template.HTML
+ signatures: [hugo.Generator]
+---
+
+```go-html-template
++{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.158.0">
+```
--- /dev/null
- languageCode = 'de-DE'
- languageName = 'Deutsch'
+---
+title: hugo.IsMultihost
+description: Reports whether each configured language has a unique base URL.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsMultihost]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages]
+ [languages.de]
+ baseURL = 'https://de.example.org/'
- languageCode = 'en-US'
- languageName = 'English'
++ label = 'Deutsch'
++ locale = 'de-DE'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.en]
+ baseURL = 'https://en.example.org/'
++ label = 'English'
++ locale = 'en-US'
+ title = 'Project Documentation'
+ weight = 2
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ hugo.IsMultihost }} → true
+```
--- /dev/null
- languageCode = 'de-DE'
- languageName = 'Deutsch'
+---
+title: hugo.IsMultilingual
+description: Reports whether there are two or more configured languages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [hugo.IsMultilingual]
+---
+
+Project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+[languages]
+ [languages.de]
- languageCode = 'en-US'
- languageName = 'English'
++ label = 'Deutsch'
++ locale = 'de-DE'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.en]
++ label = 'English'
++ locale = 'en-US'
+ title = 'Project Documentation'
+ weight = 2
+{{< /code-toggle >}}
+
+Template:
+
+```go-html-template
+{{ hugo.IsMultilingual }} → true
+```
--- /dev/null
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
+---
+title: hugo.Sites
+description: Returns a collection of all sites for all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: page.Sites
+ signatures: [hugo.Sites]
+---
+
+{{< new-in 0.156.0 />}}
+
+{{% include "/_common/functions/hugo/sites-collection.md" %}}
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+defaultContentVersionInSubdir = true
+
+[languages.de]
+contentDir = 'content/de'
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
++direction = 'ltr'
++label = 'Deutsch'
++locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+contentDir = 'content/en'
++direction = 'ltr'
++label = 'English'
++locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+
+[versions.'v1.0.0']
+[versions.'v2.0.0']
+[versions.'v3.0.0']
+{{< /code-toggle >}}
+
+This template:
+
+```go-html-template
+<ul>
+ {{ range hugo.Sites }}
+ <li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+Produces a list of links to each home page:
+
+```html
+<ul>
+ <li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
+ <li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
+ <li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
+ <li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
+</ul>
+```
+
+To render a link to the home page of the [default site](g):
+
+```go-html-template
+{{ with hugo.Sites.Default }}
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
+{{ end }}
+```
+
+This is equivalent to:
+
+```go-html-template
+{{ with index hugo.Sites 0 }}
+ <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
+{{ end }}
+```
--- /dev/null
- {{ hugo.Version }} → 0.156.0
+---
+title: hugo.Version
+description: Returns the current version of the Hugo binary.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: hugo.VersionString
+ signatures: [hugo.Version]
+---
+
+```go-html-template
++{{ hugo.Version }} → 0.158.0
+```
--- /dev/null
- See [image processing] for an overview of Hugo's image pipeline.
+---
+title: images.Config
+description: Returns an image.Config structure from the image at the specified path, relative to the working directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: image.Config
+ signatures: [images.Config PATH]
+aliases: [/functions/imageconfig]
+---
+
- 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.
+
+```go-html-template
+{{ $ic := images.Config "/static/images/a.jpg" }}
+
+{{ $ic.Width }} → 600 (int)
+{{ $ic.Height }} → 400 (int)
+```
+
++Supported image formats include AVIF, BMP, GIF, HEIC, HEIF, JPEG, PNG, TIFF, and WebP.
+
+[`Height`]: /methods/resource/height/
+[`Width`]: /methods/resource/width/
+[image processing]: /content-management/image-processing/
--- /dev/null
- signatures: [images.Filter FILTERS... IMAGE]
+---
+title: images.Filter
+description: Applies one or more image filters to the given image resource.
+categories: []
+keywords: [filter]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.ImageResource
- Apply one or more [image filters](#image-filters) to the given image.
++ signatures: [images.Filter FILTER... RESOURCE]
+---
+
- You can also apply image filters using the [`Filter`] method on a `Resource` object.
-
- [`Filter`]: /methods/resource/filter/
++{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
++
++The `images.Filter` function returns a new resource from a [processable image](g) after applying one or more [image filters](#image-filters).
++
++> [!note]
++> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
++
++## Usage
++
++Use the `images.Filter` function to apply effects such as blurring, sharpening, or grayscale conversion. You can pass a single filter or a slice of filters. When providing a slice, Hugo applies the filters from left to right.
+
+To apply a single filter:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter images.Grayscale . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To apply two or more filters, executing from left to right:
+
+```go-html-template
+{{ $filters := slice
+ images.Grayscale
+ (images.GaussianBlur 8)
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter $filters . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
- {{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
++You can also apply image filters using the [`Filter`][] method on a `Resource` object.
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with images.Filter images.Grayscale . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Grayscale"
+ filterArgs=""
+ example=true
+>}}
+
+## Image filters
+
+Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object.
+
++{{% render-list-of-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
++
++[`Filter`]: /methods/resource/filter/
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
--- /dev/null
- In the example above, `"crop 200x200 TopRight webp q50"` is the _processing specification_.
+---
+title: images.Process
+description: Returns an image filter that processes an image according to the given processing specification.
+categories: []
+keywords: [process]
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: images.filter
+ signatures: [images.Process SPECIFICATION]
+---
+
+Returns an image filter that processes an image according to the given [processing specification][]. This versatile filter supports the full range of image transformations, including resizing, cropping, rotation, and format conversion, all within a single specification string. Use this as an argument to the [`Filter`][] method or the [`images.Filter`][] function.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ $filter := images.Process "crop 200x200 TopRight webp q50" }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
++In the example above, `"crop 200x200 TopRight webp q50"` is the processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Usage
+
+Create a filter:
+
+```go-html-template
+{{ $filter := images.Process "crop 200x200 TopRight webp q50" }}
+```
+
+{{% include "/_common/functions/images/apply-image-filter.md" %}}
+
+## Example
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="crop 200x200 TopRight webp q50"
+ example=true
+>}}
+
+[`Filter`]: /methods/resource/filter/
+[`images.Filter`]: /functions/images/filter
+[processing specification]: #processing-specification
--- /dev/null
- : Install the required Node.js packages in the root of your project.
+---
+title: js.Babel
+description: Compile the given JavaScript resource with Babel.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [babel]
+ returnType: resource.Resource
+ signatures: ['js.Babel [OPTIONS] RESOURCE']
++aliases: [/functions/resources/babel/]
+---
+
+```go-html-template
+{{ with resources.Get "js/main.js" }}
+ {{ $opts := dict
+ "minified" hugo.IsProduction
+ "noComments" hugo.IsProduction
+ "sourceMap" (cond hugo.IsProduction "none" "external")
+ }}
+ {{ with . | js.Babel $opts }}
+ {{ if hugo.IsProduction }}
+ {{ with . | fingerprint }}
+ <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
+ {{ end }}
+ {{ else }}
+ <script src="{{ .RelPermalink }}"></script>
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Setup
+
+Step 1
+: Install [Node.js](https://nodejs.org/en/download)
+
+Step 2
++: Install the required Node packages in the root of your project.
+
+ ```sh
+ npm install --save-dev @babel/core @babel/cli
+ ```
+
+Step 3
+: Add the babel executable to Hugo's `security.exec.allow` list in your project configuration:
+
+ {{< code-toggle file=hugo >}}
+ [security.exec]
+ allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$', '^babel$']
+ {{< /code-toggle >}}
+
+## Configuration
+
+We add the main project's `node_modules` to `NODE_PATH` when running Babel and similar tools. There are some known [issues](https://github.com/babel/babel/issues/5618) with Babel in this area, so if you have a `babel.config.js` living in a Hugo Module (and not in the project itself), we recommend using `require` to load the presets/plugins, e.g.:
+
+```js
+module.exports = {
+ presets: [
+ [
+ require("@babel/preset-env"),
+ {
+ useBuiltIns: "entry",
+ corejs: 3,
+ },
+ ],
+ ],
+};
+```
+
+## Options
+
+compact
+: (`bool`) Whether to remove optional newlines and whitespace. Enabled when `minified` is `true`. Default is `false`
+
+config
+: (`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` file in the root of your project. See [details](https://babeljs.io/docs/en/configuration).
+
+minified
+: (`bool`) Whether to minify the compiled code. Enables the `compact` option. Default is `false`.
+
+noBabelrc
+: (`string`) Whether to ignore `.babelrc` and `.babelignore` files. Default is `false`.
+
+noComments
+: (`bool`) Whether to remove comments. Default is `false`.
+
+sourceMap
+: (`string`) Whether to generate source maps, one of `external`, `inline`, or `none`. Default is `none`.
+
+verbose
+: (`bool`) Whether to enable verbose logging. Default is `false`
+
+<!--
+In the above, technically "none" is not one of the enumerated sourceMap
+values but it has the same effect and is easier to document than an empty string.
+-->
--- /dev/null
- "minify" (not hugo.IsDevelopment)
- "sourceMap" (cond hugo.IsDevelopment "external" "")
- "targetPath" "js/main.js"
+---
+title: js.Build
+description: Bundle, transpile, tree shake, and minify JavaScript resources.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['js.Build [OPTIONS] RESOURCE']
+---
+
+The `js.Build` function uses the [evanw/esbuild] package to:
+
+- Bundle
+- Transpile (TypeScript and JSX)
+- Tree shake
+- Minify
+- Create source maps
+
+```go-html-template
+{{ with resources.Get "js/main.js" }}
+ {{$opts := dict
- `js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
++ "minify" (cond hugo.IsDevelopment false true)
++ "sourceMap" (cond hugo.IsDevelopment "linked" "none")
+ }}
+ {{ with . | js.Build $opts }}
+ {{ if hugo.IsDevelopment }}
+ <script src="{{ .RelPermalink }}"></script>
+ {{ else }}
+ {{ with . | fingerprint }}
+ <script src="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"></script>
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Options
+
+targetPath
+: (`string`) If not set, the source path will be used as the base target path. Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript.
+
+format
+: (`string`) The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag.
+
+{{% include "/_common/functions/js/options.md" %}}
+
+## Import JS code from the assets directory
+
- Use the `js.Build` function to include Node.js dependencies.
++`js.Build` has full support for Hugo's [unified file system](g). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
+
+```js
+import { hello } from 'my/module';
+```
+
+And it will resolve to the top-most `index.{js,ts,tsx,jsx}` inside `assets/my/module` in the layered file system.
+
+```js
+import { hello3 } from 'my/module/hello3';
+```
+
+Will resolve to `hello3.{js,ts,tsx,jsx}` inside `assets/my/module`.
+
+Any imports starting with `.` are resolved relative to the current file:
+
+```js
+import { hello4 } from './lib';
+```
+
+For other files (e.g. `JSON`, `CSS`) you need to use the relative path including any extension, e.g:
+
+```js
+import * as data from 'my/module/data.json';
+```
+
+Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo build`.
+
+Also note the new `params` option that can be passed from template to your JS files, e.g.:
+
+```go-html-template
+{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }}
+```
+
+And then in your JS file:
+
+```js
+import * as params from '@params';
+```
+
+Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/configuration/build/).
+
+## Node.js dependencies
+
++Use the `js.Build` function to include Node dependencies.
+
+Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo build`.
+
+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.
+
+## Examples
+
+```go-html-template
+{{ $built := resources.Get "js/index.js" | js.Build "main.js" }}
+```
+
+Or with options:
+
+```go-html-template
+{{ $externals := slice "react" "react-dom" }}
+{{ $defines := dict "process.env.NODE_ENV" `"development"` }}
+
+{{ $opts := dict "targetPath" "main.js" "externals" $externals "defines" $defines }}
+{{ $built := resources.Get "scripts/main.js" | js.Build $opts }}
+<script src="{{ $built.RelPermalink }}" defer></script>
+```
+
+[evanw/esbuild]: https://github.com/evanw/esbuild
--- /dev/null
- The base name must match the [`languageCode`][] or [language key][] as defined in your project configuration. Hugo selects the translation table based on the `languageCode`, falling back to the language key if a matching translation table does not exist.
+---
+title: lang.Translate
+description: Translates a string using the translation tables in the i18n directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [T, i18n]
+ returnType: string
+ signatures: ['lang.Translate KEY [CONTEXT]']
+aliases: [/functions/i18n]
+---
+
+The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language.
+
+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`][].
+
+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, set [`printI18nWarnings`][] to `true` in your project configuration, or use the `--printI18nWarnings` flag when building your project.
+>
+> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`][] to `true` in your project configuration.
+
+## Translation tables
+
+Create translation tables in the `i18n` directory, naming each file according to [RFC 5646][]. Translation tables may be JSON, TOML, or YAML. For example:
+
+```text
+i18n/en.toml
+i18n/pt-BR.toml
+```
+
- Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
++The base name must match the [`locale`][] or [language key][] as defined in your project configuration. Hugo selects the translation table based on the `locale`, falling back to the language key if a matching translation table does not exist.
+
+Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7][] are also supported. You may omit the `art-x-` prefix for brevity. For example:
+
+```text
+i18n/art-x-hugolang.toml
+i18n/hugolang.toml
+```
+
+> [!note]
+> Private use subtags must not exceed 8 alphanumeric characters.
+
+## Simple translations
+
- Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
++Let's say your multilingual project supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
+
+```text
+i18n/
+├── en.toml
+└── pl.toml
+```
+
+The English translation table:
+
+{{< code-toggle file=i18n/en >}}
+privacy = 'privacy'
+security = 'security'
+{{< /code-toggle >}}
+
+The Polish translation table:
+
+{{< code-toggle file=i18n/pl >}}
+privacy = 'prywatność'
+security = 'bezpieczeństwo'
+{{< /code-toggle >}}
+
+> [!note]
+> The examples below use the `T` alias for brevity.
+
+When viewing the English language site:
+
+```go-html-template
+{{ T "privacy" }} → privacy
+{{ T "security" }} → security
+````
+
+When viewing the Polish language site:
+
+```go-html-template
+{{ T "privacy" }} → prywatność
+{{ T "security" }} → bezpieczeństwo
+```
+
+## Translations with pluralization
+
- [`languageCode`]: /configuration/languages/#languagecode
++Let's say your multilingual project supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
+
+```text
+i18n/
+├── en.toml
+└── pl.toml
+```
+
+The Unicode [CLDR Plural Rules chart][CLDR] describes the pluralization categories for each language.
+
+The English translation table:
+
+{{< code-toggle file=i18n/en >}}
+[day]
+one = 'day'
+other = 'days'
+
+[day_with_count]
+one = '{{ . }} day'
+other = '{{ . }} days'
+{{< /code-toggle >}}
+
+The Polish translation table:
+
+{{< code-toggle file=i18n/pl >}}
+[day]
+one = 'miesiąc'
+few = 'miesiące'
+many = 'miesięcy'
+other = 'miesiąca'
+
+[day_with_count]
+one = '{{ . }} miesiąc'
+few = '{{ . }} miesiące'
+many = '{{ . }} miesięcy'
+other = '{{ . }} miesiąca'
+{{< /code-toggle >}}
+
+> [!note]
+> The examples below use the `T` alias for brevity.
+
+When viewing the English language site:
+
+```go-html-template
+{{ T "day" 0 }} → days
+{{ T "day" 1 }} → day
+{{ T "day" 2 }} → days
+{{ T "day" 5 }} → days
+
+{{ T "day_with_count" 0 }} → 0 days
+{{ T "day_with_count" 1 }} → 1 day
+{{ T "day_with_count" 2 }} → 2 days
+{{ T "day_with_count" 5 }} → 5 days
+````
+
+When viewing the Polish language site:
+
+```go-html-template
+{{ T "day" 0 }} → miesięcy
+{{ T "day" 1 }} → miesiąc
+{{ T "day" 2 }} → miesiące
+{{ T "day" 5 }} → miesięcy
+
+{{ T "day_with_count" 0 }} → 0 miesięcy
+{{ T "day_with_count" 1 }} → 1 miesiąc
+{{ T "day_with_count" 2 }} → 2 miesiące
+{{ T "day_with_count" 5 }} → 5 miesięcy
+```
+
+In the pluralization examples above, we passed an integer in context (the second argument). You can also pass a map in context, providing a `count` key to control pluralization.
+
+Translation table:
+
+{{< code-toggle file=i18n/en >}}
+[age]
+one = '{{ .name }} is {{ .count }} year old.'
+other = '{{ .name }} is {{ .count }} years old.'
+{{< /code-toggle >}}
+
+Template code:
+
+```go-html-template
+{{ T "age" (dict "name" "Will" "count" 1) }} → Will is 1 year old.
+{{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old.
+```
+
+> [!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:
+
+id
+: (`string`) Uniquely identifies the message.
+
+description
+: (`string`) Describes the message to give additional context to translators that may be relevant for translation.
+
+hash
+: (`string`) Uniquely identifies the content of the message that this message was translated from.
+
+leftdelim
+: (`string`) The left Go template delimiter.
+
+rightdelim
+: (`string`) The right Go template delimiter.
+
+zero
+: (`string`) The content of the message for the [CLDR][] plural form "zero".
+
+one
+: (`string`) The content of the message for the [CLDR][] plural form "one".
+
+two
+: (`string`) The content of the message for the [CLDR][] plural form "two".
+
+few
+: (`string`) The content of the message for the [CLDR][] plural form "few".
+
+many
+: (`string`) The content of the message for the [CLDR][] plural form "many".
+
+other
+: (`string`) The content of the message for the [CLDR][] plural form "other".
+
+If you need to provide a translation for one of the reserved keys, you can prepend the word with an underscore. For example:
+
+{{< code-toggle file=i18n/es >}}
+_description = 'descripción'
+_few = 'pocos'
+_many = 'muchos'
+_one = 'uno'
+_other = 'otro'
+_two = 'dos'
+_zero = 'cero'
+{{< /code-toggle >}}
+
+Then in your templates:
+
+```go-html-template
+{{ T "_description" }} → descripción
+{{ T "_few" }} → pocos
+{{ T "_many" }} → muchos
+{{ T "_one" }} → uno
+{{ T "_two" }} → dos
+{{ T "_zero" }} → cero
+{{ T "_other" }} → otro
+```
+
+[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
+[`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders
++[`locale`]: /configuration/languages/#locale
+[`printI18nWarnings`]: /configuration/all/#printi18nwarnings
+[CLDR]: https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
+[go-i18n]: https://github.com/nicksnyder/go-i18n
+[language key]: /configuration/languages/#language-keys
+[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
--- /dev/null
- The counter is global for both monolingual and multilingual sites, and its initial value for each build is 1.
+---
+title: math.Counter
+description: Increments and returns a global counter.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: uint64
+ signatures: [math.Counter]
+---
+
++The counter is global for both monolingual and multilingual projects, and its initial value for each build is 1.
+
+```go-html-template {file="layouts/page.html"}
+{{ warnf "page.html called %d times" math.Counter }}
+```
+
+```text
+WARN page.html called 1 times
+WARN page.html called 2 times
+WARN page.html called 3 times
+```
+
+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
+
+> [!note]
+> Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page.
+
+[`warnf`]: /functions/fmt/warnf/
--- /dev/null
- description: Reports whether the given value is a Resource object representing a processable image.
+---
+title: reflect.IsImageResource
- {{% glossary-term "processable image" %}}
++description: Reports whether the given value is a Resource object representing an image as defined by its media type.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsImageResource INPUT]
+---
+
+{{< new-in 0.154.0 />}}
+
- With this project structure:
++## Usage
+
- ```text
- project/
- ├── assets/
- │ ├── a.json
- │ ├── b.avif
- │ └── c.jpg
- └── content/
- └── example/
- ├── index.md
- ├── d.json
- ├── e.avif
- └── f.jpg
- ```
-
- These are the values returned by the `reflect.IsImageResource` function:
-
- ```go-html-template {file="layouts/page.html"}
- {{ with resources.Get "a.json" }}
- {{ reflect.IsImageResource . }} → false
- {{ end }}
-
- {{ with resources.Get "b.avif" }}
- {{ reflect.IsImageResource . }} → false
- {{ end }}
-
- {{ with resources.Get "c.jpg" }}
- {{ reflect.IsImageResource . }} → true
- {{ end }}
- ```
-
- In the example above, the `b.avif` image is not a processable image because Hugo can neither decode nor encode the AVIF image format.
-
- ```go-html-template {file="layouts/page.html"}
- {{ with .Resources.Get "d.json" }}
- {{ reflect.IsImageResource . }} → false
- {{ end }}
-
- {{ with .Resources.Get "e.avif" }}
- {{ reflect.IsImageResource . }} → false
- {{ end }}
-
- {{ with .Resources.Get "f.jpg" }}
- {{ reflect.IsImageResource . }} → true
++This example iterates through all project resources and uses `reflect.IsImageResource` to decide whether to render an image tag or provide a download link for non-image files.
+
- In the example above, the `e.avif` image is not a processable image because Hugo can neither decode nor encode the AVIF image format.
-
- ```go-html-template {file="layouts/page.html"}
- {{ with site.GetPage "/example" }}
- {{ reflect.IsImageResource . }} → false
- {{ end }}
- ```
++```go-html-template
++{{ range resources.Match "**" }}
++ {{ if reflect.IsImageResource . }}
++ <img src="{{ .RelPermalink }}" alt="Image">
++ {{ else }}
++ <a href="{{ .RelPermalink }}">Download</a>
++ {{ end }}
+{{ end }}
+```
+
++{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
--- /dev/null
--- /dev/null
++---
++title: reflect.IsImageResourceProcessable
++description: Reports whether the given value is a Resource object representing an image from which Hugo can extract dimensions and perform processing such as converting, resizing, cropping, or filtering.
++categories: []
++keywords: []
++params:
++ functions_and_methods:
++ aliases: []
++ returnType: bool
++ signatures: [reflect.IsImageResourceProcessable INPUT]
++---
++
++{{< new-in 0.157.0 />}}
++
++{{% glossary-term "processable image" %}}
++
++## Usage
++
++This example iterates through all project resources and uses `reflect.IsImageResourceProcessable` to ensure the image pipeline can perform transformations like resizing before processing begins.
++
++```go-html-template
++{{ range resources.Match "**" }}
++ {{ if reflect.IsImageResourceProcessable . }}
++ {{ with .Process "resize 300x webp" }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="Processed Image">
++ {{ end }}
++ {{ end }}
++{{ end }}
++```
++
++{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
--- /dev/null
--- /dev/null
++---
++title: reflect.IsImageResourceWithMeta
++description: Reports whether the given value is a Resource object representing an image from which Hugo can extract dimensions and, if present, Exif, IPTC, and XMP data.
++categories: []
++keywords: []
++params:
++ functions_and_methods:
++ aliases: []
++ returnType: bool
++ signatures: [reflect.IsImageResourceWithMeta INPUT]
++---
++
++{{< new-in 0.157.0 />}}
++
++## Usage
++
++This example iterates through all project resources and uses `reflect.IsImageResourceWithMeta` to safely display image dimensions and metadata only for supported formats.
++
++```go-html-template
++{{ range resources.Match "**" }}
++ {{ if reflect.IsImageResourceWithMeta . }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="Image with Meta">
++ {{ with .Meta }}
++ <p>Taken on: {{ .Date }}</p>
++ {{ end }}
++ {{ end }}
++{{ end }}
++```
++
++{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
--- /dev/null
- "build_date": "2026-01-11T11:27:49-08:00",
- "hugo_version": "0.156.0",
- "last_modified": "2026-01-11T11:27:59-08:00"
+---
+title: resources.FromString
+description: Returns a resource created from a string.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: [resources.FromString TARGETPATH STRING]
+---
+
+The `resources.FromString` function returns a resource created from a string, caching the result using the target path as its cache key.
+
+Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
+
+[`publish`]: /methods/resource/publish/
+[`permalink`]: /methods/resource/permalink/
+[`relpermalink`]: /methods/resource/relpermalink/
+
+Let's say you need to publish a file named "site.json" in the root of your `public` directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example:
+
+```json
+{
++ "build_date": "2026-03-16T13:56:25-07:00",
++ "hugo_version": "0.158.0",
++ "last_modified": "2026-02-16T12:04:52-07:00"
+}
+```
+
+Place this in your baseof.html template:
+
+```go-html-template
+{{ if .IsHome }}
+ {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }}
+ {{ $m := dict
+ "hugo_version" hugo.Version
+ "build_date" (now.Format $rfc3339)
+ "last_modified" (site.Lastmod.Format $rfc3339)
+ }}
+ {{ $json := jsonify $m }}
+ {{ $r := resources.FromString "site.json" $json }}
+ {{ $r.Publish }}
+{{ end }}
+```
+
+The example above:
+
+1. Creates a map with the relevant key-value pairs using the [`dict`] function
+1. Encodes the map as a JSON string using the [`jsonify`] function
+1. Creates a resource from the JSON string using the `resources.FromString` function
+1. Publishes the file to the root of the `public` directory using the resource's `.Publish` method
+
+Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your string contains template actions. Rewriting the example above:
+
+```go-html-template
+{{ if .IsHome }}
+ {{ $string := `
+ {{ $rfc3339 := "2006-01-02T15:04:05Z07:00" }}
+ {{ $m := dict
+ "hugo_version" hugo.Version
+ "build_date" (now.Format $rfc3339)
+ "last_modified" (site.Lastmod.Format $rfc3339)
+ }}
+ {{ $json := jsonify $m }}
+ `
+ }}
+ {{ $r := resources.FromString "" $string }}
+ {{ $r = $r | resources.ExecuteAsTemplate "site.json" . }}
+ {{ $r.Publish }}
+{{ end }}
+```
+
+[`dict`]: /functions/collections/dictionary/
+[`jsonify`]: /functions/encoding/jsonify/
+[`resources.ExecuteAsTemplate`]: /functions/resources/executeastemplate/
--- /dev/null
- timeout
- : (`string`) Cancels the request if it does not complete within this duration (e.g. "30s").
-
+---
+title: resources.GetRemote
+description: Returns a remote resource from the given URL, or nil if none found.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['resources.GetRemote URL [OPTIONS]']
+---
+
+{{< new-in 0.141.0 >}}
+The `Err` method on the returned resource was removed in v0.141.0.
+
+Use the [`try`](/functions/go-template/try) statement instead, as shown in the [error handling](#error-handling) example below.
+{{< /new-in >}}
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+## Options
+
+The `resources.GetRemote` function takes an optional map of options.
+
+body
+: (`string`) The data you want to transmit to the server.
+
+headers
+: (`map[string][]string`) The collection of key-value pairs that provide additional information about the request.
+
+key
+: (`string`) The cache key. Hugo derives the default value from the URL and options map. See [caching](#caching).
+
+method
+: (`string`) The action to perform on the requested resource, typically one of `GET`, `POST`, or `HEAD`.
+
- : (`[]string`) The headers to extract from the server's response, accessible through the resource's [`Data.Headers`] method. Header name matching is case-insensitive.[`Data.Headers`]: /methods/resource/data/#headers
+responseHeaders
+: {{< new-in 0.143.0 />}}
- > For brevity, the examples below do not include [error handling].
++: (`[]string`) The headers to extract from the server's response, accessible through the resource's [`Data.Headers`][] method. Header name matching is case-insensitive.
++
++timeout
++: {{< new-in 0.157.0 />}}
++: (`string`) The duration after which the request is cancelled if it does not complete, expressed as a [duration](g). If not specified, the request will timeout after 2 minutes.
+
+## Options examples
+
+> [!note]
- To set a per-request timeout (e.g. when fetching many feeds where a few slow ones should not stall the build):
++> For brevity, the examples below do not include [error handling][].
+
+To include a header:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "headers" (dict "Authorization" "Bearer abcd")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+To specify more than one value for the same header key, use a slice:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "headers" (dict "X-List" (slice "a" "b" "c"))
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+To post data:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "method" "post"
+ "body" `{"complete": true}`
+ "headers" (dict "Content-Type" "application/json")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+To override the default cache key:
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ $opts := dict
+ "key" (print $url (now.Format "2006-01-02"))
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+To extract specific headers from the server's response:
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ $opts := dict
+ "method" "HEAD"
+ "responseHeaders" (slice "X-Frame-Options" "Server")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
- When retrieving remote data, use the [`transform.Unmarshal`] function to [unmarshal](g) the response.
-
- [`transform.Unmarshal`]: /functions/transform/unmarshal/
++Use the `timeout` option to prevent slow external requests from stalling the build when fetching multiple remote feeds:
+
+```go-html-template
+{{ $url := "https://example.org/feed.rss" }}
+{{ $opts := dict "timeout" "10s" }}
+{{ with try (resources.GetRemote $url $opts) }}
+ {{ with .Err }}
+ {{ warnf "Failed to fetch feed: %s" . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ end }}
+```
+
+## Remote data
+
- > 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`.
++When retrieving remote data, use the [`transform.Unmarshal`][] function to [unmarshal](g) the response.
+
+```go-html-template
+{{ $data := dict }}
+{{ $url := "https://example.org/books.json" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+> [!note]
- Use the [`try`] statement to capture HTTP request errors. If you do not handle the error yourself, Hugo will fail the build.
++> 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
+
- The [`Data`] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response.
-
- [`Data`]: /methods/resource/data/
++Use the [`try`][] statement to capture HTTP request errors. If you do not handle the error yourself, Hugo will fail the build.
+
+> [!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" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+To log an error as a warning instead of an error:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ warnf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+
+## HTTP response
+
- Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details.
++The [`Data`][] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response.
+
+## Caching
+
- - The [Content-Type] in the response header
++Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches][] for details.
+
+By default, Hugo derives the cache key from the arguments passed to the function. Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource.
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ $cacheKey := print $url (now.Format "2006-01-02") }}
+{{ $opts := dict "key" $cacheKey }}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+## Security
+
+To protect against malicious intent, the `resources.GetRemote` function inspects the server response including:
+
- If Hugo is unable to resolve the media type to an entry in its [allowlist], the function throws an error:
++- The [Content-Type][] in the response header
+- The file extension, if any
+- The content itself
+
++If Hugo is unable to resolve the media type to an entry in its [allowlist][], the function throws an error:
+
+```text
+ERROR error calling resources.GetRemote: failed to resolve media type...
+```
+
+For example, you will see the error above if you attempt to download an executable.
+
+Although the allowlist contains entries for common media types, you may encounter situations where Hugo is unable to resolve the media type of a file that you know to be safe. In these situations, edit your project configuration to add the media type to the allowlist. For example:
+
+{{< code-toggle file=hugo >}}
+[security.http]
+mediaTypes = ['^image/avif$','^application/vnd\.api\+json$']
+{{< /code-toggle >}}
+
+Note that the entry above is:
+
+- An _addition_ to the allowlist; it does not _replace_ the allowlist
+- An array of [regular expressions](g)
+
++[`Data.Headers`]: /methods/resource/data/#headers
++[`Data`]: /methods/resource/data/
++[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[`try`]: /functions/go-template/try
+[allowlist]: https://en.wikipedia.org/wiki/Whitelist
+[configure file caches]: /configuration/caches/
+[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
+[error handling]: #error-handling
--- /dev/null
- : Install the required Node.js packages in the root of your project:
+---
+title: resources.PostProcess
+description: Processes the given resource after the build.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: postpub.PostPublishedResource
+ signatures: [resources.PostProcess RESOURCE]
+---
+
+The `resources.PostProcess` function delays resource transformation steps until the build is complete, primarily for tasks like removing unused CSS rules.
+
+## Example
+
+In this example, after the build is complete, Hugo will:
+
+1. Purge unused CSS using the [PurgeCSS] plugin for [PostCSS]
+1. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS
+1. [Minify] the CSS
+1. [Fingerprint] the CSS
+
+Step 1
+: Install [Node.js].
+
+Step 2
++: Install the required Node packages in the root of your project:
+
+ ```sh {copy=true}
+ 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`].
+
+ {{< code-toggle file=hugo copy=true >}}
+ [build.buildStats]
+ enable = true
+ {{< /code-toggle >}}
+
+ See the [configure build] documentation for details and options.
+
+Step 4
+: Create a PostCSS configuration file in the root of your project.
+
+ ```js {file="postcss.config.js" copy=true}
+ const autoprefixer = require('autoprefixer');
+ const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default;
+
+ const purgecss = purgeCSSPlugin({
+ content: ['./hugo_stats.json'],
+ defaultExtractor: content => {
+ const els = JSON.parse(content).htmlElements;
+ return [
+ ...(els.tags || []),
+ ...(els.classes || []),
+ ...(els.ids || []),
+ ];
+ },
+ // https://purgecss.com/safelisting.html
+ safelist: []
+ });
+
+ module.exports = {
+ plugins: [
+ process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
+ autoprefixer,
+ ]
+ };
+ ```
+
+ > [!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.
+
+Step 6
+: If the current environment is not `development`, process the resource with PostCSS:
+
+ ```go-html-template {copy=true}
+ {{ with resources.Get "css/main.css" }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | postCSS | minify | fingerprint | resources.PostProcess }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ ```
+
+## Environment variables
+
+Hugo passes the environment variables below to PostCSS, allowing you to do something like:
+
+```js
+process.env.HUGO_ENVIRONMENT !== 'development' ? purgecss : null,
+```
+
+PWD
+: The absolute path to the project working directory.
+
+HUGO_ENVIRONMENT
+: The current Hugo environment, set with the `--environment` command line flag.
+Default is `production` for `hugo build` and `development` for `hugo server`.
+
+HUGO_PUBLISHDIR
+: The absolute path to the publish directory, typically `public`. This value points to a directory on disk, even when rendering to memory with the `--renderToMemory` command line flag.
+
+HUGO_FILE_X
+: Hugo automatically mounts the following files from your project's root directory under `assets/_jsconfig`:
+
+- `babel.config.js`
+- `postcss.config.js`
+- `tailwind.config.js`
+
+For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores. This allows you to access these files within your JavaScript, for example:
+
+```js
+let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js';
+```
+
+## Limitations
+
+Do not use `resources.PostProcess` when running Hugo's built-in development server. The examples above specifically prevent this by verifying that the current environment is not `development`.
+
+The `resources.PostProcess` function only works within templates that produce HTML files.
+
+You cannot manipulate the values returned from the resource's methods. For example, the `strings.ToUpper` function in this example will not work as expected:
+
+```go-html-template
+{{ $css := resources.Get "css/main.css" }}
+{{ $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
--- /dev/null
--- /dev/null
++---
++title: strings.ReplacePairs
++description: Returns a copy of a string with multiple replacements performed in a single pass, using a slice of old and new string pairs.
++categories: []
++keywords: []
++params:
++ functions_and_methods:
++ aliases: []
++ returnType: string
++ signatures: ['strings.ReplacePairs OLD NEW [OLD NEW ...] INPUT']
++---
++
++{{< new-in 0.158.0 />}}
++
++Use the `strings.ReplacePairs` function to perform multiple replacements on a string in a single operation. This approach is faster than sequentially calling the [`strings.Replace`][] function.
++
++Replacing strings sequentially requires multiple function calls and variable re-assignments.
++
++```go-html-template
++{{ $s := "aabbcc" }}
++{{ $s = strings.Replace $s "a" "x" }}
++{{ $s = strings.Replace $s "b" "y" }}
++{{ $s = strings.Replace $s "c" "z" }}
++{{ $s }} → xxyyzz
++```
++
++Using `strings.ReplacePairs` produces the same result with fewer function calls in less time.
++
++```go-html-template
++{{ "aabbcc" | strings.ReplacePairs "a" "x" "b" "y" "c" "z" }} → xxyyzz
++```
++
++Pairs may also be passed as a single slice:
++
++```go-html-template
++{{ $pairs := slice
++ "a" "x"
++ "b" "y"
++ "c" "z"
++}}
++{{ "aabbcc" | strings.ReplacePairs $pairs }} → xxyyzz
++```
++
++## Examples
++
++Observe that replacements are not applied recursively because the function scans the string only once.
++
++```go-html-template
++{{ $pairs := slice
++ "a" "b"
++ "b" "c"
++}}
++{{ "a" | strings.ReplacePairs $pairs }} → b
++```
++
++Apply the first match when multiple old strings could match at the same position.
++
++```go-html-template
++{{ $pairs := slice
++ "app" "pear"
++ "apple" "orange"
++}}
++{{ "apple" | strings.ReplacePairs $pairs }} → pearle
++```
++
++Delete specific strings by providing an empty string as the second value in a pair.
++
++```go-html-template
++{{ $pairs := slice "b" "" }}
++{{ "abc" | strings.ReplacePairs $pairs }} → ac
++```
++
++## Edge cases
++
++The table below outlines how the function handles various input scenarios.
++
++Scenario|Result
++:--|:--
++Fewer than two arguments|Error
++Odd number of slice elements|Error
++Empty slice|Returns the input string
++Empty input string|Returns an empty string
++Empty old string|Returns the input string [interleaved](g) with the new string
++
++## Performance
++
++While `strings.Replace` and `strings.ReplacePairs` can produce the same results, they handle data differently. Choosing the right one can noticeably reduce the time Hugo takes to build your project.
++
++### Single pass vs. multiple passes
++
++When using `strings.Replace`, Hugo must scan the text from start to finish to find a match. If you chain three replacements together, Hugo performs three separate passes over the entire string.
++
++The `strings.ReplacePairs` function is more efficient because it performs a single pass. Hugo looks through the text once and applies all replacements simultaneously.
++
++### Caching
++
++Unlike `strings.Replace`, which performs a direct substitution, `strings.ReplacePairs` requires an initialization step to prepare the single-pass replacement logic. To make this efficient, Hugo manages this logic using a cache:
++
++- During the initial call, Hugo initializes and stores the logic for that specific set of pairs.
++- During subsequent calls, Hugo retrieves the stored logic, skipping the initialization step and reducing the duration of the call.
++
++### Choosing the right function
++
++The efficiency of `strings.ReplacePairs` increases as the text gets longer or the number of pairs grows. Consider these scenarios when deciding which function to use:
++
++- For a single replacement on a short string like a title, `strings.Replace` is efficient.
++- For multiple replacements or long strings like a long-form article, `strings.ReplacePairs` is much faster.
++
++For a document with about 8000 characters, which is roughly the length of a long-form article, `strings.ReplacePairs` outperforms five sequential `strings.Replace` calls during the initial call. Once cached, it is the faster choice for almost any situation with two or more pairs.
++
++[`strings.Replace`]: /functions/strings/replace/
--- /dev/null
- {{< new-in 0.128.0 />}}
-
+---
+title: templates.Defer
+description: Defer execution of a template until after all sites and output formats have been rendered.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [templates.Defer OPTIONS]
+aliases: [/functions/templates.defer]
+---
+
- Language Outside: {{ site.Language.Lang }}
+> [!note]
+> This feature should only be used in the main template, typically `layouts/baseof.html`. Using it in _shortcode_, _partial_, or _render hook_ templates may lead to unpredictable results. For further details, please refer to [this issue].
+
+[this issue]: https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391
+
+In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/configuration/build/) to determine which classes and other HTML identifiers are being used in the final output:
+
+```go-html-template {file="layouts/baseof.html" copy=true}
+<head>
+ ...
+ {{ with (templates.Defer (dict "key" "global")) }}
+ {{ partial "css.html" . }}
+ {{ end }}
+ ...
+</head>
+```
+
+```go-html-template {file="layouts/_partials/css.html" copy=true}
+{{ with resources.Get "css/main.css" }}
+ {{ $opts := dict "minify" (not hugo.IsDevelopment) }}
+ {{ with . | css.TailwindCSS $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+> [!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:
+
+{{< code-toggle file=hugo >}}
+[build]
+ [build.buildStats]
+ enable = true
+ [[build.cachebusters]]
+ source = 'assets/notwatching/hugo_stats\.json'
+ target = 'css'
+ [[build.cachebusters]]
+ source = '(postcss|tailwind)\.config\.js'
+ target = 'css'
+[module]
+ [[module.mounts]]
+ source = 'assets'
+ target = 'assets'
+ [[module.mounts]]
+ disableWatch = true
+ source = 'hugo_stats.json'
+ target = 'assets/notwatching/hugo_stats.json'
+{{< /code-toggle >}}
+
+## Options
+
+The `templates.Defer` function takes a single argument, a map with the following optional keys:
+
+key (`string`)
+: The key to use for the deferred template. This will, combined with a hash of the template content, be used as a cache key. If this is not set, Hugo will execute the deferred template on every render. This is not what you want for shared resources like CSS and JavaScript.
+
+data (`map`)
+: Optional map to pass as data to the deferred template. This will be available in the deferred template as `.` or `$`.
+
+```go-html-template
- Language Inside: {{ site.Language.Lang }}
++Language Outside: {{ site.Language.Name }}
+Page Outside: {{ .RelPermalink }}
+I18n Outside: {{ i18n "hello" }}
+{{ $data := (dict "page" . )}}
+{{ with (templates.Defer (dict "data" $data )) }}
- The [output format](/configuration/output-formats/), [site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Lang` and `.RelPermalink` will be the same on the inside and the outside of the deferred template.
++ Language Inside: {{ site.Language.Name }}
+ Page Inside: {{ .page.RelPermalink }}
+ I18n Inside: {{ i18n "hello" }}
+{{ end }}
+```
+
++The [output format](/configuration/output-formats/), [site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Name` and `.RelPermalink` will be the same on the inside and the outside of the deferred template.
--- /dev/null
- The `transform.HTMLUnescape` function replaces [HTML entities] with their corresponding characters.
+---
+title: transform.HTMLUnescape
+description: Returns the given string, replacing each HTML entity with its corresponding character.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: [htmlUnescape]
+ returnType: string
+ signatures: [transform.HTMLUnescape INPUT]
+aliases: [/functions/htmlunescape]
+---
+
- In most contexts Go's [html/template] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`] function.
++The `transform.HTMLUnescape` function replaces [HTML entities][] with their corresponding characters.
+
+```go-html-template
+{{ htmlUnescape "Lilo & Stitch" }} → Lilo & Stitch
+{{ htmlUnescape "7 > 6" }} → 7 > 6
+```
+
- [html/template]: https://pkg.go.dev/html/template
++In most contexts Go's [`html/template`][] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`][] function.
+
+```go-html-template
+{{ htmlUnescape "Lilo & Stitch" | safeHTML }}
+```
+
+[`safehtml`]: /functions/safe/html/
+[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
++[`html/template`]: https://pkg.go.dev/html/template
--- /dev/null
- languageCode = 'en-US'
+---
+title: transform.Remarshal
+description: Marshals a string of serialized data, or a map, into a string of serialized data in the specified format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [transform.Remarshal FORMAT INPUT]
+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.
+
+Example 1
+: Convert a string of TOML to JSON.
+
+```go-html-template
+{{ $s := `
+ baseURL = 'https://example.org/'
- "languageCode": "en-US",
++ locale = 'en-US'
+ title = 'ABC Widgets'
+`}}
+<pre>{{ transform.Remarshal "json" $s }}</pre>
+```
+
+Resulting HTML:
+
+```html
+<pre>{
+ "baseURL": "https://example.org/",
- "languageCode": "en-US",
++ "locale": "en-US",
+ "title": "ABC Widgets"
+}
+</pre>
+```
+
+Rendered in browser:
+
+```text
+{
+ "baseURL": "https://example.org/",
++ "locale": "en-US",
+ "title": "ABC Widgets"
+}
+```
+
+Example 2
+: Convert a map to YAML.
+
+```go-html-template
+{{ $m := dict
+ "a" "Hugo rocks!"
+ "b" (dict "question" "What is 6x7?" "answer" 42)
+ "c" (slice "foo" "bar")
+}}
+<pre>{{ transform.Remarshal "yaml" $m }}</pre>
+```
+
+Resulting HTML:
+
+```html
+<pre>a: Hugo rocks!
+b:
+ answer: 42
+ question: What is 6x7?
+c:
+- foo
+- bar
+</pre>
+```
+
+Rendered in browser:
+
+```text
+a: Hugo rocks!
+b:
+ answer: 42
+ question: What is 6x7?
+c:
+- foo
+- bar
+```
--- /dev/null
- The `transform.XMLEscape` function removes [disallowed characters] as defined in the XML specification, then escapes the result by replacing the following characters with [HTML entities]:
+---
+title: transform.XMLEscape
+description: Returns the given string, removing disallowed characters then escaping the result to its XML equivalent.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: [transform.XMLEscape INPUT]
+---
+
- When using `transform.XMLEscape` in a template rendered by Go's [html/template] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template:
++The `transform.XMLEscape` function removes [disallowed characters][] as defined in the XML specification, then escapes the result by replacing the following characters with [HTML entities]:
+
+- `"` → `"`
+- `'` → `'`
+- `&` → `&`
+- `<` → `<`
+- `>` → `>`
+- `\t` → `	`
+- `\n` → `
`
+- `\r` → `
`
+
+For example:
+
+```go-html-template
+{{ transform.XMLEscape "<p>abc</p>" }} → <p>abc</p>
+```
+
- [html/template]: https://pkg.go.dev/html/template
++When using `transform.XMLEscape` in a template rendered by Go's [`html/template`][] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template:
+
+```xml {file="layouts/rss.xml"}
+<description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
+```
+
+[disallowed characters]: https://www.w3.org/TR/xml/#charsets
+[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
++[`html/template`]: https://pkg.go.dev/html/template
--- /dev/null
- description: Returns the given string, replacing all percent-encoded sequences with the corresponding unescaped characters.
+---
+title: urls.PathEscape
- {{ urls.PathEscape "A/b/c?d=é&f=g+h" }} → A%2Fb%2Fc%3Fd=%C3%A9&f=g+h
++description: Returns the given string, applying percent-encoding to special characters and reserved delimiters so it can be safely used as a segment within a URL path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [urls.PathEscape INPUT]
+---
+
+{{< new-in v0.153.0 />}}
+
+The `urls.PathEscape` function does the inverse transformation of [`urls.PathUnescape`][].
+
+```go-html-template
++{{ urls.PathEscape "my café" }} → my%20caf%C3%A9
+```
+
++Use this function to escape a string so that it can be safely used as an individual segment within a URL path.
++
+[`urls.PathUnescape`]: /functions/urls/PathUnescape/
--- /dev/null
- description: Returns the given string, applying percent-encoding to special characters and reserved delimiters so it can be safely used as a segment within a URL path.
+---
+title: urls.PathUnescape
++description: Returns the given string, replacing all percent-encoded sequences with the corresponding unescaped characters.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [urls.PathUnescape INPUT]
+---
+
+{{< new-in v0.153.0 />}}
+
+The `urls.PathUnescape` function does the inverse transformation of [`urls.PathEscape`][].
+
+```go-html-template
+{{ urls.PathUnescape "A%2Fb%2Fc%3Fd=%C3%A9&f=g+h" }} → A/b/c?d=é&f=g+h
+```
+
++Use this function to decode an individual segment within a URL path.
++
+[`urls.PathEscape`]: /functions/urls/PathEscape/
--- /dev/null
- ## Union file system
+---
+title: Directory structure
+description: An overview of Hugo's directory structure.
+categories: []
+keywords: []
+weight: 30
+aliases: [/overview/source-directory/]
+---
+
+Each Hugo project is a directory, with subdirectories that contribute to content, structure, behavior, and presentation.
+
+## Project skeleton
+
+Hugo generates a project skeleton when you create a new project. For example, this command:
+
+```sh
+hugo new project my-project
+```
+
+Creates this directory structure:
+
+```txt
+my-project/
+├── archetypes/
+│ └── default.md
+├── assets/
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── static/
+├── themes/
+└── hugo.toml <-- project configuration
+```
+
+Depending on requirements, you may wish to organize your project configuration into subdirectories:
+
+```txt
+my-project/
+├── archetypes/
+│ └── default.md
+├── assets/
+├── config/ <-- project configuration
+│ └── _default/
+│ └── hugo.toml
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── static/
+└── themes/
+```
+
+When you build your project, Hugo creates a `public` directory, and typically a `resources` directory as well:
+
+```txt
+my-project/
+├── archetypes/
+│ └── default.md
+├── assets/
+├── config/
+│ └── _default/
+│ └── hugo.toml
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── public/ <-- created when you build your project
+├── resources/ <-- created when you build your project
+├── static/
+└── themes/
+```
+
+## Directories
+
+Each of the subdirectories contributes to content, structure, behavior, or presentation.
+
+archetypes
+: The `archetypes` directory contains templates for new content. See [details](/content-management/archetypes/).
+
+assets
+: The `assets` directory contains global resources typically passed through an asset pipeline. This includes resources such as images, CSS, Sass, JavaScript, and TypeScript. See [details](/hugo-pipes/introduction/).
+
+config
+: The `config` directory contains your project configuration, possibly split into multiple subdirectories and files. For projects with minimal configuration or projects that do not need to behave differently in different environments, a single configuration file named `hugo.toml` in the root of the project is sufficient. See [details](/configuration/introduction/#configuration-directory).
+
+content
+: The `content` directory contains the markup files (typically Markdown) and page resources that comprise the content of your project. See [details](/content-management/organization/).
+
+data
+: The `data` directory contains data files (JSON, TOML, YAML, or XML) that augment content, configuration, localization, and navigation. See [details](/content-management/data-sources/).
+
+i18n
+: The `i18n` directory contains translation tables for multilingual projects. See [details](/content-management/multilingual/).
+
+layouts
+: The `layouts` directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/).
+
+public
+: The `public` directory contains the published website, generated when you run the `hugo build` or `hugo server` commands. Hugo recreates this directory and its content as needed. See [details](/getting-started/usage/#build-your-project).
+
+resources
+: The `resources` directory contains cached output from Hugo's asset pipelines, generated when you run the `hugo build` or `hugo server` commands. By default this cache directory includes CSS and images. Hugo recreates this directory and its content as needed.
+
+static
+: The `static` directory contains files that will be copied to the `public` directory when you build your project. For example: `favicon.ico`, `robots.txt`, and files that verify website ownership. Before the introduction of [page bundles](g) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript.
+
+themes
+: The `themes` directory contains one or more [themes](g), each in its own subdirectory.
+
- Hugo creates a union file system, allowing you to mount two or more directories to the same location. For example, let's say your home directory contains a Hugo project in one directory, and shared content in another:
++## Unified file system
+
- > When you overlay one directory on top of another, you must mount both directories.
++Hugo creates a [unified file system](g), allowing you to mount two or more directories to the same location. For example, let's say your home directory contains a Hugo project in one directory, and shared content in another:
+
+```text
+home/
+└── user/
+ ├── my-project/
+ │ ├── content/
+ │ │ ├── books/
+ │ │ │ ├── _index.md
+ │ │ │ ├── book-1.md
+ │ │ │ └── book-2.md
+ │ │ └── _index.md
+ │ ├── themes/
+ │ │ └── my-theme/
+ │ └── hugo.toml
+ └── shared-content/
+ └── films/
+ ├── _index.md
+ ├── film-1.md
+ └── film-2.md
+```
+
+You can include the shared content using mounts. In your project configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'content'
+target = 'content'
+
+[[module.mounts]]
+source = '/home/user/shared-content'
+target = 'content'
+{{< /code-toggle >}}
+
+> [!note]
- > Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead.
++> Defining a custom mount replaces the default mounting for that [component](g). To overlay an external directory on top of the project default, you must explicitly mount both.
+>
- After mounting, the union file system has this structure:
++> Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's unified file system instead.
+
- > [!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.
++After mounting, the unified file system has this structure:
+
+```text
+home/
+└── user/
+ └── my-project/
+ ├── content/
+ │ ├── books/
+ │ │ ├── _index.md
+ │ │ ├── book-1.md
+ │ │ └── book-2.md
+ │ ├── films/
+ │ │ ├── _index.md
+ │ │ ├── film-1.md
+ │ │ └── film-2.md
+ │ └── _index.md
+ ├── themes/
+ │ └── my-theme/
+ └── hugo.toml
+```
+
- Using the union file system described above, Hugo mounts each of these directories to the corresponding location in the project. When two files have the same path, the file in the project directory takes precedence. This allows you, for example, to override a theme's template by placing a copy in the same location within the project directory.
++When two or more files share the same path, the version in the highest layer takes precedence. In the example above, if the `shared-content` directory contains `books/book-1.md`, it is ignored because the project's `content` directory is the first (highest) mount.
+
+You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/configuration/module/#mounts).
+
+You can also mount directories from Git repositories using Hugo Modules. See [details](/hugo-modules/).
+
+## Theme skeleton
+
+Hugo generates a functional theme skeleton when you create a new theme. For example, this command:
+
+```text
+hugo new theme my-theme
+```
+
+Creates this directory structure (subdirectories not shown):
+
+```text
+my-theme/
+├── archetypes/
+├── assets/
+├── content/
+├── data/
+├── i18n/
+├── layouts/
+├── static/
+└── hugo.toml
+```
+
++Using the unified file system described above, Hugo mounts each of these directories to the corresponding location in the project. When two files have the same path, the file in the project directory takes precedence. This allows you, for example, to override a theme's template by placing a copy in the same location within the project directory.
+
+If you are simultaneously using components from two or more themes or modules, and there's a path collision, the first mount takes precedence.
--- /dev/null
- languageCode = 'en-us'
+---
+title: Quick start
+description: Create your first Hugo project.
+categories: []
+keywords: []
+params:
+ minVersion: v0.156.0
+weight: 10
+aliases: [/quickstart/,/overview/quickstart/]
+---
+
+In this tutorial you will:
+
+1. Create a project
+1. Add content
+1. Configure the project
+1. Publish the project
+
+## Prerequisites
+
+Before you begin this tutorial you must:
+
+1. [Install Hugo] (extended or extended/deploy edition, {{% param "minVersion" %}} or later)
+1. [Install Git]
+
+You must also be comfortable working from the command line.
+
+## Create a project
+
+### 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][].
+
+Verify that you have installed Hugo {{% param "minVersion" %}} or later.
+
+```text
+hugo version
+```
+
+Run these commands to create a Hugo project with the [Ananke][] theme. The next section provides an explanation of each command.
+
+```text
+hugo new project quickstart
+cd quickstart
+git init
+git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
+echo "theme = 'ananke'" >> hugo.toml
+hugo server
+```
+
+View your project at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server.
+
+### Explanation of commands
+
+Create the [project skeleton][] for your project in the `quickstart` directory.
+
+```text
+hugo new project quickstart
+```
+
+Change the current directory to the root of your project.
+
+```text
+cd quickstart
+```
+
+Initialize an empty Git repository in the current directory.
+
+```text
+git init
+```
+
+Clone the [Ananke][] theme into the `themes` directory, adding it to your project as a [Git submodule][].
+
+```text
+git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
+```
+
+Append a line to your project configuration file, indicating the current theme.
+
+```text
+echo "theme = 'ananke'" >> hugo.toml
+```
+
+Start Hugo's development server.
+
+```text
+hugo server
+```
+
+Press `Ctrl + C` to stop Hugo's development server.
+
+## Add content
+
+Add a new page to your project.
+
+```text
+hugo new content content/posts/my-first-post.md
+```
+
+Hugo created the file in the `content/posts` directory. Open the file with your editor.
+
+```text
++++
+title = 'My First Post'
+date = 2024-01-14T07:07:07+01:00
+draft = true
++++
+```
+
+Notice the `draft` value in the [front matter][] is `true`. By default, Hugo does not publish draft content when you build the project. Learn more about [draft, future, and expired content][].
+
+Add some [Markdown][] to the body of the post, but do not change the `draft` value.
+
+```text
++++
+title = 'My First Post'
+date = 2024-01-14T07:07:07+01:00
+draft = true
++++
+## Introduction
+
+This is **bold** text, and this is *emphasized* text.
+
+Visit the [Hugo](https://gohugo.io) website!
+```
+
+Save the file, then start Hugo's development server. You can run either of the following commands to include draft content.
+
+```text
+hugo server --buildDrafts
+hugo server -D
+```
+
+View your project at the URL displayed in your terminal. Keep the development server running as you continue to add and change content.
+
+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.
+
+## Configure the project
+
+With your editor, open your [project configuration][] file (`hugo.toml`) in the root of your project.
+
+```text
+baseURL = 'https://example.org/'
- 1. Set the `languageCode` to your locale.
++locale = 'en-us'
+title = 'My New Hugo Project'
+theme = 'ananke'
+```
+
+Make the following changes:
+
+1. Set the `baseURL` for your project. This value must begin with the protocol and end with a slash, as shown above.
++1. Set the `locale` to your locale.
+1. Set the `title` for your project.
+
+Start Hugo's development server to see your changes, remembering to include draft content.
+
+```text
+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][].
+
+## Publish the project
+
+In this step you will _publish_ your project, but you will not _deploy_ it.
+
+When you publish your project, Hugo renders all build artifacts to the `public` directory in the root of your project. This includes the HTML files for every site, along with assets such as images, CSS, and JavaScript. The command is simple.
+
+```text
+hugo
+```
+
+To learn how to _deploy_ your project, see the [host and deploy][] section.
+
+## Ask for help
+
+Hugo's [forum][] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
+
+## Other resources
+
+For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources][] page.
+
+[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke
+[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/
+[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme
+[draft, future, and expired content]: /getting-started/usage/#draft-future-and-expired-content
+[external learning resources]: /getting-started/external-learning-resources/
+[forum]: https://discourse.gohugo.io/
+[front matter]: /content-management/front-matter/
+[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+[host and deploy]: /host-and-deploy/
+[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Install Hugo]: /installation/
+[live testing tool]: https://spec.commonmark.org/dingus/
+[Markdown]: https://daringfireball.net/projects/markdown
+[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
+[project configuration]: /configuration/
+[project skeleton]: /getting-started/directory-structure/#project-skeleton
+[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
+[specification]: https://spec.commonmark.org/
+[The New Dynamic]: https://www.thenewdynamic.com/
--- /dev/null
- hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio
+---
+title: Basic usage
+description: Use the command-line interface (CLI) to perform basic tasks.
+categories: []
+keywords: []
+weight: 20
+aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
+---
+
+## Test your installation
+
+After [installing] Hugo, test your installation by running:
+
+```sh
+hugo version
+```
+
+You should see something like:
+
+```text
++hugo v0.158.0-f41be7959a44108641f1e081adf5c4be7fc1bb63+extended linux/amd64 BuildDate=2026-03-16T17:42:04Z VendorInfo=gohugoio
+```
+
+## Display available commands
+
+To see a list of the available commands and flags:
+
+```sh
+hugo help
+```
+
+To get help with a subcommand, use the `--help` flag. For example:
+
+```sh
+hugo server --help
+```
+
+## Build your project
+
+To build your project, `cd` into your project directory and run:
+
+```sh
+hugo build
+```
+
+The [`hugo build`] command builds your project, publishing the files to the `public` directory. To publish your project to a different directory, use the [`--destination`] flag or set [`publishDir`] in your project configuration.
+
+> [!note]
+> Hugo does not clear the `public` directory before building your project. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build.
+>
+> Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build.
+
+## Draft, future, and expired content
+
+Hugo allows you to set `draft`, `date`, `publishDate`, and `expiryDate` in the [front matter] of your content. By default, Hugo will not publish content when:
+
+- The `draft` value is `true`
+- The `date` is in the future
+- The `publishDate` is in the future
+- The `expiryDate` is in the past
+
+> [!note]
+> Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
+
+You can override the default behavior when running `hugo build` or `hugo server` with command line flags:
+
+```sh
+hugo build --buildDrafts # or -D
+hugo build --buildExpired # or -E
+hugo build --buildFuture # or -F
+```
+
+Although you can also set these values in your project configuration, it can lead to unwanted results unless all content authors are aware of, and understand, the settings.
+
+> [!note]
+> As noted above, Hugo does not clear the `public` directory before building your project. Depending on the _current_ evaluation of the four conditions above, after the build your `public` directory may contain extraneous files from a previous build.
+>
+> A common practice is to manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
+
+## Develop and test your site
+
+To view your site while developing layouts or creating content, `cd` into your project directory and run:
+
+```sh
+hugo server
+```
+
+The [`hugo server`] command builds your site and serves your pages using a minimal HTTP server. When you run `hugo server` it will display the URL of your local site:
+
+```text
+Web Server is available at http://localhost:1313/
+```
+
+While the server is running, it watches your project directory for changes to assets, configuration, content, data, layouts, translations, and static files. When it detects a change, the server rebuilds your site and refreshes your browser using [LiveReload].
+
+Most Hugo builds are so fast that you may not notice the change unless you are looking directly at your browser.
+
+### LiveReload
+
+While the server is running, Hugo injects JavaScript into the generated HTML pages. The LiveReload script creates a connection from the browser to the server via web sockets. You do not need to install any software or browser plugins, nor is any configuration required.
+
+### Automatic redirection
+
+When editing content, if you want your browser to automatically redirect to the page you last modified, run:
+
+```sh
+hugo server --navigateToChanged
+```
+
+## Deploy your site
+
+> [!note]
+> As noted above, Hugo does not clear the `public` directory before building your project. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
+
+When you are ready to deploy your site, run:
+
+```sh
+hugo
+```
+
+This builds your site, publishing the files to the `public` directory. The directory structure will look something like this:
+
+```text
+public/
+├── categories/
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── posts/
+│ ├── my-first-post/
+│ │ └── index.html
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── tags/
+│ ├── index.html
+│ └── index.xml <-- RSS feed for this section
+├── index.html
+├── index.xml <-- RSS feed for the site
+└── sitemap.xml
+```
+
+In a simple hosting environment, where you typically `ftp`, `rsync`, or `scp` your files to the root of a virtual host, the contents of the `public` directory are all that you need.
+
+Most of our users deploy their sites to a [CI/CD](g) platform, where a push[^1] to their remote Git repository triggers a build and deployment. Learn more in the [host and deploy] section.
+
+[^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 build`]: /commands/hugo/
+[`publishDir`]: /configuration/all/#publishdir
+[build options]: /content-management/build-options/
+[front matter]: /content-management/front-matter/
+[host and deploy]: /host-and-deploy/
+[installing]: /installation/
+[LiveReload]: https://github.com/livereload/livereload-js
--- /dev/null
- 1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+---
+title: Host on AWS Amplify
+description: Host your site on AWS Amplify.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-aws-amplify/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://aws.amazon.com/resources/create-account/) an AWS account
+1. [Log in](https://console.aws.amazon.com/) to your AWS account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
- DART_SASS_VERSION: 1.97.3
- GO_VERSION: 1.26.0
- HUGO_VERSION: 0.156.0
++1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository.
+
+## Procedure
+
+This procedure will enable continuous deployment from a GitHub repository. The procedure is essentially the same if you are using GitLab or Bitbucket.
+
+Step 1
+: Create a file named `amplify.yml` in the root of your project.
+
+ ```sh
+ touch amplify.yml
+ ```
+
+Step 2
+: Copy and paste the YAML below into the file you created. Change the application versions and time zone as needed.
+
+ ```yaml {file="amplify.yml" copy=true}
+ version: 1
+ env:
+ variables:
+ # Application versions
++ DART_SASS_VERSION: 1.98.0
++ GO_VERSION: 1.26.1
++ HUGO_VERSION: 0.158.0
+ # Time zone
+ TZ: Europe/Oslo
+ # Cache
+ HUGO_CACHEDIR: ${PWD}/.hugo
+ NPM_CONFIG_CACHE: ${PWD}/.npm
+ frontend:
+ phases:
+ preBuild:
+ commands:
+ # Create directory for user-specific executable files
+ - echo "Creating directory for user-specific executable files..."
+ - mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ - echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ - export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ - echo "Installing Go ${GO_VERSION}..."
+ - curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ - tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ - rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ - echo "Installing Hugo ${HUGO_VERSION}..."
+ - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - mkdir "${HOME}/.local/hugo"
+ - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ - export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Verify installations
+ - echo "Verifying installations..."
+ - "echo Dart Sass: $(sass --version)"
+ - "echo Go: $(go version)"
+ - "echo Hugo: $(hugo version)"
+ - "echo Node.js: $(node --version)"
+
+ # Install Node.js dependencies
+ - echo "Installing Node.js dependencies..."
+ - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
+
+ # Configure Git
+ - echo "Configuring Git..."
+ - git config core.quotepath false
+ build:
+ commands:
+ - echo "Building site..."
+ - hugo build --gc --minify
+ artifacts:
+ baseDirectory: public
+ files:
+ - '**/*'
+ cache:
+ paths:
+ - ${HUGO_CACHEDIR}/**/*
+ - ${NPM_CONFIG_CACHE}/**/*
+ ```
+
+Step 3
+: Commit and push the change to your GitHub repository.
+
+ ```sh
+ git add -A
+ git commit -m "Create amplify.yml"
+ git push
+ ```
+
+Step 4
+: Log in to your AWS account, navigate to the [Amplify Console], then press the **Deploy an app** button.
+
+Step 5
+: Choose a source code provider, then press the **Next** button.
+
+ 
+
+Step 6
+: Authorize AWS Amplify to access your GitHub account.
+
+ 
+
+Step 7
+: Select your personal account or relevant organization.
+
+ 
+
+Step 8
+: Authorize access to one or more repositories.
+
+ 
+
+Step 9
+: Select a repository and branch, then press the **Next** button.
+
+ 
+
+Step 10
+: On the "App settings" page, scroll to the bottom then press the **Next** button. Amplify reads the `amplify.yml` file you created in Steps 1-3 instead of using the values on this page.
+
+Step 11
+: On the "Review" page, scroll to the bottom then press the **Save and deploy** button.
+
+Step 12
+: When your site has finished deploying, press the **Visit deployed URL** button to view your published site.
+
+ 
+
+[Amplify Console]: https://console.aws.amazon.com/amplify/apps
--- /dev/null
- 1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+---
+title: Host on Cloudflare
+description: Host your site on Cloudflare.
+categories: []
+keywords: []
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://dash.cloudflare.com/sign-up) a Cloudflare account
+1. [Log in](https://dash.cloudflare.com/login) to your Cloudflare account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
- name = "hosting-cloudflare-worker"
- compatibility_date = "2025-07-31"
++1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a `wrangler.toml` file in the root of your project.
+
+ ```toml {file="wrangler.toml" copy=true}
- command = "chmod a+x build.sh && ./build.sh"
++ name = 'hosting-cloudflare-worker'
++ compatibility_date = '2025-07-31'
+
+ [build]
- directory = "./public"
- not_found_handling = "404-page"
++ command = 'chmod a+x build.sh && ./build.sh'
+
+ [assets]
- DART_SASS_VERSION=1.97.3
- GO_VERSION=1.26.0
- HUGO_VERSION=0.156.0
- NODE_VERSION=24.13.1
++ directory = './public'
++ not_found_handling = '404-page'
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on a Cloudflare Worker.
+ #
+ # The Cloudflare Worker automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ main() {
+
++ DART_SASS_VERSION=1.98.0
++ GO_VERSION=1.26.1
++ HUGO_VERSION=0.158.0
++ NODE_VERSION=24.14.0
+
+ export TZ=Europe/Oslo
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site..."
+ hugo build --gc --minify
+
+ }
+
+ set -euo pipefail
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: In the upper right corner of the Cloudflare [dashboard](https://dash.cloudflare.com/), press the **Add** button and select "Workers" from the drop down menu.
+
+ 
+
+Step 5
+: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item.
+
+ 
+
+Step 6
+: Connect to GitHub.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Cloudflare Workers and Pages application.
+
+ 
+
+Step 8
+: Authorize the Cloudflare Workers and Pages application to access all repositories or only select repositories, then press the **Install & Authorize** button.
+
+ 
+
+ Your browser will be redirected to the Cloudflare dashboard.
+
+Step 9
+: On the "Workers" tab, press the **Get started** button to the right of the "Import a repository" item.
+
+ 
+
+Step 10
+: Select the repository to import.
+
+ 
+
+Step 11
+: On the "Set up your application" screen, provide a project name, leave the build command blank, then press the **Create and deploy** button.
+
+ 
+
+Step 12
+: Wait for the site to build and deploy, then visit your site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Cloudflare will rebuild and deploy your site.
--- /dev/null
- 1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+---
+title: Host on GitHub Pages
+description: Host your site on GitHub Pages.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-github/]
+---
+
+## 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.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
- dir = ":cacheDir/images"
++1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository
+
+## Procedure
+
+Step 1
+: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this:
+
+ 
+
+ Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button.
+
+ 
+
+Step 2
+: In your project configuration, change the location of the image cache to the [`cacheDir`] as shown below:
+
+ {{< code-toggle file=hugo copy=true >}}
+ [caches.images]
- DART_SASS_VERSION: 1.97.3
- GO_VERSION: 1.26.0
- HUGO_VERSION: 0.156.0
- NODE_VERSION: 24.13.1
++ dir = ':cacheDir/images'
+ {{< /code-toggle >}}
+
+ See [configure file caches] for more information.
+
+Step 3
+: Create a file named `hugo.yaml` in a directory named `.github/workflows`.
+
+ ```text
+ mkdir -p .github/workflows
+ touch .github/workflows/hugo.yaml
+ ```
+
+Step 4
+: Copy and paste the YAML below into the file you created.
+
+ ```yaml {file=".github/workflows/hugo.yaml" copy=true}
+ name: Build and deploy
+ on:
+ push:
+ branches:
+ - main
+ workflow_dispatch:
+ permissions:
+ contents: read
+ pages: write
+ id-token: write
+ concurrency:
+ group: pages
+ cancel-in-progress: false
+ defaults:
+ run:
+ shell: bash
+ jobs:
+ build:
+ runs-on: ubuntu-latest
+ env:
- ## Customize the workflow
-
- The example workflow above includes this step, which typically takes 10‑15 seconds:
-
- ```yaml
- - name: Install Dart Sass
- run: sudo snap install dart-sass
- ```
-
- You may remove this step if your site, themes, and modules do not transpile Sass to CSS using the [Dart Sass] transpiler.
-
++ DART_SASS_VERSION: 1.98.0
++ GO_VERSION: 1.26.1
++ HUGO_VERSION: 0.158.0
++ NODE_VERSION: 24.14.0
+ TZ: Europe/Oslo
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v6
+ with:
+ submodules: recursive
+ fetch-depth: 0
+ - name: Setup Go
+ uses: actions/setup-go@v6
+ with:
+ go-version: ${{ env.GO_VERSION }}
+ cache: false
+ - name: Setup Node.js
+ uses: actions/setup-node@v6
+ with:
+ node-version: ${{ env.NODE_VERSION }}
+ - name: Setup Pages
+ id: pages
+ uses: actions/configure-pages@v5
+ - name: Create directory for user-specific executable files
+ run: |
+ mkdir -p "${HOME}/.local"
+ - name: Install Dart Sass
+ run: |
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}"
+ - name: Install Hugo
+ run: |
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}"
+ - name: Verify installations
+ run: |
+ echo "Dart Sass: $(sass --version)"
+ echo "Go: $(go version)"
+ echo "Hugo: $(hugo version)"
+ echo "Node.js: $(node --version)"
+ - name: Install Node.js dependencies
+ run: |
+ [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true
+ - name: Configure Git
+ run: |
+ git config core.quotepath false
+ - name: Cache restore
+ id: cache-restore
+ uses: actions/cache/restore@v5
+ with:
+ path: ${{ runner.temp }}/hugo_cache
+ key: hugo-${{ github.run_id }}
+ restore-keys:
+ hugo-
+ - name: Build the site
+ run: |
+ hugo build \
+ --gc \
+ --minify \
+ --baseURL "${{ steps.pages.outputs.base_url }}/" \
+ --cacheDir "${{ runner.temp }}/hugo_cache"
+ - name: Cache save
+ id: cache-save
+ uses: actions/cache/save@v5
+ with:
+ path: ${{ runner.temp }}/hugo_cache
+ key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v3
+ with:
+ path: ./public
+ deploy:
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ needs: build
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
+ ```
+
+Step 5
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 6
+: From GitHub's main menu, choose **Actions**. You will see something like this:
+
+ 
+
+Step 7
+: When GitHub has finished building and deploying your site, the color of the status indicator will change to green.
+
+ 
+
+Step 8
+: Click on the commit message as shown above. Under the deploy step, you will see a link to your live site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, GitHub Pages will rebuild and deploy your site.
+
- [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)
+
+[`cacheDir`]: /configuration/all/#cachedir
+[configure file caches]: /configuration/caches/
+[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
--- /dev/null
- DART_SASS_VERSION: 1.97.3
- HUGO_VERSION: 0.156.0
- NODE_VERSION: 24.13.1
+---
+title: Host on GitLab Pages
+description: Host your site on GitLab Pages.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-gitlab/]
+---
+
+## Assumptions
+
+- Working familiarity with Git for version control
+- Completion of the Hugo [Quick Start]
+- A [GitLab account](https://gitlab.com/users/sign_in)
+- A Hugo website on your local machine that you are ready to publish
+
+## BaseURL
+
+The `baseURL` in your [project configuration](/configuration/) must reflect the full URL of your GitLab pages repository if you are using the default GitLab Pages URL (e.g., `https://<YourUsername>.gitlab.io/<your-hugo-site>/`) and not a custom domain.
+
+## Configure GitLab CI/CD
+
+Define your [CI/CD](g) jobs by creating a `.gitlab-ci.yml` file in the root of your project.
+
+```yaml {file=".gitlab-ci.yml" copy=true}
+variables:
+ # Application versions
- name: golang:1.26.0-bookworm
++ DART_SASS_VERSION: 1.98.0
++ HUGO_VERSION: 0.158.0
++ NODE_VERSION: 24.14.0
+ # Git
+ GIT_DEPTH: 0
+ GIT_STRATEGY: clone
+ GIT_SUBMODULE_STRATEGY: recursive
+ # Time zone
+ TZ: Europe/Oslo
+
+image:
- # Create directory for user-specific executable files
- - echo "Creating directory for user-specific executable files..."
- - mkdir -p "${HOME}/.local"
-
- # Install utilities
- - echo "Installing utilities..."
- - apt-get update
- - apt-get install -y brotli xz-utils zstd
-
- # Install Dart Sass
- - echo "Installing Dart Sass ${DART_SASS_VERSION}..."
- - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- - export PATH="${HOME}/.local/dart-sass:${PATH}"
-
- # Install Hugo
- - echo "Installing Hugo ${HUGO_VERSION}..."
- - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- - mkdir "${HOME}/.local/hugo"
- - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- - export PATH="${HOME}/.local/hugo:${PATH}"
-
- # Install Node.js
- - echo "Installing Node.js ${NODE_VERSION}..."
- - curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
- - tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
- - rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
- - export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
-
- # Verify installations
- - echo "Verifying installations..."
- - "echo Dart Sass: $(sass --version)"
- - "echo Go: $(go version)"
- - "echo Hugo: $(hugo version)"
- - "echo Node.js: $(node --version)"
- - "echo brotli: $(brotli --version)"
- - "echo xz: $(xz --version)"
- - "echo zstd: $(zstd --version)"
-
- # Install Node.js dependencies
- - echo "Installing Node.js dependencies..."
- - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
-
- # Configure Git
- - echo "Configuring Git..."
- - git config core.quotepath false
-
- # Build site
- - echo "Building site..."
- - hugo build --gc --minify --baseURL "${CI_PAGES_URL}"
-
- # Compress published files
- - echo "Compressing published files..."
- - find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
- - time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
- - time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
++ name: golang:1.26.1-bookworm
+
+pages:
+ stage: deploy
+ script:
++ - |
++ # Create directory for user-specific executable files
++ echo "Creating directory for user-specific executable files..."
++ mkdir -p "${HOME}/.local"
++
++ # Install utilities
++ echo "Installing utilities..."
++ apt-get update
++ apt-get install -y brotli xz-utils zstd
++
++ # Install Dart Sass
++ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
++ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
++ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
++ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
++ export PATH="${HOME}/.local/dart-sass:${PATH}"
++
++ # Install Hugo
++ echo "Installing Hugo ${HUGO_VERSION}..."
++ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
++ mkdir -p "${HOME}/.local/hugo"
++ tar -C "${HOME}/.local/hugo" -xf "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
++ rm "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
++ export PATH="${HOME}/.local/hugo:${PATH}"
++
++ # Install Node.js
++ echo "Installing Node.js ${NODE_VERSION}..."
++ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
++ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
++ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
++ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
++
++ # Verify installations
++ echo "Verifying installations..."
++ echo "Dart Sass: $(sass --version)"
++ echo "Go: $(go version)"
++ echo "Hugo: $(hugo version)"
++ echo "Node.js: $(node --version)"
++ echo "brotli: $(brotli --version)"
++ echo "xz: $(xz --version)"
++ echo "zstd: $(zstd --version)"
++
++ # Install Node.js dependencies
++ echo "Installing Node.js dependencies..."
++ [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true
++
++ # Configure Git
++ echo "Configuring Git..."
++ git config core.quotepath false
++
++ # Build site
++ echo "Building site..."
++ hugo --gc --minify --baseURL "${CI_PAGES_URL}"
++
++ # Compress published files
++ echo "Compressing published files..."
++ find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
++ time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
++ time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
+ artifacts:
+ paths:
+ - public
+ rules:
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+## Push your Hugo website to GitLab
+
+Next, create a new repository on GitLab. It is not necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.
+
+```sh
+# initialize new git repository
+git init
+
+# add /public directory to our .gitignore file
+echo "/public" >> .gitignore
+
+# commit and push code to master branch
+git add .
+git commit -m "Initial commit"
+git remote add origin https://gitlab.com/YourUsername/your-hugo-site.git
+git push -u origin master
+```
+
+## Wait for your page to build
+
+That's it! You can now follow the CI agent building your page at `https://gitlab.com/<YourUsername>/<your-hugo-site>/pipelines`.
+
+After the build has passed, your new website is available at `https://<YourUsername>.gitlab.io/<your-hugo-site>/`.
+
+## Next steps
+
+GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/).
+
+[Quick Start]: /getting-started/quick-start/
--- /dev/null
- 1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+---
+title: Host on Netlify
+description: Host your site on Netlify.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-netlify/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Azure DevOps, Bitbucket, or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://app.netlify.com/signup) a Netlify account
+1. [Log in](https://app.netlify.com/login) to your Netlify account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
- DART_SASS_VERSION = "1.97.3"
- GO_VERSION = "1.26.0"
- HUGO_VERSION = "0.156.0"
- NODE_VERSION = "24.13.1"
++1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+1. Commit the changes to your local Git repository and push to your GitHub repository.
+
+## Procedure
+
+<!-- Using "text" as the code block language because "toml" looks terrible. -->
+
+Step 1
+: Create a `netlify.toml` file in the root of your project.
+
+ ```text {file="netlify.toml" copy=true}
+ [build.environment]
- DART_SASS_VERSION = "1.97.3"
- GO_VERSION = "1.26.0"
- HUGO_VERSION = "0.156.0"
- NODE_VERSION = "24.13.1"
++ DART_SASS_VERSION = "1.98.0"
++ GO_VERSION = "1.26.1"
++ HUGO_VERSION = "0.158.0"
++ NODE_VERSION = "24.14.0"
+ TZ = "Europe/Oslo"
+
+ [build]
+ publish = "public"
+ command = """\
+ git config core.quotepath false && \
+ hugo build --gc --minify --baseURL "${URL}"
+ """
+ ```
+
+ If your site requires Dart Sass to transpile Sass to CSS, set the `DART_SASS_VERSION` and include the Dart Sass installation in the build step.
+
+ ```text {file="netlify.toml" copy=true}
+ [build.environment]
++ DART_SASS_VERSION = "1.98.0"
++ GO_VERSION = "1.26.1"
++ HUGO_VERSION = "0.158.0"
++ NODE_VERSION = "24.14.0"
+ TZ = "Europe/Oslo"
+
+ [build]
+ publish = "public"
+ command = """\
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" && \
+ export PATH="${HOME}/.local/dart-sass:${PATH}" && \
+ git config core.quotepath false && \
+ hugo build --gc --minify --baseURL "${URL}"
+ """
+ ```
+
+Step 2
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 3
+: In the upper right corner of the Netlify dashboard, press the **Add new project** button and select “Import an existing project".
+
+ 
+
+Step 4
+: Connect to GitHub.
+
+ 
+
+Step 5
+: Press the "Authorize Netlify" button to allow the Netlify application to access your GitHub account.
+
+ 
+
+Step 6
+: Press the **Configure Netlify on GitHub** button.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Netlify application.
+
+ 
+
+Step 8
+: Authorize the Netlify application to access all repositories or only select repositories, then press the Install button.
+
+ 
+
+Your browser will be redirected to the Netlify dashboard.
+
+Step 9
+: Click on the name of the repository you wish to import.
+
+ 
+
+Step 10
+: On the "Review configuration" page, enter a project name, leave the settings at their default values, then press the **Deploy** button.
+
+ 
+
+ 
+
+Step 11
+: When the deployment completes, click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Netlify will rebuild and deploy your site.
--- /dev/null
- 1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+---
+title: Host on Render
+description: Host your site on Render.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-render/]
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://dashboard.render.com/register) a Render account
+1. [Log in](https://dashboard.render.com/login) to your Render account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
- value: 1.97.3
++1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a [Render Blueprint][] in the root of your project.
+
+ ``` {file="render.yaml" copy=true}
+ services:
+ - type: web
+ name: hosting-render
+ repo: https://github.com/jmooring/hosting-render
+ runtime: static
+ buildCommand: chmod a+x build.sh && ./build.sh
+ staticPublishPath: public
+ envVars:
+ - key: DART_SASS_VERSION
- value: 1.26.0
++ value: 1.98.0
+ - key: GO_VERSION
- value: 0.156.0
++ value: 1.26.1
+ - key: HUGO_VERSION
- value: 24.13.1
++ value: 0.158.0
+ - key: NODE_VERSION
++ value: 24.14.0
+ - key: TZ
+ value: Europe/Oslo
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on a Render.
+ #
+ # Render automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ main() {
+
+ # Create directory for user-specific executable files
+ echo "Creating directory for user-specific executable files..."
+ mkdir -p "${HOME}/.local"
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir -p "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site..."
+ hugo build --gc --minify --baseURL "${RENDER_EXTERNAL_URL}"
+
+ }
+
+ set -euo pipefail
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: On the Render [dashboard][], press the **Add new** button and select "Blueprint" from the drop-down menu.
+
+ 
+
+Step 5
+: Press the **GitHub** button to connect to your GitHub account.
+
+ 
+
+Step 6
+: Press the **Authorize Render** button to allow the Render application to access your GitHub account.
+
+ 
+
+Step 7
+: Select the GitHub account where you want to install the Render application.
+
+ 
+
+Step 8
+: Authorize the Render application to access all repositories or only select repositories, then press the **Install** button.
+
+
+
+Step 9
+: On the "Create a new Blueprint Instance in My Workspacee" page, press the **Connect** button to the right of the name of your GitHub repository.
+
+ 
+
+Step 10
+: Enter a unique name for your Blueprint, then press the **Deploy Blueprint** button at the bottom of the page.
+
+ 
+
+Step 11
+: Wait for the site to build and deploy, then click on the "Resources" link on the left side of the page.
+
+ 
+
+Step 12
+: Click on the link to the static site resource.
+
+ 
+
+Step 13
+: Click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Render will rebuild and deploy your site.
+
+[Render Blueprint]: https://render.com/docs/blueprint-spec
+[dashboard]: https://dashboard.render.com/
--- /dev/null
- DART_SASS_VERSION=1.97.1 # Latest version as of 20/12/2025
+---
+title: Host on SourceHut Pages
+description: Host your site on SourceHut Pages.
+categories: []
+keywords: []
+aliases: [/hosting-and-deployment/hosting-on-sourcehut/]
+---
+
+## Assumptions
+
+- Working familiarity with [Git][] or [Mercurial][] for version control
+- Completion of the Hugo [Quick Start][]
+- A [SourceHut account][]
+- A Hugo website on your local machine that you are ready to publish
+
+[Git]: https://git-scm.com/
+[Mercurial]: https://www.mercurial-scm.org/
+[SourceHut account]: https://meta.sr.ht/login
+[Quick Start]: /getting-started/quick-start/
+
+Any and all mentions of `<YourUsername>` refer to your actual SourceHut username and must be substituted accordingly.
+
+## BaseURL
+
+The [`baseURL`][] in your project configuration must reflect the full URL provided by SourceHut Pages if you are using the default address (e.g. `https://<YourUsername>.srht.site/`). If you want to use another domain, check the [custom domain section][] of the official documentation.
+
+[`baseURL`]: /configuration/all/#baseurl
+[custom domain section]: https://srht.site/custom-domains
+
+## Manual deployment
+
+This method does not require a paid account. To proceed you will need to create a [SourceHut personal access token][] and install and configure the [hut][] CLI tool:
+
+[SourceHut personal access token]: https://meta.sr.ht/oauth2/personal-token
+[hut]: https://sr.ht/~xenrox/hut/
+
+```sh
+hugo build
+tar -C public -cvz . > site.tar.gz
+hut init
+hut pages publish -d <YourUsername>.srht.site site.tar.gz
+```
+
+A TLS certificate will be automatically obtained for you, and your new website will be available at `https://<YourUsername>.srht.site/` (or the provided custom domain).
+
+## Automated deployment
+
+This method requires a paid account and relies on the SourceHut build system.
+
+First, define your [build manifest][] by creating a `.build.yml` file in the root of your project. The following is a bare-bones template:
+
+[build manifest]: https://man.sr.ht/builds.sr.ht/#build-manifests
+
+```yaml {file=".build.yml" copy=true}
+image: alpine/edge
+packages:
+ - hugo
+ - hut
+oauth: pages.sr.ht/PAGES:RW
+environment:
+ site: <YourUsername>.srht.site
+tasks:
+- package: |
+ cd $site
+ hugo build
+ tar -C public -cvz . > ../site.tar.gz
+- upload: |
+ hut pages publish -d $site site.tar.gz
+```
+
+If your site requires [Dart Sass][] to transpile Sass to CSS, set the DART_SASS_VERSION to the [latest version number][] and include the Dart Sass installation lines before running the Hugo build step. Note that for Alpine, the `linux-x64-musl` version is used.
+
+[Dart Sass]: https://gohugo.io/functions/css/sass/#dart-sass
+[latest version number]: https://github.com/sass/dart-sass/releases
+
+```yaml {file=".build.yml" copy=true}
+image: alpine/edge
+packages:
+ - hugo
+ - hut
+ - curl # For Dart Sass installation
+oauth: pages.sr.ht/PAGES:RW
+environment:
+ site: <YourUsername>.srht.site
+tasks:
+- package: |
++ DART_SASS_VERSION=1.98.0
+ mkdir -p $HOME/.local
+ curl -L https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64-musl.tar.gz -o dart-sass.tar.gz
+ tar -xzf dart-sass.tar.gz -C $HOME/.local
+ rm dart-sass.tar.gz
+ chmod -R +x $HOME/.local/dart-sass/src
+ export PATH="$HOME/.local/dart-sass:$PATH"
+ sass --version # Verify installation
+ cd $site
+ hugo build
+ tar -C public -cvz . > ../site.tar.gz
+- upload: |
+ hut pages publish -d $site site.tar.gz
+```
+
+Now what's left is creating a repository titled `<YourUsername>.srht.site` (or your custom domain, if applicable) and pushing your local project. Here's an example using Git:
+
+```sh
+# initialize new git repository
+git init
+
+# add /public directory to our .gitignore file
+echo "/public" >> .gitignore
+
+# commit and push code to main branch
+git add .
+git commit -m "Initial commit"
+git remote add origin https://git.sr.ht/~<YourUsername>/<YourUsername>.srht.site
+git push -u origin main
+```
+
+You can now follow the build progress of your page at `https://builds.sr.ht/`.
+
+After the build has passed, a TLS certificate will be automatically obtained for you and your new website will be available at `https://<YourUsername>.srht.site/` (or the provided custom domain).
+
+## Other resources
+
+- [SourceHut Pages](https://srht.site/)
+- [SourceHut Builds user manual](https://man.sr.ht/builds.sr.ht/)
--- /dev/null
- 1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+---
+title: Host on Vercel
+description: Host your site on Vercel.
+categories: []
+keywords: []
+---
+
+Use these instructions to enable continuous deployment from a GitHub repository. The same general steps apply if you are using Bitbucket or GitLab for version control.
+
+## Prerequisites
+
+Please complete the following tasks before continuing:
+
+1. [Create](https://vercel.com/signup) a Vercel account
+1. [Log in](https://vercel.com/login) to your Vercel account
+1. [Create](https://github.com/signup) a GitHub account
+1. [Log in](https://github.com/login) to your GitHub account
+1. [Create](https://github.com/new) a GitHub repository for your project
+1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
- DART_SASS_VERSION=1.97.3
- GO_VERSION=1.26.0
- HUGO_VERSION=0.156.0
- NODE_VERSION=24.13.1
++1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
+
+## Procedure
+
+Step 1
+: Create a `vercel.json` file in the root of your project.
+
+ ```json {file="vercel.json" copy=true}
+ {
+ "$schema": "https://openapi.vercel.sh/vercel.json",
+ "buildCommand": "chmod a+x build.sh && ./build.sh",
+ "outputDirectory": "public"
+ }
+ ```
+
+Step 2
+: Create a `build.sh` file in the root of your project.
+
+ ```sh {file="build.sh" copy=true}
+ #!/usr/bin/env bash
+
+ #------------------------------------------------------------------------------
+ # @file
+ # Builds a Hugo site hosted on Vercel.
+ #
+ # The Vercel build image automatically installs Node.js dependencies.
+ #------------------------------------------------------------------------------
+
+ main() {
+
++ DART_SASS_VERSION=1.98.0
++ GO_VERSION=1.26.1
++ HUGO_VERSION=0.158.0
++ NODE_VERSION=24.14.0
+
+ export TZ=Europe/Oslo
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Go
+ echo "Installing Go ${GO_VERSION}..."
+ curl -sLJO "https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz"
+ tar -C "${HOME}/.local" -xf "go${GO_VERSION}.linux-amd64.tar.gz"
+ rm "go${GO_VERSION}.linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/go/bin:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo Dart Sass: "$(sass --version)"
+ echo Go: "$(go version)"
+ echo Hugo: "$(hugo version)"
+ echo Node.js: "$(node --version)"
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+
+ # Build the site
+ echo "Building the site"
+ hugo build --gc --minify --baseURL "https://${VERCEL_PROJECT_PRODUCTION_URL}"
+
+ }
+
+ set -euo pipefail
+ main "$@"
+ ```
+
+Step 3
+: Commit the changes to your local Git repository and push to your GitHub repository.
+
+Step 4
+: In the upper right corner of the Vercel dashboard, press the **Add New** button and select "Project" from the drop down menu.
+
+ 
+
+Step 5
+: Press the "Continue with GitHub" button.
+
+ 
+
+Step 6
+: Press the **Authorize Vercel** button to allow the Vercel application to access your GitHub account.
+
+ 
+
+Step 7
+: Press the **Install** button to install the Vercel application.
+
+ 
+
+Step 8
+: Select the GitHub account where you want to install the Vercel application.
+
+ 
+
+Step 9
+: Authorize the Vercel application to access all repositories or only select repositories, then press the **Install** button.
+
+ 
+
+ Your browser will be redirected to the Cloudflare dashboard.
+
+Step 10
+: Press the **Import** button to the right of the name of your GitHub repository.
+
+ 
+
+Step 11
+: On the "New Project" page, leave the settings at their default values and press the **Deploy** button.
+
+ 
+
+Step 12
+: When the deployment completes, press the **Continue to Dashboard" button at the bottom of the page.
+
+ 
+
+Step 13
+: On the "Production Deployment" page, click on the link to your published site.
+
+ 
+
+In the future, whenever you push a change from your local Git repository, Vercel will rebuild and deploy your site.
--- /dev/null
- go 1.24
+---
+title: Use Hugo Modules
+description: Use modules to manage the content, layout, presentation, and behavior of your site.
+categories: []
+keywords: []
+weight: 20
+aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/]
+---
+
+> [!note]
+> To work with modules you must install [Git][] and [Go][] 1.18 or later.
+
+## Introduction
+
+{{% glossary-term module %}}
+
+- Modules can be imported in any combination or sequence.
+- Module imports are recursive; importing Module A can trigger the import of Module B, and so on.
+- Modules can provide configuration files and directories, subject to the constraints described in the [merge configuration settings][] section of the documentation.
+- External directories, including those from non-Hugo projects, can be mounted to create a [unified file system](g).
+
+## Import
+
+To import a module, first initialize the project itself as a module. For example:
+
+```sh
+hugo mod init github.com/user/project
+```
+
+This will generate a [`go.mod`][] file in the project root.
+
+> [!note]
+> The module name is a unique identifier rather than a hosting requirement. Using a name like `github.com/user/project` is a common convention but it does not mean you must use Git or host your code on GitHub. You can use any name you like if you do not plan to have others import your project as a module. For example, you could use a simple name such as `my-project` when you run the initialization command.
+
+Then define one or more imports in your project configuration. This contrived example imports three modules, each containing custom shortcodes:
+
+{{< code-toggle file=hugo >}}
+[module]
+ [[module.imports]]
+ path = 'shortcodes-a'
+ [[module.imports]]
+ path = '/home/user/shortcodes-b'
+ [[module.imports]]
+ path = 'github.com/user/shortcodes-c'
+{{< /code-toggle >}}
+
+Import precedence is top-down. For example, if `shortcodes-a`, `shortcodes-b`, and `shortcodes-c` each define an `image` shortcode, the `image` shortcode from `shortcodes-a` will take effect.
+
+> [!note]
+> If multiple modules contain data files or [translation tables](g) with identical paths, the data is deeply merged, following top-down precedence.
+
+When you build your project, Hugo will:
+
+1. Download the modules
+1. Cache them for future use
+1. Generate a [`go.sum`][] file in the project root
+
+See [configuring module imports][] for details and options.
+
+## Update
+
+When you import a module, Hugo creates `go.mod` and `go.sum` files in your project root, storing version and checksum data. Clearing the module cache and rebuilding will re-download the originally imported module version, as specified in the `go.mod` file, ensuring consistent builds. Modules can be updated to other versions as needed.
+
+To update a module to the latest version:
+
+```sh
+hugo mod get -u github.com/user/shortcodes-c
+```
+
+To update a module to a specific version:
+
+```sh
+hugo mod get -u github.com/user/shortcodes-c@v0.42.0
+```
+
+To update all modules to the latest version:
+
+```sh
+hugo mod get -u
+```
+
+To recursively update all modules to the latest version:
+
+```sh
+hugo mod get -u ./...
+```
+
+## Tidy
+
+To remove unused entries from the `go.mod` and `go.sum` files:
+
+```sh
+hugo mod tidy
+```
+
+## Cache
+
+Hugo caches modules to avoid repeated downloads during site builds. By default, these are stored in the `modules` directory within the [`cacheDir`][].
+
+To clean the module cache for the current project:
+
+```sh
+hugo mod clean
+```
+
+To clean the module cache for all projects:
+
+```sh
+hugo mod clean --all
+```
+
+For details on cache location and eviction, see [configuring file caches][].
+
+## Vendor
+
+{{% glossary-term vendor %}}
+
+Vendoring a module provides the benefits described above and allows for local inspection of its [components](g).
+
+```sh
+hugo mod vendor
+```
+
+This command creates a `_vendor` directory containing copies of all imported modules, used in subsequent builds. Note that:
+
+- The `hugo mod vendor` command can be run from any module tree level.
+- Modules within the `themes` directory are not vendored.
+- The `--ignoreVendorPaths` flag allows you to exclude vendored modules matching a [glob pattern](g) from specific commands.
+
+> [!important]
+> Instead of modifying files directly within the `_vendor` directory, override them by creating a corresponding file with the same relative path in your project's root.
+
+To remove the vendored modules, delete the `_vendor` directory.
+
+## Replace
+
+For local module development, use a `replace` directive in `go.mod` pointing to your local directory:
+
+```text
+replace github.com/user/module => /home/user/projects/module
+```
+
+With `hugo serve`r running, this change will trigger a configuration reload and add the local directory to the watch list. Alternatively, configure replacements by setting the [`replacements`][] parameter in your project configuration.
+
+## Workspace
+
+{{% glossary-term "workspace" %}}
+
+Workspaces simplify local development of sites with modules. Create a `.work` file to define a workspace, and activate it via the [`workspace`][] configuration parameter or the `HUGO_MODULE_WORKSPACE` environment variable.
+
+A `.work` file example:
+
+```text
++go 1.25
+
+use .
+use ../my-hugo-module
+```
+
+Use the `use` directive to list module paths, including the main project (`.`). Start the Hugo server with the workspace enabled:
+
+```sh
+HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"
+```
+
+The `--ignoreVendorPaths` flag, used to ignore vendored dependencies (if applicable), enables live reloading of local edits within the workspace.
+
+## Graph
+
+To generate a [dependency graph](g), including vendoring, module replacement, and disabled module information, execute `hugo mod graph` within the target module directory. For example:
+
+```sh
+$ hugo mod graph
+
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0
+github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4
+github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0
+DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396
+github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1
+github.com/bep/my-modular-site in-themesdir
+```
+
+## Mounts
+
+Imported modules automatically mount their component directories to Hugo's [unified file system](g). You can also manually mount any directory, including those from non-Hugo projects, to component directories.
+
+See [configuring module mounts][] for details.
+
+[`cacheDir`]: /configuration/all/#cachedir
+[`go.mod`]: https://go.dev/ref/mod#go-mod-file
+[`go.sum`]: https://go.dev/ref/mod#go-sum-files
+[`replacements`]: /configuration/module/#replacements
+[`workspace`]: /configuration/module/#workspace
+[configuring file caches]: /configuration/caches/
+[configuring module imports]: /configuration/module/#imports
+[configuring module mounts]: /configuration/module/#mounts
+[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
+[Go]: https://go.dev/doc/install
+[merge configuration settings]: /configuration/introduction/#merge-configuration-settings
--- /dev/null
- This example uses the `Identifier` method when querying the translation table on a multilingual site, falling back the `name` property if a matching key in the translation table does not exist:
+---
+title: Identifier
+description: Returns the `identifier` property of the given menu entry.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.Identifier]
+---
+
+The `Identifier` method returns the `identifier` property of the menu entry. If you define the menu entry [automatically], it returns the page's section.
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+identifier = 'about'
+name = 'About'
+pageRef = '/about'
+weight = 10
+
+[[menus.main]]
+identifier = 'contact'
+name = 'Contact'
+pageRef = '/contact'
+weight = 20
+{{< /code-toggle >}}
+
++This example uses the `Identifier` method when querying the translation table on a multilingual project, falling back the `name` property if a matching key in the translation table does not exist:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ or (T .Identifier) .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+> [!note]
+> In the menu definition above, note that the `identifier` property is only required when two or more menu entries have the same name, or when localizing the name using translation tables.
+
+[automatically]: /content-management/menus/#define-automatically
--- /dev/null
- This example uses the `KeyName` method when querying the translation table on a multilingual site, falling back the `name` property if a matching key in the translation table does not exist:
+---
+title: KeyName
+description: Returns the `identifier` property of the given menu entry, falling back to its `name` property.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [MENUENTRY.KeyName]
+---
+
+In this menu definition, the second entry does not contain an `identifier`, so the `Identifier` method returns its `name` property instead:
+
+{{< code-toggle file=hugo >}}
+[[menus.main]]
+identifier = 'about'
+name = 'About'
+pageRef = '/about'
+weight = 10
+
+[[menus.main]]
+name = 'Contact'
+pageRef = '/contact'
+weight = 20
+{{< /code-toggle >}}
+
++This example uses the `KeyName` method when querying the translation table on a multilingual project, falling back the `name` property if a matching key in the translation table does not exist:
+
+```go-html-template
+<ul>
+ {{ range .Site.Menus.main }}
+ <li><a href="{{ .URL }}">{{ or (T (.KeyName | lower)) .Name }}</a></li>
+ {{ end }}
+</ul>
+```
+
+In the example above, we need to pass the value returned by `.KeyName` through the [`lower`] function because the keys in the translation table are lowercase.
+
+[`lower`]: /functions/strings/tolower/
--- /dev/null
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
+---
+title: Aliases
+description: Returns the aliases defined in front matter as server-relative URLs, resolved according to the current content dimension.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]string'
+ signatures: [PAGE.Aliases]
+---
+
+The `Aliases` method on a `Page` object returns the values defined in the [`aliases`][] front matter field as server-relative URLs, resolved according to the current [content dimension](g).
+
+The `Aliases` method is useful for generating a `_redirects` file, which contains a source URL, a target URL, and an HTTP status code for each alias. You can use a `_redirects` file with hosting services such as Cloudflare, GitLab Pages, and Netlify.
+
+## Redirects
+
+By default, Hugo handles aliases by creating individual HTML files for each alias path. These files contain a `meta http-equiv="refresh"` tag to redirect the visitor via the browser.
+
+While functional, generating a single `_redirects` file allows your hosting provider to handle redirects at the server level. This is more efficient than client-side redirection and improves performance by eliminating the need to load a middle-man HTML page.
+
+> [!tip]
+> You can use the same general approach to generate an `.htaccess` file.
+
+## Example
+
+The following example demonstrates how to configure your site and create a template to automate the generation of a `_redirects` file.
+
+### Content structure
+
+The content structure for this multilingual example looks like this:
+
+```text
+content/
+├── examples/
+│ ├── a.de.md aliases = ['a-old']
+│ ├── a.en.md aliases = ['a-old', 'a-older']
+│ ├── b.de.md aliases = ['b-old']
+│ └── b.en.md aliases = ['b-old', 'b-older']
+└── _index.md
+```
+
+In the example above, the aliases are [page-relative](g). To specify a [site-relative](g) path, preface the entry with a slash (`/`). Both forms are resolved to [server-relative](g) paths.
+
+Page-relative paths can also include directory traversal:
+
+| Path type | File path | Alias | Server-relative path |
+| :--- | :--- | :--- | :--- |
+| page-relative | `content/examples/a.en.md` | `a-old` | `/en/examples/a-old/` |
+| page-relative | `content/examples/a.en.md` | `../a-old` | `/en/a-old/` |
+| site-relative | `content/examples/a.en.md` | `/a-old` | `/en/a-old/` |
+
+### Project configuration
+
+To implement this, you must update your project configuration to:
+
+1. Disable the generation of default HTML redirect files by setting `disableAliases` to `true`.
+1. Define a [media type][] named `text/redirects` to handle the file format.
+1. Define a custom [output format][] named `redirects` to set the filename to `_redirects` and place it at the root of the published site.
+1. Configure the home page [outputs][] to include the `redirects` format in addition to `html`.
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+disableAliases = true
+
+defaultContentLanguage = 'en'
+defaultContentLanguageInSubdir = true
+
+[languages.en]
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
++ locale = 'en-US'
++ direction = 'ltr'
++ name = 'English'
+ weight = 1
+ title = 'My Site in English'
+
+[languages.de]
++ locale = 'de-DE'
++ direction = 'ltr'
++ name = 'Deutsch'
+ weight = 2
+ title = 'My Site in German'
+
+[mediaTypes]
+ [mediaTypes.'text/redirects']
+ delimiter = ''
+
+[outputFormats]
+ [outputFormats.redirects]
+ baseName = '_redirects'
+ isPlainText = true
+ mediaType = 'text/redirects'
+ root = true
+
+[outputs]
+ home = ['html', 'redirects']
+{{< /code-toggle >}}
+
+### Template implementation
+
+Next, create a home page template specifically for the `redirects` output format. The following template iterates through every page in every language and extracts its aliases.
+
+To ensure the resulting `_redirects` file is valid, the template uses the [`strings.FindRE`][] function to check for whitespace such as tabs or newlines within the alias string. If whitespace is detected, Hugo will throw an error and fail the build to prevent generating an invalid file.
+
+```go-html-template {file="layouts/home.redirects" copy=true}
+{{- if site.IsDefault -}}
+ {{- range hugo.Sites -}}
+ {{- range $p := .Pages -}}
+ {{- range .Aliases -}}
+ {{- if findRE `\s` . -}}
+ {{- errorf "One of the front matter aliases in %q contains whitespace" $p.String -}}
+ {{- end -}}
+ {{- printf "%s %s 301\n" . $p.RelPermalink -}}
+ {{- end -}}
+ {{- end -}}
+ {{- end -}}
+{{- end -}}
+```
+
+### Generated output
+
+Once Hugo processes the template, it produces a clean list of redirect rules. Each line follows the required format: the source URL, the destination URL, and the HTTP status code.
+
+The resulting `_redirects` file looks like this:
+
+```text
+/de/examples/a-old /de/examples/a/ 301
+/de/examples/b-old /de/examples/b/ 301
+/en/examples/b-old /en/examples/b/ 301
+/en/examples/b-older /en/examples/b/ 301
+/en/examples/a-old /en/examples/a/ 301
+/en/examples/a-older /en/examples/a/ 301
+```
+
+[`aliases`]: /content-management/front-matter/#aliases
+[`strings.FindRE`]: /functions/strings/findre/
+[media type]: /configuration/media-types/
+[output format]: /configuration/output-formats/
+[outputs]: /configuration/outputs/
--- /dev/null
- description: Returns all translations of the given page, including the current language, sorted by language weight.
+---
+title: AllTranslations
- languageCode = 'en-US'
- languageName = 'English'
++description: Returns all translations of the given page, including the current language, sorted by language weight then language name.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.AllTranslations]
+---
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
- languageCode = 'de-DE'
- languageName = 'Deutsch'
++label = 'English'
++locale = 'en-US'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
- languageCode = 'fr-FR'
- languageName = 'Français'
++label = 'Deutsch'
++locale = 'de-DE'
+weight = 2
+
+[languages.fr]
+contentDir = 'content/fr'
- <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a>
++label = 'Français'
++locale = 'fr-FR'
+weight = 3
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── fr/
+│ ├── books/
+│ │ └── book-1.md
+│ └── _index.md
+└── _index.md
+```
+
+And this template:
+
+```go-html-template
+{{ with .AllTranslations }}
+ <ul>
+ {{ range . }}
+ <li>
++ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.Locale }}">{{ .LinkTitle }} ({{ or .Language.Label .Language.Name }})</a>
+ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo will render this list on the "Book 1" page of each site:
+
+```html
+<ul>
+ <li><a href="/books/book-1/" hreflang="en-US">Book 1 (English)</a></li>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+ <li><a href="/fr/books/book-1/" hreflang="fr-FR">Book 1 (Français)</a></li>
+</ul>
+```
+
+On the "Book 2" page of the English and German sites, Hugo will render this:
+
+```html
+<ul>
+ <li><a href="/books/book-1/" hreflang="en-US">Book 1 (English)</a></li>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+</ul>
+```
--- /dev/null
- description: Returns Git information related to the last commit of the given page.
+---
+title: GitInfo
- The `GitInfo` method on a `Page` object returns an object with additional methods.
++description: Provides access to commit metadata for a given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '*gitmap.GitInfo'
+ signatures: [PAGE.GitInfo]
+---
+
- > Hugo's Git integration is performant, but may increase build times on large sites.
++The `GitInfo` method on a `Page` object provides access to commit metadata from your Git history, such as the author's name, the commit hash, and the commit message.
+
+> [!note]
- You must also allow Hugo to access your repository. In your project configuration:
++> Hugo's Git integration is performant, but may increase build times for large projects.
+
+## Prerequisites
+
+Install Git, create a repository, and commit your project files.
+
- Alternatively, use the command line flag when building your project:
-
- ```sh
- hugo build --enableGitInfo
- ```
-
++You must also allow Hugo to access your repository by adding this to your project configuration:
+
+{{< code-toggle file=hugo >}}
+enableGitInfo = true
+{{< /code-toggle >}}
+
- > 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.
+> [!note]
- > This is configurable. See [details].
++> When you set [`enableGitInfo`][] to `true`, the last modification date for each content page will automatically be the Author Date of the last commit for that file.
+>
- (`string`) The abbreviated commit hash.
++> This is configurable. See [details][].
++
++## Scope
++
++Commit metadata is available for content stored in your local repository and for content provided by [modules](g).
++
++### Local content
++
++Hugo retrieves commit metadata for files tracked within your project's local repository. This includes all content files managed by Git in your main project directory.
++
++### Module content
++
++{{< new-in 0.157.0 />}}
++
++Hugo also retrieves commit metadata for content provided by modules. This allows you to display commit data for remote repositories that are mounted as content directories, such as when aggregating documentation from multiple sources.
+
+## Methods
+
+### AbbreviatedHash
+
- {{ .AbbreviatedHash }} → aab9ec0b3
++(`string`) Returns the seven-character shortened version of the commit hash.
+
+```go-html-template
+{{ with .GitInfo }}
- (`time.Time`) The author date.
++ {{ .AbbreviatedHash }} → aab9ec0
+{{ end }}
+```
+
+### AuthorDate
+
- (`string`) The author's email address, respecting [gitmailmap].
++(`time.Time`) Returns the date the author originally created the commit.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AuthorDate.Format "2006-01-02" }} → 2023-10-09
+{{ end }}
+```
+
+### AuthorEmail
+
- (`string`) The author's name, respecting [gitmailmap].
++(`string`) Returns the author's email address, respecting [gitmailmap][].
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AuthorEmail }} → jsmith@example.org
+{{ end }}
+```
+
+### AuthorName
+
- (`time.Time`) The commit date.
++(`string`) Returns the author's name, respecting [gitmailmap][].
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .AuthorName }} → John Smith
+{{ end }}
+```
+
+### CommitDate
+
- (`string`) The commit hash.
++(`time.Time`) Returns the date the commit was applied to the branch.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .CommitDate.Format "2006-01-02" }} → 2023-10-09
+{{ end }}
+```
+
+### Hash
+
- (`string`) The commit message subject.
++(`string`) Returns the full SHA-1 commit hash.
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .Hash }} → aab9ec0b31ebac916a1468c4c9c305f2bebf78d4
+{{ end }}
+```
+
+### Subject
+
- (`string`) The commit message body.
++(`string`) Returns the first line of the commit message (the summary).
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ .Subject }} → Add tutorials
+{{ end }}
+```
+
+### Body
+
- {{ .Body }} → - Two new pages added.
++(`string`) Returns the full content of the commit message, excluding the subject line.
+
+```go-html-template
+{{ with .GitInfo }}
- (`gitmap.GitInfos`) A slice of file-filtered ancestor commits, if any, ordered from most recent to least recent.
++ {{ .Body }} → Two new pages added.
+{{ end }}
+```
+
+### Ancestors
+
- (`*gitmap.GitInfo`) The first file-filtered ancestor commit, if any.
++(`gitmap.GitInfos`) Returns a list of previous commits for this specific file, ordered from most recent to oldest.
+
+For example, to list the last 5 commits:
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ range .Ancestors | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+{{ end }}
+```
+
+To reverse the order:
+
+```go-html-template
+{{ with .GitInfo }}
+ {{ range .Ancestors.Reverse | first 5 }}
+ {{ .CommitDate.Format "2006-01-02" }}: {{ .Subject }}
+ {{ end }}
+{{ end }}
+```
+
+### Parent
+
- You can change this behavior in your [project configuration].
++(`*gitmap.GitInfo`) Returns the most recent ancestor commit for the file, if any.
+
+## Last modified date
+
+By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` object returns the Git AuthorDate of the last commit that included the file.
+
++You can change this behavior in your [project configuration][].
+
+## Hosting considerations
+
+On a [CI/CD](g) platform, 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 be inaccurate. It might incorrectly reflect the most recent repository commit, rather than the commit that actually modified the file.
+
+While some providers perform a deep clone by default, others require you to configure the depth yourself.
+
+Hosting service|Default clone depth|Configurable
+:--|:--|:--
+AWS Amplify|Deep|N/A
+Cloudflare|Shallow|Yes [^1]
+DigitalOcean App Platform|Deep|N/A
+GitHub Pages|Shallow|Yes [^2]
+GitLab Pages|Shallow|Yes [^3]
+Netlify|Deep|N/A
+Render|Shallow|Yes [^1]
+Vercel|Shallow|Yes [^1]
+
+[^1]: To perform a deep clone when hosting on Cloudflare, Render, or Vercel, include this code in the build script after the repository has been cloned:
+
+ ```text
+ if [ "$(git rev-parse --is-shallow-repository)" = "true" ]; then
+ git fetch --unshallow
+ fi
+ ```
+
+[^2]: To perform a deep clone when hosting on GitHub Pages, set `fetch-depth: 0` in the `checkout` step of the GitHub Action. See [example](/host-and-deploy/host-on-github-pages/#step-7).
+
+[^3]: To perform a deep clone when hosting on GitLab Pages, set the `GIT_DEPTH` environment variable to `0` in the workflow file. See [example](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd).
+
++[`enableGitInfo`]: /configuration/all/#enablegitinfo
+[details]: /configuration/front-matter/#dates
+[gitmailmap]: https://git-scm.com/docs/gitmailmap
+[project configuration]: /configuration/front-matter/
--- /dev/null
- languageCode = 'en-US'
- languageName = 'English'
+---
+title: IsTranslated
+description: Reports whether the given page has one or more translations.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [PAGE.IsTranslated]
+---
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
- languageCode = 'de-DE'
- languageName = 'Deutsch'
++label = 'English'
++locale = 'en-US'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
++label = 'Deutsch'
++locale = 'de-DE'
+weight = 2
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ └── book-1.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+└── _index.md
+```
+
+When rendering `content/en/books/book-1.md`:
+
+```go-html-template
+{{ .IsTranslated }} → true
+```
+
+When rendering `content/en/books/book-2.md`:
+
+```go-html-template
+{{ .IsTranslated }} → false
+```
--- /dev/null
- The examples below assume the following in your project configuration:
+---
+title: Language
+description: Returns the Language object for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: langs.Language
+ signatures: [PAGE.Language]
+---
+
+The `Language` method on a `Page` object returns the `Language` object for the given page, derived from the language definition in your project configuration.
+
+You can also use the `Language` method on a `Site` object. See [details][].
+
+## Methods
+
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
++The examples below assume the following language definition.
+
+{{< code-toggle file=hugo >}}
+[languages.de]
- ### Lang
++direction = 'ltr'
++label = 'Deutsch'
++locale = 'de-DE'
+weight = 2
+{{< /code-toggle >}}
+
++### Direction
++
++{{< new-in 0.158.0 />}}
++
++(`string`) Returns the [`direction`][] from the language definition.
++
++```go-html-template
++{{ .Language.Direction }} → ltr
++```
++
+### IsDefault
+
+{{< new-in 0.153.0 />}}
+
+(`bool`) Reports whether this is the [default language][].
+
+```go-html-template
+{{ .Language.IsDefault }} → true
+```
+
- (`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration.
++### Label
+
- {{ .Language.Lang }} → de
++{{< new-in 0.158.0 />}}
++
++(`string`) Returns the [`label`][] from the language definition.
+
+```go-html-template
- (`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined.
++{{ .Language.Label }} → Deutsch
+```
+
++### Lang
++
++{{<deprecated-in 0.158.0 />}}
++
++Use [`Name`](#name) instead.
++
+### LanguageCode
+
- ```go-html-template
- {{ .Language.LanguageCode }} → de-DE
- ```
++{{<deprecated-in 0.158.0 />}}
+
- (`string`) Returns the [`languageDirection`][] from your project configuration.
++Use [`Locale`](#locale) instead.
+
+### LanguageDirection
+
- ```go-html-template
- {{ .Language.LanguageDirection }} → ltr
- ```
++{{<deprecated-in 0.158.0 />}}
+
- (`string`) Returns the [`languageName`][] from your project configuration.
++Use [`Direction`](#direction) instead.
+
+### LanguageName
+
- {{ .Language.LanguageName }} → Deutsch
++{{<deprecated-in 0.158.0 />}}
++
++Use [`Label`](#label) instead.
++
++### Locale
++
++{{< new-in 0.158.0 />}}
++
++(`string`) Returns the [`locale`][] from the language definition, falling back to [`Name`](#name).
+
+```go-html-template
- (`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`.
++{{ .Language.Locale }} → de-DE
+```
+
+### Name
+
+{{< new-in 0.153.0 />}}
+
- (`int`) Returns the language [`weight`][] from your project configuration.
++(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from the language definition.
+
+```go-html-template
+{{ .Language.Name }} → de
+```
+
+### Weight
+
- ```go-html-template
- {{ .Language.Weight }} → 2
- ```
-
- [`languageCode`]: /configuration/languages/#languagecode
- [`languageDirection`]: /configuration/languages/#languagedirection
- [`languageName`]: /configuration/languages/#languagename
- [`weight`]: /configuration/languages/#weight
- [default language]: /quick-reference/glossary/#default-language
- [details]: /methods/page/language/
++{{<deprecated-in 0.158.0 />}}
+
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
++[`direction`]: /configuration/languages/#direction
++[`label`]: /configuration/languages/#label
++[`locale`]: /configuration/languages/#locale
++[default language]: /quick-reference/glossary/#default-language
++[details]: /methods/site/language/
++
++## Example
++
++Use the code below to create a language selector, allowing users to navigate between the different translated versions of the current page.
++
++```go-html-template {file="layouts/_partials/language-selector.html" copy=true}
++{{ with .Rotate "language" }}
++ <nav class="language-selector">
++ <ul>
++ {{ range . }}
++ {{ if eq .Language $.Language }}
++ <li class="active">
++ <a aria-current="page" href="{{ .Permalink }}" hreflang="{{ .Language.Locale }}">{{ .Language.Label }}</a>
++ </li>
++ {{ else }}
++ <li>
++ <a href="{{ .Permalink }}" hreflang="{{ .Language.Locale }}">{{ .Language.Label }}</a>
++ </li>
++ {{ end }}
++ {{ end }}
++ </ul>
++ </nav>
++{{ end }}
++```
--- /dev/null
- ### Monolingual site
+---
+title: Path
+description: Returns the logical path of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Path]
+---
+
+The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file.
+
+{{% glossary-term "logical path" %}}
+
+```go-html-template
+{{ .Path }} → /posts/post-1
+```
+
+> [!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.
+
+## Examples
+
++### Monolingual project
+
+Note that the logical path is independent of content format and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.md`||`/`
+`content/posts/_index.md`||`/posts`
+`content/posts/post-1.md`|`foo`|`/posts/post-1`
+`content/posts/post-2.html`|`bar`|`/posts/post-2`
+
+### Multilingual site
+
+Note that the logical path is independent of content format, language identifiers, and URL modifiers.
+
+File path|Front matter slug|Logical path
+:--|:--|:--
+`content/_index.en.md`||`/`
+`content/_index.de.md`||`/`
+`content/posts/_index.en.md`||`/posts`
+`content/posts/_index.de.md`||`/posts`
+`content/posts/posts-1.en.md`|`foo`|`/posts/post-1`
+`content/posts/posts-1.de.md`|`foo`|`/posts/post-1`
+`content/posts/posts-2.en.html`|`bar`|`/posts/post-2`
+`content/posts/posts-2.de.html`|`bar`|`/posts/post-2`
+
+### Pages not backed by a file
+
+The `Path` method on a `Page` object returns a value regardless of whether the page is backed by a file.
+
+```text
+content/
+└── posts/
+ └── post-1.md <-- front matter: tags = ['hugo']
+```
+
+When you build the site:
+
+```text
+public/
+├── posts/
+│ ├── post-1/
+│ │ └── index.html .Page.Path = /posts/post-1
+│ └── index.html .Page.Path = /posts
+├── tags/
+│ ├── hugo/
+│ │ └── index.html .Page.Path = /tags/hugo
+│ └── index.html .Page.Path = /tags
+└── index.html .Page.Path = /
+```
+
+## Finding pages
+
+These methods, functions, and shortcodes use the logical path to find the given page:
+
+Methods|Functions|Shortcodes
+:--|:--|:--
+[`Site.GetPage`]|[`urls.Ref`]|[`ref`]
+[`Page.GetPage`]|[`urls.RelRef`]|[`relref`]
+[`Page.Ref`]| |
+[`Page.RelRef`]| |
+[`Shortcode.Ref`]| |
+[`Shortcode.RelRef`]| |
+
+> [!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
+
+Just as file paths form a file tree, logical paths form a logical tree.
+
+A file tree:
+
+```text
+content/
+└── s1/
+ ├── p1/
+ │ └── index.md
+ └── p2.md
+```
+
+The same content represented as a logical tree:
+
+```text
+content/
+└── s1/
+ ├── p1
+ └── p2
+```
+
+A key difference between these trees is the relative path from p1 to p2:
+
+- In the file tree, the relative path from p1 to p2 is `../p2.md`
+- In the logical tree, the relative path is `p2`
+
+> [!note]
+> Remember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
+
+[`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
--- /dev/null
- The `Plain` method on a `Page` object renders Markdown and [shortcodes](g) to HTML, then strips the HTML [tags]. It does not strip HTML [entities].
+---
+title: Plain
+description: Returns the rendered content of the given page, removing all HTML tags.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.Plain]
+---
+
- To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function.
++The `Plain` method on a `Page` object renders Markdown and [shortcodes](g) to HTML, then strips the HTML [tags][]. It does not strip HTML [entities][].
+
- [html/template]: https://pkg.go.dev/html/template
++To prevent Go's [`html/template`][] package from escaping HTML entities, pass the result through the [`htmlUnescape`][] function.
+
+```go-html-template
+{{ .Plain | htmlUnescape }}
+```
+
++[`html/template`]: https://pkg.go.dev/html/template
+[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
+[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag
+[`htmlUnescape`]: /functions/transform/htmlunescape/
--- /dev/null
- Reading speed varies by language. Create language-specific estimated reading times on your multilingual site using site parameters.
+---
+title: ReadingTime
+description: Returns the estimated reading time, in minutes, for the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGE.ReadingTime]
+---
+
+The estimated reading time is calculated by dividing the number of words in the content by the reading speed.
+
+By default, Hugo assumes a reading speed of 212 words per minute. For CJK languages, it assumes 500 words per minute.
+
+```go-html-template
+{{ printf "Estimated reading time: %d minutes" .ReadingTime }}
+```
+
- languageCode = 'de-DE'
- languageName = 'Deutsch'
++Reading speed varies by language. Create language-specific estimated reading times on your multilingual project using site parameters.
+
+{{< code-toggle file=hugo >}}
+[languages]
+ [languages.de]
+ contentDir = 'content/de'
- languageCode = 'en-US'
- languageName = 'English'
++ label = 'Deutsch'
++ locale = 'de-DE'
+ weight = 2
+ [languages.de.params]
+ reading_speed = 179
+ [languages.en]
+ contentDir = 'content/en'
++ label = 'English'
++ locale = 'en-US'
+ weight = 1
+ [languages.en.params]
+ reading_speed = 228
+{{< /code-toggle >}}
+
+Then in your template:
+
+```go-html-template
+{{ $readingTime := div (float .WordCount) .Site.Params.reading_speed }}
+{{ $readingTime = math.Ceil $readingTime }}
+```
+
+We cast the `.WordCount` to a float to obtain a float when we divide by the reading speed. Then round up to the nearest integer.
--- /dev/null
- description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in the site configuration.
+---
+title: Sitemap
++description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in your project configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: config.SitemapConfig
+ signatures: [PAGE.Sitemap]
+---
+
+Access to the `Sitemap` method on a `Page` object is restricted to [sitemap templates].
+
+## Methods
+
+### ChangeFreq
+
+(`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef).
+
+```go-html-template
+{{ .Sitemap.ChangeFreq }}
+```
+
+### Disable
+
+(`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
+
+```go-html-template
+{{ .Sitemap.Disable }}
+```
+
+### Priority
+
+(`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#prioritydef).
+
+```go-html-template
+{{ .Sitemap.Priority }}
+```
+
+## Example
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+[sitemap]
+changeFreq = 'monthly'
+{{< /code-toggle >}}
+
+And this content:
+
+{{< code-toggle file=content/news.md fm=true >}}
+title = 'News'
+[sitemap]
+changeFreq = 'hourly'
+{{< /code-toggle >}}
+
+And this simplistic sitemap template:
+
+```xml {file="layouts/sitemap.xml"}
+{{ printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+ xmlns:xhtml="http://www.w3.org/1999/xhtml">
+ {{ range .Pages }}
+ <url>
+ <loc>{{ .Permalink }}</loc>
+ {{ if not .Lastmod.IsZero }}
+ <lastmod>{{ .Lastmod.Format "2006-01-02T15:04:05-07:00" | safeHTML }}</lastmod>
+ {{ end }}
+ {{ with .Sitemap.ChangeFreq }}
+ <changefreq>{{ . }}</changefreq>
+ {{ end }}
+ </url>
+ {{ end }}
+</urlset>
+```
+
+The change frequency will be `hourly` for the news page, and `monthly` for other pages.
+
+[sitemap templates]: /templates/sitemap/
--- /dev/null
- Use [`hugo.Sites`] instead.
-
- [`hugo.Sites`]: /functions/hugo/sites/
+---
+title: Sites
+description: Returns a collection of all sites for all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Sites
+ signatures: [PAGE.Sites]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
-
- {{% include "/_common/functions/hugo/sites-collection.md" %}}
-
- With this project configuration:
-
- {{< code-toggle file=hugo >}}
- defaultContentLanguage = 'de'
- defaultContentLanguageInSubdir = true
- defaultContentVersionInSubdir = true
-
- [languages.de]
- contentDir = 'content/de'
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
- title = 'Projekt Dokumentation'
- weight = 1
-
- [languages.en]
- contentDir = 'content/en'
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
- title = 'Project Documentation'
- weight = 2
-
- [versions.'v1.0.0']
- [versions.'v2.0.0']
- [versions.'v3.0.0']
- {{< /code-toggle >}}
-
- This template:
-
- ```go-html-template
- <ul>
- {{ range .Sites }}
- <li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
- {{ end }}
- </ul>
- ```
-
- Produces a list of links to each home page:
-
- ```html
- <ul>
- <li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
- <li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
- <li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
- <li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
- <li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
- <li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
- </ul>
- ```
-
- To render a link to the home page of the [default site](g):
-
- ```go-html-template
- {{ with .Sites.Default }}
- <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
- {{ end }}
- ```
-
- This is equivalent to:
-
- ```go-html-template
- {{ with index .Sites 0 }}
- <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
- {{ end }}
- ```
++Use [`hugo.Sites`](/functions/hugo/sites/) instead.
+{{< /deprecated-in >}}
--- /dev/null
- languageCode = 'en-US'
- languageName = 'English'
+---
+title: TranslationKey
+description: Returns the translation key of the given page.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [PAGE.TranslationKey]
+---
+
+The translation key creates a relationship between all translations of a given page. The translation key is derived from the file path, or from the `translationKey` parameter if defined in front matter.
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
- languageCode = 'de-DE'
- languageName = 'Deutsch'
++label = 'English'
++locale = 'en-US'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
++label = 'Deutsch'
++locale = 'de-DE'
+weight = 2
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ ├── buch-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+└── _index.md
+```
+
+And this front matter:
+
+{{< code-toggle file=content/en/books/book-1.md fm=true >}}
+title = 'Book 1'
+translationKey = 'foo'
+{{< /code-toggle >}}
+
+{{< code-toggle file=content/de/books/buch-1.md fm=true >}}
+title = 'Buch 1'
+translationKey = 'foo'
+{{< /code-toggle >}}
+
+When rendering either either of the pages above:
+
+```go-html-template
+{{ .TranslationKey }} → page/foo
+```
+
+If the front matter of Book 2, in both languages, does not include a translation key:
+
+```go-html-template
+{{ .TranslationKey }} → page/books/book-2
+```
--- /dev/null
- description: Returns all translations of the given page, excluding the current language, sorted by language weight.
+---
+title: Translations
- languageCode = 'en-US'
- languageName = 'English'
++description: Returns all translations of the given page, excluding the current language, sorted by language weight then language name.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.Translations]
+---
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'en'
+
+[languages.en]
+contentDir = 'content/en'
- languageCode = 'de-DE'
- languageName = 'Deutsch'
++label = 'English'
++locale = 'en-US'
+weight = 1
+
+[languages.de]
+contentDir = 'content/de'
- languageCode = 'fr-FR'
- languageName = 'Français'
++label = 'Deutsch'
++locale = 'de-DE'
+weight = 2
+
+[languages.fr]
+contentDir = 'content/fr'
- <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a>
++label = 'Français'
++locale = 'fr-FR'
+weight = 3
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+├── de/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── en/
+│ ├── books/
+│ │ ├── book-1.md
+│ │ └── book-2.md
+│ └── _index.md
+├── fr/
+│ ├── books/
+│ │ └── book-1.md
+│ └── _index.md
+└── _index.md
+```
+
+And this template:
+
+```go-html-template
+{{ with .Translations }}
+ <ul>
+ {{ range . }}
+ <li>
++ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.Locale }}">{{ .LinkTitle }} ({{ or .Language.Label .Language.Name }})</a>
+ </li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Hugo will render this list on the "Book 1" page of the English site:
+
+```html
+<ul>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+ <li><a href="/fr/books/book-1/" hreflang="fr-FR">Book 1 (Français)</a></li>
+</ul>
+```
+
+Hugo will render this list on the "Book 2" page of the English site:
+
+```html
+<ul>
+ <li><a href="/de/books/book-1/" hreflang="de-DE">Book 1 (Deutsch)</a></li>
+</ul>
+```
--- /dev/null
- {{< new-in 0.128.0 />}}
-
+---
+title: PagerSize
+description: Returns the number of pages per pager.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [PAGER.PagerSize]
++aliases: [/methods/pager/pagesize/]
+---
+
+The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [project configuration].
+
+[`Paginate`]: /methods/page/paginate/
+[project configuration]: /templates/pagination/#configuration
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ with $paginator }}
+ {{ .PagerSize }}
+{{ end }}
+```
--- /dev/null
- The `Colors` method on a `Resource` image object returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image.
+---
+title: Colors
+description: Applicable to images, returns a slice of the most dominant colors using a simple histogram method.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: '[]images.Color'
+ signatures: [RESOURCE.Colors]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- Each color is an object with the following methods:
++The `Colors` method returns a slice of the most dominant colors in a [processable image](g), ordered from most dominant to least dominant.
++
++> [!note]
++> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
++
++## Usage
++
++This method is fast, but if you downscale your image first, you can further improve performance by extracting colors from the smaller resource.
+
+## Methods
+
- (`string`) Returns the [hexadecimal color] value, prefixed with a hash sign.
++Each color in the slice is an object with the following methods:
+
+### ColorHex
+
- (`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.
++(`string`) Returns the [hexadecimal color][] value, prefixed with a hash sign.
+
+### Luminance
+
- > 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.
++(`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]
- In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG] guidelines for either the [minimum] or the [enhanced] contrast ratio?
++> 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
+
+As a contrived example, create a table of an image's dominant colors with the most dominant color first, and display the relative luminance of each dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ <table>
+ <thead>
+ <tr>
+ <th>Color</th>
+ <th>Relative luminance</th>
+ </tr>
+ </thead>
+ <tbody>
+ {{ range .Colors }}
+ <tr>
+ <td>{{ .ColorHex }}</td>
+ <td>{{ .Luminance | lang.FormatNumber 4 }}</td>
+ </tr>
+ {{ end }}
+ </tbody>
+ </table>
+{{ end }}
+```
+
+Hugo renders this to:
+
+ColorHex|Relative luminance
+:--|:--
+`#bebebd`|`0.5145`
+`#514947`|`0.0697`
+`#768a9a`|`0.2436`
+`#647789`|`0.1771`
+`#90725e`|`0.1877`
+`#a48974`|`0.2704`
+
+To sort by dominance with the least dominant color first:
+
+```go-html-template
+{{ range .Colors | collections.Reverse }}
+```
+
+To sort by relative luminance with the darkest color first:
+
+```go-html-template
+{{ range sort .Colors "Luminance" }}
+```
+
+To sort by relative luminance with the lightest color first, use either of these constructs:
+
+```go-html-template
+{{ range sort .Colors "Luminance" | collections.Reverse }}
+{{ range sort .Colors "Luminance" "desc" }}
+```
+
+## Examples
+
+### Image borders
+
+To add a 5 pixel border to an image using the most dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $mostDominant := index .Colors 0 }}
+ {{ $filter := images.Padding 5 $mostDominant }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+To add a 5 pixel border to an image using the darkest dominant color:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $filter := images.Padding 5 $darkest }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+### Light text on dark background
+
+To create a text box where the foreground and background colors are derived from an image's lightest and darkest dominant colors:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+ <div style="background: {{ $darkest }};">
+ <div style="color: {{ $lightest }};">
+ <p>This is light text on a dark background.</p>
+ </div>
+ </div>
+{{ end }}
+```
+
+### WCAG contrast ratio
+
- The WCAG defines the [contrast ratio] as:
++In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG][] guidelines for either the [minimum][] or the [enhanced][] contrast ratio?
+
- where $L_1$ is the relative luminance of the lightest color and $L_2$ is the relative luminance of the darkest color.
++The WCAG defines the [contrast ratio][] as:
+
+$$contrast\ ratio = { L_1 + 0.05 \over L_2 + 0.05 }$$
+
- [WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
++where \(L_1\) is the relative luminance of the lightest color and \(L_2\) is the relative luminance of the darkest color.
+
+Calculate the contrast ratio to determine WCAG conformance:
+
+```go-html-template
+{{ with resources.Get "images/a.jpg" }}
+ {{ $lightest := index (sort .Colors "Luminance" "desc") 0 }}
+ {{ $darkest := index (sort .Colors "Luminance") 0 }}
+ {{ $cr := div
+ (add $lightest.Luminance 0.05)
+ (add $darkest.Luminance 0.05)
+ }}
+ {{ if ge $cr 7.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AAA." $cr }}
+ {{ else if ge $cr 4.5 }}
+ {{ printf "The %.2f contrast ratio conforms to WCAG Level AA." $cr }}
+ {{ else }}
+ {{ printf "The %.2f contrast ratio does not conform to WCAG guidelines." $cr }}
+ {{ end }}
+{{ end }}
+```
+
++[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
+[`images.Dither`]: /functions/images/dither/
+[`images.Padding`]: /functions/images/padding/
+[`images.Text`]: /functions/images/text/
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[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
--- /dev/null
- Crop an image according to the given [processing specification][]. When cropping, you must provide both width and height (such as `200x200`) within the specification. This method does not perform any resizing; it simply extracts a region of the image based on the dimensions and the [anchor](#anchor) provided, if any.
+---
+title: Crop
+description: Applicable to images, returns a new image resource cropped according to the given processing specification.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Crop SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- In the example above, `"200x200 TopRight"` is the _processing specification_.
++The `Crop` method returns a new resource from a [processable image](g) according to the given [processing specification][].
++
++> [!note]
++> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
++
++## Usage
++
++When cropping, you must provide both width and height (such as `200x200`) within the specification. This method does not perform any resizing; it simply extracts a region of the image based on the dimensions and the [anchor](#anchor) provided, if any.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Crop "200x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
++In the example above, `"200x200 TopRight"` is the processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Crop "200x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="crop 200x200 TopRight"
+ example=true
+>}}
+
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
--- /dev/null
-
- The `Err` method on a resource returned by the [`resources.GetRemote`] function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build.
-
- [`resources.GetRemote`]: /functions/resources/getremote/
-
- In this example we send an HTTP request to a nonexistent domain:
-
- ```go-html-template
- {{ $url := "https://broken-example.org/images/a.jpg" }}
- {{ with resources.GetRemote $url }}
- {{ with .Err }}
- {{ errorf "%s" . }}
- {{ else }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
- {{ end }}
- {{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
- {{ end }}
- ```
-
- The code above captures the error from the HTTP request, then fails the build:
-
- ```text
- ERROR error calling resources.GetRemote: Get "https://broken-example.org/images/a.jpg": dial tcp: lookup broken-example.org on 127.0.0.53:53: no such host
- ```
-
- To log an error as a warning instead of an error:
-
- ```go-html-template
- {{ $url := "https://broken-example.org/images/a.jpg" }}
- {{ with resources.GetRemote $url }}
- {{ with .Err }}
- {{ warnf "%s" . }}
- {{ else }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
- {{ end }}
- {{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
- {{ 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.
+---
+title: Err
+description: Applicable to resources returned by the resources.GetRemote function, returns an error message if the HTTP request fails, else nil.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: resource.resourceError
+ signatures: [RESOURCE.Err]
+expiryDate: 2027-01-16 # deprecated 2025-01-16 in v0.141.0
+---
+
+{{< deprecated-in 0.141.0 >}}
+Use the `try` statement instead. See [example].
+
+[example]: /functions/go-template/try/#example
+{{< /deprecated-in >}}
--- /dev/null
- description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif metadata.
+---
+title: Exif
- {{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-
- Applicable to JPEG, PNG, TIFF, and WebP images, the `Exif` method on an image `Resource` object returns an object containing [Exif][Exif_Definition] metadata.
-
- To extract [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata, use the [`Meta`] method instead.
-
- > [!note]
- > Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from JPEG, PNG, TIFF, and WebP images.
-
- ## Methods
-
- ### Date
-
- (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function.
-
- ### Lat
-
- (`float64`) Returns the GPS latitude in degrees from Exif metadata.
-
- ### Long
-
- (`float64`) Returns the GPS longitude in degrees from Exif metadata.
-
- ### Tags
-
- (`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`includeFields`][] and [`excludeFields`][] settings in your project configuration.
-
- ## Examples
-
- To list the creation date, latitude, and longitude:
-
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ with .Exif }}
- <pre>
- {{ printf "%-25s %v\n" "Date" .Date }}
- {{ printf "%-25s %v\n" "Latitude" .Lat }}
- {{ printf "%-25s %v\n" "Longitude" .Long }}
- </pre>
- {{ end }}
- {{ end }}
- ```
-
- To list the available Exif fields:
-
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ with .Exif }}
- <pre>
- {{ range $k, $v := .Tags -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
- {{ end }}
- {{ end }}
- ```
-
- To list specific Exif fields:
-
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ with .Exif }}
- <pre>
- {{ with .Tags.ApertureValue }}{{ printf "%-25s %v\n" "ApertureValue" . }}{{ end }}
- {{ with .Tags.BrightnessValue }}{{ printf "%-25s %v\n" "BrightnessValue" . }}{{ end }}
- </pre>
- {{ end }}
- {{ end }}
- ```
-
- [`excludeFields`]: /configuration/imaging/#excludefields
- [`includeFields`]: /configuration/imaging/#includefields
- [`Meta`]: /methods/resource/meta/
- [`time.Format`]: /functions/time/format/
- [Exif_Definition]: https://en.wikipedia.org/wiki/Exif
- [IPTC_Definition]: https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model
- [XMP_Definition]: https://en.wikipedia.org/wiki/Extensible_Metadata_Platform
++description: Returns an object containing Exif metadata for supported image formats.
+categories: []
+keywords: ['metadata']
+params:
+ functions_and_methods:
+ returnType: meta.ExifInfo
+ signatures: [RESOURCE.Exif]
++expiryDate: 2028-01-28 # deprecated 2026-01-28 in v0.155.0
+---
+
++{{< deprecated-in 0.155.0 >}}
++Use [`Meta`](/methods/resource/meta/) instead.
++{{< /deprecated-in >}}
--- /dev/null
- Crop and resize an image according to the given [processing specification][]. You must provide both width and height (such as `500x200`) within the specification. Unlike [`Resize`][], which may stretch the image, `Fill` maintains the original aspect ratio by cropping the image to the target ratio before resizing. The operation uses the [anchor](#anchor) and [resampling filter](#resampling-filter) provided, if any.
+---
+title: Fill
+description: Applicable to images, returns a new image resource cropped and resized according to the given processing specification.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Fill SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with .Fill "500x200 TopRight lanczos" }}
++The `Fill` method returns a new resource from a [processable image](g) according to the given [processing specification][].
++
++> [!note]
++> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
++
++## Usage
++
++When filling, you must provide both width and height (such as `500x200`) within the specification. `Fill` maintains the original aspect ratio by resizing the image to cover the target area and cropping any overflowing pixels based on the [anchor](#anchor) provided.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
- In the example above, `"500x200 TopRight lanczos"` is the _processing specification_.
++ {{ with .Fill "500x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
- {{ with .Fill "500x200 TopRight lanczos webp q85" }}
++In the example above, `"500x200 TopRight"` is the _processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
- filterArgs="fill 500x200 TopRight lanczos webp q85"
++ {{ with .Fill "500x200 TopRight" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
- [`Resize`]: /methods/resource/resize/
++ filterArgs="fill 500x200 TopRight"
+ example=true
+>}}
+
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
--- /dev/null
- Apply one or more [image filters](#image-filters) to the given image.
+---
+title: Filter
+description: Applicable to images, applies one or more image filters to the given image resource.
+categories: []
+keywords: [filter]
+params:
+ alt_title: RESOURCE.Filter
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Filter FILTER...]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- To apply two or more filters, executing from left to right:
++The `Filter` method returns a new resource from a [processable image](g) after applying one or more [image filters](#image-filters).
++
++> [!note]
++> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
++
++## Usage
++
++Use the `Filter` method to apply effects such as blurring, sharpening, or grayscale conversion. You can pass a single filter or a slice of filters. When providing a slice, Hugo applies the filters from left to right.
+
+To apply a single filter:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter images.Grayscale }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
- You can also apply image filters using the [`images.Filter`] function.
-
- [`images.Filter`]: /functions/images/filter/
++To apply multiple filters:
+
+```go-html-template
+{{ $filters := slice
+ images.Grayscale
+ (images.GaussianBlur 8)
+}}
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
- {{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
++You can also apply image filters using the [`images.Filter`][] function.
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter images.Grayscale }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Grayscale"
+ filterArgs=""
+ example=true
+>}}
+
+## Image filters
+
+Use any of these filters with the `Filter` method.
+
++{{% render-list-of-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
++
++[`images.Filter`]: /functions/images/filter/
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
--- /dev/null
- Downscale an image to fit according to the given [processing specification][] while maintaining the aspect ratio. You must provide both width and height (such as `600x400`) within the specification. Unlike [`Fill`][] or [`Resize`][], this method will never upscale an image; if the source image is smaller than the target dimensions, it remains its original size. The operation uses the [resampling filter](#resampling-filter) provided, if any.
+---
+title: Fit
+description: Applicable to images, returns a new image resource downscaled to fit according to the given processing specification.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Fit SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with .Fit "300x175 lanczos" }}
++The `Fit` method returns a new resource from a [processable image](g) according to the given [processing specification][].
++
++> [!note]
++> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
++
++## Usage
++
++When fitting, you must provide both width and height (such as `300x175`) within the specification. `Fit` maintains the original aspect ratio by downscaling the image until it fits within the specified dimensions. Unlike [`Fill`][] or [`Resize`][], this method will never upscale an image; if the source image is smaller than the target dimensions, the dimensions of the resulting image are the same as the original.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
- In the example above, `"300x175 lanczos"` is the _processing specification_.
++ {{ with .Fit "300x175" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
- {{ with .Fit "300x175 lanczos" }}
++In the example above, `"300x175"` is the processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
- filterArgs="fit 300x175 lanczos"
++ {{ with .Fit "300x175" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
- [`Resize`]: /methods/resource/resize/
++ filterArgs="fit 300x175"
+ example=true
+>}}
+
+[`Fill`]: /methods/resource/fill/
++[`Resize`]: /methods/resource/resize/
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
--- /dev/null
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ .Height }} → 400
- {{ end }}
- ```
-
- Use the `Width` and `Height` methods together when rendering an `img` element:
+---
+title: Height
+description: Applicable to images, returns the height of the given resource.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [RESOURCE.Height]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with resources.Get "images/a.jpg" }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
++Use the [`reflect.IsImageResourceWithMeta`][] function to verify that Hugo can determine the dimensions before calling the `Height` method.
+
+```go-html-template
++{{ with resources.GetMatch "images/featured.*" }}
++ {{ if reflect.IsImageResourceWithMeta . }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
++ {{ else }}
++ <img src="{{ .RelPermalink }}" alt="">
++ {{ end }}
+{{ end }}
+```
++
++[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
--- /dev/null
- description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif, IPTC, and XMP metadata.
+---
+title: Meta
- Applicable to JPEG, PNG, TIFF, and WebP images, the `Meta` method on an image `Resource` object returns an object containing [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata.
++description: Applicable to images, returns an object containing Exif, IPTC, and XMP metadata for supported image formats.
+categories: []
+keywords: ['metadata']
+params:
+ functions_and_methods:
+ returnType: meta.MetaInfo
+ signatures: [RESOURCE.Meta]
+---
+
+{{< new-in 0.155.3 />}}
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- To extract Exif metadata only, use the [`Exif`] method instead.
++The `Meta` method on an image `Resource` object returns an object containing [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata.
+
- > Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from JPEG, PNG, TIFF, and WebP images.
++While Hugo classifies many file types as images, only certain formats support metadata extraction. Supported formats include AVIF, BMP, GIF, HEIC, HEIF, JPEG, PNG, TIFF, and WebP.
+
+> [!note]
- (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function.
++> Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from supported formats.
++
++## Usage
++
++Use the [`reflect.IsImageResourceWithMeta`][] function to verify that a resource supports metadata extraction before calling the `Meta` method.
++
++```go-html-template
++{{ with resources.GetMatch "images/featured.*" }}
++ {{ if reflect.IsImageResourceWithMeta . }}
++ {{ with .Meta }}
++ {{ .Date.Format "2006-01-02" }}
++ {{ end }}
++ {{ end }}
++{{ end }}
++```
+
+## Methods
+
+### Date
+
- (`int`) Returns the value of the Exif `Orientation` tag, one of eight possible values:
++(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`][] function.
+
+### Lat
+
+(`float64`) Returns the GPS latitude in degrees from Exif metadata, with a fallback to XMP metadata.
+
+### Long
+
+(`float64`) Returns the GPS longitude in degrees from Exif metadata, with a fallback to XMP metadata.
+
+### Orientation
+
- > Use the [`images.AutoOrient`] image filter to rotate and flip an image as needed per its Exif orientation tag
++(`int`) Returns the value of the Exif `Orientation` tag, one of eight possible values.
+
+Value|Description
+:--|:--
+`1`|Horizontal (normal)
+`2`|Mirrored horizontal
+`3`|Rotated 180 degrees
+`4`|Mirrored vertical
+`5`|Mirrored horizontal and rotated 270 degrees clockwise
+`6`|Rotated 90 degrees clockwise
+`7`|Mirrored horizontal and rotated 90 degrees clockwise
+`8`|Rotated 270 degrees clockwise
+{class="!mt-0"}
+
+> [!tip]
- {{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ printf "%-25s %v\n" "Date" .Date }}
- {{ printf "%-25s %v\n" "Latitude" .Lat }}
- {{ printf "%-25s %v\n" "Longitude" .Long }}
- {{ printf "%-25s %v\n" "Orientation" .Orientation }}
- </pre>
- {{ end }}
- {{ end }}
- ```
-
- To list the available Exif fields:
-
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ range $k, $v := .Exif -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
- {{ end }}
- {{ end }}
- ```
-
- To list the available IPTC fields:
-
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ range $k, $v := .IPTC -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
- {{ end }}
- {{ end }}
- ```
-
- To list the available XMP fields:
-
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ range $k, $v := .XMP -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
- {{ end }}
- {{ end }}
- ```
-
- To list the available Exif, IPTC, and XMP fields together:
-
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ range $k, $v := merge .Exif .IPTC .XMP -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
++> Use the [`images.AutoOrient`][] image filter to rotate and flip an image as needed per its Exif orientation tag
+
+### Exif
+
+(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
+
+### IPTC
+
+(`meta.Tags`) Returns a collection of available IPTC fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
+
+### XMP
+
+(`meta.Tags`) Returns a collection of available XMP fields for this image. Availability is determined by the [`sources`][] setting and specific fields are managed via the [`fields`][] setting, both of which are managed in your project configuration.
+
+## Examples
+
+To list the creation date, latitude, longitude, and orientation:
+
+```go-html-template
- To list specific values:
-
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ with .Exif.ApertureValue }}{{ printf "%-25s %v\n" "ApertureValue" . }}{{ end }}
- {{ with .Exif.BrightnessValue }}{{ printf "%-25s %v\n" "BrightnessValue" . }}{{ end }}
-
- {{ with .IPTC.Headline }}{{ printf "%-25s %v\n" "Headline" . }}{{ end }}
- {{ with index .IPTC "Province-State" }}{{ printf "%-25s %v\n" "Province-State" . }}{{ end }}
-
- {{ with .XMP.Creator }}{{ printf "%-25s %v\n" "Creator" . }}{{ end }}
- {{ with .XMP.Subject }}{{ printf "%-25s %v\n" "Subject" . }}{{ end }}
- </pre>
- {{ end }}
- {{ end }}
- ```
++{{ with resources.GetMatch "images/featured.*" }}
++ {{ if reflect.IsImageResourceWithMeta . }}
++ {{ with .Meta }}
++ <pre>
++ {{ printf "%-25s %v\n" "Date" .Date }}
++ {{ printf "%-25s %v\n" "Latitude" .Lat }}
++ {{ printf "%-25s %v\n" "Longitude" .Long }}
++ {{ printf "%-25s %v\n" "Orientation" .Orientation }}
++ </pre>
++ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
- [`Exif`]: /methods/resource/exif/
++{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
+
+[`fields`]: /configuration/imaging/#fields
+[`images.AutoOrient`]: /functions/images/autoorient/
++[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
+[`sources`]: /configuration/imaging/#sources
+[`time.Format`]: /functions/time/format/
+[Exif_Definition]: https://en.wikipedia.org/wiki/Exif
+[IPTC_Definition]: https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model
+[XMP_Definition]: https://en.wikipedia.org/wiki/Extensible_Metadata_Platform
--- /dev/null
- Process an image according to the given [processing specification][]. This versatile method supports the full range of image transformations, including resizing, cropping, rotation, and format conversion, all within a single specification string.
+---
+title: Process
+description: Applicable to images, returns a new image resource processed according to the given processing specification.
+categories: []
+keywords: [process]
+params:
+ alt_title: RESOURCE.Process
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Process SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- In the example above, `"crop 200x200 TopRight webp q50"` is the _processing specification_.
++The `Process` method returns a new resource from a [processable image](g) according to the given [processing specification][].
++
++> [!note]
++> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
++
++## Usage
++
++This versatile method supports the full range of image transformations including resizing, cropping, rotation, and format conversion within a single specification string. Unlike specialized methods such as [`Resize`][] or [`Crop`][], you must explicitly include the [action](#action) in the specification if you are changing the image dimensions.
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Process "crop 200x200 TopRight webp q50" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
- The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [`images.Process`].
++In the example above, `"crop 200x200 TopRight webp q50"` is the processing specification.
+
+You can also use this method to apply simple transformations such as rotation and conversion:
+
+```go-html-template
+{{/* Rotate 90 degrees counter-clockwise. */}}
+{{ $image := $image.Process "r90" }}
+
+{{/* Convert to WebP. */}}
+{{ $image := $image.Process "webp" }}
+```
+
++The `Process` method is also available as a filter. This is more effective if you need to apply multiple filters to an image. See [`images.Process`][].
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Process "crop 200x200 TopRight webp q50" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
+ filterArgs="crop 200x200 TopRight webp q50"
+ example=true
+>}}
+
++[`Crop`]: /methods/resource/crop/
++[`Resize`]: /methods/resource/resize/
+[`images.Process`]: /functions/images/process/
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
--- /dev/null
- Resize an image according to the given [processing specification][]. You may specify only the width (such as `300x`) or only the height (`such as x150`) for proportional scaling. If you specify both width and height (such as `300x150`), the resulting image will be scaled to those exact dimensions; if the aspect ratio differs from the original, the image will be non-proportionally scaled (stretched or squashed). The operation uses the [resampling filter](#resampling-filter) provided, if any.
+---
+title: Resize
+description: Applicable to images, returns a new image resource resized according to the given processing specification.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: images.ImageResource
+ signatures: [RESOURCE.Resize SPECIFICATION]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with .Resize "300x lanczos" }}
++The `Resize` method returns a new resource from a [processable image](g) according to the given [processing specification][].
++
++> [!note]
++> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
++
++## Usage
++
++Resize an image according to the given processing specification. You may specify only the width (such as `300x`) or only the height (such as `x150`) for proportional scaling.
++
++If you specify both width and height (such as `300x150`), the resulting image will be scaled to those exact dimensions. If the target aspect ratio differs from the original, the image will be non-proportionally scaled (stretched or squashed).
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
- In the example above, `"300x lanczos"` is the _processing specification_.
++ {{ with .Resize "300x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
- {{ with .Resize "300x lanczos" }}
++In the example above, `"300x"` is the processing specification.
+
+{{% include "/_common/methods/resource/processing-spec.md" %}}
+
+## Example
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
- filterArgs="resize 300x lanczos"
++ {{ with .Resize "300x" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="Process"
++ filterArgs="resize 300x"
+ example=true
+>}}
+
++[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[processing specification]: #processing-specification
--- /dev/null
- ```go-html-template
- {{ with resources.Get "images/a.jpg" }}
- {{ .Width }} → 600
- {{ end }}
- ```
-
- Use the `Width` and `Height` methods together when rendering an `img` element:
+---
+title: Width
+description: Applicable to images, returns the width of the given resource.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: int
+ signatures: [RESOURCE.Width]
+---
+
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
- {{ with resources.Get "images/a.jpg" }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
++Use the [`reflect.IsImageResourceWithMeta`][] function to verify that Hugo can determine the dimensions before calling the `Width` method.
+
+```go-html-template
++{{ with resources.GetMatch "images/featured.*" }}
++ {{ if reflect.IsImageResourceWithMeta . }}
++ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
++ {{ else }}
++ <img src="{{ .RelPermalink }}" alt="">
++ {{ end }}
+{{ end }}
+```
++
++[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
--- /dev/null
-
- This method returns all page [kinds](g) in all languages, in the [default sort order](g). That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
-
- In most cases you should use the [`RegularPages`] method instead.
-
- [`RegularPages`]: /methods/site/regularpages/
-
- ```go-html-template
- {{ range .Site.AllPages }}
- <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
- {{ end }}
- ```
+---
+title: AllPages
+description: Returns a collection of all pages in all languages.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [SITE.AllPages]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+See [details](https://discourse.gohugo.io/t/56732).
+{{< /deprecated-in >}}
--- /dev/null
-
- By default, draft pages are not published when building a site. You can change this behavior with a command line flag:
-
- ```sh
- hugo build --buildDrafts
- ```
-
- Or by setting `buildDrafts` to `true` in your project configuration:
-
- {{< code-toggle file=hugo >}}
- buildDrafts = true
- {{< /code-toggle >}}
-
- Use the `BuildDrafts` method on a `Site` object to determine the current configuration:
-
- ```go-html-template
- {{ .Site.BuildDrafts }} → true
- ```
+---
+title: BuildDrafts
+description: Reports reports whether draft publishing is enabled for the current build.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [SITE.BuildDrafts]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+See [details](https://discourse.gohugo.io/t/56732).
+{{< /deprecated-in >}}
--- /dev/null
-
- 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.
-
- > [!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:
-
- ```text
- data/
- ├── books/
- │ ├── fiction.yaml
- │ └── nonfiction.yaml
- ├── films.json
- ├── paintings.xml
- └── sculptures.toml
- ```
-
- And these data files:
-
- ```yaml {file="data/books/fiction.yaml"}
- - title: The Hunchback of Notre Dame
- author: Victor Hugo
- isbn: 978-0140443530
- - title: Les Misérables
- author: Victor Hugo
- isbn: 978-0451419439
- ```
-
- ```yaml {file="data/books/nonfiction.yaml"}
- - title: The Ancien Régime and the Revolution
- author: Alexis de Tocqueville
- isbn: 978-0141441641
- - title: Interpreting the French Revolution
- author: François Furet
- isbn: 978-0521280495
- ```
-
- Access the data by [chaining](g) the [identifiers](g):
-
- ```go-html-template
- {{ range $category, $books := .Site.Data.books }}
- <p>{{ $category | title }}</p>
- <ul>
- {{ range $books }}
- <li>{{ .title }} ({{ .isbn }})</li>
- {{ end }}
- </ul>
- {{ end }}
- ```
-
- Hugo renders this to:
-
- ```html
- <p>Fiction</p>
- <ul>
- <li>The Hunchback of Notre Dame (978-0140443530)</li>
- <li>Les Misérables (978-0451419439)</li>
- </ul>
- <p>Nonfiction</p>
- <ul>
- <li>The Ancien Régime and the Revolution (978-0141441641)</li>
- <li>Interpreting the French Revolution (978-0521280495)</li>
- </ul>
- ```
-
- To limit the listing to fiction, and sort by title:
-
- ```go-html-template
- <ul>
- {{ range sort .Site.Data.books.fiction "title" }}
- <li>{{ .title }} ({{ .author }})</li>
- {{ end }}
- </ul>
- ```
-
- To find a fiction book by ISBN:
-
- ```go-html-template
- {{ range where .Site.Data.books.fiction "isbn" "978-0140443530" }}
- <li>{{ .title }} ({{ .author }})</li>
- {{ end }}
- ```
-
- In the template examples above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function. For example:
-
- ```go-html-template
- {{ index .Site.Data.books "historical-fiction" }}
- ```
-
- [`index`]: /functions/collections/indexfunction/
- [`transform.Unmarshal`]: /functions/transform/unmarshal/
- [mounted]: /configuration/module/#mounts
+---
+title: Data
+description: Returns a data structure composed from the files in the data directory.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: map
+ signatures: [SITE.Data]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+Use [`hugo.Data`](/functions/hugo/data/) instead.
+{{< /deprecated-in >}}
--- /dev/null
- {{ with where hugo.Sites "Language.Lang" "eq" "de" }}
+---
+title: GetPage
+description: Returns a Page object from the given path.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Page
+ signatures: [SITE.GetPage PATH]
+---
+
+The `GetPage` method is also available on `Page` objects, allowing you to specify a path relative to the current page. See [details].
+
+[details]: /methods/page/getpage/
+
+When using the `GetPage` method on a `Site` object, specify a path relative to the `content` directory.
+
+If Hugo cannot resolve the path to a page, the method returns nil.
+
+Consider this content structure:
+
+```text
+content/
+├── works/
+│ ├── paintings/
+│ │ ├── _index.md
+│ │ ├── starry-night.md
+│ │ └── the-mona-lisa.md
+│ ├── sculptures/
+│ │ ├── _index.md
+│ │ ├── david.md
+│ │ └── the-thinker.md
+│ └── _index.md
+└── _index.md
+```
+
+This _home_ template:
+
+```go-html-template {file="layouts/home.html"}
+{{ with .Site.GetPage "/works/paintings" }}
+ <ul>
+ {{ range .Pages }}
+ <li>{{ .Title }} by {{ .Params.artist }}</li>
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+Is rendered to:
+
+```html
+<ul>
+ <li>Starry Night by Vincent van Gogh</li>
+ <li>The Mona Lisa by Leonardo da Vinci</li>
+</ul>
+```
+
+To get a regular page instead of a section page:
+
+```go-html-template {file="layouts/home.html"}
+{{ with .Site.GetPage "/works/paintings/starry-night" }}
+ {{ .Title }} → Starry Night
+ {{ .Params.artist }} → Vincent van Gogh
+{{ end }}
+```
+
+## Multilingual projects
+
+With multilingual projects, the `GetPage` method on a `Site` object resolves the given path to a page in the current language.
+
+To get a page from a different language, query the `Sites` object:
+
+```go-html-template
++{{ with where hugo.Sites "Language.Name" "eq" "de" }}
+ {{ with index . 0 }}
+ {{ with .GetPage "/works/paintings/starry-night" }}
+ {{ .Title }} → Sternenklare Nacht
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+## Page bundles
+
+Consider this content structure:
+
+```text
+content/
+├── headless/
+│ ├── a.jpg
+│ ├── b.jpg
+│ ├── c.jpg
+│ └── index.md <-- front matter: headless = true
+└── _index.md
+```
+
+In the _home_ template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle](g):
+
+```go-html-template {file="layouts/home.html"}
+{{ with .Site.GetPage "/headless" }}
+ {{ range .Resources.ByType "image" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
--- /dev/null
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
+---
+title: IsDefault
+description: Reports whether the given site is the default site across all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: bool
+ signatures: [SITE.IsDefault]
+---
+
+{{< new-in 0.156.0 />}}
+
+The `IsDefault` method on a `Site` object reports whether the given site is the [default site](g) across all dimensions: [language](g), [version](g), and [role](g). This is useful to ensure that a block of code executes only once per build, regardless of the number of [sites](g) generated by your [dimensions](g).
+
+For example, the following configuration defines a matrix of sites across language and version dimensions.
+
+{{< code-toggle file=hugo >}}
+[languages.de]
+contentDir = 'content/de'
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
++direction = 'ltr'
++label = 'Deutsch'
++locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
+contentDir = 'content/en'
++direction = 'ltr'
++label = 'English'
++locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+
+[versions.'v1.0.0']
+[versions.'v2.0.0']
+[versions.'v3.0.0']
+{{< /code-toggle >}}
+
+If you call an initialization partial to handle one-time build logic or global variable setup, wrap that call in an [`if`][] statement using this function. This prevents the logic from being executed for every dimensional variation.
+
+```go-html-template
+{{ if .Site.IsDefault }}
+ {{ partial "init.html" . }}
+{{ end }}
+```
+
+In this setup, the code block is only executed for the English version v3.0.0 site. English is selected because it has the lowest weight, and version v3.0.0 is selected because it is the first version when sorted semantically in descending order.
+
+[`if`]: /functions/go-template/if/
--- /dev/null
- The examples below assume the following in your project configuration:
+---
+title: Language
+description: Returns the Language object for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: langs.Language
+ signatures: [SITE.Language]
+---
+
+The `Language` method on a `Site` object returns the `Language` object for the given site, derived from the language definition in your project configuration.
+
+You can also use the `Language` method on a `Page` object. See [details][].
+
+## Methods
+
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
- weight = 1
++The examples below assume the following language definition.
+
+{{< code-toggle file=hugo >}}
+[languages.de]
- ### Lang
++direction = 'ltr'
++label = 'Deutsch'
++locale = 'de-DE'
++weight = 2
+{{< /code-toggle >}}
+
++### Direction
++
++{{< new-in 0.158.0 />}}
++
++(`string`) Returns the [`direction`][] from the language definition.
++
++```go-html-template
++{{ .Site.Language.Direction }} → ltr
++```
++
+### IsDefault
+
+{{< new-in 0.153.0 />}}
+
+(`bool`) Reports whether this is the [default language][].
+
+```go-html-template
+{{ .Site.Language.IsDefault }} → true
+```
+
- (`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration.
++### Label
+
- {{ .Site.Language.Lang }} → de
++{{< new-in 0.158.0 />}}
++
++(`string`) Returns the [`label`][] from the language definition.
+
+```go-html-template
- (`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined.
++{{ .Site.Language.Label }} → Deutsch
+```
+
++### Lang
++
++{{<deprecated-in 0.158.0 />}}
++
++Use [`Name`](#name) instead.
++
+### LanguageCode
+
- ```go-html-template
- {{ .Site.Language.LanguageCode }} → de-DE
- ```
++{{<deprecated-in 0.158.0 />}}
+
- (`string`) Returns the [`languageDirection`][] from your project configuration.
++Use [`Locale`](#locale) instead.
+
+### LanguageDirection
+
- ```go-html-template
- {{ .Site.Language.LanguageDirection }} → ltr
- ```
++{{<deprecated-in 0.158.0 />}}
+
- (`string`) Returns the [`languageName`][] from your project configuration.
++Use [`Direction`](#direction) instead.
+
+### LanguageName
+
- {{ .Site.Language.LanguageName }} → Deutsch
++{{<deprecated-in 0.158.0 />}}
++
++Use [`Label`](#label) instead.
++
++### Locale
++
++{{< new-in 0.158.0 />}}
++
++(`string`) Returns the [`locale`][] from the language definition, falling back to [`Name`](#name).
+
+```go-html-template
- (`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`.
++{{ .Site.Language.Locale }} → de-DE
+```
+
+### Name
+
+{{< new-in 0.153.0 />}}
+
- (`int`) Returns the language [`weight`][] from your project configuration.
-
- ```go-html-template
- {{ .Site.Language.Weight }} → 1
- ```
++(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from the language definition.
+
+```go-html-template
+{{ .Site.Language.Name }} → de
+```
+
+### Weight
+
- lang="{{ .Site.Language.LanguageCode }}"
- dir="{{ or .Site.Language.LanguageDirection `ltr` }}"
++{{<deprecated-in 0.158.0 />}}
+
+## Example
+
+Some of the methods above are commonly used in a base template as attributes for the `html` element.
+
+```go-html-template
+<html
- [`languageCode`]: /configuration/languages/#languagecode
- [`languageDirection`]: /configuration/languages/#languagedirection
- [`languageName`]: /configuration/languages/#languagename
- [`weight`]: /configuration/languages/#weight
++ lang="{{ .Site.Language.Locale }}"
++ dir="{{ or .Site.Language.Direction `ltr` }}"
+>
+```
+
- [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
++[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
++[`direction`]: /configuration/languages/#direction
++[`label`]: /configuration/languages/#label
++[`locale`]: /configuration/languages/#locale
+[default language]: /quick-reference/glossary/#default-language
+[details]: /methods/page/language/
--- /dev/null
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
+---
+title: LanguagePrefix
+description: Returns the URL language prefix, if any, for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [SITE.LanguagePrefix]
+---
+
+Consider this project configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = false
+
+[languages.de]
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
++direction = 'ltr'
++label = 'Deutsch'
++locale = 'de-DE'
+title = 'Projekt Dokumentation'
+weight = 1
+
+[languages.en]
- You may use the `LanguagePrefix` method with both monolingual and multilingual sites.
++direction = 'ltr'
++label = 'English'
++locale = 'en-US'
+title = 'Project Documentation'
+weight = 2
+{{< /code-toggle >}}
+
+When visiting the German language site:
+
+```go-html-template
+{{ .Site.LanguagePrefix }} → ""
+```
+
+When visiting the English language site:
+
+```go-html-template
+{{ .Site.LanguagePrefix }} → /en
+```
+
+If you change `defaultContentLanguageInSubdir` to `true`, when visiting the German language site:
+
+```go-html-template
+{{ .Site.LanguagePrefix }} → /de
+```
+
++You may use the `LanguagePrefix` method with both monolingual and multilingual projects.
--- /dev/null
-
- The `Languages` method on a `Site` object returns a collection of language objects for all sites, ordered by language weight. Each language object points to its language definition in your project configuration.
-
- To inspect the data structure:
-
- ```go-html-template
- <pre>{{ debug.Dump .Site.Languages }}</pre>
- ```
-
- With this project configuration:
-
- {{< code-toggle file=hugo >}}
- defaultContentLanguage = 'de'
- defaultContentLanguageInSubdir = false
-
- [languages.de]
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
- title = 'Projekt Dokumentation'
- weight = 1
-
- [languages.en]
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
- title = 'Project Documentation'
- weight = 2
- {{< /code-toggle >}}
-
- This template:
-
- ```go-html-template
- <ul>
- {{ range .Site.Languages }}
- <li>{{ .Title }} ({{ .LanguageName }})</li>
- {{ end }}
- </ul>
- ```
-
- Is rendered to:
-
- ```html
- <ul>
- <li>Projekt Dokumentation (Deutsch)</li>
- <li>Project Documentation (English)</li>
- </ul>
- ```
+---
+title: Languages
+description: Returns a collection of language objects for all sites, ordered by language weight.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: langs.Languages
+ signatures: [SITE.Languages]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
+See [details](https://discourse.gohugo.io/t/56732).
+{{< /deprecated-in >}}
--- /dev/null
- Use [`hugo.Sites`] instead.
-
- [`hugo.Sites`]: /functions/hugo/sites/
+---
+title: Sites
+description: Returns a collection of all sites for all dimensions.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Sites
+ signatures: [SITE.Sites]
+expiryDate: '2028-02-18' # deprecated 2026-02-18 in v0.156.0
+---
+
+{{< deprecated-in 0.156.0 >}}
-
- {{% include "/_common/functions/hugo/sites-collection.md" %}}
-
- With this project configuration:
-
- {{< code-toggle file=hugo >}}
- defaultContentLanguage = 'de'
- defaultContentLanguageInSubdir = true
- defaultContentVersionInSubdir = true
-
- [languages.de]
- contentDir = 'content/de'
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
- title = 'Projekt Dokumentation'
- weight = 1
-
- [languages.en]
- contentDir = 'content/en'
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
- title = 'Project Documentation'
- weight = 2
-
- [versions.'v1.0.0']
- [versions.'v2.0.0']
- [versions.'v3.0.0']
- {{< /code-toggle >}}
-
- This template:
-
- ```go-html-template
- <ul>
- {{ range .Site.Sites }}
- <li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
- {{ end }}
- </ul>
- ```
-
- Produces a list of links to each home page:
-
- ```html
- <ul>
- <li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
- <li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
- <li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
- <li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
- <li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
- <li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
- </ul>
- ```
-
- To render a link to the home page of the [default site](g):
-
- ```go-html-template
- {{ with .Site.Sites.Default }}
- <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
- {{ end }}
- ```
-
- This is equivalent to:
-
- ```go-html-template
- {{ with index .Site.Sites 0 }}
- <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
- {{ end }}
- ```
++Use [`hugo.Sites`](/functions/hugo/sites/) instead.
+{{< /deprecated-in >}}
--- /dev/null
--- /dev/null
++---
++title: interleave
++---
++
++To _interleave_ (verb) is to insert a string at the beginning, the end, and between every character of another string.
--- /dev/null
- A _mount_ is a configuration object that maps a file system path (source) to a [_component_](g) path (target) within Hugo's [_unified file system_](g).
+---
+title: mount
+params:
+ reference: /configuration/module
+---
+
++A _mount_ is a configuration object that maps a file path (source) to a [_component_](g) path (target) within Hugo's [_unified file system_](g).
--- /dev/null
- Hugo can decode and encode these image formats, allowing you to use any of the [resource methods][] applicable to images such as `Width`, `Height`, `Crop`, `Fill`, `Fit`, `Resize`, etc.
+---
+title: processable image
+---
+
+A _processable image_ is an image file characterized by one of the following [_media types_](g):
+
++ - `image/bmp`
+ - `image/gif`
+ - `image/jpeg`
+ - `image/png`
+ - `image/tiff`
+ - `image/webp`
+
++ Hugo can decode and encode these image formats, allowing you to use any of the [resource methods][] applicable to images such as `Width`, `Height`, `Crop`, `Fill`, `Fit`, `Filter`, `Process`, `Resize`, etc.
+
++ Use the [`reflect.IsImageResourceProcessable`][] function to determine if an image can be processed.
++
++ [`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+ [resource methods]: /methods/resource
--- /dev/null
+---
+title: segment
++params:
++ reference: /configuration/segments/
+---
+
+A _segment_ is a subset of a site, filtered by [_logical path_](g), [_sites matrix_](g), [_page kind_](g), or [_output format_](g).
--- /dev/null
- Hugo's _unified file system_ provides a layered view for each of its seven [_component_](g) types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files. Project component directories are layered over [_module_](g) component directories. Hugo searches these layers in order to locate files.
+---
+title: unified file system
+---
+
++Hugo's _unified file system_ provides a layered view for each of its seven [_component_](g) types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files. Project component directories are layered over [_module_](g) component directories. When multiple layers contain the same file, Hugo uses the version from the highest layer.
--- /dev/null
- {{% list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=PAGE. %}}
+---
+title: Page collections
+description: A quick reference guide to Hugo's page collections.
+categories: []
+keywords: []
+---
+
+## Page
+
+Use these `Page` methods when rendering lists on [section pages](g), [taxonomy pages](g), [term pages](g), and the home page.
+
- {{% list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=SITE. %}}
++{{% render-list-of-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=PAGE. %}}
+
+## Site
+
+Use these `Site` methods when rendering lists on any page.
+
- Use the [`where`] function to filter page collections.
++{{% render-list-of-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=SITE. %}}
+
+## Filter
+
- {{% list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. titlePrefix=PAGES. %}}
++Use the [`where`][] function to filter page collections.
+
+## Sort
+
+{{% glossary-term "default sort order" %}}
+
+Use these methods to sort page collections by different criteria.
+
- {{% list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. titlePrefix=PAGES. %}}
++{{% render-list-of-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. titlePrefix=PAGES. %}}
+
+## Group
+
+Use these methods to group page collections.
+
++{{% render-list-of-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. titlePrefix=PAGES. %}}
+
+[`where`]: /functions/collections/where/
--- /dev/null
- When set to `auto` as shown above, 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. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+---
+title: Image render hooks
+linkTitle: Images
+description: Create image render hook templates to override the rendering of Markdown images to HTML.
+categories: []
+keywords: []
+---
+
+## Markdown
+
+A Markdown image has three components: the image description, the image destination, and optionally the image title.
+
+```text
+
+ ------------ ------------------ ---------
+ description destination title
+```
+
+These components are passed into the render hook [context](g) as shown below.
+
+## Context
+
+Image _render hook_ templates receive the following context:
+
+Attributes
+: (`map`) The [Markdown attributes], available if you configure your site as follows:
+
+ {{< code-toggle file=hugo >}}
+ [markup.goldmark.parser]
+ wrapStandAloneImageWithinParagraph = false
+ [markup.goldmark.parser.attribute]
+ block = true
+ {{< /code-toggle >}}
+
+Destination
+: (`string`) The image destination.
+
+IsBlock
+: (`bool`) Reports whether a standalone image is not wrapped within a paragraph element.
+
+Ordinal
+: (`int`) The zero-based ordinal of the image on the page.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+PlainText
+: (`string`) The image description as plain text.
+
+Text
+: (`template.HTML`) The image description.
+
+Title
+: (`string`) The image title.
+
+## 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.
+
+In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+```go-html-template {file="layouts/_markup/render-image.html" copy=true}
+<img src="{{ .Destination | safeURL }}"
+ {{- with .PlainText }} alt="{{ . }}"{{ end -}}
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+>
+{{- /* chomp trailing newline */ -}}
+```
+
+To render standalone images within `figure` elements:
+
+```go-html-template {file="layouts/_markup/render-image.html" copy=true}
+{{- if .IsBlock -}}
+ <figure>
+ <img src="{{ .Destination | safeURL }}"
+ {{- with .PlainText }} alt="{{ . }}"{{ end -}}
+ >
+ {{- with .Title }}<figcaption>{{ . }}</figcaption>{{ end -}}
+ </figure>
+{{- else -}}
+ <img src="{{ .Destination | safeURL }}"
+ {{- with .PlainText }} alt="{{ . }}"{{ end -}}
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+ >
+{{- end -}}
+```
+
+Note that the above requires the following project configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false
+{{< /code-toggle >}}
+
+## Embedded
+
+Hugo includes an [embedded image render hook] to resolve Markdown image destinations. You can adjust its behavior in your project configuration. This is the default setting:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.renderHooks.image]
+useEmbedded = 'auto'
+{{< /code-toggle >}}
+
++When set to `auto` as shown above, Hugo automatically uses the embedded image render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+
+You can also configure Hugo to `always` use the embedded image render hook, use it only as a `fallback`, or `never` use it. 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.
+
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
+
+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/
--- /dev/null
- When set to `auto` as shown above, 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. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+---
+title: Link render hooks
+linkTitle: Links
+description: Create a link render hook to override the rendering of Markdown links to HTML.
+categories: []
+keywords: []
+---
+
+## Markdown
+
+A Markdown link has three components: the link text, the link destination, and optionally the link title.
+
+```text
+[Post 1](/posts/post-1 "My first post")
+ ------ ------------- -------------
+ text destination title
+```
+
+These components are passed into the render hook [context](g) as shown below.
+
+## Context
+
+Link _render hook_ templates receive the following context:
+
+Destination
+: (`string`) The link destination.
+
+Page
+: (`page`) A reference to the current page.
+
+PageInner
+: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
+
+PlainText
+: (`string`) The link description as plain text.
+
+Text
+: (`template.HTML`) The link description.
+
+Title
+: (`string`) The link title.
+
+## 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.
+
+In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
+
+```go-html-template {file="layouts/_markup/render-link.html" copy=true}
+<a href="{{ .Destination | safeURL }}"
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+>
+ {{- with .Text }}{{ . }}{{ end -}}
+</a>
+{{- /* chomp trailing newline */ -}}
+```
+
+To include a `rel` attribute set to `external` for external links:
+
+```go-html-template {file="layouts/_markup/render-link.html" copy=true}
+{{- $u := urls.Parse .Destination -}}
+<a href="{{ .Destination | safeURL }}"
+ {{- with .Title }} title="{{ . }}"{{ end -}}
+ {{- if $u.IsAbs }} rel="external"{{ end -}}
+>
+ {{- with .Text }}{{ . }}{{ end -}}
+</a>
+{{- /* chomp trailing newline */ -}}
+```
+
+## Embedded
+
+Hugo includes an [embedded link render hook] to resolve Markdown link destinations. You can adjust its behavior in your project configuration. This is the default setting:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.renderHooks.link]
+useEmbedded = 'auto'
+{{< /code-toggle >}}
+
++When set to `auto` as shown above, Hugo automatically uses the embedded link render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+
+You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. 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.
+
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+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 %}}>
--- /dev/null
- > 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. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+---
+title: Ref shortcode
+linkTitle: Ref
+description: Insert a permalink to the given page reference using the ref shortcode.
+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]
+> 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 projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+>
+> You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
+
+## Usage
+
+The `ref` shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below.
+
+## Arguments
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The `ref` shortcode typically provides the destination for a Markdown link.
+
+> [!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:
+
+```md
+[Link A]({{%/* ref "/books/book-1" */%}})
+
+[Link B]({{%/* ref path="/books/book-1" */%}})
+
+[Link C]({{%/* ref path="/books/book-1" lang="de" */%}})
+
+[Link D]({{%/* ref path="/books/book-1" lang="de" outputFormat="json" */%}})
+```
+
+Rendered:
+
+```html
+<a href="https://example.org/en/books/book-1/">Link A</a>
+
+<a href="https://example.org/en/books/book-1/">Link B</a>
+
+<a href="https://example.org/de/books/book-1/">Link C</a>
+
+<a href="https://example.org/de/books/book-1/index.json">Link D</a>
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
+
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded link render hook]: /render-hooks/links/#embedded
+[Markdown notation]: /content-management/shortcodes/#notation
+[source code]: <{{% eturl relref %}}>
--- /dev/null
- > 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. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+---
+title: Relref shortcode
+linkTitle: Relref
+description: Insert a relative permalink to the given page reference using the relref shortcode.
+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]
+> 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 projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+>
+> You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
+
+## Usage
+
+The `relref` shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below.
+
+## Arguments
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The `relref` shortcode typically provides the destination for a Markdown link.
+
+> [!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:
+
+```md
+[Link A]({{%/* relref "/books/book-1" */%}})
+
+[Link B]({{%/* relref path="/books/book-1" */%}})
+
+[Link C]({{%/* relref path="/books/book-1" lang="de" */%}})
+
+[Link D]({{%/* relref path="/books/book-1" lang="de" outputFormat="json" */%}})
+```
+
+Rendered:
+
+```html
+<a href="/en/books/book-1/">Link A</a>
+
+<a href="/en/books/book-1/">Link B</a>
+
+<a href="/de/books/book-1/">Link C</a>
+
+<a href="/de/books/book-1/index.json">Link D</a>
+```
+
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
+
+[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
+[embedded link render hook]: /render-hooks/links/#embedded
+[Markdown notation]: /content-management/shortcodes/#notation
+[source code]: <{{% eturl relref %}}>
--- /dev/null
- https://vimeo.com/channels/staffpicks/55073825
+---
+title: Vimeo shortcode
+linkTitle: Vimeo
+description: Embed a Vimeo video in your content using the vimeo shortcode.
+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.
+
+## Example
+
+To display a Vimeo video with this URL:
+
+```text
- {{</* vimeo 55073825 */>}}
++https://vimeo.com/19899678
+```
+
+Include this in your Markdown:
+
+```text
- {{< vimeo 55073825 >}}
++{{</* vimeo 19899678 */>}}
+```
+
+Hugo renders this to:
+
- {{</* vimeo id=55073825 allowFullScreen=false loading=lazy */>}}
++{{< vimeo 19899678 >}}
+
+## Arguments
+
+id
+: (string) The video `id`. Optional if the `id` is the first and only positional argument.
+
+allowFullScreen
+: {{< new-in 0.146.0 />}}
+: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
+
+class
+: (`string`) The `class` attribute of the wrapping `div` element. Adding one or more CSS classes disables inline styling.
+
+loading
+: {{< new-in 0.146.0 />}}
+: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
+
+title
+: (`string`) The `title` attribute of the `iframe` element.
+
+Here's an example using some of the available arguments:
+
+```text
++{{</* vimeo id=19899678 allowFullScreen=false loading=lazy */>}}
+```
+
+## Privacy
+
+Adjust the relevant privacy settings in your project configuration.
+
+{{< code-toggle config=privacy.vimeo />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+enableDNT
+: (`bool`) Whether to block the Vimeo player from tracking session data and analytics. Default is `false`.
+
+simple
+: (`bool`) Whether to enable simple mode. If `true`, the video thumbnail is fetched from Vimeo and overlaid with a play button. Clicking the thumbnail opens the video in a new Vimeo tab. Default is `false`.
+
+The source code for the simple version of the shortcode is available [in this file].
+
+[in this file]: <{{% eturl vimeo_simple %}}>
+[source code]: <{{% eturl vimeo %}}>
--- /dev/null
- For multilingual sites, add the language key to the file name:
+---
+title: Custom 404 page
+linkTitle: 404 templates
+description: Create a template to render a 404 error page.
+categories: []
+keywords: []
+weight: 200
+---
+
+To render a 404 error page in the root of your site, create a 404 template in the root of the `layouts` directory. For example:
+
+```go-html-template {file="layouts/404.html"}
+{{ define "main" }}
+ <h1>404 Not Found</h1>
+ <p>The page you requested cannot be found.</p>
+ <p>
+ <a href="{{ .Site.Home.RelPermalink }}">
+ Return to the home page
+ </a>
+ </p>
+{{ end }}
+```
+
++For multilingual projects, add the language key to the file name:
+
+```text
+layouts/
+├── 404.de.html
+├── 404.en.html
+└── 404.fr.html
+```
+
+Your production server redirects the browser to the 404 page when a page is not found. Capabilities and configuration vary by host.
+
+Host|Capabilities and configuration
+:--|:--
+Amazon CloudFront|See [details](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/GeneratingCustomErrorResponses.html).
+Amazon S3|See [details](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CustomErrorDocSupport.html).
+Apache|See [details](https://httpd.apache.org/docs/2.4/custom-error.html).
+Azure Static Web Apps|See [details](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides).
+Azure Storage|See [details](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website#setting-up-a-static-website).
+Caddy|See [details](https://caddyserver.com/docs/caddyfile/directives/handle_errors).
+Cloudflare Pages|See [details](https://developers.cloudflare.com/pages/configuration/serving-pages/#not-found-behavior).
+DigitalOcean App Platform|See [details](https://docs.digitalocean.com/products/app-platform/how-to/manage-static-sites/#configure-a-static-site).
+Firebase|See [details](https://firebase.google.com/docs/hosting/full-config#404).
+GitHub Pages|Redirection to is automatic and not configurable.
+GitLab Pages|See [details](https://docs.gitlab.com/ee/user/project/pages/introduction.html#custom-error-codes-pages).
+NGINX|See [details](https://nginx.org/en/docs/http/ngx_http_core_module.html#error_page).
+Netlify|See [details](https://docs.netlify.com/routing/redirects/redirect-options/).
--- /dev/null
- id = "G-MEASUREMENT_ID"
+---
+title: Embedded partial templates
+description: Hugo provides embedded partial templates for common use cases.
+categories: []
+keywords: []
+weight: 180
+aliases: [/templates/internal]
+---
+
+{{< newtemplatesystem >}}
+
+## Disqus
+
+> [!note]
+> To override Hugo's embedded Disqus template, copy the [source code](<{{% eturl disqus %}}>) 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.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "disqus.html" . }}
+```
+
+### Configuration {#configuration-disqus}
+
+To use Hugo's Disqus template, first set up a single configuration value:
+
+{{< code-toggle file=hugo >}}
+[services.disqus]
+shortname = 'your-disqus-shortname'
+{{</ code-toggle >}}
+
+Hugo's Disqus template accesses this value with:
+
+```go-html-template
+{{ .Site.Config.Services.Disqus.Shortname }}
+```
+
+You can also set the following in the front matter for a given piece of content:
+
+- `disqus_identifier`
+- `disqus_title`
+- `disqus_url`
+
+### Privacy {#privacy-disqus}
+
+Adjust the relevant privacy settings in your project configuration.
+
+{{< code-toggle config=privacy.disqus />}}
+
+disable
+: (`bool`) Whether to disable the template. Default is `false`.
+
+## Google Analytics
+
+> [!note]
+> To override Hugo's embedded Google Analytics template, copy the [source code](<{{% eturl google_analytics %}}>) 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].
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "google_analytics.html" . }}
+```
+
+### Configuration {#configuration-google-analytics}
+
+Provide your tracking ID in your configuration file:
+
+{{< code-toggle file=hugo >}}
+[services.googleAnalytics]
- title = "Post title"
- description = "Text about this post"
++id = 'G-MEASUREMENT_ID'
+{{</ code-toggle >}}
+
+To use this value in your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
+
+### Privacy {#privacy-google-analytics}
+
+Adjust the relevant privacy settings in your project configuration.
+
+{{< code-toggle config=privacy.googleAnalytics />}}
+
+disable
+: (`bool`) Whether to disable the template. Default is `false`.
+
+respectDoNotTrack
+: (`bool`) Whether to respect the browser's "do not track" setting. Default is `true`.
+
+## Open Graph
+
+> [!note]
+> To override Hugo's embedded Open Graph template, copy the [source code](<{{% eturl opengraph %}}>) 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.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "opengraph.html" . }}
+```
+
+### Configuration {#configuration-open-graph}
+
+Hugo's Open Graph template is configured using a mix of configuration settings and [front matter](/content-management/front-matter/) on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ description = 'Text about my cool site'
+ images = ['site-feature-image.jpg']
+ title = 'My cool site'
+ [params.social]
+ facebook_admin = 'jsmith'
+[taxonomies]
+ series = 'series'
+{{</ code-toggle >}}
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
- description = "Text about my cool site"
++title = 'Post title'
++description = 'Text about this post'
+date = 2024-03-08T08:18:11-08:00
+images = ["post-cover.png"]
+audio = []
+videos = []
+series = []
+tags = []
+{{</ code-toggle >}}
+
+Hugo uses the page title and description for the title and description metadata. The first 6 URLs from the `images` array are used for image metadata. If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata.
+
+Various optional metadata can also be set:
+
+- Date, published date, and last modified data are used to set the published time metadata if specified.
+- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively.
+- The first 6 `tags` on the page are used for the tags metadata.
+- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series.
+
+If using YouTube this will produce a og:video tag like `<meta property="og:video" content="url">`. Use the `https://youtu.be/<id>` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`).
+
+## Pagination
+
+See [details](/templates/pagination/).
+
+## Schema
+
+> [!note]
+> To override Hugo's embedded Schema template, copy the [source code](<{{% eturl schema %}}>) 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.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "schema.html" . }}
+```
+
+## X (Twitter) Cards
+
+> [!note]
+> To override Hugo's embedded Twitter Cards template, copy the [source code](<{{% eturl twitter_cards %}}>) 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.
+
+To include the embedded template:
+
+```go-html-template
+{{ partial "twitter_cards.html" . }}
+```
+
+### Configuration {#configuration-x-cards}
+
+Hugo's X (Twitter) Card template is configured using a mix of configuration settings and [front-matter](/content-management/front-matter/) values on individual pages.
+
+{{< code-toggle file=hugo >}}
+[params]
+ images = ["site-feature-image.jpg"]
- title = "Post title"
- description = "Text about this post"
++ description = 'Text about my cool site'
+{{</ code-toggle >}}
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
- twitter = "GoHugoIO"
++title = 'Post title'
++description = 'Text about this post'
+images = ["post-cover.png"]
+{{</ code-toggle >}}
+
+If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. If no image resources with those names are found, the images defined in your [project configuration](/configuration/) are used instead. If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`.
+
+Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given.
+
+Set the value of `twitter:site` in your project configuration:
+
+{{< code-toggle file=hugo >}}
+[params.social]
++twitter = 'GoHugoIO'
+{{</ code-toggle >}}
+
+NOTE: The `@` will be added for you
+
+```html
+<meta name="twitter:site" content="@GoHugoIO"/>
+```
+
+[`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/
--- /dev/null
- Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page.
+---
+title: Introduction to templating
+linkTitle: Introduction
+description: An introduction to Hugo's templating syntax.
+categories: []
+keywords: []
+weight: 10
+---
+
+{{< newtemplatesystem >}}
+
+{{% glossary-term template %}}
+
- > Hugo uses Go's [text/template] and [html/template] packages.
++Templates use [variables][], [functions][], and [methods][] to transform your content, resources, and data into a published page.
+
+> [!note]
- > 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.
++> Hugo uses Go's [`text/template`][] and [`html/template`][] packages.
+>
- > By default, Hugo uses the html/template package when rendering HTML files.
++> 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.
+>
- 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].
++> 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.
+
+```go-html-template
+{{ $v1 := 6 }}
+{{ $v2 := 7 }}
+<p>The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.</p>
+```
+
+While HTML templates are the most common, you can create templates for any [output format](g) including CSV, JSON, RSS, and plain text.
+
+## Context
+
+The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects](g) and associated [methods](g).
+
+For example, a _page_ template receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
+
+### Current context
+
+Within a template, the dot (`.`) represents the current context.
+
+```go-html-template {file="layouts/page.html"}
+<h2>{{ .Title }}</h2>
+```
+
- 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.
++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][].
+
- With variables that represent a slice or map, use the [`index`] function to return the desired value.
++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.
+
+```go-html-template {file="layouts/page.html"}
+<h2>{{ .Title }}</h2>
+
+{{ range slice "foo" "bar" }}
+ <p>{{ . }}</p>
+{{ end }}
+
+{{ with "baz" }}
+ <p>{{ . }}</p>
+{{ end }}
+```
+
+In the example above, the context changes as we `range` through the [slice](g) of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to:
+
+```html
+<h2>My Page Title</h2>
+<p>foo</p>
+<p>bar</p>
+<p>baz</p>
+```
+
+### Template context
+
+Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot:
+
+```go-html-template {file="layouts/page.html"}
+{{ with "foo" }}
+ <p>{{ $.Title }} - {{ . }}</p>
+{{ end }}
+```
+
+Hugo renders this to:
+
+```html
+<p>My Page Title - foo</p>
+```
+
+> [!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
+
+In the examples above, the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template.
+
+A template action may contain literal values ([boolean](g), [string](g), [integer](g), and [float](g)), the [current context](#current-context), [variables](#variables), [functions](#functions), [methods](#methods), and the [`nil`](#nil) keyword.
+
+```go-html-template {file="layouts/page.html"}
+{{ $convertToLower := true }}
+{{ if $convertToLower }}
+ <h2>{{ strings.ToLower .Title }}</h2>
+{{ end }}
+```
+
+In the example above:
+
+- `$convertToLower` is a variable
+- `true` is a literal boolean value
+- `if` is the beginning of a control structure
+- `strings.ToLower` is a function that converts all characters to lowercase
+- `Title` is a method on a the `Page` object
+- `end` is the end of a control structure
+
+Hugo renders the above to:
+
+```html {trim=false}
+
+
+ <h2>my page title</h2>
+
+```
+
+### Whitespace
+
+Notice the blank lines and indentation in the previous example? Although irrelevant in production when you typically minify the output, you can remove the adjacent whitespace by using template action delimiters with hyphens:
+
+```go-html-template {file="layouts/page.html"}
+{{- $convertToLower := true -}}
+{{- if $convertToLower -}}
+ <h2>{{ strings.ToLower .Title }}</h2>
+{{- end -}}
+```
+
+Hugo renders this to:
+
+```html
+<h2>my page title</h2>
+```
+
+Whitespace includes spaces, horizontal tabs, carriage returns, and newlines.
+
+### Quote characters
+
+Hugo templates use different quote characters to define how text and characters are processed.
+
+Use double quotes for [interpreted string literals](g). These interpret backslashes as special instructions:
+
+```go-html-template
+{{ print "Hello world\u0021" }} → Hello world!
+```
+
+Use backticks for [raw string literals](g). These ignore backslashes and treat every character literally:
+
+```go-html-template
+{{ print `Hello world\u0021` }} → Hello world\u0021
+```
+
+Use single quotes for [rune literals](g). Unlike strings, these represent a single character as its numerical Unicode value:
+
+```go-html-template
+{{ print '!' }} → 33
+```
+
+In practical terms, you will rarely, if ever, use rune literals in your template code. They are most commonly used in low-level programming; in a Hugo template, you will almost always want a string instead.
+
+### Pipes
+
+Within a template action you may [pipe](g) a value to a function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent:
+
+```go-html-template
+{{ strings.ToLower "Hugo" }} → hugo
+{{ "Hugo" | strings.ToLower }} → hugo
+```
+
+You can pipe the result of one function or method into another. For example, these are equivalent:
+
+```go-html-template
+{{ strings.TrimSuffix "o" (strings.ToLower "Hugo") }} → hug
+{{ "Hugo" | strings.ToLower | strings.TrimSuffix "o" }} → hug
+```
+
+These are also equivalent:
+
+```go-html-template
+{{ mul 6 (add 2 5) }} → 42
+{{ 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.
+
+### Line splitting
+
+You can split a template action over two or more lines. For example, these are equivalent:
+
+```go-html-template
+{{ $v := or $arg1 $arg2 }}
+
+{{ $v := or
+ $arg1
+ $arg2
+}}
+```
+
+You can also split [raw string literals](g) over two or more lines. For example, these are equivalent:
+
+```go-html-template
+{{ $msg := "This is line one.\nThis is line two." }}
+
+{{ $msg := `This is line one.
+This is line two.`
+}}
+```
+
+### Nil
+
+Other than using the `nil` keyword in comparisons, you may not use it as an argument to any function or method, nor may you assign it to a variable. For example, these are valid uses of the `nil` keyword:
+
+```go-html-template
+{{ if gt 42 nil }}
+ <p>42 is greater than nil</p>
+{{ end }}
+
+{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
+```
+
+These, on the other hand, are invalid:
+
+```go-html-template
+{{ $a := nil }}
+{{ add 3 nil }}
+{{ nil | print}}
+```
+
+The actions above throw an error.
+
+## Variables
+
+A variable is a user-defined [identifier](g) prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
+
+Variables may contain [scalars](g), [slices](g), [maps](g), or [objects](g).
+
+Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. For example:
+
+```go-html-template
+{{ $total := 3 }}
+{{ range slice 7 11 21 }}
+ {{ $total = add $total . }}
+{{ end }}
+{{ $total }} → 42
+```
+
+Variables initialized inside of an `if`, `range`, or `with` block are scoped to the block. Variables initialized outside of these blocks are scoped to the template.
+
- 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.
++With variables that represent a slice or map, use the [`index`][] function to return the desired value.
+
+```go-html-template
+{{ $slice := slice "foo" "bar" "baz" }}
+{{ index $slice 2 }} → baz
+
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ index $map "c" }} → baz
+```
+
+> [!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.
+
+```go-html-template
+{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
+{{ $map.c }} → baz
+
+{{ $homePage := .Site.Home }}
+{{ $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.
+
+## Functions
+
+Used within a template action, a function takes one or more arguments and returns a value. Unlike methods, functions are not associated with an object.
+
- Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other functions:
++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.
+
- The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object.
++Hugo provides hundreds of custom [functions][] categorized by namespace. For example, the `strings` namespace includes these and other functions:
+
+Function|Alias
+:--|:--
+[`strings.ToLower`](/functions/strings/tolower)|`lower`
+[`strings.ToUpper`](/functions/strings/toupper)|`upper`
+[`strings.Replace`](/functions/strings/replace)|`replace`
+
+As shown above, frequently used functions have an alias. Use aliases in your templates to reduce code length.
+
+When calling a function, separate the arguments from the function, and from each other, with a space. For example:
+
+```go-html-template
+{{ $total := add 1 2 3 4 }}
+```
+
+## Methods
+
+Used within a template action and associated with an object, a method takes zero or more arguments and either returns a value or performs an action.
+
- Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context].
++The most commonly accessed objects are the [`Page`][] and [`Site`][] objects. This is a small sampling of the [methods][] available to each object.
+
+Object|Method|Description
+:--|:--|:--
+`Page`|[`Date`](methods/page/date/)|Returns the date of the given page.
+`Page`|[`Params`](methods/page/params/)|Returns a map of custom parameters as defined in the front matter of the given page.
+`Page`|[`Title`](methods/page/title/)|Returns the title of the given page.
+`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the `data` directory.
+`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in your project configuration.
+`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the your project configuration.
+
- To render an HTML comment, pass a string through the [`safeHTML`] template function. For example:
++Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context][].
+
+```go-html-template {file="layouts/page.html"}
+{{ .Site.Title }} → My Site Title
+{{ .Page.Title }} → My Page Title
+```
+
+The context passed into most templates is a `Page` object, so this is equivalent to the previous example:
+
+```go-html-template {file="layouts/page.html"}
+{{ .Site.Title }} → My Site Title
+{{ .Title }} → My Page Title
+```
+
+Some methods take an argument. Separate the argument from the method with a space. For example:
+
+```go-html-template {file="layouts/page.html"}
+{{ $page := .Page.GetPage "/books/les-miserables" }}
+{{ $page.Title }} → Les Misérables
+```
+
+## 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.
+
+Template comments are similar to template actions. Paired opening and closing braces represent the beginning and end of a comment. For example:
+
+```text
+{{/* This is an inline comment. */}}
+{{- /* This is an inline comment with adjacent whitespace removed. */ -}}
+```
+
+Code within a comment is not parsed, executed, or displayed. Comments may be inline, as shown above, or in block form:
+
+```text
+{{/*
+This is a block comment.
+*/}}
+
+{{- /*
+This is a block comment with
+adjacent whitespace removed.
+*/ -}}
+```
+
+You may not nest one comment inside of another.
+
- Use the [`template`] function to include one or more of Hugo's [embedded templates]:
++To render an HTML comment, pass a string through the [`safeHTML`][] template function. For example:
+
+```go-html-template
+{{ "<!-- I am an HTML comment. -->" | safeHTML }}
+{{ printf "<!-- This is the %s site. -->" .Site.Title | safeHTML }}
+```
+
+## Include
+
- Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
++Use the [`template`][] function to include one or more of Hugo's [embedded templates]:
+
+```go-html-template
+{{ partial "google_analytics.html" . }}
+{{ partial "opengraph" . }}
+{{ partial "pagination.html" . }}
+{{ partial "schema.html" . }}
+{{ partial "twitter_cards.html" . }}
+```
+
- This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions], [methods], and [templates] documentation for specific examples.
++Use the [`partial`][] or [`partialCached`][] function to include one or more [partial templates][]:
+
+```go-html-template
+{{ partial "breadcrumbs.html" . }}
+{{ partialCached "css.html" . }}
+```
+
+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.
+
+## Examples
+
- See documentation for [`if`], [`else`], and [`end`].
++This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions][], [methods][], and [templates][] documentation for specific examples.
+
+### Conditional blocks
+
- See documentation for [`and`] and [`or`].
++See documentation for [`if`][], [`else`][], and [`end`][].
+
+```go-html-template
+{{ $var := 42 }}
+{{ if eq $var 6 }}
+ {{ print "var is 6" }}
+{{ else if eq $var 7 }}
+ {{ print "var is 7" }}
+{{ else if eq $var 42 }}
+ {{ print "var is 42" }}
+{{ else }}
+ {{ print "var is something else" }}
+{{ end }}
+```
+
+### Logical operators
+
- See documentation for [`range`], [`else`], and [`end`].
++See documentation for [`and`][] and [`or`][].
+
+```go-html-template
+{{ $v1 := true }}
+{{ $v2 := false }}
+{{ $v3 := false }}
+{{ $result := false }}
+
+{{ if and $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → false
+
+{{ if or $v1 $v2 $v3 }}
+ {{ $result = true }}
+{{ end }}
+{{ $result }} → true
+```
+
+### Loops
+
- See documentation for [`with`], [`else`], and [`end`].
++See documentation for [`range`][], [`else`][], and [`end`][].
+
+```go-html-template
+{{ $s := slice "foo" "bar" "baz" }}
+{{ range $s }}
+ <p>{{ . }}</p>
+{{ else }}
+ <p>The collection is empty</p>
+{{ end }}
+```
+
+To loop a specified number of times:
+
+```go-html-template
+{{ $s := slice }}
+{{ range 3 }}
+ {{ $s = $s | append . }}
+{{ end }}
+{{ $s }} → [0 1 2]
+```
+
+### Rebind context
+
- The `title` and `date` fields are standard [front matter fields], while the other fields are user-defined.
++See documentation for [`with`][], [`else`][], and [`end`][].
+
+```go-html-template
+{{ $var := "foo" }}
+{{ with $var }}
+ {{ . }} → foo
+{{ else }}
+ {{ print "var is falsy" }}
+{{ end }}
+```
+
+To test multiple conditions:
+
+```go-html-template
+{{ $v1 := 0 }}
+{{ $v2 := 42 }}
+{{ with $v1 }}
+ {{ . }}
+{{ else with $v2 }}
+ {{ . }} → 42
+{{ else }}
+ {{ print "v1 and v2 are falsy" }}
+{{ end }}
+```
+
+### Access site parameters
+
+See documentation for the [`Params`](/methods/site/params/) method on a `Site` object.
+
+With this project configuration:
+
+{{< code-toggle file=hugo >}}
+title = 'ABC Widgets'
+baseURL = 'https://example.org'
+[params]
+ subtitle = 'The Best Widgets on Earth'
+ copyright-year = '2023'
+ [params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+ [params.layouts]
+ rfc_1123 = 'Mon, 02 Jan 2006 15:04:05 MST'
+ rfc_3339 = '2006-01-02T15:04:05-07:00'
+{{< /code-toggle >}}
+
+Access the custom site parameters by chaining the identifiers:
+
+```go-html-template
+{{ .Site.Params.subtitle }} → The Best Widgets on Earth
+{{ .Site.Params.author.name }} → John Smith
+
+{{ $layout := .Site.Params.layouts.rfc_1123 }}
+{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT
+```
+
+### Access page parameters
+
+See documentation for the [`Params`](/methods/page/params/) method on a `Page` object.
+
+By way of example, consider this front matter:
+
+{{< code-toggle file=content/annual-conference.md fm=true >}}
+title = 'Annual conference'
+date = 2023-10-17T15:11:37-07:00
+[params]
+display_related = true
+key-with-hyphens = 'must use index function'
+[params.author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+{{< /code-toggle >}}
+
- In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
++The `title` and `date` fields are standard [front matter fields][], while the other fields are user-defined.
+
+Access the custom fields by [chaining](g) the [identifiers](g) when needed:
+
+```go-html-template
+{{ .Params.display_related }} → true
+{{ .Params.author.email }} → jsmith@example.org
+{{ .Params.author.name }} → John Smith
+```
+
- [html/template]: https://pkg.go.dev/html/template
++In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`][] function:
+
+```go-html-template
+{{ index .Params "key-with-hyphens" }} → must use index function
+```
+
+[`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/
+[`safeHTML`]: /functions/safe/html
+[`Site`]: /methods/site/
+[`template`]: /functions/go-template/template/
+[`Title`]: /methods/page/title
+[`with`]: /functions/go-template/with/
+[current context]: #current-context
+[embedded templates]: /templates/embedded/
+[front matter fields]: /content-management/front-matter/#fields
+[front matter]: /content-management/front-matter/
+[functions]: /functions/
+[go-templates]: /functions/go-template/
- [text/template]: https://pkg.go.dev/text/template
++[`html/template`]: https://pkg.go.dev/html/template
+[methods]: /methods/
+[partial templates]: /templates/types/#partial
+[templates]: /templates/
++[`text/template`]: https://pkg.go.dev/text/template
+[variables]: #variables
--- /dev/null
- - [`Paginate`]
- - [`Paginator`]
+---
+title: Pagination
+description: Split a list page into two or more subsets.
+categories: []
+keywords: []
+weight: 160
+aliases: [/extras/pagination,/doc/pagination/]
+---
+
+Displaying a large page collection on a list page is not user-friendly:
+
+- A massive list can be intimidating and difficult to navigate. Users may get lost in the sheer volume of information.
+- Large pages take longer to load, which can frustrate users and lead to them abandoning the site.
+- Without any filtering or organization, finding a specific item becomes a tedious scrolling exercise.
+
+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.
+
+## Terminology
+
+paginate
+: To split a [list page](g) into two or more subsets.
+
+pagination
+: The process of paginating a list page.
+
+pager
+: Created during pagination, a pager contains a subset of a list page and navigation links to other pagers.
+
+paginator
+: A collection of pagers.
+
+## Configuration
+
+See [configure pagination](/configuration/pagination).
+
+## Methods
+
+To paginate a `home`, `section`, `taxonomy`, or `term` page, invoke either of these methods on the `Page` object in the corresponding template:
+
- Use pagination with any of the [grouping methods]. For example:
++- [`Paginate`][]
++- [`Paginator`][]
+
+The `Paginate` method is more flexible, allowing you to:
+
+- Paginate any page collection
+- Filter, sort, and group the page collection
+- Override the number of pages per pager as defined in your project configuration
+
+By comparison, the `Paginator` method paginates the page collection passed into the template, and you cannot override the number of pages per pager.
+
+## Examples
+
+To paginate a list page using the `Paginate` method:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate $pages.ByTitle 7 }}
+
+{{ range $paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
+
+In the example above, we:
+
+1. Build a page collection
+1. Sort the page collection by title
+1. Paginate the page collection, with 7 pages per pager
+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
+
+To paginate a list page using the `Paginator` method:
+
+```go-html-template
+{{ range .Paginator.Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
+
+In the example above, we:
+
+1. Paginate the page collection passed into the template, with the default number of pages per pager
+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
+
+## Caching
+
+> [!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.
+
+## Grouping
+
- > 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:
++Use pagination with any of the [grouping methods][]. For example:
+
+```go-html-template
+{{ $pages := where site.RegularPages "Type" "posts" }}
+{{ $paginator := .Paginate ($pages.GroupByDate "Jan 2006") }}
+
+{{ range $paginator.PageGroups }}
+ <h2>{{ .Key }}</h2>
+ {{ range .Pages }}
+ <h3><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h3>
+ {{ end }}
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
+
+## Navigation
+
+As shown in the examples above, the easiest way to add navigation between pagers is with Hugo's embedded pagination template:
+
+```go-html-template
+{{ partial "pagination.html" . }}
+```
+
+The embedded pagination template has two formats: `default` and `terse`. The above is equivalent to:
+
+```go-html-template
+{{ partial "pagination.html" (dict "page" . "format" "default") }}
+```
+
+The `terse` format has fewer controls and page slots, consuming less space when styled as a horizontal list. To use the `terse` format:
+
+```go-html-template
+{{ partial "pagination.html" (dict "page" . "format" "terse") }}
+```
+
+> [!note]
- {{% list-pages-in-section path=/methods/pager %}}
++> 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:
+
++{{% render-list-of-pages-in-section path=/methods/pager %}}
+
+## Structure
+
+The example below depicts the published site structure when paginating a list page.
+
+With this content:
+
+```text
+content/
+├── posts/
+│ ├── _index.md
+│ ├── post-1.md
+│ ├── post-2.md
+│ ├── post-3.md
+│ └── post-4.md
+└── _index.md
+```
+
+And this project configuration:
+
+{{< code-toggle file=hugo >}}
+[pagination]
+ disableAliases = false
+ pagerSize = 2
+ path = 'page'
+{{< /code-toggle >}}
+
+And this _section_ template:
+
+```go-html-template {file="layouts/section.html"}
+{{ range (.Paginate .Pages).Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+
+{{ partial "pagination.html" . }}
+```
+
+The published site has this structure:
+
+```text
+public/
+├── posts/
+│ ├── page/
+│ │ ├── 1/
+│ │ │ └── index.html <-- alias to public/posts/index.html
+│ │ └── 2/
+│ │ └── index.html
+│ ├── post-1/
+│ │ └── index.html
+│ ├── post-2/
+│ │ └── index.html
+│ ├── post-3/
+│ │ └── index.html
+│ ├── post-4/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+To disable alias generation for the first pager, change your project configuration:
+
+{{< code-toggle file=hugo >}}
+[pagination]
+ disableAliases = true
+ pagerSize = 2
+ path = 'page'
+{{< /code-toggle >}}
+
+Now the published site will have this structure:
+
+```text
+public/
+├── posts/
+│ ├── page/
+│ │ └── 2/
+│ │ └── index.html
+│ ├── post-1/
+│ │ └── index.html
+│ ├── post-2/
+│ │ └── index.html
+│ ├── post-3/
+│ │ └── index.html
+│ ├── post-4/
+│ │ └── index.html
+│ └── index.html
+└── index.html
+```
+
+[`Paginate`]: /methods/page/paginate/
+[`Paginator`]: /methods/page/paginator/
+[`partial`]: /functions/partials/include/
+[grouping methods]: /quick-reference/page-collections/#group
+[source code]: <{{% eturl pagination %}}>
--- /dev/null
- > 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.
+---
+title: Shortcode templates
+description: Create custom shortcodes to simplify and standardize content creation.
+categories: []
+keywords: []
+weight: 120
+aliases: [/templates/shortcode-templates/]
+---
+
+{{< newtemplatesystem >}}
+
+> [!note]
- Hugo provides [embedded shortcodes] for many common tasks, but you'll likely need to create your own for more specific needs. Some examples of custom shortcodes you might develop include:
++> 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
+
- {{% list-pages-in-section path=/methods/shortcode %}}
++Hugo provides [embedded shortcodes][] for many common tasks, but you'll likely need to create your own for more specific needs. Some examples of custom shortcodes you might develop include:
+
+- Audio players
+- Video players
+- Image galleries
+- Diagrams
+- Maps
+- Tables
+- And many other custom elements
+
+## Directory structure
+
+Create _shortcode_ templates within the `layouts/_shortcodes` directory, either at its root or organized into subdirectories.
+
+```text
+layouts/
+└── _shortcodes/
+ ├── diagrams/
+ │ ├── kroki.html
+ │ └── plotly.html
+ ├── media/
+ │ ├── audio.html
+ │ ├── gallery.html
+ │ └── video.html
+ ├── capture.html
+ ├── column.html
+ ├── include.html
+ └── row.html
+```
+
+When calling a shortcode in a subdirectory, specify its path relative to the `_shortcode` directory, excluding the file extension.
+
+```text
+{{</* media/audio path=/audio/podcast/episode-42.mp3 */>}}
+```
+
+## Lookup order
+
+Hugo selects _shortcode_ templates based on the shortcode name, the current output format, and the current language. The examples below are sorted by specificity in descending order. The least specific path is at the bottom of the list.
+
+Shortcode name|Output format|Language|Template path
+:--|:--|:--|:--
+foo|html|en|`layouts/_shortcodes/foo.en.html`
+foo|html|en|`layouts/_shortcodes/foo.html.html`
+foo|html|en|`layouts/_shortcodes/foo.html`
+foo|html|en|`layouts/_shortcodes/foo.html.en.html`
+
+Shortcode name|Output format|Language|Template path
+:--|:--|:--|:--
+foo|rss|en|`layouts/_shortcodes/foo.en.rss.xml`
+foo|rss|en|`layouts/_shortcodes/foo.rss.xml`
+foo|rss|en|`layouts/_shortcodes/foo.en.xml`
+foo|rss|en|`layouts/_shortcodes/foo.xml`
+
+## Methods
+
+Use these methods in your _shortcode_ templates. Refer to each methods's documentation for details and examples.
+
- 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.
++{{% render-list-of-pages-in-section path=/methods/shortcode %}}
+
+## Examples
+
+These examples range in complexity from simple to moderately advanced, with some simplified for clarity.
+
+### Insert year
+
+Create a shortcode to insert the current year:
+
+```go-html-template {file="layouts/_shortcodes/year.html"}
+{{- now.Format "2006" -}}
+```
+
+Then call the shortcode from within your markup:
+
+```text {file="content/example.md"}
+This is {{</* year */>}}, and look at how far we've come.
+```
+
- - The [`with`] statement to rebind the [context](g) after each successful operation
- - The [`Get`] method to retrieve arguments by name
++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.
+
+### 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).
+
+```text
+content/
+├── example/
+│ ├── a.jpg
+│ └── index.md
+└── _index.md
+```
+
+Create a shortcode to capture an image as a page resource, resize it to the given width, convert it to the WebP format, and add an `alt` attribute:
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{- with .Page.Resources.Get (.Get "path") }}
+ {{- with .Process (printf "resize %dx wepb" ($.Get "width")) -}}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ $.Get "alt" }}">
+ {{- end }}
+{{- end -}}
+```
+
+Then call the shortcode from within your markup:
+
+```text {file="content/example/index.md"}
+{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
+```
+
+The example above uses:
+
- > Read more about context in the [introduction to templating].
++- The [`with`][] statement to rebind the [context](g) after each successful operation
++- The [`Get`][] method to retrieve arguments by name
+- The `$` to access the template context
+
+> [!note]
+> Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context.
+>
- 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:
++> Read more about context in the [introduction to templating][].
+
+### Insert image with error handling
+
+The previous example, while functional, silently fails if the image is missing, and does not gracefully exit if a required argument is missing. We'll add error handling to address these issues:
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{- with .Get "path" }}
+ {{- with $r := $.Page.Resources.Get ($.Get "path") }}
+ {{- with $.Get "width" }}
+ {{- with $r.Process (printf "resize %dx wepb" ($.Get "width" )) }}
+ {{- $alt := or ($.Get "alt") "" -}}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="{{ $alt }}">
+ {{- end }}
+ {{- else }}
+ {{- errorf "The %q shortcode requires a 'width' argument: see %s" $.Name $.Position }}
+ {{- end }}
+ {{- else }}
+ {{- warnf "The %q shortcode was unable to find %s: see %s" $.Name ($.Get "path") $.Position }}
+ {{- end }}
+{{- else }}
+ {{- errorf "The %q shortcode requires a 'path' argument: see %s" .Name .Position }}
+{{- end -}}
+```
+
+This template throws an error and gracefully fails the build if the author neglected to provide a `path` or `width` argument, and it emits a warning if it cannot find the image at the specified path. If the author does not provide an `alt` argument, the `alt` attribute is set to an empty string.
+
- 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:
++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:
+
+```text
+ERROR The "image" shortcode requires a 'width' argument: see "/home/user/project/content/example/index.md:7:1"
+```
+
+### Positional arguments
+
- You can create a shortcode that will accept both named and positional arguments, but not at the same time. Use the [`IsNamedParams`] method to determine whether the shortcode call used named or positional arguments:
++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:
+
+```text {file="content/example/index.md"}
+{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
+```
+
+Here's how to call it with positional arguments:
+
+```text {file="content/example/index.md"}
+{{</* image a.jpg 300 "A white kitten" */>}}
+```
+
+Using the `Get` method with zero-indexed keys, we'll initialize variables with descriptive names in our template:
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{ $path := .Get 0 }}
+{{ $width := .Get 1 }}
+{{ $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.
+
+### 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.
++You can create a shortcode that will accept both named and positional arguments, but not at the same time. Use the [`IsNamedParams`][] method to determine whether the shortcode call used named or positional arguments:
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{ $path := cond (.IsNamedParams) (.Get "path") (.Get 0) }}
+{{ $width := cond (.IsNamedParams) (.Get "width") (.Get 1) }}
+{{ $alt := cond (.IsNamedParams) (.Get "alt") (.Get 2) }}
+```
+
- Use the [`Params`] method to access the arguments as a collection.
++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.
+
+### Argument collection
+
- Combine the `Params` method with the [`collections.IsSet`] function to determine if a parameter is set, even if its value is falsy.
++Use the [`Params`][] method to access the arguments as a collection.
+
+When using named arguments, the `Params` method returns a map:
+
+```text {file="content/example/index.md"}
+{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{ .Params.path }} → a.jpg
+{{ .Params.width }} → 300
+{{ .Params.alt }} → A white kitten
+```
+
+ When using positional arguments, the `Params` method returns a slice:
+
+```text {file="content/example/index.md"}
+{{</* image a.jpg 300 "A white kitten" */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/image.html"}
+{{ index .Params 0 }} → a.jpg
+{{ index .Params 1 }} → 300
+{{ index .Params 1 }} → A white kitten
+```
+
- 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.
++Combine the `Params` method with the [`collections.IsSet`][] function to determine if a parameter is set, even if its value is falsy.
+
+### Inner content
+
- 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].
++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.
+
+```text {file="content/example.md"}
+{{</* contrived title="A Contrived Example" */>}}
+This is a **bold** word, and this is an _emphasized_ word.
+{{</* /contrived */>}}
+```
+
+```go-html-template {file="layouts/_shortcodes/contrived.html"}
+<div class="contrived">
+ <h2>{{ .Get "title" }}</h2>
+ {{ .Inner | .Page.RenderString }}
+</div>
+```
+
- 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.
++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][].
+
+### Nesting
+
- For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub], can provide a useful model.
++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.
+
+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"}
+<div class="{{ .Get "class" }}">
+ {{ .Inner }}
+</div>
+```
+
+You also have an `img` shortcode with a single named `src` argument that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`:
+
+```go-html-template {file="layouts/_shortcodes/img.html"}
+{{ $src := .Get "src" }}
+{{ with .Parent }}
+ <img src="{{ $src }}" class="{{ .Get "class" }}-image">
+{{ else }}
+ <img src="{{ $src }}">
+{{ end }}
+```
+
+You can then call your shortcode in your content as follows:
+
+```text {file="content/example.md"}
+{{</* gallery class="content-gallery" */>}}
+ {{</* img src="/images/one.jpg" */>}}
+ {{</* img src="/images/two.jpg" */>}}
+{{</* /gallery */>}}
+{{</* img src="/images/three.jpg" */>}}
+```
+
+This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`:
+
+```html
+<div class="content-gallery">
+ <img src="/images/one.jpg" class="content-gallery-image">
+ <img src="/images/two.jpg" class="content-gallery-image">
+</div>
+<img src="/images/three.jpg">
+```
+
+### Other examples
+
- The [`HasShortcode`] method allows you to check if a specific shortcode has been called on a page. For example, consider a custom audio shortcode:
++For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub][], can provide a useful model.
+
+## 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:
+
+```text {file="content/example.md"}
+{{</* audio src=/audio/test.mp3 */>}}
+```
+
+You can use the `HasShortcode` method in your base template to conditionally load CSS if the audio shortcode was used on the page:
+
+```go-html-template {file="layouts/baseof.html"}
+<head>
+ ...
+ {{ if .HasShortcode "audio" }}
+ <link rel="stylesheet" src="/css/audio.css">
+ {{ end }}
+ ...
+</head>
+```
+
+[`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
--- /dev/null
- <html lang="{{ site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
+---
+title: Template types
+description: Create templates of different types to render your content, resources, and data.
+categories: []
+keywords: []
+weight: 30
+aliases: [
+ '/templates/base/',
+ '/templates/content-view/',
+ '/templates/home/',
+ '/templates/lists/',
+ '/templates/partial/',
+ '/templates/section/',
+ '/templates/single/',
+ '/templates/taxonomy/',
+ '/templates/term/',
+]
+---
+
+## Structure
+
+Create templates in the `layouts` directory in the root of your project.
+
+Although your site may not require each of these templates, the example below is typical for a site of medium complexity.
+
+```text
+layouts/
+├── _markup/
+│ ├── render-image.html <-- render hook
+│ └── render-link.html <-- render hook
+├── _partials/
+│ ├── footer.html
+│ └── header.html
+├── _shortcodes/
+│ ├── audio.html
+│ └── video.html
+├── books/
+│ ├── page.html
+│ └── section.html
+├── films/
+│ ├── view_card.html <-- content view
+│ ├── view_li.html <-- content view
+│ ├── page.html
+│ └── section.html
+├── baseof.html
+├── home.html
+├── page.html
+├── section.html
+├── taxonomy.html
+└── term.html
+```
+
+Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page.
+
+> [!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.
+
+## Base
+
+A _base_ template serves as a foundational layout that other templates can build upon. It typically defines the common structural components of your HTML, such as the `html`, `head`, and `body` elements. It also often includes recurring features like headers, footers, navigation, and script inclusions that appear across multiple pages of your site. By defining these common aspects once in a _base_ template, you avoid redundancy, ensure consistency, and simplify the maintenance of your website.
+
+Hugo can apply a _base_ template to the following template types: [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), [list](#list), and [all](#all). When Hugo parses any of these template types, it will apply a _base_ template only if the template being parsed meets these specific conditions:
+
+- It must include at least one [`define`] [action](g).
+- It can only contain `define` actions, whitespace, and [template comments]. No other content is allowed.
+
+> [!note]
+> If a template doesn't meet all these criteria, Hugo executes it exactly as provided, without applying a _base_ template.
+
+When Hugo applies a _base_ template, it replaces its [`block`] actions with content from the corresponding `define` actions found in the template to which the base template is applied.
+
+For example, the _base_ template below calls the [`partial`] function to include `head`, `header`, and `footer` elements. The `block` action acts as a placeholder, and its content will be replaced by a matching `define` action from the template to which it is applied.
+
+```go-html-template {file="layouts/baseof.html"}
+<!DOCTYPE html>
++<html lang="{{ site.Language.Locale }}" dir="{{ or site.Language.Direction `ltr` }}">
+<head>
+ {{ partial "head.html" . }}
+</head>
+<body>
+ <header>
+ {{ partial "header.html" . }}
+ </header>
+ <main>
+ {{ block "main" . }}
+ This will be replaced with content from the
+ corresponding "define" action found in the template
+ to which this base template is applied.
+ {{ end }}
+ </main>
+ <footer>
+ {{ partial "footer.html" . }}
+ </footer>
+</body>
+</html>
+```
+
+```go-html-template {file="layouts/home.html"}
+{{ define "main" }}
+ This will replace the content of the "block" action
+ found in the base template.
+{{ end }}
+```
+
+## Home
+
+A _home_ template renders your site's home page.
+
+For example, Hugo applies a _base_ template to the _home_ template below, then renders the page content and a list of the site's regular pages.
+
+```go-html-template {file="layouts/home.html"}
+{{ define "main" }}
+ {{ .Content }}
+ {{ range .Site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/filter-sort-group.md" %}}
+
+## Page
+
+A _page_ template renders a regular page.
+
+For example, Hugo applies a _base_ template to the _page_ template below, then renders the page title and page content.
+
+```go-html-template {file="layouts/page.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+```
+
+## Section
+
+A _section_ template renders a list of pages within a [section](g).
+
+For example, Hugo applies a _base_ template to the _section_ template below, then renders the page title, page content, and a list of pages in the current section.
+
+```go-html-template {file="layouts/section.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/filter-sort-group.md" %}}
+
+## Taxonomy
+
+A _taxonomy_ template renders a list of terms in a [taxonomy](g).
+
+For example, Hugo applies a _base_ template to the _taxonomy_ template below, then renders the page title, page content, and a list of [terms](g) in the current taxonomy.
+
+```go-html-template {file="layouts/taxonomy.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/filter-sort-group.md" %}}
+
+Within a _taxonomy_ template, the [`Data`] object provides these taxonomy-specific methods:
+
+- [`Singular`][taxonomy-singular]
+- [`Plural`][taxonomy-plural]
+- [`Terms`]
+
+The `Terms` method returns a [taxonomy object](g), allowing you to call any of its methods including [`Alphabetical`] and [`ByCount`]. For example, use the `ByCount` method to render a list of terms sorted by the number of pages associated with each term:
+
+```go-html-template {file="layouts/taxonomy.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Data.Terms.ByCount }}
+ <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a> ({{ .Count }})</h2>
+ {{ end }}
+{{ end }}
+```
+
+## Term
+
+A _term_ template renders a list of pages associated with a [term](g).
+
+For example, Hugo applies a _base_ template to the _term_ template below, then renders the page title, page content, and a list of pages associated with the current term.
+
+```go-html-template {file="layouts/term.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/filter-sort-group.md" %}}
+
+Within a _term_ template, the [`Data`] object provides these term-specific methods:
+
+- [`Singular`][term-singular]
+- [`Plural`][term-plural]
+- [`Term`]
+
+## Single
+
+A _single_ template is a fallback for a _page_ template. If a _page_ template does not exist, Hugo will look for a _single_ template instead.
+
+For example, Hugo applies a _base_ template to the _single_ template below, then renders the page title and page content.
+
+```go-html-template {file="layouts/single.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+{{ end }}
+```
+
+## List
+
+A _list_ template is a fallback for [home](#home), [section](#section), [taxonomy](#taxonomy), and [term](#term) templates. If one of these template types does not exist, Hugo will look for a _list_ template instead.
+
+For example, Hugo applies a _base_ template to the _list_ template below, then renders the page title, page content, and a list of pages.
+
+```go-html-template {file="layouts/list.html"}
+{{ define "main" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+## All
+
+An _all_ template is a fallback for [home](#home), [page](#page), [section](#section), [taxonomy](#taxonomy), [term](#term), [single](#single), and [list](#list) templates. If one of these template types does not exist, Hugo will look for an _all_ template instead.
+
+For example, Hugo applies a _base_ template to the _all_ template below, then conditionally renders a page based on its page kind.
+
+```go-html-template {file="layouts/all.html"}
+{{ define "main" }}
+ {{ if eq .Kind "home" }}
+ {{ .Content }}
+ {{ range .Site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+ {{ else if eq .Kind "page" }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ else if in (slice "section" "taxonomy" "term") .Kind }}
+ <h1>{{ .Title }}</h1>
+ {{ .Content }}
+ {{ range .Pages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+ {{ else }}
+ {{ errorf "Unsupported page kind: %s" .Kind }}
+ {{ end }}
+{{ end }}
+```
+
+## Partial
+
+A _partial_ template is typically used to render a component of your site, though you may also create _partial_ templates that return values.
+
+For example, the _partial_ template below renders copyright information:
+
+```go-html-template {file="layouts/_partials/footer.html"}
+<p>Copyright {{ now.Year }}. All rights reserved.</p>
+```
+
+Execute the _partial_ template by calling the [`partial`] or [`partialCached`] function, optionally passing context as the second argument:
+
+```go-html-template {file="layouts/baseof.html"}
+{{ partial "footer.html" . }}
+```
+
+<!-- https://github.com/gohugoio/hugo/pull/13614#issuecomment-2805977008 -->
+Unlike other template types, Hugo does not consider the current page kind, content type, logical path, language, or output format when searching for a matching _partial_ template. However, it _does_ apply the same _name_ matching logic it uses for other template types. This means it tries to find the most specific match first, then progressively looks for more general versions if the specific one isn't found.
+
+For example, with this call:
+
+```go-html-template {file="layouts/baseof.html"}
+{{ partial "footer.section.de.html" . }}
+```
+
+Hugo uses this lookup order to find a matching template:
+
+1. `layouts/_partials/footer.section.de.html`
+1. `layouts/_partials/footer.section.html`
+1. `layouts/_partials/footer.de.html`
+1. `layouts/_partials/footer.html`
+
+A _partial_ template can also be defined inline within another template. However, it's important to note that the template namespace is global; ensuring unique names for these _partial_ templates is necessary to prevent conflicts.
+
+```go-html-template
+Value: {{ partial "my-inline-partial.html" . }}
+
+{{ define "_partials/my-inline-partial.html" }}
+ {{ $value := 32 }}
+ {{ return $value }}
+{{ end }}
+```
+
+## Content view
+
+A _content view_ template is similar to a _partial_ template, invoked by calling the [`Render`] method on a `Page` object. Unlike _partial_ templates, _content view_ templates:
+
+- Inherit the context of the current page
+- Can target any page kind, content type, logical path, language, or output format
+- Can reside at any level within the `layouts` directory
+
+For example, Hugo applies a _base_ template to the _home_ template below, then renders the page content and a card component for each page within the "films" section of your site.
+
+```go-html-template {file="layouts/home.html"}
+{{ define "main" }}
+ {{ .Content }}
+ <ul>
+ {{ range where site.RegularPages "Section" "films" }}
+ {{ .Render "view_card" }}
+ {{ end }}
+ </ul>
+{{ end }}
+```
+
+```go-html-template {file="layouts/films/view_card.html"}
+<div class="card">
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ .Summary }}
+</div>
+```
+
+In the example above, the content view template's name starts with `view_`. While not strictly required, this naming convention helps distinguish content view templates from other templates within the same directory, improving organization and clarity.
+
+## Render hook
+
+A _render hook_ template overrides the conversion of Markdown to HTML.
+
+For example, the _render hook_ template below adds an anchor link to the right of each heading.
+
+```go-html-template {file="layouts/_markup/render-heading.html"}
+<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
+ {{ .Text }}
+ <a href="#{{ .Anchor }}">#</a>
+</h{{ .Level }}>
+```
+
+Learn more about [render hook templates](/render-hooks/).
+
+## Shortcode
+
+A _shortcode_ template is used to render a component of your site. Unlike _partial_ or _content view_ templates, _shortcode_ templates are called from content pages.
+
+For example, the _shortcode_ template below renders an audio element from a [global resource](g).
+
+```go-html-template {file="layouts/_shortcodes/audio.html"}
+{{ with resources.Get (.Get "src") }}
+ <audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
+{{ end }}
+```
+
+Then call the shortcode from within markup:
+
+```text {file="content/example.md"}
+{{</* audio src=/audio/test.mp3 */>}}
+```
+
+Learn more about [shortcode templates](/templates/shortcode/).
+
+## Other
+
+Use other specialized templates to create:
+
+- [Sitemaps](/templates/sitemap)
+- [RSS feeds](/templates/rss/)
+- [404 error pages](/templates/404/)
+- [robots.txt files](/templates/robots/)
+
+[`Alphabetical`]: /methods/taxonomy/alphabetical/
+[`block`]: /functions/go-template/block/
+[`ByCount`]: /methods/taxonomy/bycount/
+[`Data`]: /methods/page/data/
+[`define`]: /functions/go-template/define/
+[`partial`]: /functions/partials/include/
+[`partialCached`]: /functions/partials/includeCached/
+[`Render`]: /methods/page/render/
+[`Term`]: /methods/page/data/#term
+[`Terms`]: /methods/page/data/#terms
+[taxonomy-plural]: /methods/page/data/#plural
+[taxonomy-singular]: /methods/page/data/#singular
+[template comments]: /templates/introduction/#comments
+[template lookup order]: /templates/lookup-order/
+[term-plural]: /methods/page/data/#plural-1
+[term-singular]: /methods/page/data/#singular-1
--- /dev/null
+---
+title: Migrate to Hugo
+linkTitle: Migrations
+description: A list of community-developed tools for migrating from your existing static site generator or content management system to Hugo.
+categories: []
+keywords: []
+weight: 40
+aliases: [/developer-tools/migrations/, /developer-tools/migrated/]
+---
+
+This section highlights some independently developed projects related to Hugo. These tools extend functionality or help you to get started.
+
+Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll help you export your content into Hugo-friendly formats.
+
+## Jekyll
+
+Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jekyll/).
+
+[JekyllToHugo](https://github.com/fredrikloch/JekyllToHugo)
+: A Small script for converting Jekyll blog posts to a Hugo site.
+
+[ConvertToHugo](https://github.com/coderzh/ConvertToHugo)
+: Convert your blog from Jekyll to Hugo.
+
+## Octopress
+
+[octohug](https://github.com/codebrane/octohug)
+: Octopress to Hugo migrator.
+
+## DokuWiki
+
+[dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo)
+: Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extras like the TODO plugin. Written with extensibility in mind using Python 3. Also generates a TOML header for each page. Designed to copy-paste the wiki directory into your `content` directory.
+
+## WordPress
+
+[wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter)
+: A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built-in Jekyll converter listed above.)
+
+[blog2md](https://github.com/palaniraja/blog2md)
+: Works with [exported xml](https://en.support.wordpress.com/export/) file of your free YOUR-TLD.wordpress.com website. It also saves approved comments to `YOUR-POST-NAME-comments.md` file along with posts.
+
+[wordhugopress](https://github.com/nantipov/wordhugopress)
+: A small utility written in Java that exports the entire WordPress site from the database and resource (e.g., images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging multiple WordPress sites into a single Hugo site.
+
+[wp2hugo](https://github.com/ashishb/wp2hugo)
+: A Go-based CLI tool to migrate WordPress websites to Hugo. It preserves original URLs, GUIDs, image URLs, code highlights, tables of contents, and WordPress navigation categories. It migrates WordPress custom post types, custom taxonomies, custom fields, and page hierarchy. It supports translated WordPress blogs via Polylang or WPML. It imports a WordPress media library database with original titles and dates. The tool can download all media or only media inserted into pages from the original server. It converts WordPress shortcodes and Gutenberg blocks to Hugo shortcodes including galleries, images, audio, YouTube embeds, Gists, and Google Maps.
+
+## Medium
+
+[medium2md](https://github.com/gautamdhameja/medium-2-md)
+: A simple Medium to Hugo exporter able to import stories in one command, including front matter.
+
+[medium-to-hugo](https://github.com/bgadrian/medium-to-hugo)
+: A CLI tool written in Go to export medium posts into a Hugo-compatible Markdown format. Tags and images are included. All images will be downloaded locally and linked appropriately.
+
+## Tumblr
+
+[tumblr-importr](https://github.com/carlmjohnson/tumblr-importr)
+: An importer that uses the Tumblr API to create a Hugo static site.
+
+[tumblr2hugomarkdown](https://github.com/Wysie/tumblr2hugomarkdown)
+: Export all your Tumblr content to Hugo Markdown files with preserved original formatting.
+
+[Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo)
+: A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. It also generates a CSV file to help you set up URL redirects.
+
+## Drupal
+
+[drupal2hugo](https://github.com/danapsimer/drupal2hugo)
+: Convert a Drupal site to Hugo.
+
+## Joomla
+
+[hugojoomla](https://github.com/davetcc/hugojoomla)
+: This utility written in Java takes a Joomla database and converts all the content into Markdown files. It changes any URLs that are in Joomla's internal format and converts them to a suitable form.
+
+## Blogger
+
+[blogimport](https://github.com/natefinch/blogimport)
+: A tool to import from Blogger posts to Hugo.
+
+[blogger-to-hugo](https://pypi.org/project/blogger-to-hugo/)
+: Another tool to import Blogger posts to Hugo. It also downloads embedded images so they will be stored locally.
+
+[blog2md](https://github.com/palaniraja/blog2md)
+: Works with [exported xml](https://support.google.com/blogger/answer/41387?hl=en) file of your YOUR-TLD.blogspot.com website. It also saves comments to `YOUR-POST-NAME-comments.md` file along with posts.
+
+[BloggerToHugo](https://github.com/huanlin/blogger-to-hugo)
+: Yet another tool to import Blogger posts to Hugo. For Windows platform only, and .NET Framework 4.5 is required. See README.md before using this tool.
+
++[blogger2hugo](https://github.com/noorkhafidzin/blogger2hugo)
++: Converts a Blogger backup file (`.atom`) from [Google Takeout](https://takeout.google.com/takeout/custom/blogger?hl=en) to Markdown (`.md`) files. The tool generates output compatible with the Hugo `content/` structure.
++
+## Contentful
+
+[contentful-hugo](https://github.com/ModiiMedia/contentful-hugo)
+: A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/).
+
+## BlogML
+
+[BlogML2Hugo](https://github.com/jijiechen/BlogML2Hugo)
+: A tool that helps you convert BlogML xml file to Hugo Markdown files. Users need to take care of links to attachments and images by themselves. This helps the blogs that export BlogML files (e.g. BlogEngine.NET) transform to hugo sites easily.
--- /dev/null
- {{% list-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include %}}
+---
+title: Logging
+description: Enable logging to inspect events while building your project.
+categories: []
+keywords: []
+---
+
+## Command line
+
+Enable console logging with the `--logLevel` command line flag.
+
+Hugo has four logging levels:
+
+error
+: Display error messages only.
+
+ ```sh
+ hugo build --logLevel error
+ ```
+
+warn
+: Display warning and error messages.
+
+ ```sh
+ hugo build --logLevel warn
+ ```
+
+info
+: Display information, warning, and error messages.
+
+ ```sh
+ hugo build --logLevel info
+ ```
+
+debug
+: Display debug, information, warning, and error messages.
+
+ ```sh
+ hugo build --logLevel debug
+ ```
+
+> [!note]
+> If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed.
+
+## Template functions
+
+You can also use template functions to print warnings or errors to the console. These functions are typically used to report data validation errors, missing files, etc.
+
++{{% render-list-of-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include %}}
+
+## LiveReload
+
+To log Hugo's LiveReload requests in your browser, add this query string to the URL when running Hugo's development server:
+
+```text
+debug=LR-verbose
+```
+
+For example:
+
+```text
+http://localhost:1313/?debug=LR-verbose
+```
+
+Then monitor the reload requests in your browser's dev tools console. Make sure the dev tools "preserve log" option is enabled.
--- /dev/null
- - RPGLE
+chroma:
+ lexers:
+ - Aliases:
+ - abap
+ Name: ABAP
+ - Aliases:
+ - abnf
+ Name: ABNF
+ - Aliases:
+ - as
+ - actionscript
+ Name: ActionScript
+ - Aliases:
+ - as3
+ - actionscript3
+ Name: ActionScript 3
+ - Aliases:
+ - ada
+ - ada95
+ - ada2005
+ Name: Ada
+ - Aliases:
+ - agda
+ Name: Agda
+ - Aliases:
+ - al
+ Name: AL
+ - Aliases:
+ - alloy
+ Name: Alloy
+ - Aliases:
+ - ng2
+ Name: Angular2
+ - Aliases:
+ - antlr
+ Name: ANTLR
+ - Aliases:
+ - apacheconf
+ - aconf
+ - apache
+ Name: ApacheConf
+ - Aliases:
+ - apl
+ Name: APL
+ - Aliases:
+ - applescript
+ Name: AppleScript
+ - Aliases:
+ - aql
+ Name: ArangoDB AQL
+ - Aliases:
+ - arduino
+ Name: Arduino
+ - Aliases:
+ - armasm
+ Name: ArmAsm
+ - Aliases:
+ - atl
+ Name: ATL
+ - Aliases:
+ - autohotkey
+ - ahk
+ Name: AutoHotkey
+ - Aliases:
+ - autoit
+ Name: AutoIt
+ - Aliases:
+ - awk
+ - gawk
+ - mawk
+ - nawk
+ Name: Awk
+ - Aliases:
+ - ballerina
+ Name: Ballerina
+ - Aliases:
+ - bash
+ - sh
+ - ksh
+ - zsh
+ - shell
+ Name: Bash
+ - Aliases:
+ - bash-session
+ - console
+ - shell-session
+ Name: Bash Session
+ - Aliases:
+ - bat
+ - batch
+ - dosbatch
+ - winbatch
+ Name: Batchfile
+ - Aliases:
+ - beef
+ Name: Beef
+ - Aliases:
+ - bib
+ - bibtex
+ Name: BibTeX
+ - Aliases:
+ - bicep
+ Name: Bicep
+ - Aliases:
+ - blitzbasic
+ - b3d
+ - bplus
+ Name: BlitzBasic
+ - Aliases:
+ - bnf
+ Name: BNF
+ - Aliases:
+ - bqn
+ Name: BQN
+ - Aliases:
+ - brainfuck
+ - bf
+ Name: Brainfuck
+ - Aliases:
+ - c
+ Name: C
+ - Aliases:
+ - csharp
+ - 'c#'
+ Name: 'C#'
+ - Aliases:
+ - cpp
+ - c++
+ Name: C++
+ - Aliases:
+ - c3
+ Name: C3
+ - Aliases:
+ - caddyfile
+ - caddy
+ Name: Caddyfile
+ - Aliases:
+ - caddyfile-directives
+ - caddyfile-d
+ - caddy-d
+ Name: Caddyfile Directives
+ - Aliases:
+ - capnp
+ Name: Cap'n Proto
+ - Aliases:
+ - cassandra
+ - cql
+ Name: Cassandra CQL
+ - Aliases:
+ - ceylon
+ Name: Ceylon
+ - Aliases:
+ - cfengine3
+ - cf3
+ Name: CFEngine3
+ - Aliases:
+ - cfs
+ Name: cfstatement
+ - Aliases:
+ - chai
+ - chaiscript
+ Name: ChaiScript
+ - Aliases:
+ - chapel
+ - chpl
+ Name: Chapel
+ - Aliases:
+ - cheetah
+ - spitfire
+ Name: Cheetah
+ - Aliases:
+ - clojure
+ - clj
+ - edn
+ Name: Clojure
+ - Aliases:
+ - cmake
+ Name: CMake
+ - Aliases:
+ - cobol
+ Name: COBOL
+ - Aliases:
+ - coffee-script
+ - coffeescript
+ - coffee
+ Name: CoffeeScript
+ - Aliases:
+ - common-lisp
+ - cl
+ - lisp
+ Name: Common Lisp
+ - Aliases:
+ - coq
+ Name: Coq
+ - Aliases:
+ - core
+ Name: Core
+ - Aliases:
+ - cr
+ - crystal
+ Name: Crystal
+ - Aliases:
+ - css
+ Name: CSS
+ - Aliases:
+ - csv
+ Name: CSV
+ - Aliases:
+ - cue
+ Name: CUE
+ - Aliases:
+ - cython
+ - pyx
+ - pyrex
+ Name: Cython
+ - Aliases:
+ - d
+ Name: D
+ - Aliases:
+ - dart
+ Name: Dart
+ - Aliases:
+ - dax
+ Name: Dax
+ - Aliases:
+ - desktop
+ - desktop_entry
+ Name: Desktop file
+ - Aliases:
+ - devicetree
+ - dts
+ Name: Devicetree
+ - Aliases:
+ - diff
+ - udiff
+ Name: Diff
+ - Aliases:
+ - django
+ - jinja
+ Name: Django/Jinja
+ - Aliases:
+ - zone
+ - bind
+ Name: dns
+ - Aliases:
+ - docker
+ - dockerfile
+ - containerfile
+ Name: Docker
+ - Aliases:
+ - dtd
+ Name: DTD
+ - Aliases:
+ - dylan
+ Name: Dylan
+ - Aliases:
+ - ebnf
+ Name: EBNF
+ - Aliases:
+ - elixir
+ - ex
+ - exs
+ Name: Elixir
+ - Aliases:
+ - elm
+ Name: Elm
+ - Aliases:
+ - emacs
+ - elisp
+ - emacs-lisp
+ Name: EmacsLisp
+ - Aliases:
+ - erlang
+ Name: Erlang
+ - Aliases:
+ - factor
+ Name: Factor
+ - Aliases:
+ - fennel
+ - fnl
+ Name: Fennel
+ - Aliases:
+ - fish
+ - fishshell
+ Name: Fish
+ - Aliases:
+ - forth
+ Name: Forth
+ - Aliases:
+ - fortran
+ - f90
+ Name: Fortran
+ - Aliases:
+ - fortranfixed
+ Name: FortranFixed
+ - Aliases:
+ - fsharp
+ Name: FSharp
+ - Aliases:
+ - gas
+ - asm
+ Name: GAS
+ - Aliases:
+ - gdscript
+ - gd
+ Name: GDScript
+ - Aliases:
+ - gdscript3
+ - gd3
+ Name: GDScript3
+ - Aliases:
+ - gemtext
+ - gmi
+ - gmni
+ - gemini
+ Name: Gemtext
+ - Aliases:
+ - genshi
+ - kid
+ - xml+genshi
+ - xml+kid
+ Name: Genshi
+ - Aliases:
+ - html+genshi
+ - html+kid
+ Name: Genshi HTML
+ - Aliases:
+ - genshitext
+ Name: Genshi Text
+ - Aliases:
+ - cucumber
+ - Cucumber
+ - gherkin
+ - Gherkin
+ Name: Gherkin
+ - Aliases:
+ - gleam
+ Name: Gleam
+ - Aliases:
+ - glsl
+ Name: GLSL
+ - Aliases:
+ - gnuplot
+ Name: Gnuplot
+ - Aliases:
+ - go
+ - golang
+ Name: Go
+ - Aliases:
+ - go-html-template
+ Name: Go HTML Template
+ - Aliases:
+ - go-template
+ Name: Go Template
+ - Aliases:
+ - go-text-template
+ Name: Go Text Template
+ - Aliases:
+ - graphql
+ - graphqls
+ - gql
+ Name: GraphQL
+ - Aliases:
+ - groff
+ - nroff
+ - man
+ Name: Groff
+ - Aliases:
+ - groovy
+ Name: Groovy
+ - Aliases:
+ - handlebars
+ - hbs
+ Name: Handlebars
+ - Aliases:
+ - hare
+ Name: Hare
+ - Aliases:
+ - haskell
+ - hs
+ Name: Haskell
+ - Aliases:
+ - hx
+ - haxe
+ - hxsl
+ Name: Haxe
+ - Aliases:
+ - hcl
+ Name: HCL
+ - Aliases:
+ - hexdump
+ Name: Hexdump
+ - Aliases:
+ - hlb
+ Name: HLB
+ - Aliases:
+ - hlsl
+ Name: HLSL
+ - Aliases:
+ - holyc
+ Name: HolyC
+ - Aliases:
+ - html
+ Name: HTML
+ - Aliases:
+ - http
+ Name: HTTP
+ - Aliases:
+ - hylang
+ Name: Hy
+ - Aliases:
+ - idris
+ - idr
+ Name: Idris
+ - Aliases:
+ - igor
+ - igorpro
+ Name: Igor
+ - Aliases:
+ - ini
+ - cfg
+ - dosini
+ Name: INI
+ - Aliases:
+ - io
+ Name: Io
+ - Aliases:
+ - iscdhcpd
+ Name: ISCdhcpd
+ - Aliases:
+ - j
+ Name: J
+ - Aliases:
+ - janet
+ Name: Janet
+ - Aliases:
+ - java
+ Name: Java
+ - Aliases:
+ - js
+ - javascript
+ Name: JavaScript
+ - Aliases:
+ - json
+ Name: JSON
+ - Aliases:
+ - jsonata
+ Name: JSONata
+ - Aliases:
+ - jsonnet
+ Name: Jsonnet
+ - Aliases:
+ - julia
+ - jl
+ Name: Julia
+ - Aliases:
+ - jungle
+ Name: Jungle
+ - Aliases:
+ - kak
+ - kakoune
+ - kakrc
+ - kakscript
+ Name: Kakoune
+ - Aliases:
+ - kdl
+ Name: KDL
+ - Aliases:
+ - kotlin
+ Name: Kotlin
+ - Aliases:
+ - lean4
+ - lean
+ Name: Lean4
+ - Aliases:
+ - lighty
+ - lighttpd
+ Name: Lighttpd configuration file
+ - Aliases:
+ - llvm
+ Name: LLVM
+ - Aliases: null
+ Name: lox
+ - Aliases:
+ - lua
+ - luau
+ Name: Lua
+ - Aliases:
+ - make
+ - makefile
+ - mf
+ - bsdmake
+ Name: Makefile
+ - Aliases:
+ - mako
+ Name: Mako
+ - Aliases:
+ - md
+ - mkd
+ Name: markdown
+ - Aliases:
+ - mess
+ Name: Markless
+ - Aliases:
+ - mason
+ Name: Mason
+ - Aliases:
+ - materialize
+ - mzsql
+ Name: Materialize SQL dialect
+ - Aliases:
+ - mathematica
+ - mma
+ - nb
+ Name: Mathematica
+ - Aliases:
+ - matlab
+ Name: Matlab
+ - Aliases:
+ - mcfunction
+ - mcf
+ Name: MCFunction
+ - Aliases:
+ - meson
+ - meson.build
+ Name: Meson
+ - Aliases:
+ - metal
+ Name: Metal
+ - Aliases:
+ - µcad
+ Name: microcad
+ - Aliases:
+ - minizinc
+ - MZN
+ - mzn
+ Name: MiniZinc
+ - Aliases:
+ - mlir
+ Name: MLIR
+ - Aliases:
+ - modelica
+ Name: Modelica
+ - Aliases:
+ - modula2
+ - m2
+ Name: Modula-2
+ - Aliases:
+ - mojo
+ - 🔥
+ Name: Mojo
+ - Aliases:
+ - monkeyc
+ Name: MonkeyC
+ - Aliases:
+ - moonbit
+ - mbt
+ Name: MoonBit
+ - Aliases:
+ - moonscript
+ - moon
+ Name: MoonScript
+ - Aliases:
+ - morrowind
+ - mwscript
+ Name: MorrowindScript
+ - Aliases:
+ - myghty
+ Name: Myghty
+ - Aliases:
+ - mysql
+ - mariadb
+ Name: MySQL
+ - Aliases:
+ - nasm
+ Name: NASM
+ - Aliases:
+ - natural
+ Name: Natural
+ - Aliases:
+ - ndisasm
+ Name: NDISASM
+ - Aliases:
+ - newspeak
+ Name: Newspeak
+ - Aliases:
+ - nginx
+ Name: Nginx configuration file
+ - Aliases:
+ - nim
+ - nimrod
+ Name: Nim
+ - Aliases:
+ - nixos
+ - nix
+ Name: Nix
+ - Aliases:
+ - nsis
+ - nsi
+ - nsh
+ Name: NSIS
+ - Aliases:
+ - nu
+ Name: Nu
+ - Aliases:
+ - objective-c
+ - objectivec
+ - obj-c
+ - objc
+ Name: Objective-C
+ - Aliases:
+ - objectpascal
+ Name: ObjectPascal
+ - Aliases:
+ - ocaml
+ Name: OCaml
+ - Aliases:
+ - octave
+ Name: Octave
+ - Aliases:
+ - odin
+ Name: Odin
+ - Aliases:
+ - ones
+ - onesenterprise
+ - 1S
+ - 1S:Enterprise
+ Name: OnesEnterprise
+ - Aliases:
+ - openedge
+ - abl
+ - progress
+ - openedgeabl
+ Name: OpenEdge ABL
+ - Aliases:
+ - openscad
+ Name: OpenSCAD
+ - Aliases:
+ - org
+ - orgmode
+ Name: Org Mode
+ - Aliases:
+ - pacmanconf
+ Name: PacmanConf
+ - Aliases:
+ - perl
+ - pl
+ Name: Perl
+ - Aliases:
+ - php
+ - php3
+ - php4
+ - php5
+ Name: PHP
+ - Aliases:
+ - phtml
+ Name: PHTML
+ - Aliases:
+ - pig
+ Name: Pig
+ - Aliases:
+ - pkgconfig
+ Name: PkgConfig
+ - Aliases:
+ - plpgsql
+ Name: PL/pgSQL
+ - Aliases:
+ - text
+ - plain
+ - no-highlight
+ Name: plaintext
+ - Aliases:
+ - plutus-core
+ - plc
+ Name: Plutus Core
+ - Aliases:
+ - pony
+ Name: Pony
+ - Aliases:
+ - postgresql
+ - postgres
+ Name: PostgreSQL SQL dialect
+ - Aliases:
+ - postscript
+ - postscr
+ Name: PostScript
+ - Aliases:
+ - pov
+ Name: POVRay
+ - Aliases:
+ - powerquery
+ - pq
+ Name: PowerQuery
+ - Aliases:
+ - powershell
+ - posh
+ - ps1
+ - psm1
+ - psd1
+ - pwsh
+ Name: PowerShell
+ - Aliases:
+ - prolog
+ Name: Prolog
+ - Aliases:
+ - promela
+ Name: Promela
+ - Aliases:
+ - promql
+ Name: PromQL
+ - Aliases:
+ - java-properties
+ Name: properties
+ - Aliases:
+ - protobuf
+ - proto
+ Name: Protocol Buffer
+ - Aliases:
+ - txtpb
+ Name: Protocol Buffer Text Format
+ - Aliases:
+ - prql
+ Name: PRQL
+ - Aliases:
+ - psl
+ Name: PSL
+ - Aliases:
+ - puppet
+ Name: Puppet
+ - Aliases:
+ - python
+ - py
+ - sage
+ - python3
+ - py3
+ - starlark
+ Name: Python
+ - Aliases:
+ - python2
+ - py2
+ Name: Python 2
+ - Aliases:
+ - qbasic
+ - basic
+ Name: QBasic
+ - Aliases:
+ - qml
+ - qbs
+ Name: QML
+ - Aliases:
+ - splus
+ - s
+ - r
+ Name: R
+ - Aliases:
+ - racket
+ - rkt
+ Name: Racket
+ - Aliases:
+ - ragel
+ Name: Ragel
+ - Aliases:
+ - perl6
+ - pl6
+ - raku
+ Name: Raku
+ - Aliases:
+ - jsx
+ - react
+ Name: react
+ - Aliases:
+ - reason
+ - reasonml
+ Name: ReasonML
+ - Aliases:
+ - registry
+ Name: reg
+ - Aliases:
+ - rego
+ Name: Rego
+ - Aliases:
+ - rst
+ - rest
+ - restructuredtext
+ Name: reStructuredText
+ - Aliases:
+ - rexx
+ - arexx
+ Name: Rexx
+ - Aliases:
+ - rgbasm
+ Name: RGBDS Assembly
+ - Aliases:
+ - ring
+ Name: Ring
+ - Aliases:
+ - SQLRPGLE
+ - RPG IV
+ Name: RPGLE
+ - Aliases:
+ - spec
+ Name: RPMSpec
+ - Aliases:
+ - rb
+ - ruby
+ - duby
+ Name: Ruby
+ - Aliases:
+ - rust
+ - rs
+ Name: Rust
+ - Aliases:
+ - sas
+ Name: SAS
+ - Aliases:
+ - sass
+ Name: Sass
+ - Aliases:
+ - scala
+ Name: Scala
+ - Aliases:
+ - scheme
+ - scm
+ Name: Scheme
+ - Aliases:
+ - scilab
+ Name: Scilab
+ - Aliases:
+ - scss
+ Name: SCSS
+ - Aliases:
+ - sed
+ - gsed
+ - ssed
+ Name: Sed
+ - Aliases:
+ - sieve
+ Name: Sieve
+ - Aliases:
+ - smali
+ Name: Smali
+ - Aliases:
+ - smalltalk
+ - squeak
+ - st
+ Name: Smalltalk
+ - Aliases:
+ - smarty
+ Name: Smarty
+ - Aliases:
+ - snbt
+ Name: SNBT
+ - Aliases:
+ - snobol
+ Name: Snobol
+ - Aliases:
+ - sol
+ - solidity
+ Name: Solidity
+ - Aliases:
+ - sp
+ Name: SourcePawn
+ - Aliases:
+ - sparql
+ Name: SPARQL
+ - Aliases:
+ - sql
+ Name: SQL
+ - Aliases:
+ - squidconf
+ - squid.conf
+ - squid
+ Name: SquidConf
+ - Aliases:
+ - sml
+ Name: Standard ML
+ - Aliases: null
+ Name: stas
+ - Aliases:
+ - stylus
+ Name: Stylus
+ - Aliases:
+ - svelte
+ Name: Svelte
+ - Aliases:
+ - swift
+ Name: Swift
+ - Aliases:
+ - systemd
+ Name: SYSTEMD
+ - Aliases:
+ - systemverilog
+ - sv
+ Name: systemverilog
+ - Aliases:
+ - tablegen
+ Name: TableGen
+ - Aliases:
+ - tal
+ - uxntal
+ Name: Tal
+ - Aliases:
+ - tasm
+ Name: TASM
+ - Aliases:
+ - tcl
+ Name: Tcl
+ - Aliases:
+ - tcsh
+ - csh
+ Name: Tcsh
+ - Aliases:
+ - termcap
+ Name: Termcap
+ - Aliases:
+ - terminfo
+ Name: Terminfo
+ - Aliases:
+ - terraform
+ - tf
+ - hcl
+ Name: Terraform
+ - Aliases:
+ - tex
+ - latex
+ Name: TeX
+ - Aliases:
+ - thrift
+ Name: Thrift
+ - Aliases:
+ - toml
+ Name: TOML
+ - Aliases:
+ - tradingview
+ - tv
+ Name: TradingView
+ - Aliases:
+ - tsql
+ - t-sql
+ Name: Transact-SQL
+ - Aliases:
+ - turing
+ Name: Turing
+ - Aliases:
+ - turtle
+ Name: Turtle
+ - Aliases:
+ - twig
+ Name: Twig
+ - Aliases:
+ - ts
+ - tsx
+ - typescript
+ Name: TypeScript
+ - Aliases:
+ - typoscript
+ Name: TypoScript
+ - Aliases:
+ - typoscriptcssdata
+ Name: TypoScriptCssData
+ - Aliases:
+ - typoscripthtmldata
+ Name: TypoScriptHtmlData
+ - Aliases:
+ - typst
+ Name: Typst
+ - Aliases: null
+ Name: ucode
+ - Aliases:
+ - v
+ - vlang
+ Name: V
+ - Aliases:
+ - vsh
+ - vshell
+ Name: V shell
+ - Aliases:
+ - vala
+ - vapi
+ Name: Vala
+ - Aliases:
+ - vb.net
+ - vbnet
+ Name: VB.net
+ - Aliases:
+ - verilog
+ - v
+ Name: verilog
+ - Aliases:
+ - vhdl
+ Name: VHDL
+ - Aliases:
+ - vhs
+ - tape
+ - cassette
+ Name: VHS
+ - Aliases:
+ - vim
+ Name: VimL
+ - Aliases:
+ - vue
+ - vuejs
+ Name: vue
+ - Aliases: null
+ Name: WDTE
+ - Aliases:
+ - wast
+ - wat
+ Name: WebAssembly Text Format
+ - Aliases:
+ - wgsl
+ Name: WebGPU Shading Language
+ - Aliases:
+ - vtt
+ Name: WebVTT
+ - Aliases:
+ - whiley
+ Name: Whiley
+ - Aliases:
+ - xml
+ Name: XML
+ - Aliases:
+ - xorg.conf
+ Name: Xorg
+ - Aliases:
+ - yaml
+ Name: YAML
+ - Aliases:
+ - yang
+ Name: YANG
+ - Aliases:
+ - z80
+ Name: Z80 Assembly
+ - Aliases:
+ - zed
+ Name: Zed
+ - Aliases:
+ - zig
+ Name: Zig
+ styles:
-
+ - abap
+ - algol
+ - algol_nu
+ - arduino
+ - ashen
+ - aura-theme-dark
+ - aura-theme-dark-soft
+ - autumn
+ - average
+ - base16-snazzy
+ - borland
+ - bw
+ - catppuccin-frappe
+ - catppuccin-latte
+ - catppuccin-macchiato
+ - catppuccin-mocha
+ - colorful
+ - doom-one
+ - doom-one2
+ - dracula
+ - emacs
+ - evergarden
+ - friendly
+ - fruity
+ - github
+ - github-dark
+ - gruvbox
+ - gruvbox-light
+ - hr_high_contrast
+ - hrdark
+ - igor
+ - lovelace
+ - manni
+ - modus-operandi
+ - modus-vivendi
+ - monokai
+ - monokailight
+ - murphy
+ - native
+ - nord
+ - nordic
+ - onedark
+ - onesenterprise
+ - paraiso-dark
+ - paraiso-light
+ - pastie
+ - perldoc
+ - pygments
+ - rainbow_dash
+ - rose-pine
+ - rose-pine-dawn
+ - rose-pine-moon
++ - rpgle
+ - rrt
+ - solarized-dark
+ - solarized-dark256
+ - solarized-light
+ - swapoff
+ - tango
+ - tokyonight-day
+ - tokyonight-moon
+ - tokyonight-night
+ - tokyonight-storm
+ - trac
+ - vim
+ - vs
+ - vulcan
+ - witchhazel
+ - xcode
+ - xcode-dark
+config:
+ HTTPCache:
+ cache:
+ for:
+ excludes:
+ - '**'
+ includes: null
+ polls:
+ - disable: true
+ for:
+ excludes: null
+ includes:
+ - '**'
+ high: 0s
+ low: 0s
+ respectCacheControlNoStoreInRequest: true
+ respectCacheControlNoStoreInResponse: false
+ archeTypeDir: archetypes
+ assetDir: assets
+ author: {}
+ baseURL: ''
+ build:
+ buildStats:
+ disableClasses: false
+ disableIDs: false
+ disableTags: false
+ enable: false
+ cacheBusters:
+ - source: '(postcss|tailwind)\.config\.js'
+ target: (css|styles|scss|sass)
+ noJSConfigInAssets: false
+ useResourceCacheWhen: fallback
+ buildDrafts: false
+ buildExpired: false
+ buildFuture: false
+ cacheDir: ''
+ caches:
+ assets:
+ dir: :resourceDir/_gen
+ maxAge: -1
+ getresource:
+ dir: :cacheDir/:project
+ maxAge: -1
+ images:
+ dir: :resourceDir/_gen
+ maxAge: -1
+ misc:
+ dir: :cacheDir/:project
+ maxAge: -1
+ modulegitinfo:
+ dir: :cacheDir/modules
+ maxAge: 24h
+ modulequeries:
+ dir: :cacheDir/modules
+ maxAge: 24h
+ modules:
+ dir: :cacheDir/modules
+ maxAge: -1
+ canonifyURLs: false
+ capitalizeListTitles: true
+ cascade: null
+ cleanDestinationDir: false
+ contentDir: content
+ contentTypes:
+ text/asciidoc: {}
+ text/html: {}
+ text/markdown: {}
+ text/org: {}
+ text/pandoc: {}
+ text/rst: {}
+ copyright: ''
+ dataDir: data
+ defaultContentLanguage: en
+ defaultContentLanguageInSubdir: false
+ defaultContentRole: guest
+ defaultContentRoleInSubdir: false
+ defaultContentVersion: ''
+ defaultContentVersionInSubdir: false
+ defaultOutputFormat: html
+ deployment:
+ confirm: false
+ dryRun: false
+ force: false
+ invalidateCDN: true
+ matchers: null
+ maxDeletes: 256
+ order: null
+ target: ''
+ targets: null
+ workers: 10
+ disableAliases: false
+ disableDefaultLanguageRedirect: false
+ disableDefaultSiteRedirect: false
+ disableHugoGeneratorInject: false
+ disableKinds: null
+ disableLanguages: null
+ disableLiveReload: false
+ disablePathToLower: false
+ enableEmoji: false
+ enableGitInfo: false
+ enableMissingTranslationPlaceholders: false
+ enableRobotsTXT: false
+ environment: production
+ frontmatter:
+ date:
+ - date
+ - publishdate
+ - pubdate
+ - published
+ - lastmod
+ - modified
+ expiryDate:
+ - expirydate
+ - unpublishdate
+ lastmod:
+ - :git
+ - lastmod
+ - modified
+ - date
+ - publishdate
+ - pubdate
+ - published
+ publishDate:
+ - publishdate
+ - pubdate
+ - published
+ - date
+ hasCJKLanguage: false
+ i18nDir: i18n
+ ignoreCache: false
+ ignoreFiles: null
+ ignoreLogs: null
+ ignoreVendorPaths: ''
+ imaging:
+ anchor: smart
+ bgColor: ffffff
+ compression: lossy
+ exif:
+ disableDate: false
+ disableLatLong: false
+ excludeFields: GPS|Exif|Exposure[M|P|B]|Contrast|Resolution|Sharp|JPEG|Metering|Sensing|Saturation|ColorSpace|Flash|WhiteBalance
+ includeFields: ''
+ meta:
+ fields:
+ - '! *{GPS,Exif,Exposure[MPB],Contrast,Resolution,Sharp,JPEG,Metering,Sensing,Saturation,ColorSpace,Flash,WhiteBalance}*'
+ sources:
+ - exif
+ - iptc
+ quality: 75
+ resampleFilter: box
+ webp:
+ hint: photo
+ method: 2
+ useSharpYuv: false
+ languages:
+ en:
+ direction: ''
+ disabled: false
+ label: ''
+ locale: ''
+ title: ''
+ weight: 0
+ layoutDir: layouts
+ locale: ''
+ mainSections: null
+ markup:
+ asciiDocExt:
+ attributes: {}
+ backend: html5
+ extensions: []
+ failureLevel: fatal
+ noHeaderOrFooter: true
+ preserveTOC: false
+ safeMode: unsafe
+ sectionNumbers: false
+ trace: false
+ verbose: false
+ workingFolderCurrent: false
+ defaultMarkdownHandler: goldmark
+ goldmark:
+ duplicateResourceFiles: false
+ extensions:
+ cjk:
+ eastAsianLineBreaks: false
+ eastAsianLineBreaksStyle: simple
+ enable: false
+ escapedSpace: false
+ definitionList: true
+ extras:
+ delete:
+ enable: false
+ insert:
+ enable: false
+ mark:
+ enable: false
+ subscript:
+ enable: false
+ superscript:
+ enable: false
+ footnote:
+ backlinkHTML: '↩︎'
+ enable: true
+ enableAutoIDPrefix: false
+ linkify: true
+ linkifyProtocol: https
+ passthrough:
+ delimiters:
+ block: []
+ inline: []
+ enable: false
+ strikethrough: true
+ table: true
+ taskList: true
+ typographer:
+ apostrophe: '’'
+ disable: false
+ ellipsis: '…'
+ emDash: '—'
+ enDash: '–'
+ leftAngleQuote: '«'
+ leftDoubleQuote: '“'
+ leftSingleQuote: '‘'
+ rightAngleQuote: '»'
+ rightDoubleQuote: '”'
+ rightSingleQuote: '’'
+ parser:
+ attribute:
+ block: false
+ title: true
+ autoDefinitionTermID: false
+ autoHeadingID: true
+ autoIDType: github
+ wrapStandAloneImageWithinParagraph: true
+ renderHooks:
+ image:
+ enableDefault: false
+ useEmbedded: auto
+ link:
+ enableDefault: false
+ useEmbedded: auto
+ renderer:
+ hardWraps: false
+ unsafe: false
+ xhtml: false
+ highlight:
+ anchorLineNos: false
+ codeFences: true
+ guessSyntax: false
+ hl_Lines: ''
+ hl_inline: false
+ lineAnchors: ''
+ lineNoStart: 1
+ lineNos: false
+ lineNumbersInTable: true
+ noClasses: true
+ style: monokai
+ tabWidth: 4
+ wrapperClass: highlight
+ tableOfContents:
+ endLevel: 3
+ ordered: false
+ startLevel: 2
+ mediaTypes:
+ application/json:
+ delimiter: .
+ suffixes:
+ - json
+ application/manifest+json:
+ delimiter: .
+ suffixes:
+ - webmanifest
+ application/octet-stream:
+ delimiter: .
+ application/pdf:
+ delimiter: .
+ suffixes:
+ - pdf
+ application/rss+xml:
+ delimiter: .
+ suffixes:
+ - xml
+ - rss
+ application/toml:
+ delimiter: .
+ suffixes:
+ - toml
+ application/wasm:
+ delimiter: .
+ suffixes:
+ - wasm
+ application/xml:
+ delimiter: .
+ suffixes:
+ - xml
+ application/yaml:
+ delimiter: .
+ suffixes:
+ - yaml
+ - yml
+ font/otf:
+ delimiter: .
+ suffixes:
+ - otf
+ font/ttf:
+ delimiter: .
+ suffixes:
+ - ttf
+ image/avif:
+ delimiter: .
+ suffixes:
+ - avif
+ image/bmp:
+ delimiter: .
+ suffixes:
+ - bmp
+ image/gif:
+ delimiter: .
+ suffixes:
+ - gif
+ image/heic:
+ delimiter: .
+ suffixes:
+ - heic
+ image/heif:
+ delimiter: .
+ suffixes:
+ - heif
+ image/jpeg:
+ delimiter: .
+ suffixes:
+ - jpg
+ - jpeg
+ - jpe
+ - jif
+ - jfif
+ image/png:
+ delimiter: .
+ suffixes:
+ - png
+ image/svg+xml:
+ delimiter: .
+ suffixes:
+ - svg
+ image/tiff:
+ delimiter: .
+ suffixes:
+ - tif
+ - tiff
+ image/webp:
+ delimiter: .
+ suffixes:
+ - webp
+ text/asciidoc:
+ delimiter: .
+ suffixes:
+ - adoc
+ - asciidoc
+ - ad
+ text/calendar:
+ delimiter: .
+ suffixes:
+ - ics
+ text/css:
+ delimiter: .
+ suffixes:
+ - css
+ text/csv:
+ delimiter: .
+ suffixes:
+ - csv
+ text/html:
+ delimiter: .
+ suffixes:
+ - html
+ - htm
+ text/javascript:
+ delimiter: .
+ suffixes:
+ - js
+ - jsm
+ - mjs
+ text/jsx:
+ delimiter: .
+ suffixes:
+ - jsx
+ text/markdown:
+ delimiter: .
+ suffixes:
+ - md
+ - mdown
+ - markdown
+ text/org:
+ delimiter: .
+ suffixes:
+ - org
+ text/pandoc:
+ delimiter: .
+ suffixes:
+ - pandoc
+ - pdc
+ text/plain:
+ delimiter: .
+ suffixes:
+ - txt
+ text/rst:
+ delimiter: .
+ suffixes:
+ - rst
+ text/tsx:
+ delimiter: .
+ suffixes:
+ - tsx
+ text/typescript:
+ delimiter: .
+ suffixes:
+ - ts
+ text/x-gotmpl:
+ delimiter: .
+ suffixes:
+ - gotmpl
+ text/x-sass:
+ delimiter: .
+ suffixes:
+ - sass
+ text/x-scss:
+ delimiter: .
+ suffixes:
+ - scss
+ video/3gpp:
+ delimiter: .
+ suffixes:
+ - 3gpp
+ - 3gp
+ video/mp4:
+ delimiter: .
+ suffixes:
+ - mp4
+ video/mpeg:
+ delimiter: .
+ suffixes:
+ - mpg
+ - mpeg
+ video/ogg:
+ delimiter: .
+ suffixes:
+ - ogv
+ video/webm:
+ delimiter: .
+ suffixes:
+ - webm
+ video/x-msvideo:
+ delimiter: .
+ suffixes:
+ - avi
+ menus: {}
+ minify:
+ disableCSS: false
+ disableHTML: false
+ disableJS: false
+ disableJSON: false
+ disableSVG: false
+ disableXML: false
+ minifyOutput: false
+ tdewolff:
+ css:
+ inline: false
+ precision: 0
+ version: 0
+ html:
+ keepComments: false
+ keepConditionalComments: false
+ keepDefaultAttrVals: true
+ keepDocumentTags: true
+ keepEndTags: true
+ keepQuotes: false
+ keepSpecialComments: true
+ keepWhitespace: false
+ templateDelims:
+ - ''
+ - ''
+ js:
+ keepVarNames: false
+ precision: 0
+ version: 2022
+ json:
+ keepNumbers: false
+ precision: 0
+ svg:
+ keepComments: false
+ precision: 0
+ xml:
+ keepWhitespace: false
+ module:
+ auth: ''
+ hugoVersion:
+ extended: false
+ max: ''
+ min: ''
+ imports: null
+ mounts:
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: content
+ target: content
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: data
+ target: data
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: layouts
+ target: layouts
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: i18n
+ target: i18n
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: archetypes
+ target: archetypes
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: assets
+ target: assets
+ - disableWatch: false
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
+ source: static
+ target: static
+ noProxy: none
+ noVendor: ''
+ params: null
+ private: '*.*'
+ proxy: direct
+ replacements: null
+ vendorClosest: false
+ workspace: 'off'
+ newContentEditor: ''
+ noBuildLock: false
+ noChmod: false
+ noTimes: false
+ outputFormats:
+ '404':
+ baseName: ''
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: true
+ path: ''
+ permalinkable: true
+ protocol: ''
+ rel: ''
+ root: false
+ ugly: true
+ weight: 0
+ alias:
+ baseName: ''
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: ''
+ root: false
+ ugly: true
+ weight: 0
+ amp:
+ baseName: index
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: false
+ path: amp
+ permalinkable: true
+ protocol: ''
+ rel: amphtml
+ root: false
+ ugly: false
+ weight: 0
+ calendar:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: text/calendar
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: webcal://
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ css:
+ baseName: styles
+ isHTML: false
+ isPlainText: true
+ mediaType: text/css
+ noUgly: false
+ notAlternative: true
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: stylesheet
+ root: false
+ ugly: false
+ weight: 0
+ csv:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: text/csv
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ gotmpl:
+ baseName: ''
+ isHTML: false
+ isPlainText: true
+ mediaType: text/x-gotmpl
+ noUgly: false
+ notAlternative: true
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: ''
+ root: false
+ ugly: false
+ weight: 0
+ html:
+ baseName: index
+ isHTML: true
+ isPlainText: false
+ mediaType: text/html
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: true
+ protocol: ''
+ rel: canonical
+ root: false
+ ugly: false
+ weight: 10
+ json:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: application/json
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ markdown:
+ baseName: index
+ isHTML: false
+ isPlainText: true
+ mediaType: text/markdown
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ robots:
+ baseName: robots
+ isHTML: false
+ isPlainText: true
+ mediaType: text/plain
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: true
+ ugly: false
+ weight: 0
+ rss:
+ baseName: index
+ isHTML: false
+ isPlainText: false
+ mediaType: application/rss+xml
+ noUgly: true
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: alternate
+ root: false
+ ugly: false
+ weight: 0
+ sitemap:
+ baseName: sitemap
+ isHTML: false
+ isPlainText: false
+ mediaType: application/xml
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: sitemap
+ root: false
+ ugly: true
+ weight: 0
+ sitemapindex:
+ baseName: sitemap
+ isHTML: false
+ isPlainText: false
+ mediaType: application/xml
+ noUgly: false
+ notAlternative: false
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: sitemap
+ root: true
+ ugly: true
+ weight: 0
+ webappmanifest:
+ baseName: manifest
+ isHTML: false
+ isPlainText: true
+ mediaType: application/manifest+json
+ noUgly: false
+ notAlternative: true
+ path: ''
+ permalinkable: false
+ protocol: ''
+ rel: manifest
+ root: false
+ ugly: false
+ weight: 0
+ outputs:
+ home:
+ - html
+ - rss
+ page:
+ - html
+ rss:
+ - rss
+ section:
+ - html
+ - rss
+ taxonomy:
+ - html
+ - rss
+ term:
+ - html
+ - rss
+ page:
+ nextPrevInSectionSortOrder: desc
+ nextPrevSortOrder: desc
+ pagination:
+ disableAliases: false
+ pagerSize: 10
+ path: page
+ panicOnWarning: false
+ params: {}
+ permalinks:
+ page: {}
+ section: {}
+ taxonomy: {}
+ term: {}
+ pluralizeListTitles: true
+ printI18nWarnings: false
+ printPathWarnings: false
+ printUnusedTemplates: false
+ privacy:
+ disqus:
+ disable: false
+ googleAnalytics:
+ disable: false
+ respectDoNotTrack: true
+ instagram:
+ disable: false
+ simple: false
+ vimeo:
+ disable: false
+ enableDNT: false
+ simple: false
+ x:
+ disable: false
+ enableDNT: false
+ simple: false
+ youTube:
+ disable: false
+ privacyEnhanced: false
+ publishDir: public
+ refLinksErrorLevel: ''
+ refLinksNotFoundURL: ''
+ related:
+ includeNewer: false
+ indices:
+ - applyFilter: false
+ cardinalityThreshold: 0
+ name: keywords
+ pattern: ''
+ toLower: false
+ type: basic
+ weight: 100
+ - applyFilter: false
+ cardinalityThreshold: 0
+ name: date
+ pattern: ''
+ toLower: false
+ type: basic
+ weight: 10
+ - applyFilter: false
+ cardinalityThreshold: 0
+ name: tags
+ pattern: ''
+ toLower: false
+ type: basic
+ weight: 80
+ threshold: 80
+ toLower: false
+ relativeURLs: false
+ removePathAccents: false
+ renderSegments: null
+ resourceDir: resources
+ roles:
+ guest:
+ weight: 0
+ sectionPagesMenu: ''
+ security:
+ enableInlineShortcodes: false
+ exec:
+ allow:
+ - ^(dart-)?sass(-embedded)?$
+ - ^go$
+ - ^git$
+ - ^npx$
+ - ^postcss$
+ - ^tailwindcss$
+ osEnv:
+ - '(?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM|GO\w+|(XDG_CONFIG_)?HOME|USERPROFILE|SSH_AUTH_SOCK|DISPLAY|LANG|SYSTEMDRIVE|PROGRAMDATA)$'
+ funcs:
+ getenv:
+ - ^HUGO_
+ - ^CI$
+ http:
+ mediaTypes: null
+ methods:
+ - (?i)GET|POST
+ urls:
+ - .*
+ segments: {}
+ server:
+ headers: null
+ redirects:
+ - force: false
+ from: /**
+ fromHeaders: null
+ fromRe: ''
+ status: 404
+ to: /404.html
+ services:
+ disqus:
+ shortname: ''
+ googleAnalytics:
+ id: ''
+ rss:
+ limit: -1
+ x:
+ disableInlineCSS: false
+ sitemap:
+ changeFreq: ''
+ disable: false
+ filename: sitemap.xml
+ priority: -1
+ social: null
+ staticDir:
+ - static
+ staticDir0: null
+ staticDir1: null
+ staticDir10: null
+ staticDir2: null
+ staticDir3: null
+ staticDir4: null
+ staticDir5: null
+ staticDir6: null
+ staticDir7: null
+ staticDir8: null
+ staticDir9: null
+ summaryLength: 70
+ taxonomies:
+ category: categories
+ tag: tags
+ templateMetrics: false
+ templateMetricsHints: false
+ theme: null
+ themesDir: themes
+ timeZone: ''
+ timeout: 60s
+ title: ''
+ titleCaseStyle: AP
+ uglyURLs: {}
+ versions:
+ v1.0.0:
+ weight: 0
+ workingDir: ''
+config_helpers:
+ mergeStrategy:
+ build:
+ _merge: none
+ caches:
+ _merge: none
+ cascade:
+ _merge: none
+ contenttypes:
+ _merge: none
+ deployment:
+ _merge: none
+ frontmatter:
+ _merge: none
+ httpcache:
+ _merge: none
+ imaging:
+ _merge: none
+ languages:
+ _merge: none
+ en:
+ _merge: none
+ menus:
+ _merge: shallow
+ params:
+ _merge: deep
+ markup:
+ _merge: none
+ mediatypes:
+ _merge: shallow
+ menus:
+ _merge: shallow
+ minify:
+ _merge: none
+ module:
+ _merge: none
+ outputformats:
+ _merge: shallow
+ outputs:
+ _merge: none
+ page:
+ _merge: none
+ pagination:
+ _merge: none
+ params:
+ _merge: deep
+ permalinks:
+ _merge: none
+ privacy:
+ _merge: none
+ related:
+ _merge: none
+ roles:
+ _merge: none
+ security:
+ _merge: none
+ segments:
+ _merge: none
+ server:
+ _merge: none
+ services:
+ _merge: none
+ sitemap:
+ _merge: none
+ taxonomies:
+ _merge: none
+ versions:
+ _merge: none
+output:
+ layouts: {}
+tpl:
+ funcs:
+ cast:
+ ToFloat:
+ Aliases:
+ - float
+ Args:
+ - v
+ Description: ToFloat converts v to a float.
+ Examples:
+ - - '{{ "1234" | float | printf "%T" }}'
+ - float64
+ ToInt:
+ Aliases:
+ - int
+ Args:
+ - v
+ Description: ToInt converts v to an int.
+ Examples:
+ - - '{{ "1234" | int | printf "%T" }}'
+ - int
+ ToString:
+ Aliases:
+ - string
+ Args:
+ - v
+ Description: ToString converts v to a string.
+ Examples:
+ - - '{{ 1234 | string | printf "%T" }}'
+ - string
+ collections:
+ After:
+ Aliases:
+ - after
+ Args:
+ - 'n'
+ - l
+ Description: After returns all the items after the first n items in list l.
+ Examples: []
+ Append:
+ Aliases:
+ - append
+ Args:
+ - args
+ Description: |-
+ Append appends args up to the last one to the slice in the last argument.
+ This construct allows template constructs like this:
-
++
+ {{ $pages = $pages | append $p2 $p1 }}
-
++
+ Note that with 2 arguments where both are slices of the same type,
+ the first slice will be appended to the second:
-
++
+ {{ $pages = $pages | append .Site.RegularPages }}
+ Examples: []
+ Apply:
+ Aliases:
+ - apply
+ Args:
+ - ctx
+ - c
+ - fname
+ - args
+ Description: Apply takes an array or slice c and returns a new slice with the function fname applied over it.
+ Examples: []
+ Complement:
+ Aliases:
+ - complement
+ Args:
+ - ls
+ Description: |-
+ Complement gives the elements in the last element of ls that are not in
+ any of the others.
-
++
+ All elements of ls must be slices or arrays of comparable types.
-
++
+ The reasoning behind this rather clumsy API is so we can do this in the templates:
-
++
+ {{ $c := .Pages | complement $last4 }}
+ Examples:
+ - - '{{ slice "a" "b" "c" "d" "e" "f" | complement (slice "b" "c") (slice "d" "e") }}'
+ - '[a f]'
+ D:
+ Aliases: null
+ Args:
+ - seed
+ - 'n'
+ - hi
+ Description: 'D returns a sorted slice of unique random integers in the half-open interval\n[0, hi) using the provided seed value. The number of elements in the\nresulting slice is n or hi, whichever is less.\n\nIf n <= hi, it returns a sorted random sample of size n using J. S. Vitter’s\nMethod D for sequential random sampling.\n\nIf n > hi, it returns the full, sorted range [0, hi) of size hi.\n\nIf n == 0 or hi == 0, it returns an empty slice.\n\nReference:\n\n\tJ. S. Vitter, "An efficient algorithm for sequential random sampling," ACM Trans. Math. Softw., vol. 11, no. 1, pp. 37–57, 1985.\n\tSee also: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/'
+ Examples: []
+ Delimit:
+ Aliases:
+ - delimit
+ Args:
+ - ctx
+ - l
+ - sep
+ - last
+ Description: |-
+ Delimit takes a given list l and returns a string delimited by sep.
+ If last is passed to the function, it will be used as the final delimiter.
+ Examples:
+ - - '{{ delimit (slice "A" "B" "C") ", " " and " }}'
+ - A, B and C
+ Dictionary:
+ Aliases:
+ - dict
+ Args:
+ - values
+ Description: |-
+ Dictionary creates a new map from the given parameters by
+ treating values as key-value pairs. The number of values must be even.
+ The keys can be string slices, which will create the needed nested structure.
+ Examples: []
+ First:
+ Aliases:
+ - first
+ Args:
+ - limit
+ - l
+ Description: First returns the first limit items in list l.
+ Examples: []
+ Group:
+ Aliases:
+ - group
+ Args:
+ - key
+ - items
+ Description: |-
+ Group groups a set of items by the given key.
+ This is currently only supported for Pages.
+ Examples: []
+ In:
+ Aliases:
+ - in
+ Args:
+ - l
+ - v
+ Description: In returns whether v is in the list l. l may be an array or slice.
+ Examples:
+ - - '{{ if in "this string contains a substring" "substring" }}Substring found!{{ end }}'
+ - Substring found!
+ Index:
+ Aliases:
+ - index
+ Args:
+ - item
+ - args
+ Description: |-
+ Index returns the result of indexing its first argument by the following
+ arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each
+ indexed item must be a map, slice, or array.
-
++
+ Adapted from Go stdlib src/text/template/funcs.go.
-
++
+ We deviate from the stdlib mostly because of https://github.com/golang/go/issues/14751.
+ Examples: []
+ Intersect:
+ Aliases:
+ - intersect
+ Args:
+ - l1
+ - l2
+ Description: |-
+ Intersect returns the common elements in the given sets, l1 and l2. l1 and
+ l2 must be of the same type and may be either arrays or slices.
+ Examples: []
+ IsSet:
+ Aliases:
+ - isSet
+ - isset
+ Args:
+ - c
+ - key
+ Description: |-
+ IsSet returns whether a given array, channel, slice, or map in c has the given key
+ defined.
+ Examples: []
+ KeyVals:
+ Aliases:
+ - keyVals
+ Args:
+ - key
+ - values
+ Description: KeyVals creates a key and values wrapper.
+ Examples:
+ - - '{{ keyVals "key" "a" "b" }}'
+ - 'key: [a b]'
+ Last:
+ Aliases:
+ - last
+ Args:
+ - limit
+ - l
+ Description: Last returns the last limit items in the list l.
+ Examples: []
+ Merge:
+ Aliases:
+ - merge
+ Args:
+ - params
+ Description: |-
+ Merge creates a copy of the final parameter in params and merges the preceding
+ parameters into it in reverse order.
-
++
+ Currently only maps are supported. Key handling is case insensitive.
+ Examples:
+ - - '{{ dict "title" "Hugo Rocks!" | collections.Merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!") | sort }}'
+ - '[Yes, Hugo Rocks! Hugo Rocks!]'
+ - - '{{ merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!") (dict "title" "Hugo Rocks!") | sort }}'
+ - '[Yes, Hugo Rocks! Hugo Rocks!]'
+ - - '{{ merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!") (dict "title" "Hugo Rocks!") (dict "extra" "For reals!") | sort }}'
+ - '[Yes, Hugo Rocks! For reals! Hugo Rocks!]'
+ NewScratch:
+ Aliases:
+ - newScratch
+ Args: null
+ Description: |-
+ NewScratch creates a new Scratch which can be used to store values in a
+ thread safe way.
+ Examples:
+ - - '{{ $scratch := newScratch }}{{ $scratch.Add "b" 2 }}{{ $scratch.Add "b" 2 }}{{ $scratch.Get "b" }}'
+ - '4'
+ Querify:
+ Aliases:
+ - querify
+ Args:
+ - params
+ Description: |-
+ Querify returns a URL query string composed of the given key-value pairs,
+ encoded and sorted by key.
+ Examples:
+ - - '{{ (querify "foo" 1 "bar" 2 "baz" "with spaces" "qux" "this&that=those") | safeHTML }}'
+ - bar=2&baz=with+spaces&foo=1&qux=this%26that%3Dthose
+ - - <a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
+ - <a href="https://www.google.com?page=3&q=test">Search</a>
+ - - '{{ slice "foo" 1 "bar" 2 | querify | safeHTML }}'
+ - bar=2&foo=1
+ Reverse:
+ Aliases: null
+ Args:
+ - l
+ Description: Reverse creates a copy of the list l and reverses it.
+ Examples: []
+ Seq:
+ Aliases:
+ - seq
+ Args:
+ - args
+ Description: |-
+ Seq creates a sequence of integers from args. It's named and used as GNU's seq.
-
++
+ Examples:
-
++
+ 3 => 1, 2, 3
+ 1 2 4 => 1, 3
+ -3 => -1, -2, -3
+ 1 4 => 1, 2, 3, 4
+ 1 -2 => 1, 0, -1, -2
+ Examples:
+ - - '{{ seq 3 }}'
+ - '[1 2 3]'
+ Shuffle:
+ Aliases:
+ - shuffle
+ Args:
+ - l
+ Description: Shuffle returns list l in a randomized order.
+ Examples: []
+ Slice:
+ Aliases:
+ - slice
+ Args:
+ - args
+ Description: Slice returns a slice of all passed arguments.
+ Examples:
+ - - '{{ slice "B" "C" "A" | sort }}'
+ - '[A B C]'
+ Sort:
+ Aliases:
+ - sort
+ Args:
+ - ctx
+ - l
+ - args
+ Description: Sort returns a sorted copy of the list l.
+ Examples: []
+ SymDiff:
+ Aliases:
+ - symdiff
+ Args:
+ - s2
+ - s1
+ Description: |-
+ SymDiff returns the symmetric difference of s1 and s2.
+ Arguments must be either a slice or an array of comparable types.
+ Examples:
+ - - '{{ slice 1 2 3 | symdiff (slice 3 4) }}'
+ - '[1 2 4]'
+ Union:
+ Aliases:
+ - union
+ Args:
+ - l1
+ - l2
+ Description: |-
+ Union returns the union of the given sets, l1 and l2. l1 and
+ l2 must be of the same type and may be either arrays or slices.
+ If l1 and l2 aren't of the same type then l1 will be returned.
+ If either l1 or l2 is nil then the non-nil list will be returned.
+ Examples:
+ - - '{{ union (slice 1 2 3) (slice 3 4 5) }}'
+ - '[1 2 3 4 5]'
+ Uniq:
+ Aliases:
+ - uniq
+ Args:
+ - l
+ Description: Uniq returns a new list with duplicate elements in the list l removed.
+ Examples:
+ - - '{{ slice 1 2 3 2 | uniq }}'
+ - '[1 2 3]'
+ Where:
+ Aliases:
+ - where
+ Args:
+ - ctx
+ - c
+ - key
+ - args
+ Description: Where returns a filtered subset of collection c.
+ Examples: []
+ compare:
+ Conditional:
+ Aliases:
+ - cond
+ Args:
+ - cond
+ - v1
+ - v2
+ Description: |-
+ Conditional can be used as a ternary operator.
-
++
+ It returns v1 if cond is true, else v2.
+ Examples:
+ - - '{{ cond (eq (add 2 2) 4) "2+2 is 4" "what?" | safeHTML }}'
+ - 2+2 is 4
+ Default:
+ Aliases:
+ - default
+ Args:
+ - defaultv
+ - givenv
+ Description: |-
+ Default checks whether a givenv is set and returns the default value defaultv if it
+ is not. "Set" in this context means non-zero for numeric types and times;
+ non-zero length for strings, arrays, slices, and maps;
+ any boolean or struct value; or non-nil for any other types.
+ Examples:
+ - - '{{ "Hugo Rocks!" | default "Hugo Rules!" }}'
+ - Hugo Rocks!
+ - - '{{ "" | default "Hugo Rules!" }}'
+ - Hugo Rules!
+ Eq:
+ Aliases:
+ - eq
+ Args:
+ - first
+ - others
+ Description: Eq returns the boolean truth of arg1 == arg2 || arg1 == arg3 || arg1 == arg4.
+ Examples:
+ - - '{{ if eq .Section "blog" }}current-section{{ end }}'
+ - current-section
+ Ge:
+ Aliases:
+ - ge
+ Args:
+ - first
+ - others
+ Description: Ge returns the boolean truth of arg1 >= arg2 && arg1 >= arg3 && arg1 >= arg4.
+ Examples:
+ - - '{{ if ge hugo.Version "0.80" }}Reasonable new Hugo version!{{ end }}'
+ - Reasonable new Hugo version!
+ Gt:
+ Aliases:
+ - gt
+ Args:
+ - first
+ - others
+ Description: Gt returns the boolean truth of arg1 > arg2 && arg1 > arg3 && arg1 > arg4.
+ Examples: []
+ Le:
+ Aliases:
+ - le
+ Args:
+ - first
+ - others
+ Description: Le returns the boolean truth of arg1 <= arg2 && arg1 <= arg3 && arg1 <= arg4.
+ Examples: []
+ Lt:
+ Aliases:
+ - lt
+ Args:
+ - first
+ - others
+ Description: Lt returns the boolean truth of arg1 < arg2 && arg1 < arg3 && arg1 < arg4.
+ Examples: []
+ LtCollate:
+ Aliases: null
+ Args:
+ - collator
+ - first
+ - others
+ Description: |-
+ LtCollate returns the boolean truth of arg1 < arg2 && arg1 < arg3 && arg1 < arg4.
+ The provided collator will be used for string comparisons.
+ This is for internal use.
+ Examples: []
+ Ne:
+ Aliases:
+ - ne
+ Args:
+ - first
+ - others
+ Description: Ne returns the boolean truth of arg1 != arg2 && arg1 != arg3 && arg1 != arg4.
+ Examples: []
+ crypto:
+ HMAC:
+ Aliases:
+ - hmac
+ Args:
+ - h
+ - k
+ - m
+ - e
+ Description: HMAC returns a cryptographic hash that uses a key to sign a message.
+ Examples:
+ - - '{{ hmac "sha256" "Secret key" "Hello world, gophers!" }}'
+ - b6d11b6c53830b9d87036272ca9fe9d19306b8f9d8aa07b15da27d89e6e34f40
+ MD5:
+ Aliases:
+ - md5
+ Args:
+ - v
+ Description: MD5 hashes the v and returns its MD5 checksum.
+ Examples:
+ - - '{{ md5 "Hello world, gophers!" }}'
+ - b3029f756f98f79e7f1b7f1d1f0dd53b
+ - - '{{ crypto.MD5 "Hello world, gophers!" }}'
+ - b3029f756f98f79e7f1b7f1d1f0dd53b
+ SHA1:
+ Aliases:
+ - sha1
+ Args:
+ - v
+ Description: SHA1 hashes v and returns its SHA1 checksum.
+ Examples:
+ - - '{{ sha1 "Hello world, gophers!" }}'
+ - c8b5b0e33d408246e30f53e32b8f7627a7a649d4
+ SHA256:
+ Aliases:
+ - sha256
+ Args:
+ - v
+ Description: SHA256 hashes v and returns its SHA256 checksum.
+ Examples:
+ - - '{{ sha256 "Hello world, gophers!" }}'
+ - 6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46
+ css:
++ Build:
++ Aliases: null
++ Args:
++ - args
++ Description: |-
++ Build processes the given CSS Resource with ESBuild.
++ Note that this method is identical to the one in the js Namespace.
++ Examples: []
+ PostCSS:
+ Aliases:
+ - postCSS
+ Args:
+ - args
+ Description: PostCSS processes the given Resource with PostCSS.
+ Examples: []
+ Quoted:
+ Aliases: null
+ Args:
+ - v
+ Description: Quoted returns a string that needs to be quoted in CSS.
+ Examples: []
+ Sass:
+ Aliases:
+ - toCSS
+ Args:
+ - args
+ Description: Sass processes the given Resource with SASS.
+ Examples: []
+ TailwindCSS:
+ Aliases: null
+ Args:
+ - args
+ Description: TailwindCSS processes the given Resource with tailwindcss.
+ Examples: []
+ Unquoted:
+ Aliases: null
+ Args:
+ - v
+ Description: Unquoted returns a string that does not need to be quoted in CSS.
+ Examples: []
+ debug:
+ Dump:
+ Aliases: null
+ Args:
+ - val
+ Description: |-
+ Dump returns a object dump of val as a string.
+ Note that not every value passed to Dump will print so nicely, but
+ we'll improve on that.
-
++
+ We recommend using the "go" Chroma lexer to format the output
+ nicely.
-
++
+ Also note that the output from Dump may change from Hugo version to the next,
+ so don't depend on a specific output.
+ Examples:
+ - - '{{ $m := newScratch }}\n{{ $m.Set "Hugo" "Rocks!" }}\n{{ $m.Values | debug.Dump | safeHTML }}'
+ - '{\n "Hugo": "Rocks!"\n}'
+ TestDeprecationErr:
+ Aliases: null
+ Args:
+ - item
+ - alternative
+ Description: Internal template func, used in tests only.
+ Examples: []
+ TestDeprecationInfo:
+ Aliases: null
+ Args:
+ - item
+ - alternative
+ Description: Internal template func, used in tests only.
+ Examples: []
+ TestDeprecationWarn:
+ Aliases: null
+ Args:
+ - item
+ - alternative
+ Description: Internal template func, used in tests only.
+ Examples: []
+ Timer:
+ Aliases: null
+ Args:
+ - name
+ Description: ''
+ Examples: []
+ VisualizeSpaces:
+ Aliases: null
+ Args:
+ - val
+ Description: VisualizeSpaces returns a string with spaces replaced by a visible string.
+ Examples: []
+ diagrams:
+ Goat:
+ Aliases: null
+ Args:
+ - v
+ Description: Goat creates a new SVG diagram from input v.
+ Examples: []
+ encoding:
+ Base64Decode:
+ Aliases:
+ - base64Decode
+ Args:
+ - content
+ Description: Base64Decode returns the base64 decoding of the given content.
+ Examples:
+ - - '{{ "SGVsbG8gd29ybGQ=" | base64Decode }}'
+ - Hello world
+ - - '{{ 42 | base64Encode | base64Decode }}'
+ - '42'
+ Base64Encode:
+ Aliases:
+ - base64Encode
+ Args:
+ - content
+ Description: Base64Encode returns the base64 encoding of the given content.
+ Examples:
+ - - '{{ "Hello world" | base64Encode }}'
+ - SGVsbG8gd29ybGQ=
+ Jsonify:
+ Aliases:
+ - jsonify
+ Args:
+ - args
+ Description: |-
+ Jsonify encodes a given object to JSON. To pretty print the JSON, pass a map
+ or dictionary of options as the first value in args. Supported options are
+ "prefix" and "indent". Each JSON element in the output will begin on a new
+ line beginning with prefix followed by one or more copies of indent according
+ to the indentation nesting.
+ Examples:
+ - - '{{ (slice "A" "B" "C") | jsonify }}'
+ - '["A","B","C"]'
+ - - '{{ (slice "A" "B" "C") | jsonify (dict "indent" " ") }}'
+ - '[\n "A",\n "B",\n "C"\n]'
+ fmt:
+ Errorf:
+ Aliases:
+ - errorf
+ Args:
+ - format
+ - args
+ Description: |-
+ Errorf formats args according to a format specifier and logs an ERROR.
+ It returns an empty string.
+ Examples:
+ - - '{{ errorf "%s." "failed" }}'
+ - ''
+ Erroridf:
+ Aliases:
+ - erroridf
+ Args:
+ - id
+ - format
+ - args
+ Description: |-
+ Erroridf formats args according to a format specifier and logs an ERROR and
+ an information text that the error with the given id can be suppressed in config.
+ It returns an empty string.
+ Examples:
+ - - '{{ erroridf "my-err-id" "%s." "failed" }}'
+ - ''
+ Errormf:
+ Aliases: null
+ Args:
+ - m
+ - format
+ - args
+ Description: Errormf is experimental and subject to change at any time.
+ Examples: []
+ Print:
+ Aliases:
+ - print
+ Args:
+ - args
+ Description: Print returns a string representation of args.
+ Examples:
+ - - '{{ print "works!" }}'
+ - works!
+ Printf:
+ Aliases:
+ - printf
+ Args:
+ - format
+ - args
+ Description: Printf returns string representation of args formatted with the layout in format.
+ Examples:
+ - - '{{ printf "%s!" "works" }}'
+ - works!
+ Println:
+ Aliases:
+ - println
+ Args:
+ - args
+ Description: Println returns string representation of args ending with a newline.
+ Examples:
+ - - '{{ println "works!" }}'
+ - |
+ works!
+ Warnf:
+ Aliases:
+ - warnf
+ Args:
+ - format
+ - args
+ Description: |-
+ Warnf formats args according to a format specifier and logs a WARNING.
+ It returns an empty string.
+ Examples:
+ - - '{{ warnf "%s." "warning" }}'
+ - ''
+ Warnidf:
+ Aliases:
+ - warnidf
+ Args:
+ - id
+ - format
+ - args
+ Description: |-
+ Warnidf formats args according to a format specifier and logs an WARNING and
+ an information text that the warning with the given id can be suppressed in config.
+ It returns an empty string.
+ Examples:
+ - - '{{ warnidf "my-warn-id" "%s." "warning" }}'
+ - ''
+ Warnmf:
+ Aliases: null
+ Args:
+ - m
+ - format
+ - args
+ Description: Warnmf is experimental and subject to change at any time.
+ Examples: []
+ hash:
+ FNV32a:
+ Aliases: null
+ Args:
+ - v
+ Description: FNV32a hashes v using fnv32a algorithm.
+ Examples:
+ - - '{{ hash.FNV32a "Hugo Rocks!!" }}'
+ - '1515779328'
+ XxHash:
+ Aliases:
+ - xxhash
+ Args:
+ - v
+ Description: XxHash returns the xxHash of the input string.
+ Examples:
+ - - '{{ hash.XxHash "The quick brown fox jumps over the lazy dog" }}'
+ - 0b242d361fda71bc
+ hugo:
+ Data:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Deps:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Environment:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
++ ForEeachIdentityByName:
++ Aliases: null
++ Args: null
++ Description: ''
++ Examples: null
+ Generator:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsDevelopment:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsExtended:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsMultiHost:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsMultihost:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsMultilingual:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsProduction:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsServer:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Sites:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Store:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Version:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ WorkingDir:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ images:
+ AutoOrient:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Brightness:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ ColorBalance:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Colorize:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Config:
+ Aliases:
+ - imageConfig
+ Args:
+ - path
+ Description: |-
+ Config returns the image.Config for the specified path relative to the
+ working directory.
+ Examples: []
+ Contrast:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Dither:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Filter:
+ Aliases: null
+ Args:
+ - args
+ Description: Filter applies the given filters to the image given as the last element in args.
+ Examples: []
+ Gamma:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ GaussianBlur:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Grayscale:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Hue:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Invert:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Mask:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Opacity:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Overlay:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Padding:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Pixelate:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Process:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ QR:
+ Aliases: null
+ Args:
+ - args
+ Description: |-
+ QR encodes the given text into a QR code using the specified options,
+ returning an image resource.
+ Examples: []
+ Saturation:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Sepia:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Sigmoid:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Text:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ UnsharpMask:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ inflect:
+ Humanize:
+ Aliases:
+ - humanize
+ Args:
+ - v
+ Description: |-
+ Humanize returns the humanized form of v.
- Description: Build processes the given Resource with ESBuild.
++
+ If v is either an integer or a string containing an integer
+ value, the behavior is to add the appropriate ordinal.
+ Examples:
+ - - '{{ humanize "my-first-post" }}'
+ - My first post
+ - - '{{ humanize "myCamelPost" }}'
+ - My camel post
+ - - '{{ humanize "52" }}'
+ - 52nd
+ - - '{{ humanize 103 }}'
+ - 103rd
+ Pluralize:
+ Aliases:
+ - pluralize
+ Args:
+ - v
+ Description: Pluralize returns the plural form of the single word in v.
+ Examples:
+ - - '{{ "cat" | pluralize }}'
+ - cats
+ Singularize:
+ Aliases:
+ - singularize
+ Args:
+ - v
+ Description: Singularize returns the singular form of a single word in v.
+ Examples:
+ - - '{{ "cats" | singularize }}'
+ - cat
+ js:
+ Babel:
+ Aliases:
+ - babel
+ Args:
+ - args
+ Description: Babel processes the given Resource with Babel.
+ Examples: []
+ Batch:
+ Aliases: null
+ Args:
+ - id
+ Description: |-
+ Batch creates a new Batcher with the given ID.
+ Repeated calls with the same ID will return the same Batcher.
+ The ID will be used to name the root directory of the batch.
+ Forward slashes in the ID is allowed.
+ Examples: []
+ Build:
+ Aliases: null
+ Args:
+ - args
-
++ Description: Build processes the given JavaScript Resource with ESBuild.
+ Examples: []
+ lang:
+ FormatAccounting:
+ Aliases: null
+ Args:
+ - precision
+ - currency
+ - number
+ Description: |-
+ FormatAccounting returns the currency representation of number for the given currency and precision
+ for the current language in accounting notation.
-
++
+ The return value is formatted with at least two decimal places.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatAccounting 2 "NOK" }}'
+ - NOK512.50
+ FormatCurrency:
+ Aliases: null
+ Args:
+ - precision
+ - currency
+ - number
+ Description: |-
+ FormatCurrency returns the currency representation of number for the given currency and precision
+ for the current language.
-
++
+ The return value is formatted with at least two decimal places.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatCurrency 2 "USD" }}'
+ - $512.50
+ FormatNumber:
+ Aliases: null
+ Args:
+ - precision
+ - number
+ Description: FormatNumber formats number with the given precision for the current language.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatNumber 2 }}'
+ - '512.50'
+ FormatNumberCustom:
+ Aliases: null
+ Args:
+ - precision
+ - number
+ - options
+ Description: 'FormatNumberCustom formats a number with the given precision. The first\noptions parameter is a space-delimited string of characters to represent\nnegativity, the decimal point, and grouping. The default value is `- . ,`.\nThe second options parameter defines an alternate delimiting character.\n\nNote that numbers are rounded up at 5 or greater.\nSo, with precision set to 0, 1.5 becomes `2`, and 1.4 becomes `1`.\n\nFor a simpler function that adapts to the current language, see FormatNumber.'
+ Examples:
+ - - '{{ lang.FormatNumberCustom 2 12345.6789 }}'
+ - 12,345.68
+ - - '{{ lang.FormatNumberCustom 2 12345.6789 "- , ." }}'
+ - 12.345,68
+ - - '{{ lang.FormatNumberCustom 6 -12345.6789 "- ." }}'
+ - '-12345.678900'
+ - - '{{ lang.FormatNumberCustom 0 -12345.6789 "- . ," }}'
+ - -12,346
+ - - '{{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }}'
+ - -12 346
+ - - '{{ -98765.4321 | lang.FormatNumberCustom 2 }}'
+ - -98,765.43
+ FormatPercent:
+ Aliases: null
+ Args:
+ - precision
+ - number
+ Description: |-
+ FormatPercent formats number with the given precision for the current language.
+ Note that the number is assumed to be a percentage.
+ Examples:
+ - - '{{ 512.5032 | lang.FormatPercent 2 }}'
+ - 512.50%
+ Merge:
+ Aliases: null
+ Args:
+ - p2
+ - p1
+ Description: Merge creates a union of pages from two languages.
+ Examples: []
+ Translate:
+ Aliases:
+ - i18n
+ - T
+ Args:
+ - ctx
+ - id
+ - args
+ Description: Translate returns a translated string for id.
+ Examples: []
+ math:
+ Abs:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Abs returns the absolute value of n.
+ Examples:
+ - - '{{ math.Abs -2.1 }}'
+ - '2.1'
+ Acos:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Acos returns the arccosine, in radians, of n.
+ Examples:
+ - - '{{ math.Acos 1 }}'
+ - '0'
+ Add:
+ Aliases:
+ - add
+ Args:
+ - inputs
+ Description: Add adds the multivalued addends n1 and n2 or more values.
+ Examples:
+ - - '{{ add 1 2 }}'
+ - '3'
+ Asin:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Asin returns the arcsine, in radians, of n.
+ Examples:
+ - - '{{ math.Asin 1 }}'
+ - '1.5707963267948966'
+ Atan:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Atan returns the arctangent, in radians, of n.
+ Examples:
+ - - '{{ math.Atan 1 }}'
+ - '0.7853981633974483'
+ Atan2:
+ Aliases: null
+ Args:
+ - 'n'
+ - m
+ Description: Atan2 returns the arc tangent of n/m, using the signs of the two to determine the quadrant of the return value.
+ Examples:
+ - - '{{ math.Atan2 1 2 }}'
+ - '0.4636476090008061'
+ Ceil:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Ceil returns the least integer value greater than or equal to n.
+ Examples:
+ - - '{{ math.Ceil 2.1 }}'
+ - '3'
+ Cos:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Cos returns the cosine of the radian argument n.
+ Examples:
+ - - '{{ math.Cos 1 }}'
+ - '0.5403023058681398'
+ Counter:
+ Aliases: null
+ Args: null
+ Description: 'Counter increments and returns a global counter.\nThis was originally added to be used in tests where now.UnixNano did not\nhave the needed precision (especially on Windows).\nNote that given the parallel nature of Hugo, you cannot use this to get sequences of numbers,\nand the counter will reset on new builds.\n<docsmeta>{"identifiers": ["now.UnixNano"] }</docsmeta>'
+ Examples: []
+ Div:
+ Aliases:
+ - div
+ Args:
+ - inputs
+ Description: Div divides n1 by n2.
+ Examples:
+ - - '{{ div 6 3 }}'
+ - '2'
+ Floor:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Floor returns the greatest integer value less than or equal to n.
+ Examples:
+ - - '{{ math.Floor 1.9 }}'
+ - '1'
+ Log:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Log returns the natural logarithm of the number n.
+ Examples:
+ - - '{{ math.Log 1 }}'
+ - '0'
+ Max:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Max returns the greater of all numbers in inputs. Any slices in inputs are flattened.
+ Examples:
+ - - '{{ math.Max 1 2 }}'
+ - '2'
+ MaxInt64:
+ Aliases: null
+ Args: null
+ Description: MaxInt64 returns the maximum value for a signed 64-bit integer.
+ Examples:
+ - - '{{ math.MaxInt64 }}'
+ - '9223372036854775807'
+ Min:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Min returns the smaller of all numbers in inputs. Any slices in inputs are flattened.
+ Examples:
+ - - '{{ math.Min 1 2 }}'
+ - '1'
+ Mod:
+ Aliases:
+ - mod
+ Args:
+ - n1
+ - n2
+ Description: Mod returns n1 % n2.
+ Examples:
+ - - '{{ mod 15 3 }}'
+ - '0'
+ ModBool:
+ Aliases:
+ - modBool
+ Args:
+ - n1
+ - n2
+ Description: ModBool returns the boolean of n1 % n2. If n1 % n2 == 0, return true.
+ Examples:
+ - - '{{ modBool 15 3 }}'
+ - 'true'
+ Mul:
+ Aliases:
+ - mul
+ Args:
+ - inputs
+ Description: Mul multiplies the multivalued numbers n1 and n2 or more values.
+ Examples:
+ - - '{{ mul 2 3 }}'
+ - '6'
+ Pi:
+ Aliases: null
+ Args: null
+ Description: Pi returns the mathematical constant pi.
+ Examples:
+ - - '{{ math.Pi }}'
+ - '3.141592653589793'
+ Pow:
+ Aliases:
+ - pow
+ Args:
+ - n1
+ - n2
+ Description: Pow returns n1 raised to the power of n2.
+ Examples:
+ - - '{{ math.Pow 2 3 }}'
+ - '8'
+ Product:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Product returns the product of all numbers in inputs. Any slices in inputs are flattened.
+ Examples: []
+ Rand:
+ Aliases: null
+ Args: null
+ Description: Rand returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0).
+ Examples:
+ - - '{{ math.Rand }}'
+ - '0.6312770459590062'
+ Round:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Round returns the integer nearest to n, rounding half away from zero.
+ Examples:
+ - - '{{ math.Round 1.5 }}'
+ - '2'
+ Sin:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Sin returns the sine of the radian argument n.
+ Examples:
+ - - '{{ math.Sin 1 }}'
+ - '0.8414709848078965'
+ Sqrt:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Sqrt returns the square root of the number n.
+ Examples:
+ - - '{{ math.Sqrt 81 }}'
+ - '9'
+ Sub:
+ Aliases:
+ - sub
+ Args:
+ - inputs
+ Description: Sub subtracts multivalued.
+ Examples:
+ - - '{{ sub 3 2 }}'
+ - '1'
+ Sum:
+ Aliases: null
+ Args:
+ - inputs
+ Description: Sum returns the sum of all numbers in inputs. Any slices in inputs are flattened.
+ Examples: []
+ Tan:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: Tan returns the tangent of the radian argument n.
+ Examples:
+ - - '{{ math.Tan 1 }}'
+ - '1.557407724654902'
+ ToDegrees:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: ToDegrees converts radians into degrees.
+ Examples:
+ - - '{{ math.ToDegrees 1.5707963267948966 }}'
+ - '90'
+ ToRadians:
+ Aliases: null
+ Args:
+ - 'n'
+ Description: ToRadians converts degrees into radians.
+ Examples:
+ - - '{{ math.ToRadians 90 }}'
+ - '1.5707963267948966'
+ openapi3:
+ Unmarshal:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: []
+ os:
+ FileExists:
+ Aliases:
+ - fileExists
+ Args:
+ - i
+ Description: FileExists checks whether a file exists under the given path.
+ Examples:
+ - - '{{ fileExists "foo.txt" }}'
+ - 'false'
+ Getenv:
+ Aliases:
+ - getenv
+ Args:
+ - key
+ Description: |-
+ Getenv retrieves the value of the environment variable named by the key.
+ It returns the value, which will be empty if the variable is not present.
+ Examples: []
+ ReadDir:
+ Aliases:
+ - readDir
+ Args:
+ - i
+ Description: ReadDir lists the directory contents relative to the configured WorkingDir.
+ Examples:
+ - - '{{ range (readDir "files") }}{{ .Name }}{{ end }}'
+ - README.txt
+ ReadFile:
+ Aliases:
+ - readFile
+ Args:
+ - i
+ Description: |-
+ ReadFile reads the file named by filename relative to the configured WorkingDir.
+ It returns the contents as a string.
+ There is an upper size limit set at 1 megabytes.
+ Examples:
+ - - '{{ readFile "files/README.txt" }}'
+ - Hugo Rocks!
+ Stat:
+ Aliases: null
+ Args:
+ - i
+ Description: Stat returns the os.FileInfo structure describing file.
+ Examples: []
+ partials:
+ Include:
+ Aliases:
+ - partial
+ Args:
+ - ctx
+ - name
+ - contextList
+ Description: |-
+ Include executes the named partial.
+ If the partial contains a return statement, that value will be returned.
+ Else, the rendered output will be returned:
+ A string if the partial is a text/template, or template.HTML when html/template.
+ Note that ctx is provided by Hugo, not the end user.
+ Examples:
+ - - '{{ partial "header.html" . }}'
+ - <title>Hugo Rocks!</title>
+ IncludeCached:
+ Aliases:
+ - partialCached
+ Args:
+ - ctx
+ - name
+ - context
+ - variants
+ Description: |-
+ IncludeCached executes and caches partial templates. The cache is created with name+variants as the key.
+ Note that ctx is provided by Hugo, not the end user.
+ Examples: []
+ path:
+ Base:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Base returns the last element of path.
+ Trailing slashes are removed before extracting the last element.
+ If the path is empty, Base returns ".".
+ If the path consists entirely of slashes, Base returns "/".
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ Examples: []
+ BaseName:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ BaseName returns the last element of path, removing the extension if present.
+ Trailing slashes are removed before extracting the last element.
+ If the path is empty, Base returns ".".
+ If the path consists entirely of slashes, Base returns "/".
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ Examples: []
+ Clean:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Clean replaces the separators used with standard slashes and then
+ extraneous slashes are removed.
+ Examples: []
+ Dir:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Dir returns all but the last element of path, typically the path's directory.
+ After dropping the final element using Split, the path is Cleaned and trailing
+ slashes are removed.
+ If the path is empty, Dir returns ".".
+ If the path consists entirely of slashes followed by non-slash bytes, Dir
+ returns a single slash. In any other case, the returned path does not end in a
+ slash.
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ Examples: []
+ Ext:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Ext returns the file name extension used by path.
+ The extension is the suffix beginning at the final dot
+ in the final slash-separated element of path;
+ it is empty if there is no dot.
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ Examples: []
+ Join:
+ Aliases: null
+ Args:
+ - elements
+ Description: |-
+ Join joins any number of path elements into a single path, adding a
+ separating slash if necessary. All the input
+ path elements are passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ The result is Cleaned; in particular,
+ all empty strings are ignored.
+ Examples:
+ - - '{{ slice "my/path" "filename.txt" | path.Join }}'
+ - my/path/filename.txt
+ - - '{{ path.Join "my" "path" "filename.txt" }}'
+ - my/path/filename.txt
+ - - '{{ "my/path/filename.txt" | path.Ext }}'
+ - .txt
+ - - '{{ "my/path/filename.txt" | path.Base }}'
+ - filename.txt
+ - - '{{ "my/path/filename.txt" | path.Dir }}'
+ - my/path
+ Split:
+ Aliases: null
+ Args:
+ - path
+ Description: |-
+ Split splits path immediately following the final slash,
+ separating it into a directory and file name component.
+ If there is no slash in path, Split returns an empty dir and
+ file set to path.
+ The input path is passed into filepath.ToSlash converting any Windows slashes
+ to forward slashes.
+ The returned values have the property that path = dir+file.
+ Examples:
+ - - '{{ "/my/path/filename.txt" | path.Split }}'
+ - /my/path/|filename.txt
+ - - '{{ "/my/path/filename.txt" | path.Split }}'
+ - /my/path/|filename.txt
+ reflect:
+ IsImageResource:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsImageResourceProcessable:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsImageResourceWithMeta:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsMap:
+ Aliases: null
+ Args:
+ - v
+ Description: IsMap reports whether v is a map.
+ Examples:
+ - - '{{ if reflect.IsMap (dict "a" 1) }}Map{{ end }}'
+ - Map
+ IsPage:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsResource:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsSite:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsSlice:
+ Aliases: null
+ Args:
+ - v
+ Description: IsSlice reports whether v is a slice.
+ Examples:
+ - - '{{ if reflect.IsSlice (slice 1 2 3) }}Slice{{ end }}'
+ - Slice
+ resources:
+ ByType:
+ Aliases: null
+ Args:
+ - typ
+ Description: ByType returns resources of a given resource type (e.g. "image").
+ Examples: []
+ Concat:
+ Aliases: null
+ Args:
+ - targetPathIn
+ - r
+ Description: |-
+ Concat concatenates a slice of Resource objects. These resources must
+ (currently) be of the same Media Type.
+ Examples: []
+ Copy:
+ Aliases: null
+ Args:
+ - s
+ - r
+ Description: Copy copies r to the new targetPath in s.
+ Examples: []
+ ExecuteAsTemplate:
+ Aliases: null
+ Args:
+ - ctx
+ - args
+ Description: |-
+ ExecuteAsTemplate creates a Resource from a Go template, parsed and executed with
+ the given data, and published to the relative target path.
+ Examples: []
+ Fingerprint:
+ Aliases:
+ - fingerprint
+ Args:
+ - args
+ Description: |-
+ Fingerprint transforms the given Resource with a MD5 hash of the content in
+ the RelPermalink and Permalink.
+ Examples: []
+ FromString:
+ Aliases: null
+ Args:
+ - targetPathIn
+ - contentIn
+ Description: FromString creates a Resource from a string published to the relative target path.
+ Examples: []
+ Get:
+ Aliases: null
+ Args:
+ - filename
+ Description: |-
+ Get locates the filename given in Hugo's assets filesystem
+ and creates a Resource object that can be used for further transformations.
+ Examples: []
+ GetMatch:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ GetRemote:
+ Aliases: null
+ Args:
+ - args
+ Description: 'GetRemote gets the URL (via HTTP(s)) in the first argument in args and creates Resource object that can be used for\nfurther transformations.\n\nA second argument may be provided with an option map.\n\nNote: This method does not return any error as a second return value,\nfor any error situations the error can be checked in .Err.'
+ Examples: []
+ Match:
+ Aliases: null
+ Args:
+ - pattern
+ Description: |-
+ Match gets all resources matching the given base path prefix, e.g
+ "*.png" will match all png files. The "*" does not match path delimiters (/),
+ so if you organize your resources in sub-folders, you need to be explicit about it, e.g.:
+ "images/*.png". To match any PNG image anywhere in the bundle you can do "**.png", and
+ to match all PNG images below the images folder, use "images/**.jpg".
-
++
+ The matching is case insensitive.
-
++
+ Match matches by using the files name with path relative to the file system root
+ with Unix style slashes (/) and no leading slash, e.g. "images/logo.png".
-
++
+ See https://github.com/gobwas/glob for the full rules set.
-
++
+ It looks for files in the assets file system.
-
++
+ See Match for a more complete explanation about the rules used.
+ Examples: []
+ Minify:
+ Aliases:
+ - minify
+ Args:
+ - r
+ Description: |-
+ Minify minifies the given Resource using the MediaType to pick the correct
+ minifier.
+ Examples: []
+ PostProcess:
+ Aliases: null
+ Args:
+ - r
+ Description: PostProcess processes r after the build.
+ Examples: []
+ safe:
+ CSS:
+ Aliases:
+ - safeCSS
+ Args:
+ - s
+ Description: CSS returns the string s as html/template CSS content.
+ Examples:
+ - - '{{ "Bat&Man" | safeCSS | safeCSS }}'
+ - Bat&Man
+ HTML:
+ Aliases:
+ - safeHTML
+ Args:
+ - s
+ Description: HTML returns the string s as html/template HTML content.
+ Examples:
+ - - '{{ "Bat&Man" | safeHTML | safeHTML }}'
+ - Bat&Man
+ - - '{{ "Bat&Man" | safeHTML }}'
+ - Bat&Man
+ HTMLAttr:
+ Aliases:
+ - safeHTMLAttr
+ Args:
+ - s
+ Description: HTMLAttr returns the string s as html/template HTMLAttr content.
+ Examples: []
+ JS:
+ Aliases:
+ - safeJS
+ Args:
+ - s
+ Description: JS returns the given string as a html/template JS content.
+ Examples:
+ - - '{{ "(1*2)" | safeJS | safeJS }}'
+ - (1*2)
+ JSStr:
+ Aliases:
+ - safeJSStr
+ Args:
+ - s
+ Description: JSStr returns the given string as a html/template JSStr content.
+ Examples: []
+ URL:
+ Aliases:
+ - safeURL
+ Args:
+ - s
+ Description: URL returns the string s as html/template URL content.
+ Examples:
+ - - '{{ "http://gohugo.io" | safeURL | safeURL }}'
+ - http://gohugo.io
+ site:
+ AllPages:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ BaseURL:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ BuildDrafts:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ CheckReady:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Config:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Copyright:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Current:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Data:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Dimension:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ ForEeachIdentityByName:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ GetPage:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Home:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Hugo:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsDefault:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Key:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Language:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ LanguageCode:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ LanguagePrefix:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Languages:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Lastmod:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ MainSections:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Menus:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Pages:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Param:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Params:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ RegularPages:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Role:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Sections:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ ServerPort:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Sites:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Store:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ String:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Taxonomies:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Title:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ Version:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ strings:
+ Chomp:
+ Aliases:
+ - chomp
+ Args:
+ - s
+ Description: Chomp returns a copy of s with all trailing newline characters removed.
+ Examples:
+ - - '{{ chomp "<p>Blockhead</p>\n" | safeHTML }}'
+ - <p>Blockhead</p>
+ Contains:
+ Aliases: null
+ Args:
+ - s
+ - substr
+ Description: Contains reports whether substr is in s.
+ Examples:
+ - - '{{ strings.Contains "abc" "b" }}'
+ - 'true'
+ - - '{{ strings.Contains "abc" "d" }}'
+ - 'false'
+ ContainsAny:
+ Aliases: null
+ Args:
+ - s
+ - chars
+ Description: ContainsAny reports whether any Unicode code points in chars are within s.
+ Examples:
+ - - '{{ strings.ContainsAny "abc" "bcd" }}'
+ - 'true'
+ - - '{{ strings.ContainsAny "abc" "def" }}'
+ - 'false'
+ ContainsNonSpace:
+ Aliases: null
+ Args:
+ - s
+ Description: 'ContainsNonSpace reports whether s contains any non-space characters as defined\nby Unicode''s White Space property,\n<docsmeta>{"newIn": "0.111.0" }</docsmeta>'
+ Examples: []
+ Count:
+ Aliases: null
+ Args:
+ - substr
+ - s
+ Description: |-
+ Count counts the number of non-overlapping instances of substr in s.
+ If substr is an empty string, Count returns 1 + the number of Unicode code points in s.
+ Examples:
+ - - '{{ "aabab" | strings.Count "a" }}'
+ - '3'
+ CountRunes:
+ Aliases:
+ - countrunes
+ Args:
+ - s
+ Description: CountRunes returns the number of runes in s, excluding whitespace.
+ Examples: []
+ CountWords:
+ Aliases:
+ - countwords
+ Args:
+ - s
+ Description: CountWords returns the approximate word count in s.
+ Examples: []
+ Diff:
+ Aliases: null
+ Args:
+ - oldname
+ - old
+ - newname
+ - new
+ Description: |-
+ Diff returns an anchored diff of the two texts old and new in the “unified
+ diff” format. If old and new are identical, Diff returns an empty string.
+ Examples: []
+ FindRE:
+ Aliases:
+ - findRE
+ Args:
+ - expr
+ - content
+ - limit
+ Description: |-
+ FindRE returns a list of strings that match the regular expression. By default all matches
+ will be included. The number of matches can be limited with an optional third parameter.
+ Examples:
+ - - '{{ findRE "[G|g]o" "Hugo is a static side generator written in Go." 1 }}'
+ - '[go]'
+ FindRESubmatch:
+ Aliases:
+ - findRESubmatch
+ Args:
+ - expr
+ - content
+ - limit
+ Description: |-
+ FindRESubmatch returns a slice of all successive matches of the regular
+ expression in content. Each element is a slice of strings holding the text
+ of the leftmost match of the regular expression and the matches, if any, of
+ its subexpressions.
-
++
+ By default all matches will be included. The number of matches can be
+ limited with the optional limit parameter. A return value of nil indicates
+ no match.
+ Examples:
+ - - '{{ findRESubmatch `<a\s*href="(.+?)">(.+?)</a>` `<li><a href="#foo">Foo</a></li> <li><a href="#bar">Bar</a></li>` | print | safeHTML }}'
+ - '[[<a href="#foo">Foo</a> #foo Foo] [<a href="#bar">Bar</a> #bar Bar]]'
+ FirstUpper:
+ Aliases: null
+ Args:
+ - s
+ Description: FirstUpper converts s making the first character upper case.
+ Examples:
+ - - '{{ "hugo rocks!" | strings.FirstUpper }}'
+ - Hugo rocks!
+ HasPrefix:
+ Aliases:
+ - hasPrefix
+ Args:
+ - s
+ - prefix
+ Description: HasPrefix tests whether the input s begins with prefix.
+ Examples:
+ - - '{{ hasPrefix "Hugo" "Hu" }}'
+ - 'true'
+ - - '{{ hasPrefix "Hugo" "Fu" }}'
+ - 'false'
+ HasSuffix:
+ Aliases:
+ - hasSuffix
+ Args:
+ - s
+ - suffix
+ Description: HasSuffix tests whether the input s begins with suffix.
+ Examples:
+ - - '{{ hasSuffix "Hugo" "go" }}'
+ - 'true'
+ - - '{{ hasSuffix "Hugo" "du" }}'
+ - 'false'
+ Repeat:
+ Aliases: null
+ Args:
+ - 'n'
+ - s
+ Description: Repeat returns a new string consisting of n copies of the string s.
+ Examples:
+ - - '{{ "yo" | strings.Repeat 4 }}'
+ - yoyoyoyo
+ Replace:
+ Aliases:
+ - replace
+ Args:
+ - s
+ - old
+ - new
+ - limit
+ Description: |-
+ Replace returns a copy of the string s with all occurrences of old replaced
+ with new. The number of replacements can be limited with an optional fourth
+ parameter.
+ Examples:
+ - - '{{ replace "Batman and Robin" "Robin" "Catwoman" }}'
+ - Batman and Catwoman
+ - - '{{ replace "aabbaabb" "a" "z" 2 }}'
+ - zzbbaabb
++ ReplacePairs:
++ Aliases: null
++ Args:
++ - args
++ Description: |-
++ ReplacePairs returns a copy of a string with multiple replacements performed
++ in a single pass. The last argument is the source string. Preceding arguments
++ are old/new string pairs, either as a slice or as individual arguments.
++ Examples:
++ - - '{{ "aab" | strings.ReplacePairs "a" "b" "b" "c" }}'
++ - bbc
++ - - '{{ "aab" | strings.ReplacePairs (slice "a" "b" "b" "c") }}'
++ - bbc
+ ReplaceRE:
+ Aliases:
+ - replaceRE
+ Args:
+ - pattern
+ - repl
+ - s
+ - 'n'
+ Description: |-
+ ReplaceRE returns a copy of s, replacing all matches of the regular
+ expression pattern with the replacement text repl. The number of replacements
+ can be limited with an optional fourth parameter.
+ Examples:
+ - - '{{ replaceRE "a+b" "X" "aabbaabbab" }}'
+ - XbXbX
+ - - '{{ replaceRE "a+b" "X" "aabbaabbab" 1 }}'
+ - Xbaabbab
+ RuneCount:
+ Aliases: null
+ Args:
+ - s
+ Description: RuneCount returns the number of runes in s.
+ Examples: []
+ SliceString:
+ Aliases:
+ - slicestr
+ Args:
+ - a
+ - startEnd
+ Description: |-
+ SliceString slices a string by specifying a half-open range with
+ two indices, start and end. 1 and 4 creates a slice including elements 1 through 3.
+ The end index can be omitted, it defaults to the string's length.
+ Examples:
+ - - '{{ slicestr "BatMan" 0 3 }}'
+ - Bat
+ - - '{{ slicestr "BatMan" 3 }}'
+ - Man
+ Split:
+ Aliases:
+ - split
+ Args:
+ - a
+ - delimiter
+ Description: Split slices an input string into all substrings separated by delimiter.
+ Examples: []
+ Substr:
+ Aliases:
+ - substr
+ Args:
+ - a
+ - nums
+ Description: 'Substr extracts parts of a string, beginning at the character at the specified\nposition, and returns the specified number of characters.\n\nIt normally takes two parameters: start and length.\nIt can also take one parameter: start, i.e. length is omitted, in which case\nthe substring starting from start until the end of the string will be returned.\n\nTo extract characters from the end of the string, use a negative start number.\n\nIn addition, borrowing from the extended behavior described at http://php.net/substr,\nif length is given and is negative, then that many characters will be omitted from\nthe end of string.'
+ Examples:
+ - - '{{ substr "BatMan" 0 -3 }}'
+ - Bat
+ - - '{{ substr "BatMan" 3 3 }}'
+ - Man
+ Title:
+ Aliases:
+ - title
+ Args:
+ - s
+ Description: |-
+ Title returns a copy of the input s with all Unicode letters that begin words
+ mapped to their title case.
+ Examples:
+ - - '{{ title "Bat man" }}'
+ - Bat Man
+ - - '{{ title "somewhere over the rainbow" }}'
+ - Somewhere Over the Rainbow
+ ToLower:
+ Aliases:
+ - lower
+ Args:
+ - s
+ Description: |-
+ ToLower returns a copy of the input s with all Unicode letters mapped to their
+ lower case.
+ Examples:
+ - - '{{ lower "BatMan" }}'
+ - batman
+ ToUpper:
+ Aliases:
+ - upper
+ Args:
+ - s
+ Description: |-
+ ToUpper returns a copy of the input s with all Unicode letters mapped to their
+ upper case.
+ Examples:
+ - - '{{ upper "BatMan" }}'
+ - BATMAN
+ Trim:
+ Aliases:
+ - trim
+ Args:
+ - s
+ - cutset
+ Description: |-
+ Trim returns converts the strings s removing all leading and trailing characters defined
+ contained.
+ Examples:
+ - - '{{ trim "++Batman--" "+-" }}'
+ - Batman
+ TrimLeft:
+ Aliases: null
+ Args:
+ - cutset
+ - s
+ Description: |-
+ TrimLeft returns a slice of the string s with all leading characters
+ contained in cutset removed.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimLeft "a" }}'
+ - bbaa
+ TrimPrefix:
+ Aliases: null
+ Args:
+ - prefix
+ - s
+ Description: |-
+ TrimPrefix returns s without the provided leading prefix string. If s doesn't
+ start with prefix, s is returned unchanged.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimPrefix "a" }}'
+ - abbaa
+ - - '{{ "aabbaa" | strings.TrimPrefix "aa" }}'
+ - bbaa
+ TrimRight:
+ Aliases: null
+ Args:
+ - cutset
+ - s
+ Description: |-
+ TrimRight returns a slice of the string s with all trailing characters
+ contained in cutset removed.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimRight "a" }}'
+ - aabb
+ TrimSpace:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ TrimSpace returns the given string, removing leading and trailing whitespace
+ as defined by Unicode.
+ Examples: []
+ TrimSuffix:
+ Aliases: null
+ Args:
+ - suffix
+ - s
+ Description: |-
+ TrimSuffix returns s without the provided trailing suffix string. If s
+ doesn't end with suffix, s is returned unchanged.
+ Examples:
+ - - '{{ "aabbaa" | strings.TrimSuffix "a" }}'
+ - aabba
+ - - '{{ "aabbaa" | strings.TrimSuffix "aa" }}'
+ - aabb
+ Truncate:
+ Aliases:
+ - truncate
+ Args:
+ - s
+ - options
+ Description: Truncate truncates the string in s to the specified length.
+ Examples:
+ - - '{{ "this is a very long text" | truncate 10 " ..." }}'
+ - this is a ...
+ - - '{{ "With [Markdown](/markdown) inside." | markdownify | truncate 14 }}'
+ - With <a href="/markdown">Markdown …</a>
+ templates:
+ Current:
+ Aliases: null
+ Args:
+ - ctx
+ Description: Get information about the currently executing template.
+ Examples: []
+ Defer:
+ Aliases: null
+ Args:
+ - args
+ Description: Defer defers the execution of a template block.
+ Examples: []
+ DoDefer:
+ Aliases:
+ - doDefer
+ Args:
+ - ctx
+ - id
+ - optsv
+ Description: |-
+ DoDefer defers the execution of a template block.
+ For internal use only.
+ Examples: []
+ Exists:
+ Aliases: null
+ Args:
+ - name
+ Description: |-
+ Exists returns whether the template with the given name exists.
+ Note that this is the Unix-styled relative path including filename suffix,
+ e.g. partials/header.html
+ Examples:
+ - - '{{ if (templates.Exists "_partials/header.html") }}Yes!{{ end }}'
+ - Yes!
+ - - '{{ if not (templates.Exists "_partials/doesnotexist.html") }}No!{{ end }}'
+ - No!
+ Inner:
+ Aliases:
+ - inner
+ Args:
+ - ctx
+ - data
+ Description: |-
+ Inner executes the inner content of a partial decorator.
+ Note that there is only one inner block per partial decorator, but inner may be called multiple times with, typically, different data.
+ Examples: []
+ time:
+ AsTime:
+ Aliases: null
+ Args:
+ - v
+ - args
+ Description: |-
+ AsTime converts the textual representation of the datetime string into
+ a time.Time interface.
+ Examples:
+ - - '{{ (time "2015-01-21").Year }}'
+ - '2015'
+ Duration:
+ Aliases:
+ - duration
+ Args:
+ - unit
+ - number
+ Description: |-
+ Duration converts the given number to a time.Duration.
+ Unit is one of nanosecond/ns, microsecond/us/µs, millisecond/ms, second/s, minute/m or hour/h.
+ Examples:
+ - - '{{ mul 60 60 | duration "second" }}'
+ - 1h0m0s
+ Format:
+ Aliases:
+ - dateFormat
+ Args:
+ - layout
+ - v
+ Description: |-
+ Format converts the textual representation of the datetime string in v into
+ time.Time if needed and formats it with the given layout.
+ Examples:
+ - - 'dateFormat: {{ dateFormat "Monday, Jan 2, 2006" "2015-01-21" }}'
+ - 'dateFormat: Wednesday, Jan 21, 2015'
+ In:
+ Aliases: null
+ Args:
+ - timeZoneName
+ - t
+ Description: |-
+ In returns the time t in the IANA time zone specified by timeZoneName.
+ If timeZoneName is "" or "UTC", the time is returned in UTC.
+ If timeZoneName is "Local", the time is returned in the system's local time zone.
+ Otherwise, timeZoneName must be a valid IANA location name (e.g., "Europe/Oslo").
+ Examples: []
+ Now:
+ Aliases:
+ - now
+ Args: null
+ Description: Now returns the current local time or `clock` time
+ Examples: []
+ ParseDuration:
+ Aliases: null
+ Args:
+ - s
+ Description: 'ParseDuration parses the duration string s.\nA duration string is a possibly signed sequence of\ndecimal numbers, each with optional fraction and a unit suffix,\nsuch as "300ms", "-1.5h" or "2h45m".\nValid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".\nSee https://golang.org/pkg/time/#ParseDuration'
+ Examples:
+ - - '{{ "1h12m10s" | time.ParseDuration }}'
+ - 1h12m10s
+ transform:
+ CanHighlight:
+ Aliases: null
+ Args:
+ - language
+ Description: CanHighlight returns whether the given code language is supported by the Chroma highlighter.
+ Examples: []
+ Emojify:
+ Aliases:
+ - emojify
+ Args:
+ - s
+ Description: |-
+ Emojify returns a copy of s with all emoji codes replaced with actual emojis.
++
+ See http://www.emoji-cheat-sheet.com/
+ Examples:
+ - - '{{ "I :heart: Hugo" | emojify }}'
+ - I ❤️ Hugo
+ HTMLEscape:
+ Aliases:
+ - htmlEscape
+ Args:
+ - s
+ Description: HTMLEscape returns a copy of s with reserved HTML characters escaped.
+ Examples:
+ - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" }}'
+ - Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;
+ - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | htmlUnescape | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ HTMLToMarkdown:
+ Aliases: null
+ Args:
+ - ctx
+ - args
+ Description: |-
+ This was added in Hugo v0.151.0 and should be considered experimental for now.
+ We need to test this out in the wild for a while before committing to this API,
+ and there will eventually be more options here.
+ Examples: []
+ HTMLUnescape:
+ Aliases:
+ - htmlUnescape
+ Args:
+ - s
+ Description: |-
+ HTMLUnescape returns a copy of s with HTML escape requences converted to plain
+ text.
+ Examples:
+ - - '{{ htmlUnescape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ "Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;" | htmlUnescape | htmlUnescape | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ "Cathal Garvey &amp; The Sunshine Band &lt;cathal@foo.bar&gt;" | htmlUnescape | htmlUnescape }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ - - '{{ htmlUnescape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | htmlEscape | safeHTML }}'
+ - Cathal Garvey & The Sunshine Band <cathal@foo.bar>
+ Highlight:
+ Aliases:
+ - highlight
+ Args:
+ - s
+ - lang
+ - opts
+ Description: |-
+ Highlight returns a copy of s as an HTML string with syntax
+ highlighting applied.
+ Examples: []
+ HighlightCodeBlock:
+ Aliases: null
+ Args:
+ - ctx
+ - opts
+ Description: HighlightCodeBlock highlights a code block on the form received in the codeblock render hooks.
+ Examples: []
+ Markdownify:
+ Aliases:
+ - markdownify
+ Args:
+ - ctx
+ - s
+ Description: Markdownify renders s from Markdown to HTML.
+ Examples:
+ - - '{{ .Title | markdownify }}'
+ - <strong>BatMan</strong>
+ Plainify:
+ Aliases:
+ - plainify
+ Args:
+ - s
+ Description: Plainify returns a copy of s with all HTML tags removed.
+ Examples:
+ - - '{{ plainify "Hello <strong>world</strong>, gophers!" }}'
+ - Hello world, gophers!
+ PortableText:
+ Aliases: null
+ Args:
+ - v
+ Description: |-
+ PortableText converts the portable text in v to Markdown.
+ We may add more options in the future.
+ Examples: []
+ Remarshal:
+ Aliases: null
+ Args:
+ - format
+ - data
+ Description: |-
+ Remarshal is used in the Hugo documentation to convert configuration
+ examples from YAML to JSON, TOML (and possibly the other way around).
+ The is primarily a helper for the Hugo docs site.
+ It is not a general purpose YAML to TOML converter etc., and may
+ change without notice if it serves a purpose in the docs.
+ Format is one of json, yaml or toml.
+ Examples:
+ - - '{{ "title = \"Hello World\"" | transform.Remarshal "json" | safeHTML }}'
+ - '{\n "title": "Hello World"\n}\n'
+ ToMath:
+ Aliases: null
+ Args:
+ - ctx
+ - args
+ Description: |-
+ ToMath converts a LaTeX string to math in the given format, default MathML.
+ This uses KaTeX to render the math, see https://katex.org/.
+ Examples: []
+ Unmarshal:
+ Aliases:
+ - unmarshal
+ Args:
+ - args
+ Description: |-
+ Unmarshal unmarshals the data given, which can be either a string, json.RawMessage
+ or a Resource. Supported formats are JSON, TOML, YAML, and CSV.
+ You can optionally provide an options map as the first argument.
+ Examples:
+ - - '{{ "hello = \"Hello World\"" | transform.Unmarshal }}'
+ - map[hello:Hello World]
+ - - '{{ "hello = \"Hello World\"" | resources.FromString "data/greetings.toml" | transform.Unmarshal }}'
+ - map[hello:Hello World]
+ XMLEscape:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ XMLEscape returns the given string, removing disallowed characters then
+ escaping the result to its XML equivalent.
+ Examples:
+ - - '{{ transform.XMLEscape "<p>abc</p>" }}'
+ - '<p>abc</p>'
+ urls:
+ AbsLangURL:
+ Aliases:
+ - absLangURL
+ Args:
+ - s
+ Description: |-
+ AbsLangURL the string s and converts it to an absolute URL according
+ to a page's position in the project directory structure and the current
+ language.
+ Examples: []
+ AbsURL:
+ Aliases:
+ - absURL
+ Args:
+ - s
+ Description: AbsURL takes the string s and converts it to an absolute URL.
+ Examples: []
+ Anchorize:
+ Aliases:
+ - anchorize
+ Args:
+ - s
+ Description: |-
+ Anchorize creates sanitized anchor name version of the string s that is compatible
+ with how your configured markdown renderer does it.
+ Examples:
+ - - '{{ "This is a title" | anchorize }}'
+ - this-is-a-title
+ JoinPath:
+ Aliases: null
+ Args:
+ - elements
+ Description: |-
+ JoinPath joins the provided elements into a URL string and cleans the result
+ of any ./ or ../ elements. If the argument list is empty, JoinPath returns
+ an empty string.
+ Examples:
+ - - '{{ urls.JoinPath "https://example.org" "foo" }}'
+ - https://example.org/foo
+ - - '{{ urls.JoinPath (slice "a" "b") }}'
+ - a/b
+ Parse:
+ Aliases: null
+ Args:
+ - rawurl
+ Description: |-
+ Parse parses rawurl into a URL structure. The rawurl may be relative or
+ absolute.
+ Examples: []
+ PathEscape:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ PathEscape returns the given string, applying percent-encoding to special
+ characters and reserved delimiters so it can be safely used as a segment
+ within a URL path.
+ Examples: []
+ PathUnescape:
+ Aliases: null
+ Args:
+ - s
+ Description: |-
+ PathUnescape returns the given string, replacing all percent-encoded
+ sequences with the corresponding unescaped characters.
+ Examples: []
+ Ref:
+ Aliases:
+ - ref
+ Args:
+ - p
+ - args
+ Description: Ref returns the absolute URL path to a given content item from Page p.
+ Examples: []
+ RelLangURL:
+ Aliases:
+ - relLangURL
+ Args:
+ - s
+ Description: |-
+ RelLangURL takes the string s and prepends the relative path according to a
+ page's position in the project directory structure and the current language.
+ Examples: []
+ RelRef:
+ Aliases:
+ - relref
+ Args:
+ - p
+ - args
+ Description: RelRef returns the relative URL path to a given content item from Page p.
+ Examples: []
+ RelURL:
+ Aliases:
+ - relURL
+ Args:
+ - s
+ Description: |-
+ RelURL takes the string s and prepends the relative path according to a
+ page's position in the project directory structure.
+ Examples: []
+ URLize:
+ Aliases:
+ - urlize
+ Args:
+ - s
+ Description: URLize returns the strings s formatted as an URL.
+ Examples: []
--- /dev/null
- # Do not delete. Required for layouts/_shortcodes/list-pages-in-section.html.
++# Do not delete. This file defines filters that can be applied to lists of
++# pages when rendering. The filters are defined as lists of page paths. A
++# filter can be applied to a list of pages by specifying the filter name and
++# filter type (include or exclude). Used by:
+#
- # When calling the list-pages-in-section shortcode, you can specify a page
- # filter, and whether the pages in the filter should be included or excluded
- # from the list.
- #
- # For example:
- #
- # {{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
++# - layouts/_shortcodes/render-list-of-pages-in-section.html
++# - layouts/_shortcodes/render-table-of-pages-in-section.html
+
+functions_fmt_logging:
+ - /functions/fmt/errorf
+ - /functions/fmt/erroridf
+ - /functions/fmt/warnf
+ - /functions/fmt/warnidf
+functions_images_no_filters:
+ - /functions/images/filter
+ - /functions/images/config
+methods_site_multilingual:
+ - /methods/site/ismultilingual
+ - /methods/site/language
+ - /methods/site/languageprefix
+ - /methods/site/languages
+methods_site_page_collections:
+ - /methods/site/allpages
+ - /methods/site/pages
+ - /methods/site/regularpages
+ - /methods/site/sections
+methods_page_dates:
+ - /methods/page/date
+ - /methods/page/expirydate
+ - /methods/page/lastmod
+ - /methods/page/publishdate
+methods_page_menu:
+ - /methods/page/hasmenucurrent
+ - /methods/page/ismenucurrent
+methods_page_multilingual:
+ - /methods/page/alltranslations
+ - /methods/page/istranslated
+ - /methods/page/language
+ - /methods/page/translationkey
+ - /methods/page/translations
+methods_page_page_collections:
+ - /methods/page/pages
+ - /methods/page/regularpages
+ - /methods/page/regularpagesrecursive
+ - /methods/page/sections
+methods_page_parameters:
+ - /methods/page/param
+ - /methods/page/params
+methods_page_sections:
+ - /methods/page/ancestors
+ - /methods/page/currentsection
+ - /methods/page/firstsection
+ - /methods/page/insection
+ - /methods/page/isancestor
+ - /methods/page/isdescendant
+ - /methods/page/parent
+ - /methods/page/sections
+ - /methods/page/section
+methods_pages_sort:
+ - /methods/pages/bydate
+ - /methods/pages/byexpirydate
+ - /methods/pages/bylanguage
+ - /methods/pages/bylastmod
+ - /methods/pages/bylength
+ - /methods/pages/bylinktitle
+ - /methods/pages/byparam
+ - /methods/pages/bypublishdate
+ - /methods/pages/bytitle
+ - /methods/pages/byweight
+ - /methods/pages/reverse
+methods_pages_group:
+ - /methods/pages/groupby
+ - /methods/pages/groupbydate
+ - /methods/pages/groupbyexpirydate
+ - /methods/pages/groupbylastmod
+ - /methods/pages/groupbyparam
+ - /methods/pages/groupbyparamdate
+ - /methods/pages/groupbypublishdate
+methods_pages_navigation:
+ - /methods/pages/next
+ - /methods/pages/prev
+methods_page_navigation:
+ - /methods/page/next
+ - /methods/page/nextinsection
+ - /methods/page/prev
+ - /methods/page/previnsection
++methods_resource_image_processing:
++ - /methods/resource/crop
++ - /methods/resource/fill
++ - /methods/resource/filter
++ - /methods/resource/fit
++ - /methods/resource/fit
++ - /methods/resource/resize
--- /dev/null
- languageCode = "en-US"
- languageName = "English"
- weight = 1
+baseURL = "https://gohugo.io/"
+defaultContentLanguage = "en"
+enableEmoji = true
+pluralizeListTitles = false
+timeZone = "Europe/Oslo"
+title = "Hugo"
+
+# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
+disableAliases = true
+
+[build]
+ [build.buildStats]
+ disableIDs = true
+ enable = true
+ [[build.cachebusters]]
+ source = "assets/notwatching/hugo_stats\\.json"
+ target = "css"
+ [[build.cachebusters]]
+ source = "(postcss|tailwind)\\.config\\.js"
+ target = "css"
+
+[caches]
+ [caches.images]
+ dir = ":cacheDir/images"
+ maxAge = "1440h"
+ [caches.getresource]
+ dir = ':cacheDir/:project'
+ maxAge = "1h"
+
+[[cascade]]
+ [cascade.params]
+ hide_in_this_section = true
+ show_publish_date = true
+ [cascade.target]
+ kind = 'page'
+ path = '{/news/**}'
+[[cascade]]
+ [cascade.params]
+ searchable = true
+ [cascade.target]
+ kind = 'page'
+[[cascade]]
+ [cascade.params]
+ searchable = false
+ [cascade.target]
+ kind = '{home,section,taxonomy,term}'
+
+[frontmatter]
+ date = ['date'] # do not add publishdate; it will affect page sorting
+ expiryDate = ['expirydate']
+ lastmod = [':git', 'lastmod', 'publishdate', 'date']
+ publishDate = ['publishdate', 'date']
+
+[languages]
+ [languages.en]
- autoDefinitionTermID = true
++ direction = 'ltr'
++ label = 'English'
++ locale = 'en-US'
++ weight = 1
+
+[markup]
+ [markup.goldmark]
+ [markup.goldmark.extensions]
+ [markup.goldmark.extensions.passthrough]
+ enable = true
+ [markup.goldmark.extensions.passthrough.delimiters]
+ block = [['\[', '\]'], ['$$', '$$']]
+ inline = [['\(', '\)']]
+ [markup.goldmark.parser]
- ######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES ########
++ autoDefinitionTermID = true
+ wrapStandAloneImageWithinParagraph = false
+ [markup.goldmark.parser.attribute]
+ block = true
+ [markup.highlight]
+ lineNumbersInTable = false
+ noClasses = false
+ style = 'solarized-dark'
+ wrapperClass = 'highlight not-prose'
+
+[mediaTypes]
+ [mediaTypes."text/netlify"]
+ delimiter = ""
+
+[module]
+ [module.hugoVersion]
+ min = "0.144.0"
+ [[module.mounts]]
+ source = "assets"
+ target = "assets"
+ [[module.mounts]]
+ source = 'content/en'
+ target = 'content'
+ [module.mounts.sites.matrix]
+ languages = ['en']
+ [[module.mounts]]
+ disableWatch = true
+ source = "hugo_stats.json"
+ target = "assets/notwatching/hugo_stats.json"
+
+[outputFormats]
+ [outputFormats.redir]
+ baseName = "_redirects"
+ isPlainText = true
+ mediatype = "text/netlify"
+ [outputFormats.headers]
+ baseName = "_headers"
+ isPlainText = true
+ mediatype = "text/netlify"
+ notAlternative = true
+
+[outputs]
+ home = ["html", "rss", "redir", "headers"]
+ page = ["html"]
+ section = ["html"]
+ taxonomy = ["html"]
+ term = ["html"]
+
+[params]
+ description = "The world’s fastest framework for building websites"
+ ghrepo = "https://github.com/gohugoio/hugoDocs/"
+ [params.render_hooks.link]
+ errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+ [params.social.mastodon]
+ url = "https://fosstodon.org/@gohugoio"
+
+[related]
+ includeNewer = true
+ threshold = 80
+ toLower = true
+ [[related.indices]]
+ name = 'keywords'
+ weight = 1
+
+[security]
+ [security.funcs]
+ getenv = ['^HUGO_', '^REPOSITORY_URL$', '^BRANCH$']
+
+[server]
+ [[server.headers]]
+ for = "/*"
+ [server.headers.values]
+ X-Frame-Options = "DENY"
+ X-XSS-Protection = "1; mode=block"
+ X-Content-Type-Options = "nosniff"
+ Referrer-Policy = "no-referrer"
+ [[server.headers]]
+ for = "/**.{css,js}"
+
+[services]
+ [services.googleAnalytics]
+ ID = 'G-MBZGKNMDWC'
+
+[taxonomies]
+ category = 'categories'
+
++ ######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES ########
+
+[menus]
+ [[menus.global]]
+ identifier = 'news'
+ name = 'News'
+ pageRef = '/news/'
+ weight = 1
+ [[menus.global]]
+ identifier = 'docs'
+ name = 'Docs'
+ url = '/documentation/'
+ weight = 5
+ [[menus.global]]
+ identifier = 'themes'
+ name = 'Themes'
+ url = 'https://themes.gohugo.io/'
+ weight = 10
+ [[menus.global]]
+ identifier = 'community'
+ name = 'Community'
+ post = 'external'
+ url = 'https://discourse.gohugo.io/'
+ weight = 150
+ [[menus.global]]
+ identifier = 'github'
+ name = 'GitHub'
+ post = 'external'
+ url = 'https://github.com/gohugoio/hugo'
+ weight = 200
--- /dev/null
- "ci/cd" "cicd"
+{{/* prettier-ignore-start */ -}}
+{{- /* Last modified: 2025-01-19T14:44:56-08:00 */}}
+
+{{- /*
+Copyright 2025 Veriphor LLC
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License. You may obtain a copy of
+the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations under
+the License.
+*/}}
+
+{{- /*
+This render hook resolves internal destinations by looking for a matching:
+
+ 1. Content page
+ 2. Page resource (a file in the current page bundle)
+ 3. Section resource (a file in the current section)
+ 4. Global resource (a file in the assets directory)
+
+It skips the section resource lookup if the current page is a leaf bundle.
+
+External destinations are not modified.
+
+You must place global resources in the assets directory. If you have placed
+your resources in the static directory, and you are unable or unwilling to move
+them, you must mount the static directory to the assets directory by including
+both of these entries in your site configuration:
+
+ [[module.mounts]]
+ source = 'assets'
+ target = 'assets'
+
+ [[module.mounts]]
+ source = 'static'
+ target = 'assets'
+
+By default, if this render hook is unable to resolve a destination, including a
+fragment if present, it passes the destination through without modification. To
+emit a warning or error, set the error level in your site configuration:
+
+ [params.render_hooks.link]
+ errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+
+When you set the error level to warning, and you are in a development
+environment, you can visually highlight broken internal links:
+
+ [params.render_hooks.link]
+ errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+ highlightBroken = true # true or false (default)
+
+This will add a "broken" class to anchor elements with invalid src attributes.
+Add a rule to your CSS targeting the broken links:
+
+ a.broken {
+ background: #ff0;
+ border: 2px solid #f00;
+ padding: 0.1em 0.2em;
+ }
+
+This render hook may be unable to resolve destinations created with the ref and
+relref shortcodes. Unless you set the error level to ignore you should not use
+either of these shortcodes in conjunction with this render hook.
+
+@context {string} Destination The link destination.
+@context {page} Page A reference to the page containing the link.
+@context {string} PlainText The link description as plain text.
+@context {string} Text The link description.
+@context {string} Title The link title.
+
+@returns {template.html}
+*/ -}}
+{{/* prettier-ignore-end */ -}}
+{{- /* Initialize. */}}
+{{- $renderHookName := "link" }}
+
+{{- /* Verify minimum required version. */}}
+{{- $minHugoVersion := "0.141.0" }}
+{{- if lt hugo.Version $minHugoVersion }}
+ {{- errorf "The %q render hook requires Hugo v%s or later." $renderHookName $minHugoVersion }}
+{{- end }}
+
+{{- /* Error level when unable to resolve destination: ignore, warning, or error. */}}
+{{- $errorLevel := or site.Params.render_hooks.link.errorLevel "ignore" | lower }}
+
+{{- /* If true, adds "broken" class to broken links. Applicable in development environment when errorLevel is warning. */}}
+{{- $highlightBrokenLinks := or site.Params.render_hooks.link.highlightBroken false }}
+
+{{- /* Validate error level. */}}
+{{- if not (in (slice "ignore" "warning" "error") $errorLevel) }}
+ {{- errorf "The %q render hook is misconfigured. The errorLevel %q is invalid. Please check your site configuration." $renderHookName $errorLevel }}
+{{- end }}
+
+{{- /* Determine content path for warning and error messages. */}}
+{{- $contentPath := .Page.String }}
+
+{{- /* Parse destination. */}}
+{{- $u := urls.Parse .Destination }}
+
+{{- /* Set common message. */}}
+{{- $msg := printf "The %q render hook was unable to resolve the destination %q in %s" $renderHookName $u.String $contentPath }}
+
+{{- /* Set attributes for anchor element. */}}
+{{- $attrs := dict "href" $u.String }}
+{{- if eq $u.String "g" }}
+ {{- /* Destination is a glossary term. */}}
+ {{- $ctx := dict
+ "contentPath" $contentPath
+ "errorLevel" $errorLevel
+ "renderHookName" $renderHookName
+ "text" .Text
+ }}
+ {{- $attrs = partial "inline/h-rh-l/get-glossary-link-attributes.html" $ctx }}
+{{- else if $u.IsAbs }}
+ {{- /* Destination is a remote resource. */}}
+ {{- $attrs = merge $attrs (dict "rel" "external") }}
+{{- else }}
+ {{- with $u.Path }}
+ {{- with $p := or ($.PageInner.GetPage .) ($.PageInner.GetPage (strings.TrimRight "/" .)) }}
+ {{- /* Destination is a page. */}}
+ {{- $href := .RelPermalink }}
+ {{- with $u.RawQuery }}
+ {{- $href = printf "%s?%s" $href . }}
+ {{- end }}
+ {{- with $u.Fragment }}
+ {{- $ctx := dict
+ "contentPath" $contentPath
+ "errorLevel" $errorLevel
+ "page" $p
+ "parsedURL" $u
+ "renderHookName" $renderHookName
+ }}
+ {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
+ {{- $href = printf "%s#%s" $href . }}
+ {{- end }}
+ {{- $attrs = dict "href" $href }}
+ {{- else with $.PageInner.Resources.Get $u.Path }}
+ {{- /* Destination is a page resource; drop query and fragment. */}}
+ {{- $attrs = dict "href" .RelPermalink }}
+ {{- else with (and (ne $.Page.BundleType "leaf") ($.Page.CurrentSection.Resources.Get $u.Path)) }}
+ {{- /* Destination is a section resource, and current page is not a leaf bundle. */}}
+ {{- $attrs = dict "href" .RelPermalink }}
+ {{- else with resources.Get $u.Path }}
+ {{- /* Destination is a global resource; drop query and fragment. */}}
+ {{- $attrs = dict "href" .RelPermalink }}
+ {{- else }}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- if and $highlightBrokenLinks hugo.IsDevelopment }}
+ {{- $attrs = merge $attrs (dict "class" "broken") }}
+ {{- end }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- else }}
+ {{- with $u.Fragment }}
+ {{- /* Destination is on the same page; prepend relative permalink. */}}
+ {{- $ctx := dict
+ "contentPath" $contentPath
+ "errorLevel" $errorLevel
+ "page" $.Page
+ "parsedURL" $u
+ "renderHookName" $renderHookName
+ }}
+ {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
+ {{- $attrs = dict "href" (printf "%s#%s" $.Page.RelPermalink .) }}
+ {{- else }}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- if and $highlightBrokenLinks hugo.IsDevelopment }}
+ {{- $attrs = merge $attrs (dict "class" "broken") }}
+ {{- end }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+{{- end }}
+
+{{- /* Render anchor element. */ -}}
+<a
+ {{- with .Title }}title="{{ . }}"{{- end }}
+ {{- range $k, $v := $attrs }}
+ {{- if $v }}
+ {{- printf " %s=%q" $k ($v | transform.HTMLEscape) | safeHTMLAttr }}
+ {{- end }}
+ {{- end -}}
+ >{{ .Text }}</a
+>
+
+{{- define "_partials/inline/h-rh-l/validate-fragment.html" }}
+ {{- /*
+ Validates the fragment portion of a link destination.
+
+ @context {string} contentPath The page containing the link.
+ @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error.
+ @context {page} page The page corresponding to the link destination
+ @context {struct} parsedURL The link destination parsed by urls.Parse.
+ @context {string} renderHookName The name of the render hook.
+ */}}
+
+ {{- /* Initialize. */}}
+ {{- $contentPath := .contentPath }}
+ {{- $errorLevel := .errorLevel }}
+ {{- $p := .page }}
+ {{- $u := .parsedURL }}
+ {{- $renderHookName := .renderHookName }}
+
+ {{- /* Validate. */}}
+ {{- with $u.Fragment }}
+ {{- if $p.Fragments.Identifiers.Contains . }}
+ {{- if gt ($p.Fragments.Identifiers.Count .) 1 }}
+ {{- $msg := printf "The %q render hook detected duplicate heading IDs %q in %s" $renderHookName . $contentPath }}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- else }}
+ {{- /* Determine target path for warning and error message. */}}
+ {{- $targetPath := "" }}
+ {{- with $p.File }}
+ {{- $targetPath = .Path }}
+ {{- else }}
+ {{- $targetPath = .Path }}
+ {{- end }}
+ {{- /* Set common message. */}}
+ {{- $msg := printf "The %q render hook was unable to find heading ID %q in %s. See %s" $renderHookName . $targetPath $contentPath }}
+ {{- if eq $targetPath $contentPath }}
+ {{- $msg = printf "The %q render hook was unable to find heading ID %q in %s" $renderHookName . $targetPath }}
+ {{- end }}
+ {{- /* Throw warning or error. */}}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+{{- end }}
+
+{{- define "_partials/inline/h-rh-l/get-glossary-link-attributes.html" }}
+ {{- /*
+ Returns the anchor element attributes for a link to the given glossary term.
+
+ It first checks for the existence of a glossary page for the given term. If
+ no page is found, it then checks for a glossary page for the singular form of
+ the term. If neither page exists it throws a warning or error dependent on
+ the errorLevel setting
+
+ The returned href attribute does not point to the glossary term page.
+ Instead, via its fragment, it points to an entry on the glossary page.
+
+ @context {string} contentPath The page containing the link.
+ @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error.
+ @context {string} renderHookName The name of the render hook.
+ @context {string} text The link text.
+ */}}
+
+ {{- /* Get context.. */}}
+ {{- $contentPath := .contentPath }}
+ {{- $errorLevel := .errorLevel }}
+ {{- $renderHookName := .renderHookName }}
+ {{- $text := .text | transform.Plainify | strings.ToLower }}
+
+ {{- /* Initialize. */}}
+ {{- $glossaryPath := "/quick-reference/glossary" }}
+ {{- $termGiven := $text }}
+ {{- $termActual := "" }}
+ {{- $termSingular := inflect.Singularize $termGiven }}
+
+ {{- /* Verify that the glossary page exists. */}}
+ {{- $glossaryPage := site.GetPage $glossaryPath }}
+ {{- if not $glossaryPage }}
+ {{- errorf "The %q render hook was unable to find %s: see %s" $renderHookName $glossaryPath $contentPath }}
+ {{- end }}
+
+ {{- /* There's a better way to handle this, but it works for now. */}}
+ {{- $cheating := dict
+ "chaining" "chain"
++ "ci/cd" "cicd"
++ "interleaved" "interleave"
+ "localize" "localization"
+ "localized" "localization"
+ "paginating" "paginate"
+ "walking" "walk"
+ }}
+
+ {{- /* Verify that a glossary term page exists for the given term. */}}
+ {{- if site.GetPage (urls.JoinPath $glossaryPath ($termGiven | urlize)) }}
+ {{- $termActual = $termGiven }}
+ {{- else if site.GetPage (urls.JoinPath $glossaryPath ($termSingular | urlize)) }}
+ {{- $termActual = $termSingular }}
+ {{- else }}
+ {{- $termToTest := index $cheating $termGiven }}
+ {{- if site.GetPage (urls.JoinPath $glossaryPath ($termToTest | urlize)) }}
+ {{- $termActual = $termToTest }}
+ {{- end }}
+ {{- end }}
+
+ {{- if not $termActual }}
+ {{- errorf "The %q render hook was unable to find a glossary page for either the singular or plural form of the term %q: see %s" $renderHookName $termGiven $contentPath }}
+ {{- end }}
+
+ {{- /* Create the href attribute. */}}
+ {{- $href := "" }}
+ {{- if $termActual }}
+ {{- $href = fmt.Printf "%s#%s" $glossaryPage.RelPermalink (anchorize $termActual) }}
+ {{- end }}
+
+ {{- return (dict "href" $href) }}
+{{- end -}}
--- /dev/null
- class="border-l-4 overflow-x-auto border-{{ $color }}-400 bg-{{ $color }}-50 dark:bg-{{ $color }}-800 border-1 dark:border-{{ $color }}-700 p-4 {{ $class }}">
+{{- $title := .title | default "" }}
+{{- $color := .color | default "yellow" }}
+{{- $icon := .icon | default "exclamation-triangle" }}
+{{- $text := .text | default "" }}
+{{- $class := .class | default "mt-6 mb-8" }}
+<div
++ class="border-l-4 overflow-x-auto border-{{ $color }}-400 bg-{{ $color }}-50 dark:bg-{{ $color }}-800 border dark:border-{{ $color }}-700 p-4 {{ $class }}">
+ <div class="flex">
+ <div class="shrink-0">
+ <svg class="fill-{{ $color }}-500 dark:fill-{{ $color }}-400 h-7 w-7">
+ <use href="#icon--{{ $icon }}"></use>
+ </svg>
+ </div>
+ <div class="ml-3">
+ {{- with $title }}
+ <h3 class="text-{{ $color }}-800">
+ {{ . }}
+ </h3>
+ {{- end }}
+ <div class="mt-2">
+ {{ $text }}
+ </div>
+ </div>
+ </div>
+</div>
--- /dev/null
--- /dev/null
++{{/* prettier-ignore-start */ -}}
++{{- /*
++This must be used in conjunction with the "deprecated-in" and "new-in"
++shortcodes. The "deprecated-in" shortcode should be used to indicate when a
++feature was deprecated, and the "new-in" shortcode should be used to indicate
++when a feature was introduced. This template will render the appropriate
++admonition or badge based on the feature status and version information provided
++by the shortcodes.
++
++@param {string} inner The inner content of the shortcode, if any.
++@param {string} name The name of the shortcode.
++@param {string} page The page context in which the shortcode is used.
++@param {string} position The position of the shortcode in the source file.
++@param {string} status The feature status, either "deprecated" or "new".
++@param {string} version The version in which the feature was deprecated or introduced.
++
++@config {int} majorVersionDiffThreshold The major version difference before warning.
++@config {int} minorVersionDiffThresholdDeprecatedFeature Minor versions to wait before warning about a deprecated feature.
++@config {int} minorVersionDiffThresholdNewFeature Minor versions to wait before warning about a "new" feature.
++@config {slice} validStatusValues Allowed values for the status parameter.
++@config {string} classAnchorBase Base classes for the anchor element.
++@config {string} classSpanBase Base classes for the span/badge element.
++
++@example
++
++ {{- partial "layouts/blocks/feature-state.html" (dict
++ "inner" (strings.TrimSpace $.Inner)
++ "name" $.Name
++ "page" $.Page
++ "position" $.Position
++ "status" "deprecated"
++ "version" $version
++ )
++ }}
++
++*/ -}}
++{{/* prettier-ignore-end */ -}}
++
++{{- /* Configuration */ -}}
++{{- $majorVersionDiffThreshold := 0 }}
++{{- $minorVersionDiffThresholdDeprecatedFeature := 30 }}
++{{- $minorVersionDiffThresholdNewFeature := 30 }}
++{{- $validStatusValues := slice "deprecated" "new" }}
++{{- $classAnchorBase := "dark:text-black no-underline" }}
++{{- $classSpanBase := "not-prose inline-flex items-center px-2 mr-1 rounded text-sm font-medium" }}
++
++{{- /* Initialization */ -}}
++{{- $classAnchor := $classAnchorBase }}
++{{- $classSpan := $classSpanBase }}
++{{- $color := "" }}
++{{- $expiryMessage := "" }}
++{{- $icon := "" }}
++{{- $minorVersionDiffThreshold := 0 }}
++{{- $text := "" }}
++
++{{- if and $.name $.page $.position $.status $.version }}
++ {{- if in $validStatusValues $.status }}
++ {{- if eq $.status "deprecated" }}
++ {{- $classAnchor = printf "text-orange-800 hover:text-orange-600 %s" $classAnchor }}
++ {{- $classSpan = printf "bg-orange-200 dark:bg-orange-400 fill-orange-600 %s" $classSpan }}
++ {{- $color = "orange" }}
++ {{- $expiryMessage = "The deprecation period has ended. Remove this shortcode call and the associated content" }}
++ {{- $icon = "exclamation" }}
++ {{- $minorVersionDiffThreshold = $minorVersionDiffThresholdDeprecatedFeature }}
++ {{- $text = "Deprecated in" }}
++ {{- else if eq $.status "new" }}
++ {{- $classAnchor = printf "text-green-800 hover:text-green-600 %s" $classAnchor }}
++ {{- $classSpan = printf "bg-green-200 dark:bg-green-400 fill-green-600 %s" $classSpan }}
++ {{- $color = "green" }}
++ {{- $expiryMessage = "This feature is no longer new. Remove this shortcode call" }}
++ {{- $icon = "exclamation" }}
++ {{- $minorVersionDiffThreshold = $minorVersionDiffThresholdNewFeature }}
++ {{- $text = "New in" }}
++ {{- else }}
++ {{- errorf "BUG: The %q template does not support the %q feature status: see %s" templates.Current.Name $.status $.position }}
++ {{- end }}
++
++ {{- $hv := split hugo.Version "." }}
++ {{- $sv := split $.version "." }}
++ {{- $majorDiff := sub (index $hv 0 | int) (index $sv 0 | int) }}
++ {{- $minorDiff := sub (index $hv 1 | int) (index $sv 1 | int) }}
++
++ {{- if or (gt $majorDiff $majorVersionDiffThreshold) (gt $minorDiff $minorVersionDiffThreshold) }}
++ {{- warnf "%s: %s" $expiryMessage $.position }}
++ {{- end }}
++
++ {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $.version }}
++ {{- if $.inner }}
++ {{- $text = printf "%s [v%s](%s)\n\n%s" $text $.version $href $.inner | $.page.RenderString (dict "display" "block") }}
++ {{- partial "layouts/blocks/alert.html" (dict "color" $color "icon" $icon "text" $text) }}
++ {{- else }}
++ {{- $target := "_blank"}}
++ {{- printf "<span class=%q><a class=%q href=%q target=%q>%s v%s</a></span>" $classSpan $classAnchor $href $target $text $.version | safeHTML }}
++ {{- end }}
++ {{- else }}
++ {{- errorf "The %q template does not support the %q feature status: see %s" templates.Current.Name $.status $.position }}
++ {{- end }}
++{{- else }}
++ {{- errorf "The %q template requires the following context: name, page, position, status, version: see %s" templates.Current.Name $.position }}
++{{- end }}
--- /dev/null
- class="select-none flex-none text-sm px-2 content-center border-b-1 border-gray-300 dark:border-gray-700"
+{{/* prettier-ignore-start */ -}}
+{{- /*
+Renders syntax-highlighted configuration data in JSON, TOML, and YAML formats.
+
+@param {string} [config] The section of hugo.Data.docs.config to render.
+@param {bool} [copy=false] Whether to display a copy-to-clipboard button.
+@param {string} [dataKey] The section of hugo.Data.docs to render.
+@param {string} [file] The file name to display above the rendered code.
+@param {bool} [fm=false] Whether to render the code as front matter.
+@param {bool} [skipHeader=false] Whether to omit top level key(s) when rendering a section of hugo.Data.docs.config.
+
+@example {{< code-toggle file=hugo config=build />}}
+
+@example {{< code-toggle file=content/example.md fm="true" }}
+ title='Example'
+ draft='false
+ {{< /code-toggle }}
+*/ -}}
+{{/* prettier-ignore-end */ -}}
+{{- /* Initialize. */}}
+{{- $config := "" }}
+{{- $copy := false }}
+{{- $dataKey := "" }}
+{{- $file := "" }}
+{{- $fm := false }}
+{{- $skipHeader := false }}
+
+{{- /* Get parameters. */}}
+{{- $config = .Get "config" }}
+{{- $dataKey = .Get "dataKey" }}
+{{- $file = .Get "file" }}
+{{- if in (slice "false" false 0) (.Get "copy") }}
+ {{- $copy = false }}
+{{- else if in (slice "true" true 1) (.Get "copy") }}
+ {{- $copy = true }}
+{{- end }}
+{{- if in (slice "false" false 0) (.Get "fm") }}
+ {{- $fm = false }}
+{{- else if in (slice "true" true 1) (.Get "fm") }}
+ {{- $fm = true }}
+{{- end }}
+{{- if in (slice "false" false 0) (.Get "skipHeader") }}
+ {{- $skipHeader = false }}
+{{- else if in (slice "true" true 1) (.Get "skipHeader") }}
+ {{- $skipHeader = true }}
+{{- end }}
+
+{{- /* Define constants. */}}
+{{- $delimiters := dict "toml" "+++" "yaml" "---" }}
+{{- $langs := slice "yaml" "toml" "json" }}
+{{- $placeHolder := "#-hugo-placeholder-#" }}
+
+{{- /* Render. */}}
+{{- $code := "" }}
+{{- if $config }}
+ {{- $file = $file | default "hugo" }}
+ {{- $sections := (split $config ".") }}
+ {{- $configSection := index hugo.Data.docs.config $sections }}
+ {{- $code = dict $sections $configSection }}
+ {{- if $skipHeader }}
+ {{- $code = $configSection }}
+ {{- end }}
+{{- else if $dataKey }}
+ {{- $file = $file | default $dataKey }}
+ {{- $sections := (split $dataKey ".") }}
+ {{- $code = index hugo.Data.docs $sections }}
+{{- else }}
+ {{- $code = $.Inner }}
+{{- end }}
+
+
+<div x-data class="shortcode-code not-prose relative p-0 mt-6 mb-8">
+ {{- if $copy }}
+ <svg
+ class="absolute right-4 top-12 z-30 text-blue-600 hover:text-blue-500 cursor-pointer w-6 h-6"
+ @click="$copy($refs[$store.nav.userSettings.settings.configFileType])">
+ <use href="#icon--copy"></use>
+ </svg>
+ {{- end }}
+ <nav class="relative flex" aria-label="Tabs">
+ {{- with $file }}
+ <div
- class="px-3 py-2 font-semibold text-black dark:text-slate-200 border-l-1 border-t-1 {{ if $isLast }}
- border-r-1
++ class="select-none flex-none text-sm px-2 content-center border-b border-gray-300 dark:border-gray-700"
+ aria-label="Filename">
+ {{ . }}{{ if not $fm }}.{{ end }}
+ </div>
+ {{- end }}
+ {{- range $i, $lang := $langs }}
+ {{- $isLast := eq (add $i 1) (len $langs) }}
+ <button
+ x-on:click="$store.nav.userSettings.settings.configFileType = '{{ index $langs $i }}'"
+ aria-label="{{ printf `Toggle %s` . }}"
- :class="$store.nav.userSettings.settings.configFileType === '{{ index $langs $i }}' ? 'border-b-0 bg-light dark:bg-dark' : 'border-b-1'">
++ class="px-3 py-2 font-semibold text-black dark:text-slate-200 border-l border-t {{ if $isLast }}
++ border-r
+ {{ end }} border-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 dark:border-gray-700 cursor-pointer relative min-w-0 flex-1 overflow-hidden text-sm no-underline text-center focus:z-10 overflow-x-auto"
- class="max-h-96 overflow-y-auto border-l-1 border-b-1 border-r-1 border-gray-300 dark:border-gray-700"
++ :class="$store.nav.userSettings.settings.configFileType === '{{ index $langs $i }}' ? 'border-b-0 bg-light dark:bg-dark' : 'border-b'">
+ <span class="select-none">
+ {{ . }}
+ </span>
+ </button>
+ {{- end }}
+ </nav>
+ {{- if $code }}
+ {{- range $i, $lang := $langs }}
+ <div
++ class="max-h-96 overflow-y-auto border-l border-b border-r border-gray-300 dark:border-gray-700"
+ x-ref="{{ $lang }}"
+ x-cloak
+ x-transition:enter.opacity.duration.300ms
+ x-show="$store.nav.userSettings.settings.configFileType === '{{ index $langs $i }}'">
+ {{- $hCode := $code | transform.Remarshal . }}
+ {{- if and $fm (in (slice "toml" "yaml") .) }}
+ {{- $hCode = printf "%s\n%s\n%s" $placeHolder $hCode $placeHolder }}
+ {{- end }}
+ {{- $hCode = $hCode | replaceRE `\n+` "\n" }}
+ {{- highlight $hCode . "" | replaceRE $placeHolder (index $delimiters .) | safeHTML }}
+ </div>
+ {{- end }}
+ {{- end }}
+</div>
--- /dev/null
- Renders a callout indicating the version in which a feature was deprecated.
+{{/* prettier-ignore-start */ -}}
+{{- /*
- Include descriptive text between the opening and closing tags, or omit the
- descriptive text and call the shortcode with a self-closing tag.
++Renders an admonition or badge indicating the version in which a feature was deprecated.
+
- {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}
- {{- $inner := strings.TrimSpace $.Inner }}
- {{- $text := printf "Deprecated in [v%s](%s)\n\n%s" $version $href $inner | $.Page.RenderString (dict "display" "block") }}
- {{- partial "layouts/blocks/alert.html" (dict
- "color" "orange"
- "icon" "exclamation"
- "text" $text
++To render an admonition, include descriptive text between the opening and closing
++tags. To render a badge, omit the descriptive text and call the shortcode with a
++self-closing tag.
+
+@param {string} 0 The semantic version string, with or without a leading v.
+
+@example {{< deprecated-in 0.144.0 />}}
+
+@example {{< deprecated-in 0.144.0 >}}
+ Some descriptive text here.
+ {{< /deprecated-in >}}
+*/ -}}
+{{/* prettier-ignore-end */ -}}
+{{- with $version := .Get 0 | strings.TrimLeft "vV" }}
++ {{- partial "layouts/blocks/feature-state.html" (dict
++ "inner" (strings.TrimSpace $.Inner)
++ "name" $.Name
++ "page" $.Page
++ "position" $.Position
++ "status" "deprecated"
++ "version" $version
+ )
+ }}
+{{- else }}
+ {{- errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }}
+{{- end }}
--- /dev/null
--- /dev/null
++{{- /*
++Returns the Description of the page specified by the logical path in the first
++positional argument.
++
++@param {string} logicalPath The logical path to the page.
++
++@example {{% get-page-desc "/functions/reflect/isimageresource" %}}
++*/}}
++{{- with $logicalPath := .Get 0 }}
++ {{- with $.Page.GetPage $logicalPath }}
++{{- .Description }}{{/* Do not indent. */}}
++ {{- else }}
++ {{- errorf "The %q shortcode was unable to find %s: see %s" $.Name $logicalPath $.Position }}
++ {{- end }}
++{{- else }}
++ {{- errorf "The %q shortcode requires a positional argument with the logical path to the page: see %s" $.Name $logicalPath $.Position }}
++{{- end -}}
--- /dev/null
- Renders a callout or badge indicating the version in which a feature was added.
+{{/* prettier-ignore-start */ -}}
+{{- /*
- To render a callout, include descriptive text between the opening and closing
- tags. To render a badge,omit the descriptive text and call the shortcode with a
++Renders an admonition or badge indicating the version in which a feature was introduced.
+
- When comparing the current version to the specified version, the "new in"
- button will be hidden if any of the following conditions is true:
-
- - The major version difference exceeds the majorVersionDiffThreshold
- - The minor version difference exceeds the minorVersionDiffThreshold
-
++To render an admonition, include descriptive text between the opening and closing
++tags. To render a badge, omit the descriptive text and call the shortcode with a
+self-closing tag.
+
- @example {{< new-in 0.100.0 />}}
+@param {string} 0 The semantic version string, with or without a leading v.
+
- @example {{{< new-in 0.100.0 >}}
++@example {{< new-in 0.144.0 />}}
+
- {{- $majorVersionDiffThreshold := 0 }}
- {{- $minorVersionDiffThreshold := 30 }}
- {{- $displayExpirationWarning := true }}
-
++@example {{< new-in 0.144.0 >}}
+ Some descriptive text here.
+ {{< /new-in >}}
+*/ -}}
+{{/* prettier-ignore-end */ -}}
- {{- $majorVersionDiff := sub (index (split hugo.Version ".") 0 | int) (index (split $version ".") 0 | int) }}
- {{- $minorVersionDiff := sub (index (split hugo.Version ".") 1 | int) (index (split $version ".") 1 | int) }}
- {{- if or (gt $majorVersionDiff $majorVersionDiffThreshold) (gt $minorVersionDiff $minorVersionDiffThreshold) }}
- {{- if $displayExpirationWarning }}
- {{- warnf "This call to the %q shortcode should be removed: %s. The button is now hidden because the specified version (%s) is older than the display threshold." $.Name $.Position $version }}
- {{- end }}
- {{- else }}
- {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}
- {{- with $.Inner }}
- {{- $inner := strings.TrimSpace . }}
- {{- $text := printf "New in [v%s](%s)\n\n%s" $version $href $inner | $.Page.RenderString (dict "display" "block") }}
- {{ partial "layouts/blocks/alert.html" (dict
- "color" "green"
- "icon" "exclamation"
- "text" $text
- )
- }}
- {{- else }}
- <span
- class="not-prose inline-flex items-center px-2 mr-1 rounded text-sm font-medium bg-green-200 dark:bg-green-400 fill-green-600">
- <a
- class="text-green-800 dark:text-black hover:text-green-600 no-underline"
- href="{{ $href }}"
- target="_blank">
- New in
- v{{ $version }}
- </a>
- </span>
- {{- end }}
- {{- end }}
+{{- with $version := .Get 0 | strings.TrimLeft "vV" }}
++ {{- partial "layouts/blocks/feature-state.html" (dict
++ "inner" (strings.TrimSpace $.Inner)
++ "name" $.Name
++ "page" $.Page
++ "position" $.Position
++ "status" "new"
++ "version" $version
++ )
++ }}
+{{- else }}
+ {{- errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }}
+{{- end }}
--- /dev/null
- (dict "languageCode" "/configuration/all/#languagecode")
+{{/* prettier-ignore-start */ -}}
+{{- /*
+Renders a responsive grid of the configuration keys that can be defined
+separately for each language.
+*/ -}}
+{{/* prettier-ignore-end */ -}}
+{{- $siteConfigKeys := slice
+ (dict "baseURL" "/configuration/all/#baseurl")
+ (dict "buildDrafts" "/configuration/all/#builddrafts")
+ (dict "buildExpired" "/configuration/all/#buildexpired")
+ (dict "buildFuture" "/configuration/all/#buildfuture")
+ (dict "canonifyURLs" "/configuration/all/#canonifyurls")
+ (dict "capitalizeListTitles" "/configuration/all/#capitalizelisttitles")
+ (dict "contentDir" "/configuration/all/#contentdir")
+ (dict "copyright" "/configuration/all/#copyright")
+ (dict "disableAliases" "/configuration/all/#disablealiases")
+ (dict "disableHugoGeneratorInject" "/configuration/all/#disablehugogeneratorinject")
+ (dict "disableKinds" "/configuration/all/#disablekinds")
+ (dict "disableLiveReload" "/configuration/all/#disablelivereload")
+ (dict "disablePathToLower" "/configuration/all/#disablepathtolower")
+ (dict "enableEmoji " "/configuration/all/#enableemoji")
+ (dict "frontmatter" "/configuration/front-matter/")
+ (dict "hasCJKLanguage" "/configuration/all/#hascjklanguage")
++ (dict "locale" "/configuration/all/#locale")
+ (dict "mainSections" "/configuration/all/#mainsections")
+ (dict "markup" "/configuration/markup/")
+ (dict "mediaTypes" "/configuration/media-types/")
+ (dict "menus" "/configuration/menus/")
+ (dict "outputFormats" "/configuration/output-formats")
+ (dict "outputs" "/configuration/outputs/")
+ (dict "page" "/configuration/page/")
+ (dict "pagination" "/configuration/pagination/")
+ (dict "params" "/configuration/params/")
+ (dict "permalinks" "/configuration/permalinks/")
+ (dict "pluralizeListTitles" "/configuration/all/#pluralizelisttitles")
+ (dict "privacy" "/configuration/privacy/")
+ (dict "refLinksErrorLevel" "/configuration/all/#reflinkserrorlevel")
+ (dict "refLinksNotFoundURL" "/configuration/all/#reflinksnotfoundurl")
+ (dict "related" "/configuration/related-content/")
+ (dict "relativeURLs" "/configuration/all/#relativeurls")
+ (dict "removePathAccents" "/configuration/all/#removepathaccents")
+ (dict "renderSegments" "/configuration/all/#rendersegments")
+ (dict "sectionPagesMenu" "/configuration/all/#sectionpagesmenu")
+ (dict "security" "/configuration/security/")
+ (dict "services" "/configuration/services/")
+ (dict "sitemap" "/configuration/sitemap/")
+ (dict "staticDir" "/configuration/all/#staticdir")
+ (dict "summaryLength" "/configuration/all/#summarylength")
+ (dict "taxonomies" "/configuration/taxonomies/")
+ (dict "timeZone" "/configuration/all/#timezone")
+ (dict "title" "/configuration/all/#title")
+ (dict "titleCaseStyle" "/configuration/all/#titlecasestyle")
+}}
+
+{{- $a := len $siteConfigKeys }}
+{{- $b := math.Ceil (div $a 2.) }}
+{{- $c := math.Ceil (div $a 3.) }}
+
+
+<div
+ class="grid grid-flow-col grid-rows-{{ $a }} sm:grid-rows-{{ $b }} md:grid-rows-{{ $c }} gap-1">
+ {{- range $siteConfigKeys }}
+ {{ range $k, $v := . }}
+ {{ $u := urls.Parse $v }}
+ {{ if not (site.GetPage $u.Path) }}
+ {{ errorf "The %q shorcode was unable to find %s. See %s." $.Name $u.Path $.Position }}
+ {{ end }}
+ <a href="{{ $v | relLangURL }}"><code>{{ $k }}</code></a>
+ {{ end }}
+ {{- end }}
+</div>
--- /dev/null
--- /dev/null
++{{- /*
++Renders a description list of the pages in the given section.
++
++Render a subset of the pages in the section by specifying a predefined filter,
++and whether to include those pages.
++
++Filters are defined in the data directory, in the file named page_filters. Each
++filter is an array of paths to a file, relative to the root of the content
++directory. Hugo will throw an error if the specified filter does not exist, or
++if any of the pages in the filter do not exist.
++
++@param {string} path The path to the section.
++@param {string} [filter=""] The name of filter list.
++@param {string} [filterType=""] The type of filter, either include or exclude.
++@param {string} [titlePrefix=""] The string to prepend to the link title.
++
++@example {{% render-list-of-pages-in-section path=/methods/resource %}}
++@example {{% render-list-of-pages-in-section path=/functions/images filter=some_filter filterType=exclude %}}
++@example {{% render-list-of-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo %}}
++*/}}
++
++{{- /* Initialize. */}}
++{{- $filter := or "" (.Get "filter" | lower) }}
++{{- $filterType := or (.Get "filterType") "none" | lower }}
++{{- $filteredPages := slice }}
++{{- $titlePrefix := or (.Get "titlePrefix") "" }}
++
++{{- /* Build slice of filtered pages. */}}
++{{- with $filter }}
++ {{- with index hugo.Data.page_filters . }}
++ {{- range . }}
++ {{- with site.GetPage . }}
++ {{- $filteredPages = $filteredPages | append . }}
++ {{- else }}
++ {{- errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }}
++ {{- end }}
++ {{- end }}
++ {{- else }}
++ {{- errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }}
++ {{- end }}
++{{- end }}
++
++{{- /* Render. */}}
++{{- with $sectionPath := .Get "path" }}
++ {{- with site.GetPage . }}
++ {{- with .RegularPages }}
++ {{- range $page := .ByTitle }}
++ {{- if or
++ (and (eq $filterType "include") (in $filteredPages $page))
++ (and (eq $filterType "exclude") (not (in $filteredPages $page)))
++ (eq $filterType "none")
++ }}
++ {{- $linkTitle := .LinkTitle }}
++ {{- with $titlePrefix }}
++ {{- $linkTitle = printf "%s%s" . $linkTitle }}
++ {{- end }}
++{{- /* Use page Path as the link destination for render hook to resolve correctly. */}}
++[{{ $linkTitle }}]({{ $page.Path }}){{/* Do not indent. */}}
++: {{ $page.Description }}{{/* Do not indent. */}}
++ {{ end }}
++ {{- end }}
++ {{- else }}
++ {{- warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }}
++ {{- end }}
++ {{- else }}
++ {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }}
++ {{- end }}
++{{- else }}
++ {{- errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }}
++{{- end }}
--- /dev/null
--- /dev/null
++{{- /*
++Renders a table of the pages in the given section.
++
++Render a subset of the pages in the section by specifying a predefined filter,
++and whether to include those pages.
++
++Filters are defined in the data directory, in the file named page_filters. Each
++filter is an array of paths to a file, relative to the root of the content
++directory. Hugo will throw an error if the specified filter does not exist, or
++if any of the pages in the filter do not exist.
++
++@param {string} path The path to the section.
++@param {string} [filter=""] The name of filter list.
++@param {string} [filterType=""] The type of filter, either include or exclude.
++@param {string} [titlePrefix=""] The string to prepend to the link title.
++@param {string} [headingColumn1="Item"] The heading for the first column of the table.
++@param {string} [headingColumn2="Description"] The heading for the second column of the table.
++
++@example
++
++{{% render-table-of-pages-in-section
++ path=/methods/resource
++ filter=methods_resource_image_processing
++ filterType=include
++ headingColumn1=Method
++ headingColumn2=Description
++%}}
++
++*/}}
++
++{{- /* Initialize. */}}
++{{- $filter := or "" (.Get "filter" | lower) }}
++{{- $filterType := or (.Get "filterType") "none" | lower }}
++{{- $filteredPages := slice }}
++{{- $titlePrefix := or (.Get "titlePrefix") "" }}
++{{- $headingColumn1 := or (.Get "headingColumn1") "Item" }}
++{{- $headingColumn2 := or (.Get "headingColumn2") "Description" }}
++
++{{- /* Build slice of filtered pages. */}}
++{{- with $filter }}
++ {{- with index hugo.Data.page_filters . }}
++ {{- range . }}
++ {{- with site.GetPage . }}
++ {{- $filteredPages = $filteredPages | append . }}
++ {{- else }}
++ {{- errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }}
++ {{- end }}
++ {{- end }}
++ {{- else }}
++ {{- errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }}
++ {{- end }}
++{{- end }}
++
++{{- /* Render. */}}
++{{- with $sectionPath := .Get "path" }}
++ {{- with site.GetPage . }}
++ {{- with .RegularPages }}
++{{ $headingColumn1 }}|{{ $headingColumn2 }}{{/* Do not indent. */}}
++:--|:--{{/* Do not indent. */}}
++ {{- range $page := .ByTitle }}
++ {{- if or
++ (and (eq $filterType "include") (in $filteredPages $page))
++ (and (eq $filterType "exclude") (not (in $filteredPages $page)))
++ (eq $filterType "none")
++ }}
++ {{- $linkTitle := .LinkTitle }}
++ {{- with $titlePrefix }}
++ {{- $linkTitle = printf "%s%s" . $linkTitle }}
++ {{- end }}
++{{- /* Use page Path as the link destination for render hook to resolve correctly. */}}
++[`{{ $linkTitle }}`]({{ $page.Path }})|{{ $page.Description }}{{/* Do not indent. */}}
++ {{- end }}
++ {{- end }}
++ {{- else }}
++ {{- warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }}
++ {{- end }}
++ {{- else }}
++ {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }}
++ {{- end }}
++{{- else }}
++ {{- errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }}
++{{- end }}
--- /dev/null
- lang="{{ or site.Language.LanguageCode `en-US` }}">
+<!doctype html>
+<html
+ class="h-full antialiased scheme-light dark:scheme-dark"
++ lang="{{ site.Language.Locale }}">
+ <head>
+ <meta charset="utf-8">
+ <title>
+ {{ .Title }}
+ </title>
+ <style>
+ [x-cloak] {
+ display: none !important;
+ }
+ </style>
+
+ {{ partial "layouts/head/head-js.html" . }}
+ {{ with (templates.Defer (dict "key" "global")) }}
+ {{ $t := debug.Timer "tailwindcss" }}
+ {{ with resources.Get "css/styles.css" }}
+ {{ $opts := dict "minify" (not hugo.IsDevelopment) }}
+ {{ with . | css.TailwindCSS $opts }}
+ {{ partial "helpers/linkcss.html" (dict "r" .) }}
+ {{ end }}
+ {{ end }}
+ {{ $t.Stop }}
+ {{ end }}
+ {{ $noop := .WordCount }}
+ {{ if .Page.Store.Get "hasMath" }}
+ <link
+ rel="stylesheet"
+ href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
+ integrity="sha384-WcoG4HRXMzYzfCgiyfrySxx90XSl2rxY5mnVY5TwtWE6KLrArNKn0T/mOgNL0Mmi"
+ crossorigin="anonymous"
+ >
+ {{ end }}
+ {{ partial "layouts/head/head.html" . }}
+ </head>
+
+ {{ $bodyClass := printf "flex flex-col min-h-full bg-white dark:bg-blue-950 kind-%s" .Kind }}
+ {{ if .Params.searchable }}
+ {{ $bodyClass = printf "%s searchable" $bodyClass }}
+ {{ end }}
+
+ <body class="{{ $bodyClass }}">
+ {{ partial "layouts/hooks/body-start.html" . }}
+ {{/* Layout. */}}
+ {{ block "header" . }}
+ {{ partial "layouts/header/header.html" . }}
+ {{ end }}
+ {{ block "subheader" . }}
+ {{ end }}
+ {{ block "hero" . }}
+ {{ end }}
+ <div class="flex w-full xl:w-6xl h-full flex-auto mx-auto">
+ <main
+ class="flex-1 mx-auto lg:mx-0 w-full max-w-3x lg:max-w-3x pt-8 lg:pt-14 pb-20 px-main print:pt-0">
+ {{ partial "layouts/hooks/body-main-start.html" . }}
+ {{ block "main" . }}{{ end }}
+ </main>
+ {{ block "rightsidebar" . }}
+ <aside
+ class="py-15 ml-4 xl:ml-12 w-60 hidden lg:relative lg:block lg:flex-none">
+ {{ block "rightsidebar_content" . }}{{ end }}
+ </aside>
+ {{ end }}
+ </div>
+ {{/* Common icons. */}}
+ {{ partial "layouts/icons.html" . }}
+ {{/* Common templates. */}}
+ {{ partial "layouts/templates.html" . }}
+ {{/* Footer. */}}
+ {{ block "footer" . }}
+ {{ partial "layouts/footer.html" . }}
+ {{ end }}
+ {{ partial "layouts/hooks/body-end.html" . }}
+ </body>
+</html>
--- /dev/null
- <language>{{ or site.Language.LanguageCode site.Language.Lang }}</language>
+{{- printf "<?xml version=\"1.0\" encoding=\"utf-8\" standalone=\"yes\"?>" | safeHTML }}
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+ <channel>
+ <title>Hugo News</title>
+ <description>Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility.</description>
+ <link>{{ .Permalink }}</link>
+ <generator>Hugo {{ hugo.Version }}</generator>
++ <language>{{ site.Language.Locale }}</language>
+ {{- with site.Copyright }}
+ <copyright>{{ . }}</copyright>
+ {{- end }}
+ {{- with .OutputFormats.Get "rss" }}
+ {{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
+ {{- end }}
+ {{- $limit := cond (gt site.Config.Services.RSS.Limit 0) site.Config.Services.RSS.Limit 999 }}
+ {{- $pages := "" }}
+ {{- with site.GetPage "/news" }}
+ {{- $pages = .Pages.ByPublishDate.Reverse | first $limit }}
+ {{- else }}
+ {{- errorf "The list.rss.xml layout was unable to find the 'news' page." }}
+ {{- end }}
+ <lastBuildDate>{{ (index $pages 0).PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>
+ {{- range $pages }}
+ <item>
+ <title>{{ .Title }}</title>
+ <link>{{ or .Params.permalink .Permalink }}</link>
+ <pubDate>{{ .PublishDate.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
+ <guid>{{ or .Params.permalink .Permalink }}</guid>
+ <description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
+ </item>
+ {{- end }}
+ </channel>
+</rss>
--- /dev/null
- HUGO_VERSION = "0.156.0"
+[build]
+ publish = "public"
+ command = "npm ls && hugo --gc --minify"
+
+ [build.environment]
++ HUGO_VERSION = "0.158.0"
+
+[context.production.environment]
+ HUGO_ENV = "production"
+ HUGO_ENABLEGITINFO = "true"
+
+[context.split1]
+ command = "npm ls && hugo --gc --minify --enableGitInfo"
+
+ [context.split1.environment]
+ HUGO_ENV = "production"
+
+[context.deploy-preview]
+ command = "npm ls && hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL --enableGitInfo"
+
+[context.branch-deploy]
+ command = "npm ls && hugo --gc --minify -b $DEPLOY_PRIME_URL"
+
+[context.next.environment]
+ HUGO_ENABLEGITINFO = "true"
+
+[[headers]]
+ for = "/*.jpg"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
+
+[[headers]]
+ for = "/*.png"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
+
+[[headers]]
+ for = "/*.css"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
+
+[[headers]]
+ for = "/*.js"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
+
+[[headers]]
+ for = "/*.ttf"
+
+ [headers.values]
+ Cache-Control = "public, max-age=31536000"
projects / brevno-suite / hugo / commitdiff