[codespell]
# Comma separated list of dirs to be skipped.
-skip = *.ai,chroma.css,chroma_dark.css,.cspell.json
+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,januar,te,trys,ue,womens
"**/emojis.md",
"**/commands/*",
"**/showcase/*",
- "**/tools/*",
- "data/docs.yaml"
+ "**/tools/*"
],
"ignoreRegExpList": [
"# cspell: ignore fenced code blocks",
"dring",
"fleqn",
"inor",
+ "iptc",
"jausten",
"jdoe",
"jsmith",
steps:
- name: Checkout repository
- uses: actions/checkout@v5
+ uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
- name: Initialize CodeQL
uses: github/codeql-action/init@v3
runs-on: ubuntu-latest
steps:
- name: Checkout repository
- uses: actions/checkout@v5
+ uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
- name: Run Markdown linter
- uses: DavidAnson/markdownlint-cli2-action@v20
+ uses: DavidAnson/markdownlint-cli2-action@30a0e04f1870d58f8d717450cc6134995f993c63 # v21.0.0
with:
globs: # set to null to override default of *.{md,markdown}
continue-on-error: false
spellcheck:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v5
- - uses: streetsidesoftware/cspell-action@v7
+ - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+ - uses: streetsidesoftware/cspell-action@3294df585d3d639e30f3bc019cb11940b9866e95 # v8.0.0
with:
incremental_files_only: true
strict: true
# cspell uses the .cspell.json configuration file
- - uses: codespell-project/actions-codespell@v2
+ - uses: codespell-project/actions-codespell@8f01853be192eb0f849a5c7d721450e7a467c579 # v2.2
with:
check_filenames: true
check_hidden: true
pull-requests: write
runs-on: ubuntu-latest
steps:
- - uses: actions/stale@v9
+ - uses: actions/stale@5f858e3efba33a5ca4407a664cc011ad407f2008 # v10.1.0
with:
days-before-stale: 90 # default is 60
days-before-close: 14 # default is 7
.DS_Store
.hugo_build.lock
+.hvm
/.idea
/.vscode
/dist
url_inline: false
MD055:
style: consistent
- MD056: true
+ MD056: false # interferes with Markdown attributes
# MD057 deprecated
MD058: true
MD059:
- here
- link
- more
+ MD060:
+ aligned_delimiter: false
+ style: any
--- /dev/null
+## Theme
+
+### Role
+You are an expert front-end and Tailwind CSS developer. Your primary goal is to build reliable, readable, and scalable user interfaces using the existing project structure and design system.
+
+### Directives
+* **ALWAYS** use existing Tailwind utility classes for styling.
+* **NEVER** write raw CSS in `.css` files unless absolutely necessary for a non-utility-based global reset.
+* **NEVER** use inline styles (e.g., `<div style="...">`).
+
+### Project Knowledge
+
+* **Tech Stack:** Hugo (static site generator), AlpineJS, Tailwind CSS. Icons from https://heroicons.com/.
+* **Core Files and Directories:**
+ - `hugo.toml`: Hugo configuration file.
+ - `assets/css/styles.css`: Main CSS file with Tailwind directives.
+ - `assets/js/main.js`: Main JavaScript with AlpineJS configuration.
+ - `package.json`: Project dependencies and scripts.
+ - `content/`: Directory for markdown content files.
+ - `layouts/`: Directory for Hugo templates and partials.
+ - `layouts/_partials/icons.html`: SVG icon sprites.
+
+
+
+
--- /dev/null
+@AGENTS.md
\ No newline at end of file
npm i
hugo server
```
-
-**Note:** We're working on removing the need to run `npm i` for local development. Stay tuned.
/* Fonts. */
--font-sans:
- "Mulish", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji",
- "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+ "Mulish", -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans",
+ Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
+ "Segoe UI Symbol", "Noto Color Emoji";
}
html {
:not(pre) > code {
white-space: nowrap;
}
+
+/* Utility class for tables to prevent word wrapping in the first column. */
+.no-wrap-first-col td:first-child,
+.no-wrap-first-col th:first-child {
+ white-space: nowrap;
+}
atTop: true,
},
+ mobileMenu: {
+ open: false,
+ toggle() {
+ this.open = !this.open;
+ },
+ close() {
+ this.open = false;
+ },
+ },
+
userSettings: {
// settings gets persisted between page navigations.
settings: Alpine.$persist({
: (`bool`) Whether to include the content of the source files in the source map. By default, this is `true`.
JSX
-: {{< new-in 0.124.0 />}}
: (`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
-: {{< new-in 0.124.0 />}}
: (`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.:
_comment: Do not remove front matter.
---
-Hugo is available in three editions: standard, extended, and extended/deploy. While the standard edition provides core functionality, the extended and extended/deploy editions offer advanced features.
+## Editions
+
+Hugo offers a standard edition with core features, plus extended and extended/deploy editions with more. Use the standard edition unless you need the features below.
+
+<!-- TODO Remove the transpiler row somewhere around v0.166.0 -->
Feature|extended edition|extended/deploy edition
:--|:-:|:-:
-Encode to the WebP format when [processing images]. You can decode WebP images with any edition.|:heavy_check_mark:|:heavy_check_mark:
-[Transpile Sass to CSS] using the embedded LibSass transpiler. You can use the [Dart Sass] transpiler with any edition.|:heavy_check_mark:|:heavy_check_mark:
+[Transpile Sass to CSS] via embedded LibSass. Note that embedded LibSass was deprecated in v0.153.0 and will be removed in a future release. Use the [Dart Sass] transpiler instead, which is compatible with any edition.|:heavy_check_mark:|:heavy_check_mark:
Deploy your site directly to a Google Cloud Storage bucket, an AWS S3 bucket, or an Azure Storage container. See [details].|:x:|:heavy_check_mark:
[dart sass]: /functions/css/sass/#dart-sass
-[processing images]: /content-management/image-processing/
[transpile sass to css]: /functions/css/sass/
[details]: /host-and-deploy/deploy-with-hugo-deploy/
- Use the [Hugo Modules] feature
- Install a theme as a Git submodule
- Access [commit information] from a local Git repository
-- Host your site with services such as [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify]
+- Host your site on [CI/CD](g) platforms such as [Cloudflare][], [GitHub Pages][], [GitLab Pages][], [Netlify][], [Render][], or [Vercel][]
Go is required to:
- [Go][go install]
- [Dart Sass][dart sass install]
-[cloudcannon]: https://cloudcannon.com/
-[cloudflare pages]: https://pages.cloudflare.com/
+[Cloudflare]: /host-and-deploy/host-on-cloudflare/
[commit information]: /methods/page/GitInfo
[dart sass install]: /functions/css/sass/#dart-sass
[dart sass]: https://sass-lang.com/dart-sass
[git install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
[git]: https://git-scm.com/
-[github pages]: https://pages.github.com/
-[gitlab pages]: https://docs.gitlab.com/ee/user/project/pages/
+[GitHub Pages]: /host-and-deploy/host-on-github-pages/
+[GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/
[go install]: https://go.dev/doc/install
[go]: https://go.dev/
[hugo modules]: /hugo-modules/
-[netlify]: https://www.netlify.com/
+[Netlify]: /host-and-deploy/host-on-netlify/
+[Render]: /host-and-deploy/host-on-render/
+[Vercel]: /host-and-deploy/host-on-vercel/
--- /dev/null
+---
+_comment: Do not remove front matter.
+---
+
+To use this method you must first select a specific [output format](g) from a page's [`OutputFormats`][] collection using the [`Get`][] or [`Canonical`][] methods.
+
+[`Canonical`]: /methods/page/outputformats/#canonical
+[`Get`]: /methods/page/outputformats/#get
+[`OutputFormats`]: /methods/page/outputformats/
+++ /dev/null
----
-_comment: Do not remove front matter.
----
-
-### Get IDENTIFIER
-
-(`any`) Returns the `OutputFormat` object with the given identifier.
-
-### MediaType
-
-(`media.Type`) Returns the media type of the output format.
-
-### MediaType.MainType
-
-(`string`) Returns the main type of the output format's media type.
-
-### MediaType.SubType
-
-(`string`) Returns the subtype of the current format's media type.
-
-### Name
-
-(`string`) Returns the output identifier of the output format.
-
-### Permalink
-
-(`string`) Returns the permalink of the page generated by the current output format.
-
-### Rel
-
-(`string`) Returns the `rel` value of the output format, either the default or as defined in the site configuration.
-
-### RelPermalink
-
-(`string`) Returns the relative permalink of the page generated by the current output format.
_comment: Do not remove front matter.
---
-## Process specification
+## Processing specification
-The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence:
+The processing specification is a space-delimited, case-insensitive list containing one or more of the following options in any sequence:
action
-: Applicable to the [`Process`](/methods/resource/process) method only. Specify zero or one of `crop`, `fill`, `fit`, or `resize`. If you specify an action you must also provide dimensions.
-
-dimensions
-: Provide width _or_ height when using the [`Resize`](/methods/resource/resize) method, else provide both width _and_ height. See [details](/content-management/image-processing/#dimensions).
+: 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
-: Use with the [`Crop`](/methods/resource/crop) and [`Fill`](/methods/resource/fill) methods. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See [details](/content-management/image-processing/#anchor).
+: 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 site configuration.
-rotation
-: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation).
+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 site configuration.
-target format
-: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format).
+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 site configuration.
-quality
-: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See [details](/content-management/image-processing/#quality).
+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
-: Applicable to WebP images and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#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 site configuration.
-[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
+ 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
-background color
-: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See [details](/content-management/image-processing/#background-color).
+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 site configuration.
resampling filter
-: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See [details](/content-management/image-processing/#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 site 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 site configuration.
+
+[`anchor`]: /configuration/imaging/#anchor
+[`bgcolor`]: /configuration/imaging/#bgcolor
+[`compression`]: /configuration/imaging/#compression
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
+[`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
+[`smartcrop.js`]: https://github.com/jwagner/smartcrop.js
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[source documentation]: https://github.com/disintegration/imaging#image-resizing
## PageInner details
-{{< new-in 0.125.0 />}}
-
The primary use case for `PageInner` is to resolve links and [page resources](g) relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
```go-html-template {file="layouts/_shortcodes/include.html" copy=true}
## Content management
+[Multidimensional content model]
+: Generate pages across any combination of language, role, and version 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 site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
## Asset pipelines
[Image processing]
-: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data.
+: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract metadata.
[JavaScript bundling]
: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
[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/
: (`string`) The absolute URL of your published site including the protocol, host, path, and a trailing slash.
build
-: See [configure build](/configuration/build/).
+: See [configure build][].
buildDrafts
: (`bool`) Whether to include draft content when building a site. Default is `false`.
: (`string`) The designated cache directory. See [details](#cache-directory).
caches
-: See [configure file caches](/configuration/caches/).
+: See [configure file caches][].
canonifyURLs
: (`bool`) See [details](/content-management/urls/#canonical-urls) before enabling this feature. Default is `false`.
capitalizeListTitles
-: {{< new-in 0.123.3 />}}
-: (`bool`) Whether to capitalize automatic list titles. Applicable to section, taxonomy, and term pages. Default is `true`. Use the [`titleCaseStyle`](#titlecasestyle) setting to configure capitalization rules.
+: (`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](/configuration/cascade/).
+: See [configure cascade][].
cleanDestinationDir
-: (`bool`) Whether to remove files from the [`publishDir`](#publishdir) that do not exist in the [`staticDir`](#staticdir) when building the site. This setting will not take effect if the `staticDir` does not exist. Note that `.gitignore` and `.gitattributes` files, along with directories named `.git`, are always preserved in the `publishDir`. Default is `false`.
+: (`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 %}}
: (`string`) The designated directory for data files. Default is `data`. {{% module-mounts-note %}}
defaultContentLanguage
-: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined language keys. Default is `en`.
+: (`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 language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`.
+: (`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 content [role](g). Default is `guest`.
+
+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 content version. Default is `v1.0.0`.
+
+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](/configuration/deployment/).
+: See [configure deployment][].
disableAliases
-: (`bool`) Whether to disable generation of alias redirects. Even if this option is enabled, the defined aliases will still be present on the page. This allows you to manage redirects separately, for example, by generating 301 redirects in an `.htaccess` file or a Netlify `_redirects` file using a custom output format. Default is `false`.
+: (`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 to the default language when `DefaultContentLanguageInSubdir` is `true`. Default is `false`.
+: (`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. The default site is the site with the default content language, version, and role. Default is `false`.
disableHugoGeneratorInject
: (`bool`) Whether to disable injection of a `<meta name="generator">` tag into the home page. Default is `false`.
: (`[]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.
+: (`[]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.
+: (`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
-: (`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`.
+: (`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`.
enableMissingTranslationPlaceholders
: (`bool`) Whether to show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`.
: (`string`) The build environment. Default is `production` when running `hugo` and `development` when running `hugo server`.
frontmatter
-: See [configure front matter](/configuration/front-matter/).
+: 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`.
+: (`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](/configuration/http-cache/).
+: See [configure HTTP cache][].
i18nDir
: (`string`) The designated directory for translation tables. Default is `i18n`. {{% module-mounts-note %}}
: (`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].
+: (`[]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`].
+: (`[]string`) A slice of message identifiers corresponding to warnings and errors you wish to suppress. See [`erroridf`][] and [`warnidf`][].
ignoreVendorPaths
-: (`string`) A [glob](g) pattern matching the module paths to exclude from the `_vendor` directory.
+: (`string`) A [glob pattern](g) matching the module paths to exclude from the `_vendor` directory.
imaging
-: See [configure imaging](/configuration/imaging/).
+: See [configure imaging][].
languageCode
-: (`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:
+: (`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]
+ - 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](/configuration/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.
+: (`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](/configuration/markup/).
+: See [configure markup][].
mediaTypes
-: See [configure media types](/configuration/media-types/).
+: See [configure media types][].
menus
-: See [configure menus](/configuration/menus/).
+: See [configure menus][].
minify
-: See [configure minify](/configuration/minify/).
+: See [configure minify][].
module
-: See [configure modules](/configuration/module/).
+: See [configure modules][].
newContentEditor
: (`string`) The editor to use when creating new content.
: (`bool`) Whether to disable synchronization of file modification times. Default is `false`.
outputFormats
-: See [configure output formats](/configuration/output-formats/).
+: See [configure output formats][].
outputs
-: See [configure outputs](/configuration/outputs/).
+: See [configure outputs][].
page
-: See [configure page](/configuration/page/).
+: See [configure page][].
pagination
-: See [configure pagination](/configuration/pagination/).
+: See [configure pagination][].
panicOnWarning
: (`bool`) Whether to panic on the first WARNING. Default is `false`.
params
-: See [configure params](/configuration/params/).
+: See [configure params][].
permalinks
-: See [configure permalinks](/configuration/permalinks/).
+: See [configure permalinks][].
pluralizeListTitles
: (`bool`) Whether to pluralize automatic list titles. Applicable to section pages. Default is `true`.
: (`bool`) Whether to log WARNINGs for each unused template. Default is `false`.
privacy
-: See [configure privacy](/configuration/privacy/).
+: See [configure privacy][].
publishDir
: (`string`) The designated directory for publishing the site. Default is `public`.
: (`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](/configuration/related-content/).
+: 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](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. Default is `false`.
+: (`bool`) Whether to remove [non-spacing marks][] from [composite characters][] in content paths. Default is `false`.
renderSegments
-: {{< new-in 0.124.0 />}}
-: (`[]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 --renderSegments segment1,segment2`. The provided segment names must correspond to those defined in the [`segments`] configuration.
+: (`[]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 --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](/configuration/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](/configuration/segments/).
+: See [configure segments][].
server
-: See [configure server](/configuration/server/).
+: See [configure server][].
services
-: See [configure services](/configuration/services/).
+: See [configure services][].
sitemap
-: See [configure sitemap](/configuration/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`.
+: (`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](/configuration/taxonomies/).
+: See [configure taxonomies][].
templateMetrics
: (`bool`) Whether to print template execution metrics to the console. Default is `false`. See [details](/troubleshooting/performance/#template-metrics).
: (`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`.
+: (`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.
+: (`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).
+: (`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](/configuration/ugly-urls/).
+: 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:
+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) vendors, please read their documentation. For an 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. 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`:
## 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.
+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.
+: 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].
+: Use the capitalization rules published in the [Chicago Manual of Style][].
go
: Capitalize the first letter of every word.
## Localized settings
-Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages](/configuration/languages/#localized-settings).
+Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages][].
[`cacheDir`]: #cachedir
+[`defaultContentLanguage`]: #defaultcontentlanguage
+[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
+[`defaultContentRole`]: #defaultcontentrole
+[`defaultContentRoleInSubdir`]: #defaultcontentroleinsubdir
+[`defaultContentVersion`]: #defaultcontentversion
+[`defaultContentVersionInSubdir`]: #defaultcontentversioninsubdir
[`disabled`]: /configuration/languages/#disabled
+[`disableDefaultSiteRedirect`]: #disabledefaultsiteredirect
[`erroridf`]: /functions/fmt/erroridf/
[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
[`GitInfo`]: /methods/page/gitinfo/
[`MainSections`]: /methods/site/mainsections/
+[`publishDir`]: #publishdir
[`segments`]: /configuration/segments/
+[`staticDir`]: #staticdir
[`strings.Title`]: /functions/strings/title/
[`Summary`]: /methods/page/summary/
[`time.AsTime`]: /functions/time/astime/
[`titleCaseStyle`]: #titlecasestyle
[`warnidf`]: /functions/fmt/warnidf/
[`WordCount`]: /methods/page/wordcount/
+[aliases_front_matter]: /content-management/front-matter/#aliases
+[aliases_page_method]: /methods/page/aliases/
[Associated Press Stylebook]: https://www.apstylebook.com/
[automatic summaries]: /content-management/summaries/#automatic-summary
[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
+[client-side redirection]: /content-management/urls/#client-side-redirection
+[composite characters]: https://en.wikipedia.org/wiki/Precomposed_character
+[configure build]: /configuration/build/
+[configure cascade]: /configuration/cascade/
+[configure deployment]: /configuration/deployment/
+[configure file caches]: /configuration/caches/
+[configure front matter]: /configuration/front-matter/
+[configure HTTP cache]: /configuration/http-cache/
+[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/
[default front matter configuration]: /configuration/front-matter/
[duration]: https://pkg.go.dev/time#Duration
[embedded alias template]: <{{% eturl alias %}}>
[embedded Open Graph template]: <{{% eturl opengraph %}}>
[embedded RSS template]: <{{% eturl rss %}}>
[IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+[language keys]: /configuration/languages/#language-keys
[module mounts]: /configuration/module/#mounts
+[non-spacing marks]: https://www.compart.com/en/unicode/category/Mn
[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
[this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml
{{< 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.
+
+modulequeries
+: Caches the results of module resolution queries.
+
+modules
+: Caches downloaded modules.
+
## Keys
dir
-: (`string`) The absolute file system path where the cached files will be stored. You can begin the path with the `:cacheDir` or `:resourceDir` token. These tokens will be replaced with the actual configured cache directory and resource directory paths, respectively.
+: (`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](g) a cached entry remains valid before being evicted. A value of `0` disables the cache. A value of `-1` means the cache entry never expires (the default).
+: (`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).
+: (`string`) The designated cache directory. See [details](/configuration/all/#cachedir).
`:project`
-: (`string`) The base directory name of the current Hugo project. By default, this ensures each project has isolated file caches, so running `hugo --gc` will only affect the current project's cache and not those of other Hugo projects on the same machine.
+: (`string`) The base directory name of the current Hugo project. This ensures isolated file caches for each project, preventing the `hugo --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).
+: (`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 --gc` command to remove these expired or unused entries from the file cache.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
<!-- TODO
Update the <version> and <date> below when we actually get around to deprecating _target.
-We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2026-03-10 (15 months after deprecation).
+We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2027-05-01 (15 months after deprecation).
-->
The `target`[^1] keyword allows you to target specific pages or [environments](g). For example, to cascade a "color" parameter to pages within the "articles" section, including the "articles" section page itself:
Use any combination of these keywords to target pages and/or environments:
environment
-: (`string`) A [glob](g) pattern matching the build [environment](g). For example: `{staging,production}`.
+: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`.
kind
-: (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`.
+: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
lang
-: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`.
+: (`string`) A [glob pattern](g) matching the [page language]. For example: `{en,de}`.
path
-: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
+: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
## Array
: (`string`) The CloudFront Distribution ID, applicable if you are using the Amazon Web Services CloudFront CDN. Hugo will invalidate the CDN when deploying this target.
exclude
-: (`string`) A [glob](g) pattern matching files to exclude when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
+: (`string`) A [glob pattern](g) matching files to exclude when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
googleCloudCDNOrigin
: (`string`) The Google Cloud project and CDN origin to invalidate when deploying this target, specified as `<project>/<origin>`.
include
-: (`string`) A [glob](g) pattern matching files to include when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
+: (`string`) A [glob pattern](g) matching files to include when deploying to this target. Local files failing the include/exclude filters are not uploaded, and remote files failing these filters are not deleted.
name
: (`string`) An arbitrary name for this target.
: (`bool`) Whether to respect the `no-store` directive in the server's `Cache-Control` response header when fetching remote resources via the [`resources.GetRemote`][] function. Default is `false`.
cache.for.excludes
-: (`string`) A list of [glob](g) patterns to exclude from caching. In its default configuration HTTP caching excludes all files.
+: (`[]string`) A slice of [glob patterns](g) to exclude from caching. In its default configuration HTTP caching excludes all files.
cache.for.includes
-: (`string`) A list of [glob](g) patterns to cache.
+: (`[]string`) A slice of [glob patterns](g) to cache.
polls
: A slice of polling configurations.
: (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. Default is `0s`.
polls.for.excludes
-: (`string`) A list of [glob](g) patterns to exclude from polling for this configuration.
+: (`[]string`) A slice of [glob patterns](g) to exclude from polling for this configuration.
polls.for.includes
-: (`string`) A list of [glob](g) patterns to include in polling for this configuration.
+: (`[]string`) A slice of [glob patterns](g) to include in polling for this configuration.
## HTTP polling
: (`string`) The minimum polling interval expressed as a [duration](g). This is used after a recent change and gradually increases towards `polls.high`. Default is `0s`.
polls.for.excludes
-: (`string`) A list of [glob](g) patterns to exclude from polling for this configuration.
+: (`[]string`) A list of [glob patterns](g) to exclude from polling for this configuration.
polls.for.includes
-: (`string`) A list of [glob](g) patterns to include in polling for this configuration.
+: (`[]string`) A list of [glob patterns](g) to include in polling for this configuration.
## Behavior
[imaging]
anchor = 'Smart'
bgColor = '#ffffff'
-hint = 'photo'
+compression = 'lossy'
quality = 75
resampleFilter = 'box'
{{< /code-toggle >}}
anchor
-: (`string`) When using the [`Crop`] or [`Fill`] method, the anchor determines the placement of the crop box. One of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`.
+: (`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`.
bgColor
-: (`string`) The background color of the resulting image. Applicable when converting from a format that supports transparency to a format that does not support transparency, for example, when converting from PNG to JPEG. Expressed as an RGB [hexadecimal] value. Default is `#ffffff`.
-
-[hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+: (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`.
-hint
-: (`string`) Applicable to WebP images, this option corresponds to a set of predefined encoding parameters. One of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint).
+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`) Applicable to JPEG and WebP images, this value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between `1` and `100`, inclusive. Default is `75`.
+: (`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 resampling filter used when resizing an image. Default is `box`. See [details](/content-management/image-processing/#resampling-filter)
+: (`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.
+
+## WebP images
+
+{{< new-in 0.155.0 />}}
+
+These are the default settings specific to processing WebP images:
+
+{{< code-toggle file=hugo >}}
+[imaging.webp]
+hint = 'photo'
+method = 4
+useSharpYuv = true
+{{< /code-toggle >}}
+
+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
-## EXIF data
+method
+: (`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 are the default settings for extracting EXIF data from images:
+useSharpYuv
+: (`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]
-includeFields = ""
-excludeFields = ""
disableDate = false
disableLatLong = false
+excludeFields = ""
+includeFields = ""
{{< /code-toggle >}}
disableDate
-: (`bool`) Whether to disable extraction of the image creation date/time. Default is `false`.
+: (`bool`) Whether to disable the [`Date`][] method by returning its zero value. Default is `false`.
disableLatLong
-: (`bool`) Whether to disable extraction of the GPS latitude and longitude. Default is `false`.
+: (`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 tags to exclude when extracting EXIF data.
+: (`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 tags to include when extracting EXIF data. To include all available tags, set this value to `".*"`.
+: (`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`.
-> [!note]
-> To improve performance and decrease cache size, Hugo excludes the following tags: `ColorSpace`, `Contrast`, `Exif`, `Exposure[M|P|B]`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
->
-> To control tag availability, change the `excludeFields` or `includeFields` settings as described above.
+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.
-[`Crop`]: /methods/resource/crop/
-[`Fill`]: /methods/resource/fill/
+[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
+[`Exif`]: /methods/resource/exif/
+[`Meta`]: /methods/resource/meta/
+[`smartcrop.js`]: https://github.com/jwagner/smartcrop.js
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+[source documentation]: https://github.com/disintegration/imaging#image-resizing
> [!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) deployments like GitHub Pages, GitLab Pages, and Netlify by allowing you to set values directly within their respective configuration and workflow files.
+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_`.
: (`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
-: {{< new-in 0.123.0 />}}
: (`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 building with `hugo --logLevel info` and look for the `dynacache` label.
HUGO_NUMWORKERMULTIPLIER
{{< /code-toggle >}}
defaultContentLanguage
-: (`string`) The project's default language key, conforming to the syntax described in [RFC 5646]. This value must match one of the defined [language keys](#language-keys). Default is `en`.
+: (`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 language site to a subdirectory matching the `defaultContentLanguage`. Default is `false`.
+: (`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 to the default language when `DefaultContentLanguageInSubdir` is `true`. Default is `false`.
+: (`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.
: (`bool`) Whether to disable this language when building the site. Default is `false`.
languageCode
-: (`string`) The language tag as described in [RFC 5646]. This value does not affect localization or URLs. Hugo uses this value to populate:
+: (`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.
- - 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]
+ Hugo also uses this value to populate:
- Access this value from a template using the [`Language.LanguageCode`] method on a `Site` or `Page` object.
+ - 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).
+
+ 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.
+: (`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.
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.
+: (`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.
title
-: (`string`) The site title for this language. Access this value from a template using the [`Title`] method on a `Site` object.
+: (`string`) The site title for this language. Access this value from a template using the [`Title`][] method on a `Site` object.
weight
-: (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language. Access this value from a template using the [`Language.Weight`] method on a `Site` or `Page` object.
+: (`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.
## Localized settings
## Language keys
-Language keys must conform to the syntax described in [RFC 5646]. For example:
+Language keys must conform to the syntax described in [RFC 5646][]. For example:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
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:
+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'
{{< /code-toggle >}}
> [!note]
-> In the example above, omit `contentDir` if [translating by file name].
+> In the example above, omit `contentDir` if [translating by file name][].
## Multihost
└── fr
```
+[`defaultContentLanguage`]: #defaultcontentlanguage
+[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
+[`disableDefaultSiteRedirect`]: /configuration/all/#disabledefaultsiteredirect
[`Language.LanguageCode`]: /methods/site/language/#languagecode
[`Language.LanguageDirection`]: /methods/site/language/#languagedirection
[`Language.LanguageName`]: /methods/site/language/#languagename
+[`language.Translate`]: /functions/lang/translate/
[`Language.Weight`]: /methods/site/language/#weight
[`Title`]: /methods/site/title/
[embedded alias template]: <{{% eturl alias %}}>
[embedded OpenGraph template]: <{{% eturl opengraph %}}>
[embedded RSS template]: <{{% eturl rss %}}>
-[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[language keys]: #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#section-2.1
[translating by file name]: /content-management/multilingual/#translation-by-file-name
Most of the Goldmark settings above are self-explanatory, but some require explanation.
duplicateResourceFiles
-: {{< new-in 0.123.0 />}}
: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host sites. See [multilingual page resources] for details. Default is `false`.
> [!note]
<!-- TODO: delete this on or after July 1, 2027. -->
renderHooks.image.enableDefault
-: {{< new-in 0.123.0 />}}
: 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`: Automatically use the embedded image render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `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. In this case, the embedded hook takes precedence.
+ - `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
-: {{< new-in 0.123.0 />}}
: Deprecated in v0.148.0. Use `renderHooks.link.useEmbedded` instead.
renderHooks.link.useEmbedded
-: {{< new-in 0.148.0 />}}
: (`string`) When to use the [embedded link render hook]. One of `auto`, `never`, `always`, or `fallback`. Default is `auto`.
- - `auto`: Automatically use the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+ - `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. In this case, the embedded hook takes precedence.
+ - `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
: (`string`) The backend output file format. Default is `html5`.
extensions
-: (`string array`) An array of enabled extensions, such as `asciidoctor-html5s`, `asciidoctor-bibtex`, or `asciidoctor-diagram`.
+: (`[]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`.
See the [tdewolff/minify] project page for details, but note the following:
- `css.inline` is for internal use. Changing this setting has no effect.
-- `css.keepCSS2` has been deprecated. Use `css.version` instead.
- `html.keepConditionalComments` has been deprecated. Use `html.keepSpecialComments` instead.
-- `svg.inline` is for internal use. Changing this setting has no effect.
[tdewolff/minify]: https://github.com/tdewolff/minify
: (`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](g) patterns matching paths that should not use the [configured proxy server](#proxy).
+: (`string`) A comma-separated list of [glob patterns](g),s matching paths that should not use the [configured proxy server](#proxy).
noVendor
-: (`string`) A [glob](g) pattern matching module paths to skip when vendoring.
+: (`string`) A [glob pattern](g) matching module paths to skip when vendoring.
private
-: (`string`) A comma-separated list of [glob](g) patterns matching paths that should be treated as private.
+: (`string`) A comma-separated list of [glob patterns](g),s 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.
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.152.2`.
+: (`string`) The maximum Hugo version supported, for example `0.153.0`.
min
: (`string`) The minimum Hugo version supported, for example `0.102.0`.
> [!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`][].
-[`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
-
### 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.
: {{< new-in 0.128.0 />}}
: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`.
-lang
-: (`string`) The language code, e.g. "en". Relevant for `content` mounts, and `static` mounts when in multihost mode.
+files
+: {{< new-in 0.153.0 />}}
+: (`[]string`) A [glob slice](g) defining the files to include or exclude.
-includeFiles
-: (`string` or `[]string`) One or more [glob](g) patterns matching files or directories to include. If `excludeFiles` is not set, the files matching `includeFiles` will be the files mounted.
-
- The glob patterns are matched against file names relative to the source root. Use Unix-style forward slashes (`/`), even on Windows. A single forward slash (`/`) matches the mount root, and double asterisks (`**`) act as a recursive wildcard, matching all directories and files beneath a given point (e.g., `/posts/**.jpg`). The search is case-insensitive.
-
-excludeFiles
-: (`string` or `[]string`) One or more [glob](g) patterns matching files to 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
[[module.mounts]]
source="content"
target="content"
- excludeFiles="docs/*"
+ files=["! docs/*"]
[[module.mounts]]
source="node_modules"
target="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
: (`string`) The base name of the published file. Default is `index`.
isHTML
-: (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects and when to inject the LiveReload script. Default is `false`.
+: (`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
: (`bool`) Whether to parse templates for this output format with Go's [text/template][] package instead of the [html/template][] package. Default is `false`.
: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing.
permalinkable
-: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. See [details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`.
+: (`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 site configuration, typically `https://`.
rel
-: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`.
+: (`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`.
[`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/
: (`int`) An integer weight that indicates how important this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. Default is `0`.
cardinalityThreshold
-: (`int`) If between 1 and 100, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`.
+: (`int`) If between `1` and `100`, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`.
pattern
: (`string`) This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default.
--- /dev/null
+---
+title: Configure roles
+linkTitle: Roles
+description: Configure roles.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.153.0 />}}
+
+This is the default configuration:
+
+{{< code-toggle config=roles />}}
+
+To define "guest" and "member" roles:
+
+{{< code-toggle >}}
+[roles.guest]
+weight = 20
+[roles.member]
+weight = 10
+{{< /code-toggle >}}
+
+Roles are sorted by their [weight](g) in descending order, then by their name in descending order. This affects build order and complement selection.
keywords: []
---
-{{< new-in 0.124.0 />}}
-
> [!note]
> The `segments` configuration applies only to segmented rendering. While it controls when content is rendered, it doesn't restrict access to Hugo's complete object graph (sites and pages), which remains fully available.
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](g) matchers.
+- 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](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`.
+: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
-lang
-: (`string`) A [glob](g) pattern matching the [page language]. For example: `{en,de}`.
+sites
+: {{< new-in 0.153.0 />}}
+: (`map`) A map to define [sites matrix](g).
output
-: (`string`) A [glob](g) pattern matching the [output format](g) of the page. For example: `{html,json}`.
+: (`string`) A [glob pattern](g) matching the [output format](g) of the page. For example: `{html,json}`.
path
-: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
+: (`string`) A [glob pattern](g) matching the page's [logical path](g). For example: `{/books,/books/**}`.
## Example
```
[`renderSegments`]: /configuration/all/#rendersegments
-[page language]: /methods/page/language/
: (`bool`) Whether to force a redirect even if there is existing content in the path.
from
-: (`string`) A [glob](g) pattern matching the requested URL. Either `from` or `fromRE` must be set. If both `from` and `fromRe` are specified, the URL must match both patterns.
+: (`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](g) pattern with values to match. If the map is empty, the redirect will always be triggered.
+: (`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 />}}
{{ .Site.Config.Services.GoogleAnalytics.ID }}
```
-instagram.accessToken <!-- TODO: Remove when no longer in docs.yaml -->
-: (`string`) Do not use. Deprecated in [v0.123.0]. The embedded `instagram` shortcode no longer uses this setting.
-
-instagram.disableInlineCSS <!-- TODO: Remove when no longer in docs.yaml -->
-: (`bool`) Do not use. Deprecated in [v0.123.0]. The embedded `instagram` shortcode no longer uses this setting.
-
rss.limit
: (`int`) The maximum number of items to include in an RSS feed. Set to `-1` for no limit. Default is `-1`. See [details](/templates/rss/). To access this value from a template:
{{ .Site.Config.Services.RSS.Limit }}
```
-twitter.disableInlineCSS <!-- TODO: Remove when no longer in docs.yaml -->
-: (`bool`) Do not use. Deprecated in [v0.141.0]. Use the `x` shortcode instead.
-
x.disableInlineCSS
: (`bool`) Whether to disable the inline CSS rendered by the embedded `x` shortode. See [details](/shortcodes/x/#privacy). Default is `false`. To access this value from a template:
: (`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).
disable
-: {{< new-in 0.125.0 />}}
: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
filename
--- /dev/null
+---
+title: Configure versions
+linkTitle: Versions
+description: Configure versions.
+categories: []
+keywords: []
+---
+
+{{< new-in 0.153.0 />}}
+
+This is the default configuration:
+
+{{< code-toggle config=versions />}}
+
+To define "v1.0.0" and "v2.0.0" versions:
+
+{{< code-toggle >}}
+[versions."v1.0.0"]
+weight = 0
+[versions."v2.0.0"]
+weight = 0
+{{< /code-toggle >}}
+
+Versions are sorted by their [weight](g) in ascending order, then by their [semantic version] in descending order. This affects build order and complement selection.
+
+[semantic version]: https://semver.org/
Commercial commenting systems:
+- [Commentix](https://www.commentix.com/)
- [Emote](https://emote.com/)
- [Graph Comment](https://graphcomment.com/)
- [Hyvor Talk](https://talk.hyvor.com/)
- [Staticman](https://staticman.net/)
- [Talkyard](https://blog-comments.talkyard.io/)
- [Utterances](https://utteranc.es/)
+- [Zoomment](https://zoomment.com/)
[configuration]: /configuration/
[disquspartial]: /templates/embedded/#disqus
### EnableAllLanguages
-By default, Hugo executes the content adapter for the language defined by the `_content.gotmpl` file. Use this method to activate the content adapter for all languages.
+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 }}
{{ .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, role, and version.
+
+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.
[parameters]: #parameters
aliases
-: (`string array`) An array of one or more aliases, where each alias is a relative URL that will redirect the browser to the current location. Access these values from a template using the [`Aliases`] method on a `Page` object. See the [aliases] section for details.
+: (`[]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].
: (`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 array`) 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.
+: (`[]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.
: (`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 array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
+: (`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 array`) The [output formats] to render. See [configure outputs] for more information.
+: (`[]string`) The [output formats] to render. See [configure outputs] for more information.
params
-: {{< new-in 0.123.0 />}}
: (`map`) A map of custom [page parameters].
pubdate
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.
## Parameters
-{{< new-in 0.123.0 />}}
-
Specify custom page parameters under the `params` key in front matter:
{{< code-toggle file=content/example.md fm=true >}}
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
Update the <version> and <date> below when we actually get around to deprecating _target.
-We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2026-03-10 (15 months after deprecation).
+We deprecated the `_target` front matter key in favor of `target` in <version> on <date>. Remove footnote #1 on or after 2027-05-01 (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:
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](g) pattern matching the build [environment](g). For example: `{staging,production}`.
+: (`string`) A [glob pattern](g) matching the build [environment](g). For example: `{staging,production}`.
kind
-: (`string`) A [glob](g) pattern matching the [page kind](g). For example: `{taxonomy,term}`.
+: (`string`) A [glob pattern](g) matching the [page kind](g). For example: `{taxonomy,term}`.
path
-: (`string`) A [glob](g) pattern matching the page's [logical path](g). For example: `{/books,/books/**}`.
+: (`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
---
title: Image processing
-description: Resize, crop, rotate, filter, and convert images.
+description: Process, transform, and analyze images.
categories: []
keywords: []
---
-## Image resources
+Hugo provides methods to transform and analyze images during the build process. The results are cached to ensure subsequent builds remain fast.
-To process an image you must access the file as a page resource, global resource, or remote resource.
+## Resources
-### Page resource
+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" %}}
└── sunset.jpg <-- page resource
```
-To access an image as a page resource:
+To capture an image as a page resource:
```go-html-template
{{ $image := .Resources.Get "sunset.jpg" }}
```
-### Global resource
+### Global
{{% glossary-term "global resource" %}}
└── sunset.jpg <-- global resource
```
-To access an image as a global resource:
+To capture an image as a global resource:
```go-html-template
{{ $image := resources.Get "images/sunset.jpg" }}
```
-### Remote resource
+### Remote
{{% glossary-term "remote resource" %}}
-To access an image as a remote resource:
+To capture an image as a remote resource:
```go-html-template
{{ $image := resources.GetRemote "https://gohugo.io/img/hugo-logo.png" }}
```
-## Image rendering
+## Rendering
-Once you have accessed an image as a resource, render it in your templates using the `Permalink`, `RelPermalink`, `Width`, and `Height` properties.
+Once you have captured an image as a resource, render it in your templates using the [`Permalink`][], [`RelPermalink`][], [`Width`][], and [`Height`][] methods.
-Example 1: Throws an error if the resource is not found.
+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: Skips image rendering if the resource is not found.
+Example 2: Skip image rendering if the resource is not found.
```go-html-template
{{ $image := .Resources.GetMatch "sunset.jpg" }}
{{ end }}
```
-Example 4: Skips rendering if there's problem accessing a remote resource.
+Example 4: Skip rendering if there's problem accessing a remote resource.
```go-html-template
{{ $url := "https://gohugo.io/img/hugo-logo.png" }}
{{ end }}
```
-## Image processing methods
-
-The `image` resource implements the [`Process`], [`Resize`], [`Fit`], [`Fill`], [`Crop`], [`Filter`], [`Colors`] and [`Exif`] methods.
-
-> [!note]
-> Metadata (EXIF, IPTC, XMP, etc.) is not preserved during image transformation. Use the `Exif` method with the _original_ image to extract EXIF metadata from JPEG, PNG, TIFF, and WebP images.
-
-### Process
-
-> [!note]
-> The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [Process filter](/functions/images/process).
-
-Process processes the image with the given specification. The specification can contain an optional action, one of `resize`, `crop`, `fit` or `fill`. This means that you can use this method instead of [`Resize`], [`Fit`], [`Fill`], or [`Crop`].
-
-See [Options](#image-processing-options) for available options.
-
-You can also use this method apply image processing that does not need any scaling, e.g. format conversions:
-
-```go-html-template
-{{/* Convert the image from JPG to PNG. */}}
-{{ $png := $jpg.Process "png" }}
-```
-
-Some more examples:
-
-```go-html-template
-{{/* Rotate the image 90 degrees counter-clockwise. */}}
-{{ $image := $image.Process "r90" }}
-
-{{/* Scaling actions. */}}
-{{ $image := $image.Process "resize 600x" }}
-{{ $image := $image.Process "crop 600x400" }}
-{{ $image := $image.Process "fit 600x400" }}
-{{ $image := $image.Process "fill 600x400" }}
-```
-
-### Resize
-
-Resize an image to the given width and/or height.
-
-If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio.
-
-```go-html-template
-{{/* Resize to a width of 600px and preserve aspect ratio */}}
-{{ $image := $image.Resize "600x" }}
-
-{{/* Resize to a height of 400px and preserve aspect ratio */}}
-{{ $image := $image.Resize "x400" }}
-
-{{/* Resize to a width of 600px and a height of 400px */}}
-{{ $image := $image.Resize "600x400" }}
-```
-
-### Fit
-
-Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height.
-
-```go-html-template
-{{ $image := $image.Fit "600x400" }}
-```
-
-### Fill
-
-Crop and resize an image to match the given dimensions. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point.
-
-```go-html-template
-{{ $image := $image.Fill "600x400" }}
-```
-
-### Crop
-
-Crop an image to match the given dimensions without resizing. You must provide both width and height. Use the [`anchor`] option to change the crop box anchor point.
-
-```go-html-template
-{{ $image := $image.Crop "600x400" }}
-```
-
-### Filter
-
-Apply one or more [filters] to an image.
+## Processing
-```go-html-template
-{{ $image := $image.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
-```
-
-Write this in a more functional style using pipes. Hugo applies the filters in the order given.
+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
-{{ $image := $image | images.Filter (images.GaussianBlur 6) (images.Pixelate 8) }}
-```
-
-Sometimes it can be useful to create the filter chain once and then reuse it.
-
-```go-html-template
-{{ $filters := slice (images.GaussianBlur 6) (images.Pixelate 8) }}
-{{ $image1 := $image1.Filter $filters }}
-{{ $image2 := $image2.Filter $filters }}
-```
-
-### Colors
-
-`.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method.
-
-```go-html-template
-{{ $colors := $image.Colors }}
-```
-
-This method is fast, but if you also scale down your images, it would be good for performance to extract the colors from the scaled down image.
-
-### EXIF
-
-Provides an [EXIF] object containing image metadata.
-
-You may access EXIF data in JPEG, PNG, TIFF, and WebP images. To prevent errors when processing images without EXIF data, wrap the access in a [`with`] statement.
-
-```go-html-template
-{{ with $image.Exif }}
- Date: {{ .Date }}
- Lat/Long: {{ .Lat }}/{{ .Long }}
- Tags:
- {{ range $k, $v := .Tags }}
- TAG: {{ $k }}: {{ $v }}
- {{ end }}
-{{ end }}
-```
-
-You may also access EXIF fields individually, using the [`lang.FormatNumber`] function to format the fields as needed.
-
-```go-html-template
-{{ with $image.Exif }}
- <ul>
- {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
- {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
- {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
- {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
- {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
- {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
- {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
- {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
- </ul>
-{{ end }}
-```
-
-#### EXIF methods
-
-Date
-: (`time.Time`) Returns the image creation date/time. Format with the [`time.Format`]function.
-
-Lat
-: (`float64`) Returns the GPS latitude in degrees.
-
-Long
-: (`float64`) Returns the GPS longitude in degrees.
-
-Tags
-: (`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection in the [site configuration].
-
-## Image processing options
-
-The [`Resize`], [`Fit`], [`Fill`], and [`Crop`] methods accept a space-delimited, case-insensitive list of options. The order of the options within the list is irrelevant.
-
-### Dimensions
-
-With the [`Resize`] method you must specify width, height, or both. The [`Fit`], [`Fill`], and [`Crop`] methods require both width and height. All dimensions are in pixels.
-
-```go-html-template
-{{ $image := $image.Resize "600x" }}
-{{ $image := $image.Resize "x400" }}
-{{ $image := $image.Resize "600x400" }}
-{{ $image := $image.Fit "600x400" }}
-{{ $image := $image.Fill "600x400" }}
-{{ $image := $image.Crop "600x400" }}
-```
-
-### Rotation
-
-Rotates an image counter-clockwise by the given angle. Hugo performs rotation _before_ scaling. For example, if the original image is 600x400 and you wish to rotate the image 90 degrees counter-clockwise while scaling it by 50%:
-
-```go-html-template
-{{ $image = $image.Resize "200x r90" }}
-```
-
-In the example above, the width represents the desired width _after_ rotation.
-
-To rotate an image without scaling, use the dimensions of the original image:
-
-```go-html-template
-{{ with .Resources.GetMatch "sunset.jpg" }}
- {{ with .Resize (printf "%dx%d r90" .Height .Width) }}
+{{ with .Resources.Get "sunset.jpg" }}
+ {{ with .Resize "400x" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
{{ end }}
{{ end }}
```
-In the example above, on the second line, we have reversed width and height to reflect the desired dimensions _after_ rotation.
-
-### Anchor
-
-When using the [`Crop`] or [`Fill`] method, the _anchor_ determines the placement of the crop box. You may specify `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`.
-
-The default value is `Smart`, which uses [Smartcrop] image analysis to determine the optimal placement of the crop box. You may override the default value in the [site configuration].
-
-For example, if you have a 400x200 image with a bird in the upper left quadrant, you can create a 200x100 thumbnail containing the bird:
-
-```go-html-template
-{{ $image.Crop "200x100 TopLeft" }}
-```
-
-If you apply [rotation](#rotation) when using the [`Crop`] or [`Fill`] method, specify the anchor relative to the rotated image.
-
-### Target format
-
-By default, Hugo encodes the image in the source format. You may convert the image to another format by specifying `bmp`, `gif`, `jpeg`, `jpg`, `png`, `tif`, `tiff`, or `webp`.
-
-```go-html-template
-{{ $image.Resize "600x webp" }}
-```
-
-To convert an image without scaling, use the dimensions of the original image:
-
-```go-html-template
-{{ with .Resources.GetMatch "sunset.jpg" }}
- {{ with .Resize (printf "%dx%d webp" .Width .Height) }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
- {{ end }}
-{{ end }}
-```
-
-### Quality
-
-Applicable to JPEG and WebP images, the `q` value determines the quality of the converted image. Higher values produce better quality images, while lower values produce smaller files. Set this value to a whole number between 1 and 100, inclusive.
-
-The default value is 75. You may override the default value in the [site configuration].
-
-```go-html-template
-{{ $image.Resize "600x webp q50" }}
-```
-
-### Hint
+> [!note]
+> 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.
-Applicable to WebP images, this option corresponds to a set of predefined encoding parameters, and is equivalent to the `-preset` flag for the [`cwebp`] encoder.
+Each method serves a specific transformation or metadata requirement:
-Value|Example
+Method|Description
:--|:--
-`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
+[`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"}
-The default value is `photo`. You may override the default value in the [site configuration].
+Select a method from the table above for syntax and usage examples.
-```go-html-template
-{{ $image.Resize "600x webp picture" }}
-```
-
-### Background color
+## Performance
-When converting an image from a format that supports transparency (e.g., PNG) to a format that does _not_ support transparency (e.g., JPEG), you may specify the background color of the resulting image.
+### Caching
-Use either a 3-digit or 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`).
+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 site configuration.
-The default value is `#ffffff` (white). You may override the default value in the [site configuration].
+If you host your site with Netlify, include the following in your site configuration to persist the image cache between builds:
-```go-html-template
-{{ $image.Resize "600x jpg #b31280" }}
+```toml
+[caches]
+ [caches.images]
+ dir = ':cacheDir/images'
```
-### Resampling filter
+### Garbage collection
-You may specify the resampling filter used when resizing an image. Commonly used resampling filters include:
+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:
-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
-
-The default value is `Box`. You may override the default value in the [site configuration].
-
-```go-html-template
-{{ $image.Resize "600x400 Lanczos" }}
+```text
+hugo --gc
```
-See [github.com/disintegration/imaging] for the complete list of resampling filters. If you wish to improve image quality at the expense of performance, you may wish to experiment with the alternative filters.
-
-## Image processing examples
-
-_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://bep.is) (Creative Commons Attribution-Share Alike 4.0 International license)_
-
-{{< imgproc path="sunset.jpg" spec="resize 480x" alt="A sunset" />}}
-
-{{< imgproc path="sunset.jpg" spec="fill 120x150 left" alt="A sunset" />}}
+### Resource usage
-{{< imgproc path="sunset.jpg" spec="fill 120x150 right" alt="A sunset" />}}
+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.
-{{< imgproc path="sunset.jpg" spec="fit 120x120" alt="A sunset" />}}
-
-{{< imgproc path="sunset.jpg" spec="crop 240x240 center" alt="A sunset" />}}
-
-{{< imgproc path="sunset.jpg" spec="resize 360x q10" alt="A sunset" />}}
+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).
-## Smart cropping of images
-
-By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or `Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice.
-
-Examples using the sunset image from above:
-
-{{< imgproc path="sunset.jpg" spec="fill 200x200 smart" alt="A sunset" />}}
-
-{{< imgproc path="sunset.jpg" spec="crop 200x200 smart" alt="A sunset" />}}
-
-## Image processing performance consideration
-
-Hugo caches processed images in the `resources` directory. If you include this directory in source control, Hugo will not have to regenerate the images in a [CI/CD](g) workflow (e.g., GitHub Pages, GitLab Pages, Netlify, etc.). This results in faster builds.
-
-If you change image processing methods or options, or if you rename or remove images, the `resources` directory will contain unused images. To remove the unused images, perform garbage collection with:
-
-```sh
-hugo --gc
-```
-
-[`anchor`]: /content-management/image-processing#anchor
-[`Colors`]: #colors
-[`Crop`]: #crop
-[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
-[`Exif`]: #exif
-[`Fill`]: #fill
-[`Filter`]: #filter
-[`Fit`]: #fit
-[`lang.FormatNumber`]: /functions/lang/formatnumber/
-[`Process`]: #process
-[`Resize`]: #resize
-[`time.Format`]: /functions/time/format/
-[`with`]: /functions/go-template/with/
-[EXIF]: https://en.wikipedia.org/wiki/Exif
-[filters]: /functions/images/filter/#image-filters
-[github.com/disintegration/imaging]: https://github.com/disintegration/imaging#image-resizing
-[site configuration]: /configuration/imaging/
-[Smartcrop]: https://github.com/muesli/smartcrop#smartcrop
+[`Colors`]: /methods/resource/colors/
+[`Crop`]: /methods/resource/crop/
+[`Exif`]: /methods/resource/exif/
+[`Fill`]: /methods/resource/fill/
+[`Filter`]: /methods/resource/filter/
+[`Fit`]: /methods/resource/fit/
+[`Height`]: /methods/resource/height/
+[`Meta`]: /methods/resource/meta/
+[`Permalink`]: /methods/resource/permalink/
+[`Process`]: /methods/resource/process/
+[`RelPermalink`]: /methods/resource/relpermalink/
+[`Resize`]: /methods/resource/resize/
+[`Width`]: /methods/resource/width/
{class="foo bar" id="baz"}
```
-With `class` and `id` you can use shorthand notation:
+With `class` and `id` attributes you can also use short-form notation:
```text
This is a paragraph.
{.foo .bar #baz}
```
-Hugo renders both of these to:
+Hugo renders both of the examples above to:
```html
<p class="foo bar" id="baz">This is a paragraph.</p>
```
+With `class` and `id` attributes, whether you use long-form or short-form notation, the resulting values are available in [render hook templates][] via the `Attributes` method. For example:
+
+```go-html-template
+{{ .Attributes.class }} → foo bar
+{{ .Attributes.id }} → baz
+```
+
## Block elements
Update your site configuration to enable Markdown attributes for block-level elements.
Element|Position of attribute list
:--|:--
-blockquote | bottom
-fenced code block | right
-heading | right
-horizontal rule | bottom
-image | bottom
-list | bottom
-paragraph | bottom
-table | bottom
+blockquote|bottom
+fenced code block|right
+heading|right
+horizontal rule|bottom
+image|bottom
+list|bottom
+paragraph|bottom
+table|bottom
For example:
````
As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options](/functions/transform/highlight/#options).
+
+[render hook templates]: /render-hooks/introduction/
|-------------------|-------------------|-----------------------|
| 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"` |
+| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` |
+| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` |
## Multilingual
-{{< new-in 0.123.0 />}}
-
By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site.
> [!note]
In the above, "Section 1" will be included when invoking the `TableOfContents` method, while "Section 2" will not.
-The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments.
+> [!note]
+> The shortcode author determines which notation to use. Consult each shortcode's documentation for specific usage instructions and available arguments.
## Nesting
> [!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.
+> - 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.
#### Leading slashes
-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.
+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.
Site type|Front matter `url`|Resulting URL
:--|:--|:--
#### 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].
+> 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.
## Aliases
-Create redirects from old URLs to new URLs with 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.
-- An alias with a leading slash is relative to the `baseURL`
-- An alias without a leading slash is relative to the current directory
+### Defining aliases
-### Examples {#alias-examples}
+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, role, or version.
-Change the file name of an existing page, and create an alias from the previous URL to the new URL:
-
-{{< code-toggle file=content/posts/new-file-name.md fm=true >}}
-aliases = ['/posts/previous-file-name']
+{{< 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 >}}
-Each of these directory-relative aliases is equivalent to the site-relative alias above:
+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:
-- `previous-file-name`
-- `./previous-file-name`
-- `../posts/previous-file-name`
+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/`
-You can create more than one alias to the current page:
+### Redirection methods
-{{< code-toggle file=content/posts/new-file-name.md fm=true >}}
-aliases = ['previous-file-name','original-file-name']
-{{< /code-toggle >}}
+There are two ways to implement aliases depending on your hosting environment and preferences: client-side redirection and server-side redirection.
-In a multilingual site, use a directory-relative alias, or include the language prefix with a site-relative alias:
-
-{{< code-toggle file=content/posts/new-file-name.de.md fm=true >}}
-aliases = ['/de/posts/previous-file-name']
-{{< /code-toggle >}}
+> [!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.
-### How aliases work
+#### Client-side redirection
-Using the first example above, Hugo generates the following site structure:
+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.
-```text
-public/
-├── posts/
-│ ├── new-file-name/
-│ │ └── index.html
-│ ├── previous-file-name/
-│ │ └── index.html
-│ └── index.html
-└── index.html
-```
+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`.
-The alias from the previous URL to the new URL is a client-side redirect:
+Unless you provide a custom layout, Hugo uses its [embedded alias template][] to generate the redirect files:
-```html {file="posts/previous-file-name/index.html"}
+```go-html-template
<!DOCTYPE html>
-<html lang="en-us">
+<html lang="{{ site.Language.LanguageCode }}">
<head>
- <title>https://example.org/posts/new-file-name/</title>
- <link rel="canonical" href="https://example.org/posts/new-file-name/">
+ <title>{{ .Permalink }}</title>
+ {{ with .OutputFormats.Canonical }}<link rel="{{ .Rel }}" href="{{ .Permalink }}">{{ end }}
<meta charset="utf-8">
- <meta http-equiv="refresh" content="0; url=https://example.org/posts/new-file-name/">
+ <meta http-equiv="refresh" content="0; url={{ .Permalink }}">
</head>
</html>
```
-The `link rel="canonical"` tag informs search engines that the new URL is the preferred or "canonical" version of the page. This is crucial for SEO, as it prevents issues with duplicate content by consolidating all ranking signals to a single URL.
+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.
-The `http-equiv="refresh"` meta tag instructs the web browser to automatically redirect the user to the new URL. This ensures that anyone who accesses the old alias URL is seamlessly taken to the correct, updated page.
+#### Server-side redirection
-Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected.
+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.
-### Customize
+To implement this, you typically create a single template to generate the necessary rules for your specific host or server. Common examples include:
-To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the `layouts` directory. The template receives the following context:
+- A `_redirects` file for hosting services such as Cloudflare, GitLab Pages, and Netlify.
+- An `.htaccess` file for web servers such as Apache and LiteSpeed.
-Permalink
-: The link to the page being aliased.
+See the [`Aliases`][aliases_method] method page for a complete example of how to iterate through pages to generate these rules.
-Page
-: The Page data for the page being aliased.
+If you implement server-side redirects, you should disable the generation of individual HTML files by setting [`disableAliases`][] to `true` in your site 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
-[source code]: <{{% eturl alias %}}>
To build and install a specific release:
```sh
-CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.152.2
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.155.3
```
To build and install at the latest commit on the master branch:
---
title: collections.After
-description: Slices an array to the items after the Nth item.
+description: Returns a slice containing the elements after the first N elements of the given slice.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [after]
- returnType: any
- signatures: [collections.After INDEX COLLECTION]
+ returnType: '[]any'
+ signatures: [collections.After N SLICE]
aliases: [/functions/after]
---
---
title: collections.Append
-description: Appends one or more elements to a slice and returns the resulting slice.
+description: Returns a slice by adding one or more elements, or an entire second slice, to the end of the given slice.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [append]
- returnType: any
- signatures:
- - collections.Append ELEMENT [ELEMENT...] COLLECTION
- - collections.Append COLLECTION1 COLLECTION2
+ returnType: '[]any'
+ signatures:
+ - collections.Append ELEMENT [ELEMENT...] SLICE
+ - collections.Append SLICE1 SLICE2
aliases: [/functions/append]
---
---
title: collections.Apply
-description: Returns a new collection with each element transformed by the given function.
+description: Returns a slice by transforming each element of the given slice using a specific function and parameters.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [apply]
returnType: '[]any'
- signatures: [collections.Apply COLLECTION FUNCTION PARAM...]
+ signatures: [collections.Apply SLICE FUNCTION PARAM...]
aliases: [/functions/apply]
---
-The `apply` function takes three or more arguments, depending on the function being applied to the collection elements.
+The `apply` function takes three or more arguments, depending on the function being applied to the slice elements.
-The first argument is the collection itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the collection element.
+The first argument is the slice itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the slice element.
```go-html-template
{{ $s := slice "hello" "world" }}
---
title: collections.Complement
-description: Returns the elements of the last collection that are not in any of the others.
+description: Returns a slice by identifying elements in the last given slice that do not appear in any of the preceding slices.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [complement]
- returnType: any
- signatures: ['collections.Complement COLLECTION [COLLECTION...]']
+ returnType: '[]any'
+ signatures: ['collections.Complement SLICE [SLICE...]']
aliases: [/functions/complement]
---
---
title: collections.D
-description: Returns a slice of sequentially ordered random integers.
+description: Returns a sorted slice of unique random integers based on a given seed, count, and maximum value.
categories: []
keywords: [random]
params:
functions_and_methods:
+ aliases: []
returnType: '[]int'
signatures: [collections.D SEED N HIGH]
---
{{< new-in 0.149.0 />}}
-The `collections.D` function returns a slice of `N` sequentially ordered unique random integers in the half-open [interval](g) [0, `HIGH`) using the provided [`SEED`](g) value. This function implements J. S. Vitter's Method D[^1] for sequential random sampling, a fast and efficient algorithm for this task.
+The `collections.D` function returns a sorted slice of unique random integers in the half-open [interval](g) `[0, HIGH)` using the provided [`SEED`](g) value. The number of elements in the resulting slice is `N` or `HIGH`, whichever is less.
-See [this article][] for a detailed explanation.
+- `N` and `H` must be integers in the closed interval `[0, 1000000]`
+- `SEED` must be an integer in the closed interval `[0, 2^64 - 1]`
+
+## Return values
+
+Condition|Return value
+:--|:--|:--
+`N <= HIGH`|A sorted random sample of size `N` using J. S. Vitter's [Method D][] for sequential random sampling
+`N > HIGH`|The full, sorted range `[0, HIGH)` of size `HIGH`
+`N == 0`|An empty slice
+`N < 0`|Error
+`N > 10^6`|Error
+`HIGH == 0`|An empty slice
+`HIGH < 0`|Error
+`HIGH > 10^6`|Error
+`SEED < 0`|Error
+{.no-wrap-first-col}
## Examples
{{ collections.D 2 7 42 }} → [3, 11, 19, 25, 32, 33, 38]
```
+When `N` is greater than `HIGH`, this function returns the full, sorted range [0, `HIGH`) of size `HIGH`:
+
+```go-html-template
+{{ collections.D 6 42 7 }} → [0 1 2 3 4 5 6]
+```
+
A common use case is the selection of random pages from a page collection. For example, to render a list of 5 random pages using the [day of the year][] as the seed value:
```go-html-template
Same result per page|`hash.FNV32a .Path`
Different result per page per day|`hash.FNV32a (print .Path time.Now.YearDay)`
-> [!note]
-> The slice created by this function is limited to 1 million elements.
-
-[^1]: J. S. Vitter, "An efficient algorithm for sequential random sampling," _ACM Trans. Math. Soft._, vol. 13, pp. 58–67, Mar. 1987.
-
[`collections.Shuffle`]: /functions/collections/shuffle/
[day of the year]: /methods/time/yearday/
-[this article]: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/
+[Method D]: https://getkerf.wordpress.com/2016/03/30/the-best-algorithm-no-one-knows-about/
---
title: collections.Delimit
-description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter.
+description: Returns a string by joining the values of the given slice or map with a delimiter.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [delimit]
returnType: string
- signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]']
+ signatures: ['collections.Delimit SLICE|MAP DELIMITER [LAST]']
aliases: [/functions/delimit]
---
---
title: collections.Dictionary
-description: Returns a map composed of the given key-value pairs.
+description: Returns a map created from the given key-value pairs.
categories: []
keywords: []
params:
---
title: collections.First
-description: Returns the given collection, limited to the first N elements.
+description: Returns the first N elements of the given slice or string.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [first]
- returnType: any
- signatures: [collections.First N COLLECTION]
+ returnType: 'any'
+ signatures: [collections.First N SLICE|STRING]
aliases: [/functions/first]
---
{{ end }}
```
-Set `N` to zero to return an empty collection:
+Set `N` to zero to return an empty slice:
```go-html-template
{{ $emptyPageCollection := first 0 .Pages }}
---
title: collections.Group
-description: Groups the given page collection by the given key.
+description: Returns a map by grouping the given page collection (slice) by a specific key.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [group]
- returnType: any
+ returnType: page.PageGroup
signatures: [collections.Group KEY PAGES]
aliases: [/functions/group]
---
---
title: collections.In
-description: Reports whether the given value is a member of the given set.
+description: Reports whether a value exists within the given slice or string.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [in]
returnType: bool
- signatures: [collections.In SET VALUE]
+ signatures: [collections.In SLICE|STRING VALUE]
aliases: [/functions/in]
---
-The `SET` can be an [array](g), [slice](g), or [string](g).
-
```go-html-template
{{ $s := slice "a" "b" "c" }}
{{ in $s "b" }} → true
```
-```go-html-template
-{{ $s := slice 1 2 3 }}
-{{ in $s 2 }} → true
-```
-
-```go-html-template
-{{ $s := slice 1.11 2.22 3.33 }}
-{{ in $s 2.22 }} → true
-```
-
```go-html-template
{{ $s := "abc" }}
{{ in $s "b" }} → true
---
title: collections.Index
-description: Returns the object, element, or value associated with the given key or keys.
+description: Returns an element or value from the given slice or map at the specified key(s).
categories: []
keywords: []
params:
functions_and_methods:
aliases: [index]
returnType: any
- signatures: [collections.Index COLLECTION KEY...]
+ signatures: [collections.Index SLICE|MAP KEY...]
aliases: [/functions/index,/functions/index-function]
---
---
title: collections.Intersect
-description: Returns the common elements of two arrays or slices, in the same order as the first array.
+description: Returns a slice containing the common elements found in two given slices, in the same order as the first slice.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [intersect]
- returnType: any
- signatures: [collections.Intersect SET1 SET2]
+ returnType: '[]any'
+ signatures: [collections.Intersect SLICE1 SLICE2]
aliases: [/functions/intersect]
---
---
title: collections.IsSet
-description: Reports whether the key exists within the collection.
+description: Reports whether a specific key or index exists in the given map or slice.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [isset]
returnType: bool
- signatures: [collections.IsSet COLLECTION KEY]
+ signatures: [collections.IsSet MAP|SLICE KEY|INDEX]
aliases: [/functions/isset]
---
---
title: collections.KeyVals
-description: Returns a KeyVals struct.
+description: Returns a KeyVals struct by pairing a given key and values.
categories: []
keywords: []
params:
---
title: collections.Last
-description: Returns the given collection, limited to the last N elements.
+description: Returns the last N elements of the given slice or string.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [last]
- returnType: any
- signatures: [collections.Last N COLLECTION]
+ returnType: 'any'
+ signatures: [collections.Last N SLICE|STRING]
aliases: [/functions/last]
---
{{ end }}
```
-Set `N` to zero to return an empty collection:
+Set `N` to zero to return an empty slice:
```go-html-template
{{ $emptyPageCollection := last 0 .Pages }}
---
title: collections.Merge
-description: Returns the result of merging two or more maps.
+description: Returns a map by combining two or more given maps.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [merge]
- returnType: any
+ returnType: map[string]any
signatures: [collections.Merge MAP MAP...]
aliases: [/functions/merge]
---
functions_and_methods:
aliases: [newScratch]
returnType: maps.Scratch
- signatures: [collections.NewScratch ]
+ signatures: [collections.NewScratch]
---
Use the `collections.NewScratch` function to create a locally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below.
---
title: collections.Querify
-description: Returns a URL query string composed of the given key-value pairs, encoded and sorted by key.
+description: Returns a URL query string from the given map, slice, or sequence of key-value pairs.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [querify]
returnType: string
- signatures: ['collections.Querify [VALUE...]']
+ signatures: [collections.Querify MAP|SLICE|KEY VALUE...]
aliases: [/functions/querify]
---
---
title: collections.Reverse
-description: Reverses the order of a collection.
+description: Returns a slice by reversing the order of elements in the given slice.
categories: []
keywords: []
params:
functions_and_methods:
aliases: []
- returnType: any
- signatures: [collections.Reverse COLLECTION]
+ returnType: '[]any'
+ signatures: [collections.Reverse SLICE]
aliases: [/functions/collections.reverse]
---
---
title: collections.Seq
-description: Returns a slice of integers.
+description: Returns a slice of integers starting from 1 or a given value, incrementing by 1 or a given value, and ending at a given value.
categories: []
keywords: []
params:
---
title: collections.Shuffle
-description: Returns a random permutation of a given array or slice.
+description: Returns a slice by randomizing the element order of the given slice.
categories: []
keywords: [random]
params:
functions_and_methods:
aliases: [shuffle]
- returnType: any
- signatures: [collections.Shuffle COLLECTION]
+ returnType: '[]any'
+ signatures: [collections.Shuffle SLICE]
aliases: [/functions/shuffle]
---
---
title: collections.Slice
-description: Returns a slice composed of the given values.
+description: Returns a slice created from the given values.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [slice]
- returnType: any
+ returnType: '[]any'
signatures: ['collections.Slice [VALUE...]']
aliases: [/functions/slice]
---
---
title: collections.Sort
-description: Sorts slices, maps, and page collections.
+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 COLLECTION [KEY] [ORDER]']
+ signatures: ['collections.Sort MAP|SLICE [KEY] [ORDER]']
aliases: [/functions/sort]
---
---
title: collections.SymDiff
-description: Returns the symmetric difference of two collections.
+description: Returns a slice containing the symmetric difference of two given slices.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [symdiff]
- returnType: any
- signatures: [COLLECTION | collections.SymDiff COLLECTION]
+ returnType: '[]any'
+ signatures: [SLICE1 | collections.SymDiff SLICE2]
aliases: [/functions/symdiff]
---
---
title: collections.Union
-description: Given two arrays or slices, returns a new array that contains the elements that belong to either or both arrays/slices.
+description: Returns a slice containing the unique elements from two given slices.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [union]
- returnType: any
- signatures: [collections.Union SET1 SET2]
+ returnType: '[]any'
+ signatures: [collections.Union SLICE1 SLICE2]
aliases: [/functions/union]
---
-Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both.
+
```go-html-template
{{ union (slice 1 2 3) (slice 3 4 5) }} → [1 2 3 4 5]
-
-{{ union (slice 1 2 3) nil }} → [1 2 3]
-
-{{ union nil (slice 1 2 3) }} → [1 2 3]
-
-{{ union nil nil }} → []
+{{ union (slice 1 2 3) nil }} → [1 2 3]
+{{ union nil (slice 1 2 3) }} → [1 2 3]
+{{ union nil nil }} → []
```
## OR filter in where query
---
title: collections.Uniq
-description: Returns the given collection, removing duplicate elements.
+description: Returns a slice by removing duplicate elements from the given slice.
categories: []
keywords: []
params:
functions_and_methods:
aliases: [uniq]
- returnType: any
- signatures: [collections.Uniq COLLECTION]
+ returnType: '[]any'
+ signatures: [collections.Uniq SLICE]
aliases: [/functions/uniq]
---
---
title: collections.Where
-description: Returns the given collection, removing elements that do not satisfy the comparison condition.
+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 COLLECTION KEY [OPERATOR] VALUE']
+ returnType: '[]any'
+ signatures: ['collections.Where SLICE KEY [OPERATOR] VALUE']
aliases: [/functions/where]
---
-The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is composed of the `KEY`, `OPERATOR`, and `VALUE` arguments:
+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 COLLECTION KEY [OPERATOR] VALUE
- --------------------
- comparison condition
+collections.Where SLICE KEY [OPERATOR] VALUE
+ --------------------
+ comparison condition
```
Hugo will test for equality if you do not provide an `OPERATOR` argument. For example:
The where function takes three or four arguments. The `OPERATOR` argument is optional.
-COLLECTION
-: (`any`) A [page collection](g) or a [slice](g) of [maps](g).
+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" }}
-```
+ ```go-html-template
+ {{ $result := where .Site.RegularPages "Params.foo" "bar" }}
+ ```
OPERATOR
: (`string`) The logical comparison [operator](#operators).
Compare a [`scalar`](g) to a [`slice`](g).
-For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow":
+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" }}
{{ $pages := where $fruit "Params.color" "in" $colors }}
```
-To return a collection of pages where the "color" page parameter is neither "red" nor "yellow":
+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" }}
## Intersection comparison
-Compare a `slice` to a `slice`, returning collection elements with common values. This is frequently used when comparing taxonomy terms.
+Compare a `slice` to a `slice`, returning elements with common values. This is frequently used when comparing taxonomy terms.
-For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance":
+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" }}
## Regular expression comparison
-To return a collection of pages where the "author" page parameter begins with either "victor" or "Victor":
+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 collection.
+> Use the `like` operator to compare string values. Comparing other data types will result in an empty slice.
## Date comparison
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 collection of pages that were created before the current year:
+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) }}
+++
```
-To return a collection of future events:
+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 through the collection:
+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" }}
## Nil comparison
-To return a collection of pages where the "color" parameter is present in front matter, compare to `nil`:
+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 collection of pages where the "color" parameter is not present in front matter, compare to `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 }}
To exclude a page with an undefined field from a boolean _inequality_ test:
-1. Create a collection using a boolean comparison
-1. Create a collection using a nil comparison
-1. Subtract the second collection from the first collection using the [`collections.Complement`] function.
+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:
---
title: Collections functions
linkTitle: collections
-description: Use these functions to work with arrays, slices, maps, and page collections.
+description: Use these functions to manipulate and query maps, slices, and strings.
categories: []
keywords: []
---
> [!note]
> This function is only applicable to the [`vars`] option passed to the [`css.Sass`] function.
-When 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` function to explicitly indicate that the value must be treated as a quoted string.
+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` function to explicitly indicate that the value must be treated as a quoted string.
For example:
signatures: ['css.Sass [OPTIONS] RESOURCE']
---
-{{< new-in 0.128.0 />}}
-
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
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/).
@use "hugo:vars" as v;
```
- When 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.
+ 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
## 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].
+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.
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.
+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 production environment
-To use Dart Sass with Hugo on a CI/CD platform like GitHub Pages, GitLab Pages, or Netlify, 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.
+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 sites configuration.
-By committing the `resources` directory, you're providing the pre-built CSS files directly to your CI/CD service, so it doesn't need to run the Sass compilation itself.
+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]
-- [Vercel]
+- [Cloudflare][]
+- [GitHub Pages][]
+- [GitLab Pages][]
+- [Netlify][]
+- [Render][]
+- [SourceHut][]
+- [Vercel][]
[`css.Quoted`]: /functions/css/quoted/
[`css.Unquoted`]: /functions/css/unquoted/
[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
[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/
> [!note]
> This function is only applicable to the [`vars`] option passed to the [`css.Sass`] function.
-When 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.Unquoted` function to explicitly indicate that the value must not be treated as a quoted string.
+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.Unquoted` function to explicitly indicate that the value must not be treated as a quoted string.
For example:
+++ /dev/null
----
-title: data.GetCSV
-description: Returns an array of arrays from a local or remote CSV file, or an error if the file does not exist.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- aliases: [getCSV]
- returnType: '[][]string'
- signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]']
-expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0
----
-
-{{< deprecated-in 0.123.0 >}}
-Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g).
-
-See the [remote data example].
-
-[`transform.Unmarshal`]: /functions/transform/unmarshal/
-[remote data example]: /functions/resources/getremote/#remote-data
-{{< /deprecated-in >}}
-
-Given the following directory structure:
-
-```text
-my-project/
-└── other-files/
- └── pets.csv
-```
-
-Access the data with either of the following:
-
-```go-html-template
-{{ $data := getCSV "," "other-files/pets.csv" }}
-{{ $data := getCSV "," "other-files/" "pets.csv" }}
-```
-
-> [!note]
-> When working with local data, the file path is relative to the working directory.
->
-> You must not place CSV files in the project's `data` directory.
-
-Access remote data with either of the following:
-
-```go-html-template
-{{ $data := getCSV "," "https://example.org/pets.csv" }}
-{{ $data := getCSV "," "https://example.org/" "pets.csv" }}
-```
-
-The resulting data structure is an array of arrays:
-
-```json
-[
- ["name","type","breed","age"],
- ["Spot","dog","Collie","3"],
- ["Felix","cat","Malicious","7"]
-]
-```
-
-## Options
-
-Add headers to the request by providing an options map:
-
-```go-html-template
-{{ $opts := dict "Authorization" "Bearer abcd" }}
-{{ $data := getCSV "," "https://example.org/pets.csv" $opts }}
-```
-
-Add multiple headers using a slice:
-
-```go-html-template
-{{ $opts := dict "X-List" (slice "a" "b" "c") }}
-{{ $data := getCSV "," "https://example.org/pets.csv" $opts }}
-```
-
-## Global resource alternative
-
-Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource.
-
-```text
-my-project/
-└── assets/
- └── data/
- └── pets.csv
-```
-
-```go-html-template
-{{ $data := dict }}
-{{ $p := "data/pets.csv" }}
-{{ with resources.Get $p }}
- {{ $opts := dict "delimiter" "," }}
- {{ $data = . | transform.Unmarshal $opts }}
-{{ else }}
- {{ errorf "Unable to get resource %q" $p }}
-{{ end }}
-```
-
-## Page resource alternative
-
-Consider using the [`Resources.Get`][/methods/page/resources/] method with [`transform.Unmarshal`] when accessing a page resource.
-
-```text
-my-project/
-└── content/
- └── posts/
- └── my-pets/
- ├── index.md
- └── pets.csv
-```
-
-```go-html-template
-{{ $data := dict }}
-{{ $p := "pets.csv" }}
-{{ with .Resources.Get $p }}
- {{ $opts := dict "delimiter" "," }}
- {{ $data = . | transform.Unmarshal $opts }}
-{{ else }}
- {{ errorf "Unable to get resource %q" $p }}
-{{ end }}
-```
-
-## Remote resource alternative
-
-Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control.
-
-```go-html-template
-{{ $data := dict }}
-{{ $url := "https://example.org/pets.csv" }}
-{{ with try (resources.GetRemote $url) }}
- {{ with .Err }}
- {{ errorf "%s" . }}
- {{ else with .Value }}
- {{ $opts := dict "delimiter" "," }}
- {{ $data = . | transform.Unmarshal $opts }}
- {{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
- {{ end }}
-{{ end }}
-```
-
-[`resources.GetRemote`]: /functions/resources/getremote/
-
-<!-- markdownlint-disable MD053 -->
-[`transform.Unmarshal`]: /functions/transform/unmarshal/
-<!-- markdownlint-enable MD053 -->
+++ /dev/null
----
-title: data.GetJSON
-description: Returns a JSON object from a local or remote JSON file, or an error if the file does not exist.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- aliases: [getJSON]
- returnType: any
- signatures: ['data.GetJSON INPUT... [OPTIONS]']
-expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0
----
-
-{{< deprecated-in 0.123.0 >}}
-Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g).
-
-See the [remote data example].
-
-[`transform.Unmarshal`]: /functions/transform/unmarshal/
-[remote data example]: /functions/resources/getremote/#remote-data
-{{< /deprecated-in >}}
-
-Given the following directory structure:
-
-```text
-my-project/
-└── other-files/
- └── books.json
-```
-
-Access the data with either of the following:
-
-```go-html-template
-{{ $data := getJSON "other-files/books.json" }}
-{{ $data := getJSON "other-files/" "books.json" }}
-```
-
-> [!note]
-> When working with local data, the file path is relative to the working directory.
-
-Access remote data with either of the following:
-
-```go-html-template
-{{ $data := getJSON "https://example.org/books.json" }}
-{{ $data := getJSON "https://example.org/" "books.json" }}
-```
-
-The resulting data structure is a JSON object:
-
-```json
-[
- {
- "author": "Victor Hugo",
- "rating": 5,
- "title": "Les Misérables"
- },
- {
- "author": "Victor Hugo",
- "rating": 4,
- "title": "The Hunchback of Notre Dame"
- }
-]
-```
-
-## Options
-
-Add headers to the request by providing an options map:
-
-```go-html-template
-{{ $opts := dict "Authorization" "Bearer abcd" }}
-{{ $data := getJSON "https://example.org/books.json" $opts }}
-```
-
-Add multiple headers using a slice:
-
-```go-html-template
-{{ $opts := dict "X-List" (slice "a" "b" "c") }}
-{{ $data := getJSON "https://example.org/books.json" $opts }}
-```
-
-## Global resource alternative
-
-Consider using the [`resources.Get`](/functions/resources/get/) function with [`transform.Unmarshal`] when accessing a global resource.
-
-```text
-my-project/
-└── assets/
- └── data/
- └── books.json
-```
-
-```go-html-template
-{{ $data := dict }}
-{{ $p := "data/books.json" }}
-{{ with resources.Get $p }}
- {{ $data = . | transform.Unmarshal }}
-{{ else }}
- {{ errorf "Unable to get resource %q" $p }}
-{{ end }}
-```
-
-## Page resource alternative
-
-Consider using the [`Resources.Get`][/methods/page/resources/] method with [`transform.Unmarshal`] when accessing a page resource.
-
-```text
-my-project/
-└── content/
- └── posts/
- └── reading-list/
- ├── books.json
- └── index.md
-```
-
-```go-html-template
-{{ $data := dict }}
-{{ $p := "books.json" }}
-{{ with .Resources.Get $p }}
- {{ $data = . | transform.Unmarshal }}
-{{ else }}
- {{ errorf "Unable to get resource %q" $p }}
-{{ end }}
-```
-
-## Remote resource alternative
-
-Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control.
-
-```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 }}
-```
-
-[`resources.GetRemote`]: /functions/resources/getremote/
-
-<!-- markdownlint-disable MD053 -->
-[`transform.Unmarshal`]: /functions/transform/unmarshal/
-<!-- markdownlint-enable MD053 -->
+++ /dev/null
----
-title: Data functions
-linkTitle: data
-description: Use these functions to read local or remote data files.
-categories: []
-keywords: []
----
aliases: [/functions/warnidf]
---
-{{< new-in 0.123.0 />}}
-
{{% include "/_common/functions/fmt/format-string.md" %}}
The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your site configuration.
{{% include "/_common/functions/truthy-falsy.md" %}}
+The `and` function evaluates the arguments from left to right, and returns when the result is determined.
+
```go-html-template
{{ and 1 0 "" }} → 0 (int)
{{ and 1 false 0 }} → false (bool)
{{ and 1 2 3 }} → 3 (int)
{{ and "a" "b" "c" }} → c (string)
{{ and "a" 1 true }} → true (bool)
+
+{{ and false (math.Div 1 0) }} → false (bool)
```
+
+{{% include "/_common/functions/go-template/text-template.md" %}}
{{% include "/_common/functions/truthy-falsy.md" %}}
+The `or` function evaluates the arguments from left to right, and returns when the result is determined.
+
```go-html-template
-{{ or 0 1 2 }} → 1
-{{ or false "a" 1 }} → a
-{{ or 0 true "a" }} → true
+{{ or 0 1 2 }} → 1 (int)
+{{ or false "a" 1 }} → a (string)
+{{ or 0 true "a" }} → true (bool)
+
+{{ or false "" 0 }} → 0 (int)
+{{ or 0 "" false }} → false (bool)
-{{ or false "" 0 }} → 0
-{{ or 0 "" false }} → false
+{{ or true (math.Div 1 0) }} → true (bool)
```
{{% include "/_common/functions/go-template/text-template.md" %}}
### Integers
-{{< new-in 0.123.0 />}}
-
Ranging over a positive integer `n` executes the block `n` times, with the context starting at zero and incrementing by one in each iteration.
```go-html-template
---
```go-html-template
-{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.152.2">
+{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.155.3">
```
signatures: [hugo.IsMultihost]
---
-{{< new-in 0.124.0 />}}
-
Site configuration:
{{< code-toggle file=hugo >}}
signatures: [hugo.IsMultilingual]
---
-{{< new-in 0.124.0 />}}
-
Site configuration:
{{< code-toggle file=hugo >}}
---
```go-html-template
-{{ hugo.Version }} → 0.152.2
+{{ hugo.Version }} → 0.155.3
```
---
title: images.AutoOrient
-description: Returns an image filter that rotates and flips an image as needed per its EXIF orientation tag.
+description: Returns an image filter that rotates and flips an image as needed per its Exif orientation tag.
categories: []
keywords: []
params:
signatures: ['images.Dither [OPTIONS]']
---
-{{< new-in 0.123.0 />}}
-
## Options
colors
-: (`string array`) A slice of two or more colors that make up the dithering palette, each expressed as an RGB or RGBA [hexadecimal] value, with or without a leading hash mark. The default values are opaque black (`000000ff`) and opaque white (`ffffffff`).
+: (`[]string`) A slice of two or more colors that make up the dithering palette, each expressed as an RGB or RGBA [hexadecimal] value, with or without a leading hash mark. The default values are opaque black (`000000ff`) and opaque white (`ffffffff`).
[hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
title: images.Filter
description: Applies one or more image filters to the given image resource.
categories: []
-keywords: []
+keywords: [filter]
params:
functions_and_methods:
aliases: []
---
title: images.Process
-description: Returns an image filter that processes the given image using the given specification.
+description: Returns an image filter that processes an image according to the given processing specification.
categories: []
-keywords: []
+keywords: [process]
params:
functions_and_methods:
aliases: []
returnType: images.filter
- signatures: [images.Process SPEC]
+ signatures: [images.Process SPECIFICATION]
---
-This filter has the same options as the [`Process`] method on a `Resource` object, but using it as a filter may be more effective if you need to apply multiple filters to an image.
-
-[`Process`]: /methods/resource/process/
-
-The process specification is a space-delimited, case-insensitive list of one or more of the following in any sequence:
-
-action
-: Specify zero or one of `crop`, `fill`, `fit`, or `resize`. If you specify an action you must also provide dimensions. See [details](content-management/image-processing/#image-processing-methods).
-
-```go-html-template
-{{ $filter := images.Process "resize 300x" }}
-```
-
-dimensions
-: Required if you specify an action. Provide width _or_ height when using `resize`, else provide both width _and_ height. See [details](/content-management/image-processing/#dimensions).
-
-```go-html-template
-{{ $filter := images.Process "crop 200x200" }}
-```
-
-anchor
-: Use with the `crop` or `fill` action. Specify zero or one of `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. Default is `Smart`. See [details](/content-management/image-processing/#anchor).
+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
-{{ $filter := images.Process "crop 200x200 center" }}
+{{ 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 }}
```
-rotation
-: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See [details](/content-management/image-processing/#rotation).
-
-```go-html-template
-{{ $filter := images.Process "r90" }}
-{{ $filter := images.Process "crop 200x200 center r90" }}
-```
-
-target format
-: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See [details](/content-management/image-processing/#target-format).
-
-```go-html-template
-{{ $filter := images.Process "webp" }}
-{{ $filter := images.Process "crop 200x200 center r90 webp" }}
-```
+In the example above, `"crop 200x200 TopRight webp q50"` is the _processing specification_.
-quality
-: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See [details](/content-management/image-processing/#quality).
-
-```go-html-template
-{{ $filter := images.Process "q50" }}
-{{ $filter := images.Process "crop 200x200 center r90 webp q50" }}
-```
-
-hint
-: Applicable to WebP images and equivalent to the `-preset` flag for the [`cwebp`] encoder. Specify zero or one of `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`. See [details](/content-management/image-processing/#hint).
-
-[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
-
-```go-html-template
-{{ $filter := images.Process "webp" "icon" }}
-{{ $filter := images.Process "crop 200x200 center r90 webp q50 icon" }}
-```
-
-background color
-: When converting a PNG or WebP with transparency to a format that does not support transparency, optionally specify a background color using a 3-digit or a 6-digit hexadecimal color code. Default is `#ffffff` (white). See [details](/content-management/image-processing/#background-color).
-
-```go-html-template
-{{ $filter := images.Process "jpeg #000" }}
-{{ $filter := images.Process "crop 200x200 center r90 q50 jpeg #000" }}
-```
-
-resampling filter
-: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See [details](/content-management/image-processing/#resampling-filter).
-
-```go-html-template
-{{ $filter := images.Process "resize 300x lanczos" }}
-{{ $filter := images.Process "resize 300x r90 q50 jpeg #000 lanczos" }}
-```
+{{% include "/_common/methods/resource/processing-spec.md" %}}
## Usage
Create a filter:
```go-html-template
-{{ $filter := images.Process "resize 256x q40 webp" }}
+{{ $filter := images.Process "crop 200x200 TopRight webp q50" }}
```
{{% include "/_common/functions/images/apply-image-filter.md" %}}
src="images/examples/zion-national-park.jpg"
alt="Zion National Park"
filter="Process"
- filterArgs="resize 256x q40 webp"
+ filterArgs="crop 200x200 TopRight webp q50"
example=true
>}}
+
+[`Filter`]: /methods/resource/filter/
+[`images.Filter`]: /functions/images/filter
+[processing specification]: #processing-specification
If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string.
> [!note]
-> To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site.
+> To list missing and fallback translations, set [`printI18nWarnings`][] to `true` in your site configuration, or use the `--printI18nWarnings` flag when building your site.
>
> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`][] to `true` in your site configuration.
```text
i18n/en.toml
-i18n/en-US.toml
+i18n/pt-BR.toml
```
-The base name must match the [language key][] as defined in your site configuration.
+The base name must match the [`languageCode`][] or [language key][] as defined in your site configuration. Hugo selects the translation table based on the `languageCode`, 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:
[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
[`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders
+[`languageCode`]: /configuration/languages/#languagecode
+[`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]: https://datatracker.ietf.org/doc/html/rfc5646
[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
---
title: openapi3.Unmarshal
-description: Unmarshals the given resource into an OpenAPI 3 document.
+description: Unmarshals the given resource into an OpenAPI 3 Description.
categories: []
keywords: []
params:
functions_and_methods:
aliases: []
returnType: openapi3.OpenAPIDocument
- signatures: ['openapi3.Unmarshal RESOURCE']
+ signatures: ['openapi3.Unmarshal RESOURCE [OPTIONS]']
---
-Use the `openapi3.Unmarshal` function with [global resources](g), [page resources](g), or [remote resources](g).
+The resource passed to the `openapi3.Unmarshal` function must be an [OpenAPI Document][], typically in JSON or YAML format. This resource can be a [global resource](g) or a [remote resource](g).
-[OpenAPI]: https://www.openapis.org/
+This function automatically resolves and includes all external references, both local and remote, and returns a complete [OpenAPI Description][] that fully describes the surface of an API and its semantics.
-For example, to work with a remote [OpenAPI] definition:
+## Options
-```go-html-template
-{{ $url := "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json" }}
+{{< new-in 0.153.0 />}}
+
+getremote
+: (`map`) This is a map of the options for the [`resources.GetRemote`][] function, useful when an OpenAPI Document includes remote external references.
+
+## Examples
+
+### Remote resource
+
+To work with a remote resource:
+
+```go-html-template {copy=true}
{{ $api := "" }}
-{{ with try (resources.GetRemote $url) }}
+{{ $url := "https://petstore.swagger.io/v2/swagger.json" }}
+{{ $opts := dict
+ "headers" (dict "Authorization" "Bearer abcd")
+}}
+{{ with try (resources.GetRemote $url $opts) }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else with .Value }}
- {{ $api = . | openapi3.Unmarshal }}
+ {{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ end }}
```
-To inspect the data structure:
+In the example above, the same HTTP Authorization header is used for both the initial remote request made by the `resources.GetRemote` function and for subsequent requests by the `openapi.Unmarshal` function as it retrieve remote external references.
+
+### Global resource
+
+To work with a global resource:
+
+```go-html-template {copy=true}
+{{ $api := "" }}
+{{ $opts := dict
+ "method" "post"
+ "key" now.UnixNano
+}}
+{{ with resources.Get "api/petstore.json" }}
+ {{ $api = openapi3.Unmarshal . (dict "getremote" $opts) }}
+{{ end }}
+```
+
+For global resources, local external reference paths starting with `/` are resolved relative to the `assets` directory. All other local paths are resolved relative to the entry point. In the example above, local paths are resolved relative to `assets/api/petstore.json`.
-```go-html-template
+## Inspection
+
+> [!note]
+> The unmarshaled data structure is created with [`kin-openapi`](https://github.com/getkin/kin-openapi). Many fields are structs or pointers (not maps), and therefore require accessors or other methods for indexing and iteration.
+> For example, prior to [`kin-openapi` v0.122.0](https://github.com/getkin/kin-openapi#v01220) / [Hugo v0.121.0](https://github.com/gohugoio/hugo/releases/tag/v0.121.0), `Paths` was a map (so `.Paths` was iterable) and it is now a pointer (and requires the `.Paths.Map` accessor, as in the example above).
+> See the [`kin-openapi` godoc for OpenAPI 3](https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3) for full type definitions.
+
+To inspect the unmarshaled data structure:
+
+```go-html-template {copy=true}
<pre>{{ debug.Dump $api }}</pre>
```
To list the GET and POST operations for each of the API paths:
-```go-html-template
+```go-html-template {copy=true}
{{ range $path, $details := $api.Paths.Map }}
<p>{{ $path }}</p>
<dl>
{{ end }}
```
-> [!warning]
-> The unmarshaled data structure is created with [`kin-openapi`](https://github.com/getkin/kin-openapi). Many fields are structs or pointers (not maps), and therefore require accessors or other methods for indexing and iteration.
-> For example, prior to [`kin-openapi` v0.122.0](https://github.com/getkin/kin-openapi#v01220) / [Hugo v0.121.0](https://github.com/gohugoio/hugo/releases/tag/v0.121.0), `Paths` was a map (so `.Paths` was iterable) and it is now a pointer (and requires the `.Paths.Map` accessor, as in the example above).
-> See the [`kin-openapi` godoc for OpenAPI 3](https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3) for full type definitions.
-
Hugo renders this to:
```html
<dd>Info for a specific pet</dd>
</dl>
```
+
+[`resources.GetRemote`]: /functions/resources/getremote/#options
+[OpenAPI Document]: https://swagger.io/specification/#openapi-document
+[OpenAPI Description]: https://swagger.io/specification/#openapi-description
--- /dev/null
+---
+title: reflect.IsImageResource
+description: Reports whether the given value is a Resource object representing a processable image.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsImageResource INPUT]
+---
+
+{{< new-in 0.154.0 />}}
+
+{{% glossary-term "processable image" %}}
+
+With this project structure:
+
+```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
+{{ end }}
+```
+
+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 }}
+```
--- /dev/null
+---
+title: reflect.IsPage
+description: Reports whether the given value is a Page object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsPage INPUT]
+---
+
+{{< new-in 0.154.0 />}}
+
+```go-html-template {file="layouts/page.html"}
+{{ with site.GetPage "/examples" }}
+ {{ reflect.IsPage . }} → true
+{{ end }}
+
+{{ with .Site }}
+ {{ reflect.IsPage . }} → false
+{{ end }}
+```
--- /dev/null
+---
+title: reflect.IsResource
+description: Reports whether the given value is a Resource object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsResource INPUT]
+---
+
+{{< new-in 0.154.0 />}}
+
+With this project structure:
+
+```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.IsResource` function:
+
+```go-html-template {file="layouts/page.html"}
+{{ with resources.Get "a.json" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+
+{{ with resources.Get "b.avif" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+
+{{ with resources.Get "c.jpg" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+```
+
+```go-html-template {file="layouts/page.html"}
+{{ with .Resources.Get "d.json" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+
+{{ with .Resources.Get "e.avif" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+
+{{ with .Resources.Get "f.jpg" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+```
+
+```go-html-template {file="layouts/page.html"}
+{{ with site.GetPage "/example" }}
+ {{ reflect.IsResource . }} → true
+{{ end }}
+```
--- /dev/null
+---
+title: reflect.IsSite
+description: Reports whether the given value is a Site object.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsSite INPUT]
+---
+
+{{< new-in 0.154.0 />}}
+
+```go-html-template {file="layouts/page.html"}
+{{ with .Site }}
+ {{ reflect.IsSite . }} → true
+{{ end }}
+
+{{ with site.GetPage "/examples" }}
+ {{ reflect.IsSite . }} → false
+{{ end }}
+```
```json
{
- "build_date": "2025-07-08T13:12:19-07:00",
- "hugo_version": "0.152.2",
- "last_modified": "2025-07-07T22:09:13-07:00"
+ "build_date": "2026-01-11T11:27:49-08:00",
+ "hugo_version": "0.155.3",
+ "last_modified": "2026-01-11T11:27:59-08:00"
}
```
>
> For page resources, use the [`Resources.GetMatch`] method on a `Page` object.
-Hugo determines a match using a case-insensitive [glob](g) pattern.
+Hugo determines a match using a case-insensitive [glob pattern](g).
{{% include "/_common/glob-patterns.md" %}}
signatures: [strings.Diff OLDNAME OLD NEWNAME NEW]
---
-{{< new-in 0.125.0 />}}
-
Use `strings.Diff` to compare two strings and render a highlighted diff:
```go-html-template
--- /dev/null
+---
+title: templates.Inner
+description: Executes the content block enclosed by a partial call.
+categories: []
+keywords: [decorator]
+params:
+ functions_and_methods:
+ aliases: [inner]
+ returnType: any
+ signatures: ['templates.Inner [CONTEXT]']
+---
+
+{{< new-in 0.154.0 />}}
+
+The `templates.Inner` function defines the injection point for code nested within a block style partial call. This is the core mechanism used to create a [partial decorator][].
+
+## Overview
+
+The `templates.Inner` function acts as a placeholder within a partial template. When a partial is called as a decorator, it captures a block of code from the calling template rather than rendering it immediately. The `templates.Inner` function tells Hugo exactly where to inject that captured content.
+
+This signals a reversal of execution where the callee becomes the caller. The partial manages the outer structure while the calling template remains in control of the inner content.
+
+## Usage
+
+To use this function, the calling template must use the block style syntax with a [`with`][] statement. This allows decorators to be deeply nested.
+
+```go-html-template {file="layouts/home.html"}
+{{ with partial "components/card.html" . }}
+ <p>This content is passed to the partial.</p>
+{{ end }}
+```
+
+Inside the partial, call `templates.Inner` to render the captured block.
+
+```go-html-template {file="layouts/_partials/components/card.html"}
+<div class="card-frame">
+ {{ templates.Inner . }}
+</div>
+```
+
+## Arguments
+
+The function accepts one optional argument: the [context](g). This argument determines the value of the dot (`.`) inside the captured block when it is rendered.
+
+- If you provide an argument, such as `{{ templates.Inner .SomeData }}`, the dot inside the captured block is rebound to that specific data.
+- If you do not provide an argument, the captured block uses the context of the caller where the partial was first invoked.
+
+## Context and scope
+
+When using decorators, the `with` statement creates a new [scope](g). Variables defined outside the with block in the calling template are not automatically available inside the captured block.
+
+By passing a context to `templates.Inner`, you ensure that the injected content has access to the correct data even when nested inside multiple layers of wrappers. This is critical when the decorator is used inside a loop or a specific data overlay.
+
+## Repeated execution
+
+A decorator can execute the captured content zero or more times. This is useful when the wrapper needs to repeat the same decoration for a collection of items, such as a list or a grid.
+
+```go-html-template {file="layouts/_partials/list-decorator.html"}
+<ul class="styled-list">
+ {{ range .items }}
+ <li>
+ {{ templates.Inner . }}
+ </li>
+ {{ end }}
+</ul>
+```
+
+In this example, the code provided by the caller is rendered once for every item in the .items collection, with the dot . updated to the current item in each iteration.
+
+[`with`]: /functions/go-template/with/
+[partial decorator]: /templates/partial-decorators/
In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
+ > [!note]
+ > This conditional approach only identifies math on the current page. Mathematical expressions will not display correctly when one page's content is embedded within another. For example, if a [list page](g) calls the [`Content`][] or [`Summary`][] methods while ranging through its page collection, the list page will not load the KaTeX CSS.
+ >
+ > If this affects your site, use this conditional logic instead:
+ >
+ > ```go-html-template {file="layouts/baseof.html" copy=true}
+ > {{ $noop := .WordCount }}
+ > {{ if or (.Page.Store.Get "hasMath") .IsNode }}
+ > <link rel="stylesheet" href="...">
+ > {{ end }}
+ > ```
+
Step 4
: Add some mathematical markup to your content, then test.
$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+[`Content`]: /methods/page/content/
+[`Summary`]: /methods/page/summary/
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
[KaTeX]: https://katex.org/
[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
--- /dev/null
+---
+title: urls.PathEscape
+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.PathEscape INPUT]
+---
+
+{{< new-in v0.153.0 />}}
+
+The `urls.PathEscape` function does the inverse transformation of [`urls.PathUnescape`][].
+
+```go-html-template
+{{ urls.PathEscape "A/b/c?d=é&f=g+h" }} → A%2Fb%2Fc%3Fd=%C3%A9&f=g+h
+```
+
+[`urls.PathUnescape`]: /functions/urls/PathUnescape/
--- /dev/null
+---
+title: urls.PathUnescape
+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.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
+```
+
+[`urls.PathEscape`]: /functions/urls/PathEscape/
categories: []
keywords: []
params:
- minVersion: v0.128.0
+ minVersion: v0.146.0
weight: 10
aliases: [/quickstart/,/overview/quickstart/]
---
You should see something like:
```text
-hugo v0.152.2-6abdacad3f3fe944ea42177844469139e81feda6+extended linux/amd64 BuildDate=2025-10-24T15:31:49Z VendorInfo=gohugoio
+hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio
```
## Display available commands
- The `publishDate` is in the future
- The `expiryDate` is in the past
-{{< new-in 0.123.0 />}}
-
> [!note]
> Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
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 using a [CI/CD](g) workflow, where a push[^1] to their GitHub or GitLab repository triggers a build and deployment. Popular providers include [AWS Amplify], [CloudCannon], [Cloudflare Pages], [GitHub Pages], [GitLab Pages], and [Netlify].
-
-Learn more in the [host and deploy] section.
+Most of our users deploy their sites to a [CI/CD](g) platform, where a push[^1] to their remote Git repository triggers a build and deployment. Learn more in the [host and deploy] section.
[^1]: The Git repository contains the entire project directory, typically excluding the `public` directory because the site is built _after_ the push.
[`hugo server`]: /commands/hugo_server/
[`hugo`]: /commands/hugo/
[`publishDir`]: /configuration/all/#publishdir
-[AWS Amplify]: https://aws.amazon.com/amplify/
[build options]: /content-management/build-options/
-[CloudCannon]: https://cloudcannon.com/
-[Cloudflare Pages]: https://pages.cloudflare.com/
[front matter]: /content-management/front-matter/
-[GitHub Pages]: https://pages.github.com/
-[GitLab Pages]: https://docs.gitlab.com/ee/user/project/pages/
[host and deploy]: /host-and-deploy/
[installing]: /installation/
[LiveReload]: https://github.com/livereload/livereload-js
-[Netlify]: https://www.netlify.com/
env:
variables:
# Application versions
- DART_SASS_VERSION: 1.96.0
- GO_VERSION: 1.25.5
- HUGO_VERSION: 0.152.2
+ DART_SASS_VERSION: 1.97.3
+ GO_VERSION: 1.25.6
+ HUGO_VERSION: 0.155.3
# Time zone
TZ: Europe/Oslo
# Cache
main() {
- DART_SASS_VERSION=1.96.0
- GO_VERSION=1.25.5
- HUGO_VERSION=0.152.2
- NODE_VERSION=24.12.0
+ DART_SASS_VERSION=1.97.3
+ GO_VERSION=1.25.6
+ HUGO_VERSION=0.155.3
+ NODE_VERSION=24.13.0
export TZ=Europe/Oslo
build:
runs-on: ubuntu-latest
env:
- DART_SASS_VERSION: 1.96.0
- GO_VERSION: 1.25.5
- HUGO_VERSION: 0.152.2
- NODE_VERSION: 24.12.0
+ DART_SASS_VERSION: 1.97.3
+ GO_VERSION: 1.25.6
+ HUGO_VERSION: 0.155.3
+ NODE_VERSION: 24.13.0
TZ: Europe/Oslo
steps:
- name: Checkout
- uses: actions/checkout@v5
+ uses: actions/checkout@v6
with:
submodules: recursive
fetch-depth: 0
- name: Setup Go
- uses: actions/setup-go@v5
+ uses: actions/setup-go@v6
with:
go-version: ${{ env.GO_VERSION }}
cache: false
- name: Setup Node.js
- uses: actions/setup-node@v4
+ uses: actions/setup-node@v6
with:
node-version: ${{ env.NODE_VERSION }}
- name: Setup Pages
git config core.quotepath false
- name: Cache restore
id: cache-restore
- uses: actions/cache/restore@v4
+ uses: actions/cache/restore@v5
with:
path: ${{ runner.temp }}/hugo_cache
key: hugo-${{ github.run_id }}
--cacheDir "${{ runner.temp }}/hugo_cache"
- name: Cache save
id: cache-save
- uses: actions/cache/save@v4
+ uses: actions/cache/save@v5
with:
path: ${{ runner.temp }}/hugo_cache
key: ${{ steps.cache-restore.outputs.cache-primary-key }}
```yaml {file=".gitlab-ci.yml" copy=true}
variables:
# Application versions
- DART_SASS_VERSION: 1.96.0
- HUGO_VERSION: 0.152.2
- NODE_VERSION: 24.12.0
+ DART_SASS_VERSION: 1.97.3
+ HUGO_VERSION: 0.155.3
+ NODE_VERSION: 24.13.0
# Git
GIT_DEPTH: 0
GIT_STRATEGY: clone
TZ: Europe/Oslo
image:
- name: golang:1.25.5-bookworm
+ name: golang:1.25.6-bookworm
pages:
stage: deploy
```text {file="netlify.toml" copy=true}
[build.environment]
- DART_SASS_VERSION = "1.96.0"
- GO_VERSION = "1.25.5"
- HUGO_VERSION = "0.152.2"
- NODE_VERSION = "24.12.0"
+ DART_SASS_VERSION = "1.97.3"
+ GO_VERSION = "1.25.6"
+ HUGO_VERSION = "0.155.3"
+ NODE_VERSION = "24.13.0"
TZ = "Europe/Oslo"
[build]
```text {file="netlify.toml" copy=true}
[build.environment]
- DART_SASS_VERSION = "1.96.0"
- GO_VERSION = "1.25.5"
- HUGO_VERSION = "0.152.2"
- NODE_VERSION = "24.12.0"
+ DART_SASS_VERSION = "1.97.3"
+ GO_VERSION = "1.25.6"
+ HUGO_VERSION = "0.155.3"
+ NODE_VERSION = "24.13.0"
TZ = "Europe/Oslo"
[build]
staticPublishPath: public
envVars:
- key: DART_SASS_VERSION
- value: 1.96.0
+ value: 1.97.3
- key: GO_VERSION
- value: 1.25.5
+ value: 1.25.6
- key: HUGO_VERSION
- value: 0.152.2
+ value: 0.155.3
- key: NODE_VERSION
- value: 24.12.0
+ value: 24.13.0
- key: TZ
value: Europe/Oslo
```
## Assumptions
-- Working familiarity with [Git] or [Mercurial] for version control
-- Completion of the Hugo [Quick Start]
-- A [SourceHut account]
+- 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/
## BaseURL
-The [`baseURL`] in your site 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.
+The [`baseURL`][] in your site 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:
+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/
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:
+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
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.97.1 # Latest version as of 20/12/2025
+ 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
+ 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
main() {
- DART_SASS_VERSION=1.96.0
- GO_VERSION=1.25.5
- HUGO_VERSION=0.152.2
- NODE_VERSION=24.12.0
+ DART_SASS_VERSION=1.97.3
+ GO_VERSION=1.25.6
+ HUGO_VERSION=0.155.3
+ NODE_VERSION=24.13.0
export TZ=Europe/Oslo
- You can run `hugo mod vendor` on any level in the module tree.
- Vendoring will not store modules stored in your `themes` directory.
-- Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the given [glob](g) pattern.
+- Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the given [glob pattern](g).
Also see the [CLI Doc](/commands/hugo_mod_vendor/).
weight: 40
---
-## Editions
-
{{% include "/_common/installation/01-editions.md" %}}
-Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition.
-
{{% include "/_common/installation/02-prerequisites.md" %}}
{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
weight: 20
---
-## Editions
-
{{% include "/_common/installation/01-editions.md" %}}
-Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition.
-
{{% include "/_common/installation/02-prerequisites.md" %}}
{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
## Package managers
+<!--
### Snap
[Snap] is a free and open-source package manager for Linux. Available for [most distributions], snap packages are simple to install and are automatically updated.
sudo snap disconnect hugo:ssh-keys
```
+[strictly confined]: https://snapcraft.io/docs/snap-confinement
+[most distributions]: https://snapcraft.io/docs/installing-snapd
+[Snap]: https://snapcraft.io/
+-->
+
{{% include "/_common/installation/homebrew.md" %}}
## Repository packages
[Linux Lite]: https://www.linuxliteos.com/
[Linux Mint]: https://linuxmint.com/
[Manjaro]: https://manjaro.org/
-[most distributions]: https://snapcraft.io/docs/installing-snapd
[MX Linux]: https://mxlinux.org/
[openSUSE]: https://www.opensuse.org/
[Pop!_OS]: https://pop.system76.com/
[Red Hat Enterprise Linux]: https://www.redhat.com/
-[Snap]: https://snapcraft.io/
[Solus]: https://getsol.us/
-[strictly confined]: https://snapcraft.io/docs/snap-confinement
[Ubuntu]: https://ubuntu.com/
[USE]: https://packages.gentoo.org/packages/www-apps/hugo
[Void Linux]: https://voidlinux.org/
weight: 10
---
-## Editions
-
{{% include "/_common/installation/01-editions.md" %}}
-Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition.
-
{{% include "/_common/installation/02-prerequisites.md" %}}
{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
> [!note]
> Hugo v0.121.1 and later require at least Windows 10 or Windows Server 2016.
-## Editions
-
{{% include "/_common/installation/01-editions.md" %}}
-Unless your specific deployment needs require the extended/deploy edition, we recommend the extended edition.
-
{{% include "/_common/installation/02-prerequisites.md" %}}
{{% include "/_common/installation/03-prebuilt-binaries.md" %}}
--- /dev/null
+---
+title: MediaType
+description: Returns the media type of the given output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: media.Type
+ signatures: [OUTPUTFORMAT.MediaType]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ with .MediaType }}
+ {{ .Type }} → application/rss+xml
+ {{ .MainType }} → application
+ {{ .SubType }} → rss
+ {{ end }}
+{{ end }}
+```
+
+## Methods
+
+### MainType
+
+(`string`) Returns the main type of the output format's media type.
+
+### SubType
+
+(`string`) Returns the subtype of the current format's media type.
+
+### Type
+
+(`string`) Returns the the current format's media type.
--- /dev/null
+---
+title: Name
+description: Returns the identifier of the given output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [OUTPUTFORMAT.Name]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .Name }} → rss
+{{ end }}
+```
--- /dev/null
+---
+title: Permalink
+description: Returns the permalink of the page generated by the current output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [OUTPUTFORMAT.Permalink]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .Permalink }} → https://example.org/index.xml
+{{ end }}
+```
--- /dev/null
+---
+title: Rel
+description: Returns the rel value of the given output format, either the default or as defined in the site configuration.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [OUTPUTFORMAT.Rel]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .Rel }} → alternate
+{{ end }}
+```
--- /dev/null
+---
+title: RelPermalink
+description: Returns the relative permalink of the page generated by the current output format.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: string
+ signatures: [OUTPUTFORMAT.RelPermalink]
+---
+
+{{% include "/_common/methods/output-formats/to-use-this-method.md" %}}
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .RelPermalink }} → /index.xml
+{{ end }}
+```
--- /dev/null
+---
+title: Output format methods
+linkTitle: Output format
+description: Use these methods with an OutputFormat object.
+categories: []
+keywords: []
+---
---
title: Aliases
-description: Returns the URL aliases as defined in front matter.
+description: Returns the aliases defined in front matter as server-relative URLs, resolved according to the current content dimension.
categories: []
keywords: []
params:
signatures: [PAGE.Aliases]
---
-The `Aliases` method on a `Page` object returns the URL [aliases] as defined in front matter.
+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).
-For example:
+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.
-{{< code-toggle file=content/about.md fm=true >}}
-title = 'About'
-aliases = ['/old-url','/really-old-url']
+## 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/` |
+
+### Site configuration
+
+To implement this, you must update your site 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 = 'en-US'
+ languageDirection = 'ltr'
+ languageName = 'English'
+ weight = 1
+ title = 'My Site in English'
+
+[languages.de]
+ languageCode = 'de-DE'
+ languageDirection = 'ltr'
+ languageName = '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 >}}
-To list the aliases:
+### 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 not (hugo.Store.Get "has_printed_redirects") -}}
+ {{- range .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 -}}
+ {{- hugo.Store.Set "has_printed_redirects" true -}}
+{{- 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:
-```go-html-template
-{{ range .Aliases }}
- {{ . }}
-{{ end }}
+```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/urls/#aliases
+[`aliases`]: /content-management/front-matter/#aliases
+[`strings.FindRE`]: /functions/strings/findre/
+[media type]: /configuration/media-types/
+[output format]: /configuration/output-formats/
+[outputs]: /configuration/outputs/
The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page. See [details](/configuration/output-formats/).
-## Methods
-
-{{% include "/_common/methods/page/output-format-methods.md" %}}
-
-## Example
-
-Generate a `link` element in the `<head>` of each page for each of the alternative output formats:
+For example, to generate a `link` element for each of the alternative output formats:
```go-html-template
-<head>
- ...
- {{ $title := printf "%s | %s" .Title site.Title }}
- {{ if .IsHome }}
- {{ $title = site.Title }}
- {{ end }}
- {{ range .AlternativeOutputFormats }}
- {{ printf `<link rel=%q type=%q href=%q title=%q>` .Rel .MediaType.Type .Permalink $title | safeHTML }}
- {{ end }}
- ...
-</head>
+{{ range .AlternativeOutputFormats }}
+ {{ printf "<link rel=%q type=%q href=%q>" .Rel .MediaType.Type .Permalink | safeHTML }}
+{{ end }}
```
-On the site's home page, Hugo renders this to:
+Hugo renders this to something like:
```html
-<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml" title="ABC Widgets, Inc.">
+<link rel="alternate" type="application/rss+xml" href="https://example.org/index.xml">
+<link rel="alternate" type="application/json" href="https://example.org/index.json">
```
## Hosting considerations
-In a [CI/CD](g) environment, the step that clones your project repository must perform a deep clone. If the clone is shallow, the Git information for a given file may be inaccurate. It might incorrectly reflect the most recent repository commit, rather than the commit that actually modified the file.
+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.
signatures: [PAGE.Language]
---
-The `Language` method on a `Page` object returns the language object for the given page. The language object points to the language definition in the site configuration.
+The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration.
You can also use the `Language` method on a `Site` object. See [details].
## Methods
-The examples below assume the following in your site configuration:
+The examples below assume the following in the site configuration:
{{< code-toggle file=hugo >}}
[languages.de]
weight = 2
{{< /code-toggle >}}
+### IsDefault
+
+{{< new-in 0.153.0 />}}
+
+(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration.
+
+```go-html-template
+{{ .Language.IsDefault }} → true
+```
+
### Lang
-(`string`) The language tag as defined by [RFC 5646].
+(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration.
```go-html-template
{{ .Language.Lang }} → de
{{ .Language.LanguageName }} → Deutsch
```
+### Name
+
+(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key used in the site configuration. This is an alias for `Lang`.
+
+```go-html-template
+{{ .Site.Language.Name }} → de
+```
+
### Weight
(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.
{{ .Language.Weight }} → 2
```
+[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
[details]: /methods/site/language/
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
## Methods
-{{% include "/_common/methods/page/output-format-methods.md" %}}
+### Canonical
-## Example
+{{< new-in "0.154.4" />}}
-To link to the RSS feed for the current page:
+(`page.OutputFormat`) Returns the [canonical output format](g) for the current page, if defined. Once you have captured the object, use any of its [associated methods][].
```go-html-template
-{{ with .OutputFormats.Get "rss" }}
- <a href="{{ .RelPermalink }}">RSS Feed</a>
+{{ with .Site.Home.OutputFormats.Canonical }}
+ {{ .MediaType.Type }} → text/html
+ {{ .MediaType.MainType }} → text
+ {{ .MediaType.SubType }} → html
+ {{ .Name }} → html
+ {{ .Permalink }} → https://example.org/
+ {{ .Rel }} → canonical
+ {{ .RelPermalink }} → /
+{{ end }}
+```
+
+### Get
+
+(`page.OutputFormat`) Returns the `OutputFormat` object with the given identifier. Once you have captured the object, use any of its [associated methods][].
+
+```go-html-template
+{{ with .Site.Home.OutputFormats.Get "rss" }}
+ {{ .MediaType.Type }} → application/rss+xml
+ {{ .MediaType.MainType }} → application
+ {{ .MediaType.SubType }} → rss
+ {{ .Name }} → rss
+ {{ .Permalink }} → https://example.org/index.xml
+ {{ .Rel }} → alternate
+ {{ .RelPermalink }} → /index.xml
+{{ end }}
+```
+
+## Examples
+
+To render a `link` element pointing to the [canonical output format](g) for the current page:
+
+```go-html-template
+{{ with .OutputFormats.Canonical }}
+ {{ printf "<link rel=%q type=%q href=%q>" .Rel .MediaType.Type .Permalink | safeHTML }}
{{ end }}
```
-On the site's home page, Hugo renders this to:
+To render an anchor element pointing to the `rss` output format for the current page:
-```html
-<a href="/index.xml">RSS Feed</a>
+```go-html-template
+{{ with .OutputFormats.Get "rss" }}
+ <a href="{{ .RelPermalink }}">RSS Feed</a>
+{{ end }}
```
Please see the [link to output formats] section to understand the importance of the construct above.
+[associated methods]: /methods/output-format/
[link to output formats]: /configuration/output-formats/#link-to-output-formats
signatures: [PAGE.Path]
---
-{{< new-in 0.123.0 />}}
-
The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file.
{{% glossary-term "logical path" %}}
### GetMatch
-(`resource.Resource`) Returns the first page resource from paths matching the given [glob](g) pattern, or nil if none found.
+(`resource.Resource`) Returns the first page resource from paths matching the given [glob pattern](g), or nil if none found.
```go-html-template
{{ with .Resources.GetMatch "images/*.jpg" }}
### Match
-(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob](g) pattern, or nil if none found.
+(`resource.Resources`) Returns a collection of page resources from paths matching the given [glob pattern](g), or nil if none found.
```go-html-template
{{ range .Resources.Match "images/*.jpg" }}
## Pattern matching
-With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob](g) pattern.
+With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob pattern](g).
{{% include "/_common/glob-patterns.md" %}}
--- /dev/null
+---
+title: Rotate
+description: Returns a collection of all pages sharing the same identity across the specified dimension, including the current page, sorted by the dimension's weight.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.Pages
+ signatures: [PAGE.Rotate DIMENSION]
+---
+
+{{< new-in 0.153.0 />}}
+
+The `Rotate` method on a `Page` object returns a collection of all pages sharing the same identity across the specified [dimension](g), including the current page, sorted by the dimension's weight.
+
+The `DIMENSION` argument must be one of `language`, `role`, or `version`.
+
+To render a list of all translations of the current page, including the current page:
+
+```go-html-template
+{{ with .Rotate "language" }}
+ {{ range . }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+To render a list of all [roles](g) of the current page, including the current page:
+
+```go-html-template
+{{ with .Rotate "role" }}
+ {{ range . }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
+
+To render a list of all versions of the current page, including the current page:
+
+```go-html-template
+{{ with .Rotate "version" }}
+ {{ range . }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+ {{ end }}
+{{ end }}
+```
### Disable
-{{< new-in 0.125.0 />}}
-
(`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
```go-html-template
</ul>
```
-To render a link to the home page of the site corresponding to the default content language:
+To render a link to the home page of the [default site](g):
```go-html-template
{{ with .Sites.Default }}
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Resources.Colors` method returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image.
+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.
## Methods
### ColorHex
-{{< new-in 0.125.0 />}}
-
(`string`) Returns the [hexadecimal color] value, prefixed with a hash sign.
### Luminance
-{{< new-in 0.125.0 />}}
-
(`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.
> [!note]
---
title: Crop
-description: Applicable to images, returns an image resource cropped to the given dimensions without resizing.
+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 SPEC]
+ signatures: [RESOURCE.Crop SPECIFICATION]
---
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Crop an image to match the given dimensions without resizing. You must provide both width and height.
+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.
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Crop "200x200" }}
+ {{ 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 webp q85 lanczos" }}
+ {{ with .Crop "200x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
src="images/examples/zion-national-park.jpg"
alt="Zion National Park"
filter="Process"
- filterArgs="crop 200x200 topright webp q85 lanczos"
+ filterArgs="crop 200x200 TopRight"
example=true
>}}
+
+[processing specification]: #processing-specification
---
title: Exif
-description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an EXIF object containing image metadata.
+description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif metadata.
categories: []
-keywords: []
+keywords: ['metadata']
params:
functions_and_methods:
- returnType: exif.ExifInfo
+ returnType: meta.ExifInfo
signatures: [RESOURCE.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 [EXIF] object containing image metadata.
+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
### Lat
-(`float64`) Returns the GPS latitude in degrees.
+(`float64`) Returns the GPS latitude in degrees from Exif metadata.
### Long
-(`float64`) Returns the GPS longitude in degrees.
+(`float64`) Returns the GPS longitude in degrees from Exif metadata.
### Tags
-(`exif.Tags`) Returns a collection of the available EXIF tags for this image. You may include or exclude specific tags from this collection. See [configure imaging].
-
-[configure imaging]: /configuration/imaging/#exif-data
+(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`includeFields`][] and [`excludeFields`][] settings in your site configuration.
## Examples
-To list the creation date, location, and EXIF tags:
+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 }}
- <p>Date: {{ .Date }}</p>
- <p>Lat/Long: {{ .Lat }}/{{ .Long }}</p>
- {{ with .Tags }}
- <p>Tags</p>
- <table>
- <thead>
- <tr><th>Tag</th><th>Value</th></tr>
- </thead>
- <tbody>
- {{ range $k, $v := . }}
- <tr><td>{{ $k }}</td><td>{{ $v }}</td></tr>
- {{ end }}
- </tbody>
- </table>
- {{ end }}
+ <pre>
+ {{ range $k, $v := .Tags -}}
+ {{ printf "%-25s %v\n" $k $v }}
+ {{ end }}
+ </pre>
{{ end }}
{{ end }}
```
-To list specific values:
+To list specific Exif fields:
```go-html-template
{{ with resources.Get "images/a.jpg" }}
{{ with .Exif }}
- <ul>
- {{ with .Date }}<li>Date: {{ .Format "January 02, 2006" }}</li>{{ end }}
- {{ with .Tags.ApertureValue }}<li>Aperture: {{ lang.FormatNumber 2 . }}</li>{{ end }}
- {{ with .Tags.BrightnessValue }}<li>Brightness: {{ lang.FormatNumber 2 . }}</li>{{ end }}
- {{ with .Tags.ExposureTime }}<li>Exposure Time: {{ . }}</li>{{ end }}
- {{ with .Tags.FNumber }}<li>F Number: {{ . }}</li>{{ end }}
- {{ with .Tags.FocalLength }}<li>Focal Length: {{ . }}</li>{{ end }}
- {{ with .Tags.ISOSpeedRatings }}<li>ISO Speed Ratings: {{ . }}</li>{{ end }}
- {{ with .Tags.LensModel }}<li>Lens Model: {{ . }}</li>{{ end }}
- </ul>
+ <pre>
+ {{ with .Tags.ApertureValue }}{{ printf "%-25s %v\n" "ApertureValue" . }}{{ end }}
+ {{ with .Tags.BrightnessValue }}{{ printf "%-25s %v\n" "BrightnessValue" . }}{{ end }}
+ </pre>
{{ end }}
{{ end }}
```
-[exif]: https://en.wikipedia.org/wiki/Exif
+[`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
---
title: Fill
-description: Applicable to images, returns an image resource cropped and resized to the given dimensions.
+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 SPEC]
+ signatures: [RESOURCE.Fill SPECIFICATION]
---
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Crop and resize an image to match the given dimensions. You must provide both width and height.
+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.
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Fill "200x200" }}
+ {{ with .Fill "500x200 TopRight lanczos" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```
+In the example above, `"500x200 TopRight lanczos"` is the _processing specification_.
+
{{% include "/_common/methods/resource/processing-spec.md" %}}
## Example
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Fill "200x200 top webp q85 lanczos" }}
+ {{ with .Fill "500x200 TopRight lanczos webp q85" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
src="images/examples/zion-national-park.jpg"
alt="Zion National Park"
filter="Process"
- filterArgs="fill 200x200 top webp q85 lanczos"
+ filterArgs="fill 500x200 TopRight lanczos webp q85"
example=true
>}}
+
+[`Resize`]: /methods/resource/resize/
+[processing specification]: #processing-specification
title: Filter
description: Applicable to images, applies one or more image filters to the given image resource.
categories: []
-keywords: []
+keywords: [filter]
params:
+ alt_title: RESOURCE.Filter
functions_and_methods:
returnType: images.ImageResource
signatures: [RESOURCE.Filter FILTER...]
---
title: Fit
-description: Applicable to images, returns an image resource downscaled to fit the given dimensions while maintaining aspect ratio.
+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 SPEC]
+ signatures: [RESOURCE.Fit SPECIFICATION]
---
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Downscale an image to fit the given dimensions while maintaining aspect ratio. You must provide both width and height.
+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.
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Fit "200x200" }}
+ {{ with .Fit "300x175 lanczos" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```
+In the example above, `"300x175 lanczos"` is the _processing specification_.
+
{{% include "/_common/methods/resource/processing-spec.md" %}}
## Example
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Fit "300x175 webp q85 lanczos" }}
+ {{ with .Fit "300x175 lanczos" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
src="images/examples/zion-national-park.jpg"
alt="Zion National Park"
filter="Process"
- filterArgs="fit 300x175 webp q85 lanczos"
+ filterArgs="fit 300x175 lanczos"
example=true
>}}
+
+[`Resize`]: /methods/resource/resize/
+[`Fill`]: /methods/resource/fill/
+[processing specification]: #processing-specification
--- /dev/null
+---
+title: Meta
+description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif, IPTC, and XMP metadata.
+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" %}}
+
+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.
+
+To extract Exif metadata only, use the [`Exif`] 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, with a fallback to XMP metadata.
+
+### Long
+
+(`float64`) Returns the GPS longitude in degrees from Exif metadata, with a fallback to XMP metadata.
+
+### Orientation
+
+(`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]
+> 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 site 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 site 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 site configuration.
+
+## Examples
+
+To list the creation date, latitude, longitude, and orientation:
+
+```go-html-template
+{{ 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>
+ {{ end }}
+{{ end }}
+```
+
+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 }}
+```
+
+[`Exif`]: /methods/resource/exif/
+[`fields`]: /configuration/imaging/#fields
+[`images.AutoOrient`]: /functions/images/autoorient/
+[`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
---
title: Process
-description: Applicable to images, returns an image resource processed with the given specification.
+description: Applicable to images, returns a new image resource processed according to the given processing specification.
categories: []
-keywords: []
+keywords: [process]
params:
+ alt_title: RESOURCE.Process
functions_and_methods:
returnType: images.ImageResource
- signatures: [RESOURCE.Process SPEC]
+ signatures: [RESOURCE.Process SPECIFICATION]
---
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Process an image with the given specification. The specification can contain an optional action, one of `crop`, `fill`, `fit`, or `resize`. This means that you can use this method instead of [`Crop`], [`Fill`], [`Fit`], or [`Resize`].
+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.
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Process "crop 200x200" }}
+ {{ with .Process "crop 200x200 TopRight webp q50" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```
+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
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Process "crop 200x200 topright webp q85 lanczos" }}
+ {{ with .Process "crop 200x200 TopRight webp q50" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
src="images/examples/zion-national-park.jpg"
alt="Zion National Park"
filter="Process"
- filterArgs="crop 200x200 topright webp q85 lanczos"
+ filterArgs="crop 200x200 TopRight webp q50"
example=true
>}}
-[`Crop`]: /methods/resource/crop/
-[`Fill`]: /methods/resource/fill/
-[`Fit`]: /methods/resource/fit/
-[`Resize`]: /methods/resource/resize/
[`images.Process`]: /functions/images/process/
+[processing specification]: #processing-specification
---
title: Resize
-description: Applicable to images, returns an image resource resized to the given width and/or height.
+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 SPEC]
+ signatures: [RESOURCE.Resize SPECIFICATION]
---
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Resize an image to the given width and/or height.
-
-If you specify both width and height, the resulting image will be disproportionally scaled unless the original image has the same aspect ratio.
+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.
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Resize "300x" }}
+ {{ with .Resize "300x lanczos" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```
+In the example above, `"300x lanczos"` is the _processing specification_.
+
{{% include "/_common/methods/resource/processing-spec.md" %}}
## Example
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Resize "300x webp q85 lanczos" }}
+ {{ with .Resize "300x lanczos" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
src="images/examples/zion-national-park.jpg"
alt="Zion National Park"
filter="Process"
- filterArgs="resize 300x webp q85 lanczos"
+ filterArgs="resize 300x lanczos"
example=true
>}}
+
+[processing specification]: #processing-specification
--- /dev/null
+---
+title: Dimension
+description: Returns the dimension object for the given dimension for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: page.SiteDimension
+ signatures: [SITE.Dimension DIMENSION]
+---
+
+{{< new-in 0.153.0 />}}
+
+The `Dimension` method on a `Site` object returns the dimension object for the given [dimension](g).
+
+The `DIMENSION` argument must be one of `language`, `role`, or `version`.
+
+Example|Returns|Equivalent to
+:--|:--|:--
+`{{ .Site.Dimension "language" }}`|`langs.Language`|`{{ .Site.Language }}`
+`{{ .Site.Dimension "role" }}`|`roles.Role`|`{{ .Site.Role }}`
+`{{ .Site.Dimension "version" }}`|`version.Version`|`{{ .Site.Version }}`
+
+```go-html-template
+{{ $languageObject := .Site.Dimension "language" }}
+{{ $languageObject.IsDefault }} → true
+{{ $languageObject.Name }} → en
+
+{{ $roleObject := .Site.Dimension "role" }}
+{{ $roleObject.IsDefault }} → true
+{{ $roleObject.Name }} → guest
+
+{{ $versionObject := .Site.Dimension "version" }}
+{{ $versionObject.IsDefault }} → true
+{{ $versionObject.Name }} → v1.0.0
+```
+++ /dev/null
----
-title: DisqusShortname
-description: Returns the Disqus shortname as defined in the site configuration.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- returnType: string
- signatures: [SITE.DisqusShortname]
-expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0
----
-
-{{< deprecated-in 0.120.0 >}}
-Use [`Site.Config.Services.Disqus.Shortname`] instead.
-
-[`Site.Config.Services.Disqus.Shortname`]: /methods/site/config/
-{{< /deprecated-in >}}
+++ /dev/null
----
-title: GoogleAnalytics
-description: Returns the Google Analytics tracking ID as defined in the site configuration.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- returnType: string
- signatures: [SITE.GoogleAnalytics]
-expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0
----
-
-{{< deprecated-in 0.120.0 >}}
-Use [`Site.Config.Services.GoogleAnalytics.ID`] instead.
-
-[`Site.Config.Services.GoogleAnalytics.ID`]: /methods/site/config/
-{{< /deprecated-in >}}
+++ /dev/null
----
-title: IsDevelopment
-description: Reports whether the current running environment is “development”.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- returnType: bool
- signatures: [SITE.IsDevelopment]
-expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0
----
-
-{{< deprecated-in 0.120.0 >}}
-Use [`hugo.IsDevelopment`] instead.
-
-[`hugo.IsDevelopment`]: /functions/hugo/isdevelopment/
-{{< /deprecated-in >}}
+++ /dev/null
----
-title: IsMultiLingual
-description: Reports whether there are two or more configured languages.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- returnType: bool
- signatures: [SITE.IsMultiLingual]
-expiryDate: 2026-03-16 # deprecated 2024-03-16 in 0.124.0
----
-
-{{< deprecated-in 0.124.0 >}}
-Use [`hugo.IsMultilingual`] instead.
-
-[`hugo.IsMultilingual`]: /functions/hugo/ismultilingual/
-{{< /deprecated-in >}}
+++ /dev/null
----
-title: IsServer
-description: Reports whether the built-in development server is running.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- returnType: bool
- signatures: [SITE.IsServer]
-expiryDate: 2025-10-30 # deprecated 2023-10-30 in v0.120.0
----
-
-{{< deprecated-in 0.120.0 >}}
-Use [`hugo.IsServer`] instead.
-
-[`hugo.IsServer`]: /functions/hugo/isserver/
-{{< /deprecated-in >}}
signatures: [SITE.Language]
---
-The `Language` method on a `Site` object returns the language object for the given site. The language object points to the language definition in the site configuration.
+The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration.
You can also use the `Language` method on a `Page` object. See [details].
## Methods
-The examples below assume the following in your site configuration:
+The examples below assume the following in the site configuration:
{{< code-toggle file=hugo >}}
[languages.de]
weight = 1
{{< /code-toggle >}}
+### IsDefault
+
+{{< new-in 0.153.0 />}}
+
+(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration.
+
+```go-html-template
+{{ .Site.Language.IsDefault }} → true
+```
+
### Lang
-(`string`) The language tag as defined by [RFC 5646].
+(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration.
```go-html-template
{{ .Site.Language.Lang }} → de
{{ .Site.Language.LanguageName }} → Deutsch
```
+### Name
+
+(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration. This is an alias for `Lang`.
+
+```go-html-template
+{{ .Site.Language.Name }} → de
+```
+
### Weight
(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.
>
```
+[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
[details]: /methods/page/language/
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
+++ /dev/null
----
-title: LastChange
-description: Returns the last modification date of site content.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- returnType: time.Time
- signatures: [SITE.LastChange]
-expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0
----
-
-{{< deprecated-in 0.123.0 >}}
-Use [`.Site.Lastmod`] instead.
-
-[`.Site.Lastmod`]: /methods/site/lastmod/
-{{< /deprecated-in >}}
signatures: [SITE.Lastmod]
---
-{{< new-in 0.123.0 />}}
-
The `Lastmod` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
```go-html-template
--- /dev/null
+---
+title: Role
+description: Returns the role object for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: roles.RoleSite
+ signatures: [SITE.Role]
+---
+
+{{< new-in 0.153.0 />}}
+
+The `Role` method on a `Site` object returns the role object for the given site. The role object is derived from the role definition in the site configuration.
+
+## Methods
+
+### IsDefault
+
+(`bool`) Reports whether this is the default role object as defined by the [`defaultContentRole`][] setting in the site configuration.
+
+```go-html-template
+{{ .Site.Role.IsDefault }} → true
+```
+
+### Name
+
+(`string`) Returns the role name. This is the lower cased key from the site configuration.
+
+```go-html-template
+{{ .Site.Role.Name }} → guest
+```
+
+[`defaultContentRole`]: /configuration/all/#defaultcontentrole
</ul>
```
-To render a link to the home page of the site corresponding to the default content language:
+To render a link to the home page of the [default site](g):
```go-html-template
{{ with .Site.Sites.Default }}
--- /dev/null
+---
+title: Version
+description: Returns the version object for the given site.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ returnType: versions.Version
+ signatures: [SITE.Version]
+---
+
+{{< new-in 0.153.0 />}}
+
+The `Version` method on a `Site` object returns the version object for the given site. The version object is derived from the version definition in the site configuration.
+
+## Methods
+
+### IsDefault
+
+(`bool`) Reports whether this is the default version object as defined by the [`defaultContentVersion`][] setting in the site configuration.
+
+```go-html-template
+{{ .Site.Version.IsDefault }} → true
+```
+
+### Name
+
+(`string`) Returns the version name. This is the lower cased key from the site configuration.
+
+```go-html-template
+{{ .Site.Version.Name }} → v1.0.0
+```
+
+[`defaultContentVersion`]: /configuration/all/#defaultcontentversion
signatures: [TAXONOMY.Page]
---
-{{< new-in 0.125.0 />}}
-
This `TAXONOMY` method returns nil if the taxonomy has no terms, so you must code defensively:
```go-html-template
--- /dev/null
+---
+title: Glob patterns
+description: A quick reference guide to glob pattern syntax and matching rules for wildcards, character sets, and delimiters, featuring illustrative examples.
+categories: []
+keywords: []
+---
+
+{{% glossary-term "glob pattern" %}}
+
+The table below details the supported glob pattern syntax and its matching behavior. Each example illustrates a specific match type, the pattern used, and the expected boolean result when evaluated against a test string.
+
+| Match type | Glob pattern | Test string | Match? |
+| :--- | :--- | :--- | :--- |
+| Simple wildcard | `a/*.md` | `a/page.md` | true |
+| Literal match | `'a/*.md'` | `a/*.md` | true |
+| Single-level wildcard | `a/*/page.md` | `a/b/page.md` | true |
+| Single-level wildcard | `a/*/page.md` | `a/b/c/page.md` | false |
+| Multi-level wildcard | `a/**/page.md` | `a/b/c/page.md` | true |
+| Single character | `file.???` | `file.txt` | true |
+| Single character | `file.???` | `file.js` | false |
+| Delimiter exclusion | `?at` | `f/at` | false |
+| Character list | `f.[jt]xt` | `f.txt` | true |
+| Negated list | `f.[!j]xt` | `f.txt` | true |
+| Character range | `f.[a-c].txt` | `f.b.txt` | true |
+| Character range | `f.[a-c].txt` | `f.z.txt` | false |
+| Negated range | `f.[!a-c].txt` | `f.z.txt` | true |
+| Pattern alternates | `*.{jpg,png}` | `logo.png` | true |
+| No match | `*.{jpg,png}` | `logo.webp` | false |
+
+The matching logic follows these rules:
+
+- Standard wildcard (`*`) matches any character except for a delimiter.
+- Super wildcard (`**`) matches any character including delimiters.
+- Single character (`?`) matches exactly one character, excluding delimiters.
+- Negation (`!`) matches any character except those specified in a list or range when used inside brackets.
+- Character ranges (`[a-z]`) match any single character within the specified range.
+
+The delimiter is a slash (`/`), except when matching semantic version strings, where the delimiter is a dot (`.`).
title: build
---
-To _build_ a site is to generate HTML files and assets such as images, CSS files, and JavaScript files. The build process includes rendering and resource transformations.
+To _build_ (verb) a site is to generate HTML files and assets such as images, CSS files, and JavaScript files. The build process includes rendering and resource transformations.
title: bundle
---
-See [page bundle](g).
+See [_page bundle_](g).
--- /dev/null
+---
+title: canonical output format
+---
+
+The _canonical output format_ is the [_output format_](g) for the current page where the format's [`rel`][] property is set to `canonical` in your site configuration, if such a format exists. If there is only one _output format_ for the current page, that is the _canonical output format_, regardless of whether the format's `rel` property is set to `canonical`.
+
+ By default, `html` is the only predefined _output format_ with this setting; the `rel` property for all others is set to `alternate`. If two or more _output formats_ for the current page have their `rel` property set to `canonical`, the _canonical output format_ is the first one specified in:
+
+ - The [`outputs`][outputs_front_matter] front matter field of the current page, or
+ - The [`outputs`][outputs_site_config] section of your site configuration for the current [_page kind_](g).
+
+ [`rel`]: /configuration/output-formats/#rel
+ [outputs_front_matter]: /configuration/outputs/#outputs-per-page
+ [outputs_site_config]: /configuration/outputs/#outputs-per-page-kind
title: chain
---
-To _chain_ is to connect one or more [_identifiers_](g) with a dot. An identifier can represent a [_method_](g), [_object_](g), or [_field_](g). For example, `.Site.Params.author.name` or `.Date.UTC.Hour`.
+To _chain_ (verb) is to connect one or more [_identifiers_](g) with a dot. An identifier can represent a [_method_](g), [_object_](g), or [_field_](g). For example, `.Site.Params.author.name` or `.Date.UTC.Hour`.
---
The term _CI/CD_ is an abbreviation for Continuous Integration and Continuous Delivery or Continuous Deployment depending on context.
+
+ Popular _CI/CD_ platforms for building and deploying Hugo sites include [Cloudflare][], [GitHub Pages][], [GitLab Pages][], [Netlify][], [Render][], and [Vercel][].
+
+ [Cloudflare]: /host-and-deploy/host-on-cloudflare/
+ [GitHub Pages]: /host-and-deploy/host-on-github-pages/
+ [GitLab Pages]: /host-and-deploy/host-on-gitlab-pages/
+ [Netlify]: /host-and-deploy/host-on-netlify/
+ [Render]: /host-and-deploy/host-on-render/
+ [Vercel]: /host-and-deploy/host-on-vercel/
templates|`layouts`
translation tables|`i18n`
static files|`static`
+ {class="!mt-0"}
--- /dev/null
+---
+title: content dimension
+---
+
+See [_dimension_](g).
title: content type
---
-A _content type_ is a classification of content inferred from the top-level directory name or the `type` set in [front matter](g). Pages in the root of the `content` directory, including the home page, are of type "page". The content type is a contributing factor in the template lookup order and determines which [archetype](/content-management/archetypes/) template to use when creating new content.
+A _content type_ is a classification of content inferred from the top-level directory name or the `type` set in [_front matter_](g). Pages in the root of the `content` directory, including the home page, are of type "page". The content type is a contributing factor in the template lookup order and determines which [_archetype_](g) template to use when creating new content.
--- /dev/null
+---
+title: default site
+---
+
+The _default site_ is the [_site_](g) identified by the primary value in each [_content dimension_](g). Specifically, it is the site that combines the first language, the first [_role_](g), and the first version defined in your site configuration.
+
+ The "first" language and role are those with the lowest [weight](g). If weights are tied or undefined, Hugo defaults to lexicographical order. Similarly, the "first" version is the one with the lowest weight; if weights are tied or undefined, it is identified as the last version when sorted semantically.
--- /dev/null
+---
+title: dimension
+---
+
+A _dimension_ is a categorized axis of content variation that allows multiple variations of a logical page to exist simultaneously. The three dimensions are language, [_role_](g), and version. For example, a logical page may exist in 6 languages, 4 versions, and 2 _roles_.
--- /dev/null
+---
+title: glob pattern
+reference: /quick-reference/glob-patterns/
+---
+
+A _glob pattern_ is a pattern used to match sets of values. It is a shorthand for specifying multiple targets at once, making it easier to work with groups of data or configurations.
--- /dev/null
+---
+title: glob slice
+---
+
+A _glob slice_ is a [_slice_](g) of [_glob patterns_](g). Within the _slice_, a _glob_ can be negated by prefixing it with an exclamation mark (`!`) and one space. Matches in negated patterns short-circuit the evaluation of the rest of the _slice_, and are useful for early coarse grained exclusions.
+
+ The following example illustrates how to use _glob slices_ to define a [_sites matrix_](g) in your site configuration:
+
+ ```toml
+ [sites.matrix]
+ languages = [ "! no", "**" ]
+ versions = [ "! v1.2.3", "v1.*.*", "v2.*.*" ]
+ roles = [ "{member, guest}" ]
+ ```
+
+ The `versions` example above evaluates as: `(not v1.2.3) AND (v1.*.* OR v2.*.*)`.
+++ /dev/null
----
-title: glob
-reference: https://github.com/gobwas/glob?tab=readme-ov-file#example
----
-
-A _glob_ is a pattern used to match file names and paths. It's a shorthand for specifying a set of files, making it easier to work with multiple files at once.
reference: https://go.dev/ref/spec#String_literals
---
-An _interpreted string literal_ is a character sequences between double quotes, as in "foo". Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted.
+An _interpreted string literal_ is a character sequence between double quotes, as in `"foo"`. Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted.
title: list page
---
-A list page is any [_page kind_](g) that receives a page [_collection_](g) in [_context_](g). This includes the home page, [section pages](g), [taxonomy pages](g), and [term pages](g).
+A list page is any [_page kind_](g) that receives a page [_collection_](g) in [_context_](g). This includes the home page, [_section pages_](g), [_taxonomy pages_](g), and [_term pages_](g).
reference: /functions/transform/remarshal/
---
-To _marshal_ is to transform a data structure into a serialized object. For example, transforming a [_map_](g) into a JSON string.
+To _marshal_ (verb) is to transform a data structure into a serialized object. For example, transforming a [_map_](g) into a JSON string.
reference: /configuration/output-formats/
---
-An _output format_ is a collection of settings that defines how Hugo renders a file when building a site. For example, `html`, `json`, and `rss` are built-in output formats. You can create multiple output formats and control their generation based on [page kind](g), or by enabling one or more output formats for specific pages.
+An _output format_ is a collection of settings that defines how Hugo renders a file when building a site. For example, `html`, `json`, and `rss` are built-in output formats. You can create multiple output formats and control their generation based on [_page kind_](g), or by enabling one or more output formats for specific pages.
--- /dev/null
+---
+title: page-relative
+---
+
+ A _page-relative_ path is resolved relative to the current page's location in the content hierarchy. These paths do not begin with a leading slash. Examples include `old-name`, `./old-name`, and `../old-name`.
+
+ See also: [_site-relative_](g), [_server-relative_](g).
title: paginate
---
-To _paginate_ is to split a list page into two or more subsets.
+To _paginate_ (verb) is to split a list page into two or more subsets.
--- /dev/null
+---
+title: partial decorator
+reference: /templates/partial-decorators/
+---
+
+A _partial decorator_ is specific type of [_partial_](g) that functions as a [_wrapper component_](g). While a standard partial simply renders data within a fixed template, a decorator uses composition to enclose an entire block of content. It utilizes the [`templates.Inner`][] function as a placeholder to define exactly where that external content should be injected within the wrapper's layout.
+
+ [`templates.Inner`]: /functions/templates/inner/
details: /configuration/outputs/
---
-A _primary output format_ defines the default URL returned by the [`Permalink`] and [`RelPermalink`] methods for a given [page kind](g). It is specified as the first entry within the [outputs configuration] for that page kind.
+A _primary output format_ defines the default URL returned by the [`Permalink`] and [`RelPermalink`] methods for a given [_page kind_](g). It is specified as the first entry within the [outputs configuration] for that page kind.
[`Permalink`]: /methods/page/permalink/
[`RelPermalink`]: /methods/page/relpermalink/
--- /dev/null
+---
+title: processable image
+---
+
+A _processable image_ is an image file characterized by one of the following [_media types_](g):
+
+ - `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`, `Resize`, etc.
+
+ [resource methods]: /methods/resource
reference: https://go.dev/ref/spec#String_literals
---
-A _raw string literal_ is a character sequence between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters (`\r`) inside raw string literals are discarded from the raw string value.
+A _raw string literal_ is a character sequence between backticks, as in `` `bar` ``. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters (`\r`) inside raw string literals are discarded from the raw string value.
title: resource type
---
-A _resource type_ is the main type of a resource's [media type](/methods/resource/mediatype/). Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `text`, `video`, and others. Retrieve the resource type using the [`ResourceType`](/methods/resource/resourcetype/) method on a `Resource` object.
+A _resource type_ is the main type of a resource's [_media type_](g). Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `text`, `video`, and others. Retrieve the resource type using the [`ResourceType`](/methods/resource/resourcetype/) method on a `Resource` object.
--- /dev/null
+---
+title: role
+---
+
+A _role_ is a [_dimension_](g) that allows a logical page to be served in different forms depending on the target audience. Common use cases include user personas, access control, and intended audience.
--- /dev/null
+---
+title: rune literal
+reference: https://go.dev/ref/spec#Rune_literals
+---
+
+A _rune literal_ is the textual representation of a [_rune_](g) within a [_template_](g). It consists of a character sequence enclosed in single quotes, such as `'x'`, `'\n'`, or `'ü'`.
+
+ Unlike [_interpreted string literals_](g) or [_raw string literals_](g), which represent a sequence of characters, a _rune literal_ represents a single [_integer_](g) value identifying a Unicode [code point][]. Within the quotes, any character may appear except a newline or an unescaped single quote. Multi-character sequences starting with a backslash (`\`) can be used to encode specific values, such as `\n` for a newline or `\u00FC` for the letter `ü`.
+
+ [code point]: https://en.wikipedia.org/wiki/Code_point
--- /dev/null
+---
+title: rune
+---
+
+A _rune_ is a way to represent a single character as a number. In Hugo and Go, text is stored as a sequence of bytes. However, while a basic letter like `x` uses only one byte, a single character such as the German `ü` is made up of multiple bytes. A _rune_ represents the entire character as one single value, no matter how many bytes it takes to store it.
+
+ Technically, a _rune_ is just another name for a 32-bit [_integer_](g). It stores the Unicode [code point][], which is the official number assigned to that specific character.
+
+ When you want to manipulate text character-by-character rather than by raw data size, you are working with _runes_. You write a _rune_ in a [_template_](g) using a [_rune literal_](g), such as `'x'`, `'\n'`, or `'ü'`.
+
+ [code point]: https://en.wikipedia.org/wiki/Code_point
title: scope
---
-The term _scope_ refers to the specific region of code where a [_variable_](g) or [_object_](g) is accessible. For example, a variable initialized in one [template](g) is not available within another.
+The term _scope_ refers to the specific region of code where a [_variable_](g) or [_object_](g) is accessible. For example, a variable initialized in one [_template_](g) is not available within another.
title: segment
---
-A _segment_ is a subset of a site, filtered by [_logical path_](g), language, [_page kind_](g), or [_output format_](g).
+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
+---
+title: server-relative
+---
+
+ A _server-relative_ path is the final path from the web server's root, used in the generated site. These paths always begin with a leading slash and account for the [`baseURL`] and [_content dimension_](g) prefixes such as language, [_role_](g), or version. For example, `/en/examples/old-name/` is a server-relative path.
+
+ See also: [_page-relative_](g), [_site-relative_](g).
+
+ [`baseURL`]: /configuration/all/#baseurl
--- /dev/null
+---
+title: site-relative
+---
+
+ A _site-relative_ path is resolved relative to the root of the content directory. These paths begin with a leading slash. For example, `/old-name` is a site-relative path.
+
+ See also: [_page-relative_](g), [_server-relative_](g).
--- /dev/null
+---
+title: site root
+---
+
+The _site root_ is the root directory of the current [_site_](g), relative to the [`publishDir`][]. The _site root_ may include one or more content [_dimension_](g) prefixes, such as language, [_role_](g), or version.
+
+ Project description|Site root examples
+ :--|:--|:--
+ Monolingual|`/`, `/guest`, `/guest/v1.2.3`
+ Multilingual single-host|`/en`, `/guest/en`, `/guest/v1.2.3/en`
+ Multilingual multihost|`/en`, `/en/guest`, `/en/guest/v1.2.3`
+
+ [`publishDir`]: /configuration/all/#publishdir
--- /dev/null
+---
+title: site
+---
+
+A _site_ is a specific instance of your project representing a unique combination of language, [_role_](g), and version. While a simple project may consist of only a single site, Hugo's multidimensional content model allows a single codebase to generate a matrix of sites simultaneously. Each site operates with its own configuration, set of pages, and output destination, allowing you to serve tailored content to different audiences from one unified source.
--- /dev/null
+---
+title: sites complements
+---
+
+_sites complements_ is a configuration object defined in content front matter or a file mount. The links will point to the complementary sites. The configuration is structured as a map of [_glob slices_](g).
--- /dev/null
+---
+title: sites matrix
+---
+
+_sites matrix_ is a configuration object defined in content front matter or a file mount to precisely control which sites the content should be generated for. When defined in a file mount for [_templates_](g), it controls which sites the template will be applied to.
+
+ In Hugo's multidimensional content model, the matrix defines the intersection of three dimensions: language, role, and version. The configuration is structured as a map of [_glob slices_](g).
+
+ See also [_sites complements_](g), [front matter: sites](/content-management/front-matter/#sites), [module mounts: sites](/configuration/module/#sites), and [segments: sites](/configuration/segments/#sites).
---
title: taxonomic weight
-reference: content-management/taxonomies/#order-taxonomies
+reference: /content-management/taxonomies/#taxonomic-weight
---
Defined in front matter and unique to each taxonomy, a _taxonomic weight_ is a [_weight_](g) that determines the sort order of page collections contained within a [`Taxonomy`](g) object.
title: taxonomy object
---
-A _taxonomy object_ is a [_map_](g) of [_terms_](g) and the [weighted pages](g) associated with each term.
+A _taxonomy object_ is a [_map_](g) of [_terms_](g) and the [_weighted pages_](g) associated with each term.
title: theme
---
-A _theme_ is a [_module_](g) that delivers a complete set of [components](g) defining a site's layout, presentation, and behavior. While every theme is a module, not every module is a theme.
+A _theme_ is a [_module_](g) that delivers a complete set of [_components_](g) defining a site's layout, presentation, and behavior. While every theme is a module, not every module is a theme.
title: type
---
-See [content type](g).
+See [_content type_](g).
reference: /functions/transform/unmarshal/
---
-To _unmarshal_ is to transform a serialized object into a data structure. For example, transforming a JSON file into a [_map_](g) that you can access within a template.
+To _unmarshal_ (verb) is to transform a serialized object into a data structure. For example, transforming a JSON file into a [_map_](g) that you can access within a template.
--- /dev/null
+---
+title: vendor
+---
+
+To _vendor_ (verb) in a software context is the process of including the source code of third-party dependencies directly within your own project's repository, rather than downloading them on the fly from an external package manager.
+
+ When you are asked to "vendor the dependencies into the project root," you are being told to move those external libraries from a temporary cache into a dedicated folder that gets committed to your version control system.
title: walk
---
-To _walk_ is to recursively traverse a nested data structure. For example, rendering a multilevel menu.
+To _walk_ (verb) is to recursively traverse a nested data structure. For example, rendering a multilevel menu.
title: weight
---
-A _weight_ is a numeric value used to position an element within a sorted [collection](g). Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, and output formats.
+A _weight_ is a numeric value used to position an element within a sorted [_collection_](g). Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, [_roles_](g), versions, and output formats.
--- /dev/null
+---
+title: wrapper component
+---
+
+A _wrapper component_ is an interface pattern that encloses other content through composition rather than fixed parameters. It provides a reusable shell to handle layout, styling, or logic, allowing the calling template to inject arbitrary content into the component's interior.
+
+ See also: [_partial decorator_](g)
: (`page`) A reference to the current page.
PageInner
-: {{< new-in 0.125.0 />}}
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
Position
: (`page`) A reference to the current page.
PageInner
-: {{< new-in 0.125.0 />}}
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
PlainText
: (`page`) A reference to the current page.
PageInner
-: {{< new-in 0.125.0 />}}
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
PlainText
## Embedded
-{{< new-in 0.123.0 />}}
-
Hugo includes an [embedded image render hook] to resolve Markdown image destinations. You can adjust its behavior in your site configuration. This is the default setting:
{{< code-toggle file=hugo >}}
: (`page`) A reference to the current page.
PageInner
-: {{< new-in 0.125.0 />}}
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
PlainText
## Embedded
-{{< new-in 0.123.0 />}}
-
Hugo includes an [embedded link render hook] to resolve Markdown link destinations. You can adjust its behavior in your site configuration. This is the default setting:
{{< code-toggle file=hugo >}}
+++ /dev/null
----
-title: Gist shortcode
-linkTitle: Gist
-description: Embed a GitHub Gist in your content using the gist shortcode.
-categories: []
-keywords: []
-expiryDate: 2027-02-01 # deprecated 2025-02-01 in v0.143.0
----
-
-{{< deprecated-in 0.143.0 >}}
-The `gist` shortcode was deprecated in version 0.143.0 and will be removed in a future release. To continue embedding GitHub Gists in your content, you'll need to create a custom shortcode:
-
-1. Create a new file: Create a file named `gist.html` within the `layouts/_shortcodes` directory.
-1. Copy the source code: Paste the [original source code]({{% eturl gist %}}) of the gist shortcode into the newly created `gist.html` file.
-
-This will allow you to maintain the functionality of embedding GitHub Gists in your content after the deprecation of the original shortcode.
-{{< /deprecated-in >}}
-
-To display a GitHub gist with this URL:
-
-```text
-https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
-```
-
-Include this in your Markdown:
-
-```text
-{{</* gist user 23932424365401ffa5e9d9810102a477 */>}}
-```
-
-To display a specific file within the gist:
-
-```text
-{{</* gist user 23932424365401ffa5e9d9810102a477 list.html */>}}
-```
: (`string`) The video `id`. Optional if the `id` is the first and only positional argument.
allowFullScreen
-: {{< new-in 0.125.0 />}}
: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
autoplay
-: {{< new-in 0.125.0 />}}
: (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`.
class
: (`string`) The `class` attribute of the wrapping `div` element. When specified, removes the `style` attributes from the `iframe` element and its wrapping `div` element.
controls
-: {{< new-in 0.125.0 />}}
: (`bool`) Whether to display the video controls. Default is `true`.
end
-: {{< new-in 0.125.0 />}}
: (`int`) The time, measured in seconds from the start of the video, when the player should stop playing the video.
loading
-: {{< new-in 0.125.0 />}}
: (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
loop
-: {{< new-in 0.125.0 />}}
: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`.
mute
-: {{< new-in 0.125.0 />}}
: (`bool`) Whether to mute the video. Always `true` when `autoplay` is `true`. Default is `false`.
start
-: {{< new-in 0.125.0 />}}
: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
title
At 1Password, we used to go through a different documentation platform every month: blog engines, ebooks, wikis, site generators written in Ruby and JavaScript. Each was inadequate in its own special way. Then we found **Hugo**. We made one last switch, and we're glad we did.
-### Not all static site generators are created equal
+## Not all static site generators are created equal
Finding a tool that will make your customers, writers, designers, _and_ DevOps team happy is no easy task, but we managed it with Hugo:
It was clear from the get-go that we had to go with a static site generator. Static sites are secure, performant, and give you 100% flexibility. At [Forestry.io](https://forestry.io/) we provide Content Management Solutions for websites built with static site generators, so we might be a little biased. The only question: Which static site generator was the right choice for us?
-### Why Hugo?
+## Why Hugo?
In our early research we looked at Ionic's [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn't fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast.
description: Create a template to render a 404 error page.
categories: []
keywords: []
-weight: 190
+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:
description: Hugo provides embedded partial templates for common use cases.
categories: []
keywords: []
-weight: 170
+weight: 180
aliases: [/templates/internal]
---
: (`bool`) Whether to disable the template. Default is `false`.
respectDoNotTrack
-: (`bool`) Whether to respect the browser's "do not track" setting. Default is `false`.
+: (`bool`) Whether to respect the browser's "do not track" setting. Default is `true`.
## Open Graph
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:
## Changes to the `layouts` folder
-| Description | Action required |
-| ------------- | ------------- |
-| The `_default` folder is removed. | Move all files in `layouts/_default` up to the `layouts/` root.|
-| The `layouts/partials` folder is renamed to `layouts/_partials`. | Rename the folder. |
-| The `layouts/shortcodes` folder is renamed to `layouts/_shortcodes`. | Rename the folder. |
-| Any folder in `layouts` that does not start with `_` represents the root of a [Page path]. In [Hugo v0.146.0], this can be nested as deeply as needed, and `_shortcodes` and `_markup` folders can be placed at any level in the tree.| No action required.|
-| The above also means that there's no top-level `layouts/taxonomy` or `layouts/section` folders anymore, unless it represents a [Page path].|Move them up to `layouts/` with one of the [Page kinds] `section`, `taxonomy` or `term` as the base name, or place the layouts into the taxonomy [Page path]. |
-|A template named `taxonomy.html` used to be a candidate for both Page kind `term` and `taxonomy`, now it's only considered for `taxonomy`.|Create both `taxonomy.html` and `term.html` or create a more general layout, e.g. `list.html`.|
-| For base templates (e.g., `baseof.html`), in previous Hugo versions, you could prepend one identifier (layout, type, or kind) with a hyphen in front of the baseof keyword.|Move that identifier after the first "dot," e.g., rename`list-baseof.html` to `baseof.list.html`.|
-| We have added a new `all` "catch-all" layout. This means that if you have, e.g., `layouts/all.html` and that is the only template, that layout will be used for all HTML page rendering.||
-| We have removed the concept of `_internal` Hugo templates.[^internal]|Replace constructs similar to `{{ template "_internal/opengraph.html" . }}` with `{{ partial "opengraph.html" . }}`.|
-| The identifiers that can be used in a template filename are one of the [Page kinds] (`home`, `page`, `section`, `taxonomy`, or `term`), one of the standard layouts (`list`, `single`, or `all`), a custom layout (as defined in the `layout` front matter field), a language (e.g., `en`), an output format (e.g., `html`, `rss`), and a suffix representing the media type. E.g., `all.en.html` and `home.rss.xml`.||
-| The above means that there's no such thing as an `index.html` template for the home page anymore. | Rename `index.html` to `home.html`.|
+| Description | Action required |
+|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| The `_default` folder is removed. | Move all files in `layouts/_default` up to the `layouts/` root. |
+| The `layouts/partials` folder is renamed to `layouts/_partials`. | Rename the folder. |
+| The `layouts/shortcodes` folder is renamed to `layouts/_shortcodes`. | Rename the folder. |
+| Any folder in `layouts` that does not start with `_` represents the root of a [Page path]. In [Hugo v0.146.0], this can be nested as deeply as needed, and `_shortcodes` and `_markup` folders can be placed at any level in the tree. | No action required. |
+| The above also means that there's no top-level `layouts/taxonomy` or `layouts/section` folders anymore, unless it represents a [Page path]. | Move them up to `layouts/` with one of the [Page kinds] `section`, `taxonomy` or `term` as the base name, or place the layouts into the taxonomy [Page path]. |
+| A template named `taxonomy.html` used to be a candidate for both Page kind `term` and `taxonomy`, now it's only considered for `taxonomy`. | Create both `taxonomy.html` and `term.html` or create a more general layout, e.g. `list.html`. |
+| For base templates (e.g., `baseof.html`), in previous Hugo versions, you could prepend one identifier (layout, type, or kind) with a hyphen in front of the baseof keyword. | Move that identifier after the first "dot," e.g., rename`list-baseof.html` to `baseof.list.html`. |
+| We have added a new `all` "catch-all" layout. This means that if you have, e.g., `layouts/all.html` and that is the only template, that layout will be used for all HTML page rendering. | |
+| We have removed the concept of `_internal` Hugo templates.[^internal] | Replace constructs similar to `{{ template "_internal/opengraph.html" . }}` with `{{ partial "opengraph.html" . }}`. |
+| The identifiers that can be used in a template filename are one of the [Page kinds] (`home`, `page`, `section`, `taxonomy`, or `term`), one of the standard layouts (`list`, `single`, or `all`), a custom layout (as defined in the `layout` front matter field), a language (e.g., `en`), an output format (e.g., `html`, `rss`), and a suffix representing the media type. E.g., `all.en.html` and `home.rss.xml`. | |
+| The above means that there's no such thing as an `index.html` template for the home page anymore. | Rename `index.html` to `home.html`. |
Also, see the [Example folder structure] below for a more concrete example of the new layout system.
The identifiers used in the template weighting, in order of importance, are:
-| Identifier | Description |
-| ---------- | ----------- |
-| Layout custom | The custom `layout` set in front matter. |
-| [Page kinds] | One of `home`, `section`, `taxonomy`, `term`, `page`. |
-| Layouts standard 1 | `list` or `single`. |
-| Output format | The output format (e.g., `html`, `rss`). |
-| Layouts standard 2 | `all`. |
-| Language | The language (e.g., `en`). |
-| Media type | The media type (e.g., `text/html`). |
-| [Page path] | The page path (e.g., `/blog/mypost`). |
-| Type | `type` set in front matter.[^type]|
+| Identifier | Description |
+|--------------------|-------------------------------------------------------|
+| Layout custom | The custom `layout` set in front matter. |
+| [Page kinds][] | One of `home`, `section`, `taxonomy`, `term`, `page`. |
+| Layouts standard 1 | `list` or `single`. |
+| Output format | The output format (e.g., `html`, `rss`). |
+| Layouts standard 2 | `all`. |
+| Language | The language (e.g., `en`). |
+| Media type | The media type (e.g., `text/html`). |
+| [Page path][] | The page path (e.g., `/blog/mypost`). |
+| Type | `type` set in front matter.[^type] |
For templates placed in a `layouts` folder partly or completely matching a [Page path], a closer match upwards will be considered _better_. In the [Example folder structure] below, this means that:
--- /dev/null
+---
+title: Partial decorators
+description: Use partial decorators to create reusable wrapper components that enclose and compose template content.
+categories: []
+keywords: [decorator]
+weight: 170
+---
+
+{{< new-in "0.154.0" />}}
+
+## Overview
+
+{{% glossary-term "partial decorator" %}}
+
+This approach creates a connection between two files. The calling template provides a block of code and the partial decorator determines where that code appears. This allows the partial to wrap around content without needing to know the specific markup or internal logic of the enclosed block.
+
+## Implementation
+
+To use a partial decorator, use a block-style call in your templates. The [`with`][] statement is required to initiate the partial and create a container for the content. This block can include any valid template code including page methods and functions.
+
+```go-html-template {file="layouts/home.html" copy=true}
+{{ with partial "components/wrapper.html" . }}
+ <p>Everything in this block will be wrapped.</p>
+ <p>{{ .Content | transform.Plainify | strings.Truncate 200 }}</p>
+{{ end }}
+```
+
+Inside the partial template, place the `templates.Inner` function call where the wrapped content should appear.
+
+```go-html-template {file="layouts/_partials/components/wrapper.html" copy=true}
+<div class="wrapper-styling">
+ {{ templates.Inner . }}
+</div>
+```
+
+The `with` statement creates a new [scope](g). Variables defined outside of the `with` block are not available inside it. To use external data within the wrapped content, you must ensure it is part of the [context](g) passed in the partial call.
+
+A key feature of the `templates.Inner` function is its ability to accept a context argument. By passing a context to the function, you define what the dot (`.`) represents inside the wrapped block. This ensures that the injected content has access to the correct data even when nested inside multiple layers of wrappers.
+
+## Benefits of composition
+
+Using partial decorators to build wrapper components provides several advantages:
+
+- It eliminates the need to use separate partials for opening and closing tags when encapsulating a block of code.
+- It prevents parameter bloat because a standard partial no longer requires an extensive list of arguments to account for every possible variation of the content inside it.
+- It enables clean composition where the wrapped block can execute any template logic without the wrapper needing to receive or process that data.
+
+This approach separates container logic from content logic. The wrapper handles structural requirements like specific class hierarchies or CSS grid containers. The calling template retains control over the inner markup and how data is displayed.
+
+## Example
+
+The following templates illustrate how to nest three wrapper components including a section, a column, and a card while passing context through each layer.
+
+The home template initiates the structure by calling the section, column, and card partials as decorators:
+
+```go-html-template {file="layouts/home.html" copy=true}
+{{ $ctx := dict
+ "page" .
+ "label" "Recent Posts"
+ "pageCollection" ((site.GetPage "/posts").RegularPages)
+}}
+
+{{ with partial "components/section.html" $ctx }}
+ <div class="grid-wrapper">
+ {{ range .pageCollection }}
+ {{ with partial "components/column.html" (dict "page" . "class" "col-half") }}
+ {{ with partial "components/card.html" (dict "page" .page "url" .page.RelPermalink "title" .page.LinkTitle) }}
+ <p>
+ {{ .page.Content | plainify | strings.Truncate 240 }}
+ </p>
+ {{ end }}
+ {{ end }}
+ {{ end }}
+ </div>
+{{ end }}
+```
+
+The section component provides a semantic container and an optional heading:
+
+```go-html-template {file="layouts/_partials/components/section.html" copy=true}
+<section class="content-section">
+ {{ with .label }}
+ <h2 class="section-label">{{ . }}</h2>
+ {{ end }}
+ <div class="section-content">
+ {{ templates.Inner . }}
+ </div>
+</section>
+```
+
+The column component manages layout width by applying a CSS class:
+
+```go-html-template {file="layouts/_partials/components/column.html" copy=true}
+<div class="{{ .class | default `column-default` }}">
+ {{ templates.Inner . }}
+</div>
+```
+
+The card component defines the visual boundary for the content:
+
+```go-html-template {file="layouts/_partials/components/card.html" copy=true}
+<div class="card">
+ {{ with .title }}
+ <h2 class="card-title">
+ {{ if $.url }}
+ <a href="{{ $.url }}">{{ . }}</a>
+ {{ else }}
+ {{ . }}
+ {{ end }}
+ </h2>
+ {{ end }}
+
+ <div class="card-body">
+ {{ templates.Inner . }}
+ </div>
+
+ {{ with .url }}
+ <div class="card-footer">
+ <a href="{{ . }}">Read more</a>
+ </div>
+ {{ end }}
+</div>
+```
+
+[`with`]: /functions/go-template/with/
description: Hugo can generate a customized robots.txt in the same way as any other template.
categories: []
keywords: []
-weight: 180
+weight: 190
aliases: [/extras/robots-txt/]
---
Name: C
- Aliases:
- csharp
- - c#
- Name: C#
+ - 'c#'
+ Name: 'C#'
- Aliases:
- cpp
- c++
Name: C++
+ - Aliases:
+ - c3
+ Name: C3
- Aliases:
- caddyfile
- caddy
- desktop
- desktop_entry
Name: Desktop file
+ - Aliases:
+ - devicetree
+ - dts
+ Name: Devicetree
- Aliases:
- diff
- udiff
- Aliases:
- jungle
Name: Jungle
+ - Aliases:
+ - kak
+ - kakoune
+ - kakrc
+ - kakscript
+ Name: Kakoune
+ - Aliases:
+ - kdl
+ Name: KDL
- Aliases:
- kotlin
Name: Kotlin
- md
- mkd
Name: markdown
+ - Aliases:
+ - mess
+ Name: Markless
- Aliases:
- mason
Name: Mason
- Aliases:
- metal
Name: Metal
+ - Aliases:
+ - µcad
+ Name: microcad
- Aliases:
- minizinc
- MZN
- Aliases:
- mlir
Name: MLIR
+ - Aliases:
+ - modelica
+ Name: Modelica
- Aliases:
- modula2
- m2
Name: Modula-2
- Aliases:
- mojo
- - "\U0001F525"
+ - 🔥
Name: Mojo
- Aliases:
- monkeyc
Name: MonkeyC
+ - Aliases:
+ - moonbit
+ - mbt
+ Name: MoonBit
- Aliases:
- moonscript
- moon
- protobuf
- proto
Name: Protocol Buffer
+ - Aliases:
+ - txtpb
+ Name: Protocol Buffer Text Format
- Aliases:
- prql
Name: PRQL
- sage
- python3
- py3
+ - starlark
Name: Python
- Aliases:
- python2
- rexx
- arexx
Name: Rexx
+ - Aliases:
+ - rgbasm
+ Name: RGBDS Assembly
+ - Aliases:
+ - ring
+ Name: Ring
- Aliases:
- SQLRPGLE
- RPG IV
Name: vue
- Aliases: null
Name: WDTE
+ - Aliases:
+ - wast
+ - wat
+ Name: WebAssembly Text Format
- Aliases:
- wgsl
Name: WebGPU Shading Language
- algol
- algol_nu
- arduino
+ - ashen
+ - aura-theme-dark
+ - aura-theme-dark-soft
- autumn
- average
- base16-snazzy
archeTypeDir: archetypes
assetDir: assets
author: {}
- baseURL: ""
+ baseURL: ''
build:
buildStats:
disableClasses: false
disableTags: false
enable: false
cacheBusters:
- - source: (postcss|tailwind)\.config\.js
+ - source: '(postcss|tailwind)\.config\.js'
target: (css|styles|scss|sass)
noJSConfigInAssets: false
useResourceCacheWhen: fallback
buildDrafts: false
buildExpired: false
buildFuture: false
- cacheDir: ""
+ cacheDir: ''
caches:
assets:
dir: :resourceDir/_gen
maxAge: -1
- getcsv:
- dir: :cacheDir/:project
- maxAge: -1
- getjson:
- dir: :cacheDir/:project
- maxAge: -1
getresource:
dir: :cacheDir/:project
maxAge: -1
misc:
dir: :cacheDir/:project
maxAge: -1
+ modulequeries:
+ dir: :cacheDir/modules
+ maxAge: 24h
modules:
dir: :cacheDir/modules
maxAge: -1
canonifyURLs: false
capitalizeListTitles: true
- cascade: []
+ cascade: null
cleanDestinationDir: false
contentDir: content
contentTypes:
text/org: {}
text/pandoc: {}
text/rst: {}
- copyright: ""
+ copyright: ''
dataDir: data
defaultContentLanguage: en
defaultContentLanguageInSubdir: false
+ defaultContentRole: guest
+ defaultContentRoleInSubdir: false
+ defaultContentVersion: ''
+ defaultContentVersionInSubdir: false
defaultOutputFormat: html
deployment:
confirm: false
matchers: null
maxDeletes: 256
order: null
- target: ""
+ target: ''
targets: null
workers: 10
disableAliases: false
disableDefaultLanguageRedirect: false
+ disableDefaultSiteRedirect: false
disableHugoGeneratorInject: false
disableKinds: null
disableLanguages: null
ignoreCache: false
ignoreFiles: null
ignoreLogs: null
- ignoreVendorPaths: ""
+ ignoreVendorPaths: ''
imaging:
bgColor: '#ffffff'
+ compression: lossy
hint: photo
quality: 75
resampleFilter: box
- languageCode: ""
+ webp:
+ method: 4
+ useSharpYuv: true
+ languageCode: ''
languages:
en:
disabled: false
- languageCode: ""
- languageDirection: ""
- languageName: ""
- title: ""
+ languageCode: ''
+ languageDirection: ''
+ languageName: ''
+ title: ''
weight: 0
layoutDir: layouts
mainSections: null
markup:
- asciidocExt:
+ asciiDocExt:
attributes: {}
backend: html5
extensions: []
anchorLineNos: false
codeFences: true
guessSyntax: false
- hl_Lines: ""
+ hl_Lines: ''
hl_inline: false
- lineAnchors: ""
+ lineAnchors: ''
lineNoStart: 1
lineNos: false
lineNumbersInTable: true
tdewolff:
css:
inline: false
- keepCSS2: false
precision: 0
version: 0
html:
keepSpecialComments: true
keepWhitespace: false
templateDelims:
- - ""
- - ""
+ - ''
+ - ''
js:
keepVarNames: false
precision: 0
keepNumbers: false
precision: 0
svg:
- inline: false
keepComments: false
precision: 0
xml:
keepWhitespace: false
module:
- auth: ""
+ auth: ''
hugoVersion:
extended: false
- max: ""
- min: ""
+ max: ''
+ min: ''
imports: null
mounts:
- disableWatch: false
- excludeFiles: null
- includeFiles: null
- lang: ""
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
source: content
target: content
- disableWatch: false
- excludeFiles: null
- includeFiles: null
- lang: ""
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
source: data
target: data
- disableWatch: false
- excludeFiles: null
- includeFiles: null
- lang: ""
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
source: layouts
target: layouts
- disableWatch: false
- excludeFiles: null
- includeFiles: null
- lang: ""
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
source: i18n
target: i18n
- disableWatch: false
- excludeFiles: null
- includeFiles: null
- lang: ""
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
source: archetypes
target: archetypes
- disableWatch: false
- excludeFiles: null
- includeFiles: null
- lang: ""
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
source: assets
target: assets
- disableWatch: false
- excludeFiles: null
- includeFiles: null
- lang: ""
+ files: null
+ sites:
+ complements:
+ languages: null
+ roles: null
+ versions: null
+ matrix:
+ languages: null
+ roles: null
+ versions: null
source: static
target: static
noProxy: none
- noVendor: ""
+ noVendor: ''
params: null
private: '*.*'
proxy: direct
replacements: null
vendorClosest: false
- workspace: "off"
- newContentEditor: ""
+ workspace: 'off'
+ newContentEditor: ''
noBuildLock: false
noChmod: false
noTimes: false
outputFormats:
- "404":
- baseName: ""
+ '404':
+ baseName: ''
isHTML: true
isPlainText: false
mediaType: text/html
noUgly: false
notAlternative: true
- path: ""
+ path: ''
permalinkable: true
- protocol: ""
- rel: ""
+ protocol: ''
+ rel: ''
root: false
ugly: true
weight: 0
alias:
- baseName: ""
+ baseName: ''
isHTML: true
isPlainText: false
mediaType: text/html
noUgly: false
notAlternative: false
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
- rel: ""
+ protocol: ''
+ rel: ''
root: false
ugly: true
weight: 0
notAlternative: false
path: amp
permalinkable: true
- protocol: ""
+ protocol: ''
rel: amphtml
root: false
ugly: false
mediaType: text/calendar
noUgly: false
notAlternative: false
- path: ""
+ path: ''
permalinkable: false
protocol: webcal://
rel: alternate
mediaType: text/css
noUgly: false
notAlternative: true
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
+ protocol: ''
rel: stylesheet
root: false
ugly: false
mediaType: text/csv
noUgly: false
notAlternative: false
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
+ protocol: ''
rel: alternate
root: false
ugly: false
weight: 0
gotmpl:
- baseName: ""
+ baseName: ''
isHTML: false
isPlainText: true
mediaType: text/x-gotmpl
noUgly: false
notAlternative: true
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
- rel: ""
+ protocol: ''
+ rel: ''
root: false
ugly: false
weight: 0
mediaType: text/html
noUgly: false
notAlternative: false
- path: ""
+ path: ''
permalinkable: true
- protocol: ""
+ protocol: ''
rel: canonical
root: false
ugly: false
mediaType: application/json
noUgly: false
notAlternative: false
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
+ protocol: ''
rel: alternate
root: false
ugly: false
mediaType: text/markdown
noUgly: false
notAlternative: false
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
+ protocol: ''
rel: alternate
root: false
ugly: false
mediaType: text/plain
noUgly: false
notAlternative: false
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
+ protocol: ''
rel: alternate
root: true
ugly: false
mediaType: application/rss+xml
noUgly: true
notAlternative: false
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
+ protocol: ''
rel: alternate
root: false
ugly: false
mediaType: application/xml
noUgly: false
notAlternative: false
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
+ protocol: ''
rel: sitemap
root: false
ugly: true
mediaType: application/xml
noUgly: false
notAlternative: false
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
+ protocol: ''
rel: sitemap
root: true
ugly: true
mediaType: application/manifest+json
noUgly: false
notAlternative: true
- path: ""
+ path: ''
permalinkable: false
- protocol: ""
+ protocol: ''
rel: manifest
root: false
ugly: false
page:
nextPrevInSectionSortOrder: desc
nextPrevSortOrder: desc
- paginate: 0
- paginatePath: ""
pagination:
disableAliases: false
pagerSize: 10
disable: false
googleAnalytics:
disable: false
- respectDoNotTrack: false
+ respectDoNotTrack: true
instagram:
disable: false
simple: false
- twitter:
- disable: false
- enableDNT: false
- simple: false
vimeo:
disable: false
enableDNT: false
disable: false
privacyEnhanced: false
publishDir: public
- refLinksErrorLevel: ""
- refLinksNotFoundURL: ""
+ refLinksErrorLevel: ''
+ refLinksNotFoundURL: ''
related:
includeNewer: false
indices:
- applyFilter: false
cardinalityThreshold: 0
name: keywords
- pattern: ""
+ pattern: ''
toLower: false
type: basic
weight: 100
- applyFilter: false
cardinalityThreshold: 0
name: date
- pattern: ""
+ pattern: ''
toLower: false
type: basic
weight: 10
- applyFilter: false
cardinalityThreshold: 0
name: tags
- pattern: ""
+ pattern: ''
toLower: false
type: basic
weight: 80
removePathAccents: false
renderSegments: null
resourceDir: resources
- sectionPagesMenu: ""
+ roles:
+ guest:
+ weight: 0
+ sectionPagesMenu: ''
security:
enableInlineShortcodes: false
exec:
- ^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)$
+ - '(?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_
- force: false
from: /**
fromHeaders: null
- fromRe: ""
+ fromRe: ''
status: 404
to: /404.html
services:
disqus:
- shortname: ""
+ shortname: ''
googleAnalytics:
- id: ""
- instagram:
- accessToken: ""
- disableInlineCSS: false
+ id: ''
rss:
limit: -1
- twitter:
- disableInlineCSS: false
x:
disableInlineCSS: false
sitemap:
- changeFreq: ""
+ changeFreq: ''
disable: false
filename: sitemap.xml
priority: -1
- static
staticDir0: null
staticDir1: null
+ staticDir10: null
staticDir2: null
staticDir3: null
staticDir4: null
staticDir7: null
staticDir8: null
staticDir9: null
- staticDir10: null
summaryLength: 70
taxonomies:
category: categories
templateMetricsHints: false
theme: null
themesDir: themes
- timeZone: ""
+ timeZone: ''
timeout: 60s
- title: ""
+ title: ''
titleCaseStyle: AP
uglyURLs: {}
- workingDir: ""
+ versions:
+ v1.0.0:
+ weight: 0
+ workingDir: ''
config_helpers:
mergeStrategy:
build:
_merge: none
related:
_merge: none
+ roles:
+ _merge: none
security:
_merge: none
segments:
_merge: none
taxonomies:
_merge: none
+ versions:
+ _merge: none
output:
layouts: {}
tpl:
Aliases:
- after
Args:
- - "n"
+ - 'n'
- l
Description: After returns all the items after the first n items in list l.
Examples: []
- append
Args:
- args
- Description: "Append appends args up to the last one to the slice in the last
- argument.\nThis construct allows template constructs like this:\n\n\t{{
- $pages = $pages | append $p2 $p1 }}\n\nNote that with 2 arguments where
- both are slices of the same type,\nthe first slice will be appended to the
- second:\n\n\t{{ $pages = $pages | append .Site.RegularPages }}"
+ 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:
- c
- fname
- args
- Description: Apply takes an array or slice c and returns a new slice with
- the function fname applied over it.
+ 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\nany of the others.\n\nAll elements of ls must be slices or arrays
- of comparable types.\n\nThe reasoning behind this rather clumsy API is so
- we can do this in the templates:\n\n\t{{ $c := .Pages | complement $last4
- }}"
+ 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") }}'
+ - - '{{ slice "a" "b" "c" "d" "e" "f" | complement (slice "b" "c") (slice "d" "e") }}'
- '[a f]'
D:
Aliases: null
- Args: null
- Description: ""
- Examples: 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:
- l
- v
- Description: In returns whether v is in the list l. l may be an array or
- slice.
+ 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 }}'
+ - - '{{ if in "this string contains a substring" "substring" }}Substring found!{{ end }}'
- Substring found!
Index:
Aliases:
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 }}'
+ - - '{{ 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 }}'
+ - - '{{ 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 }}'
+ - - '{{ 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 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"
+ - - '{{ $scratch := newScratch }}{{ $scratch.Add "b" 2 }}{{ $scratch.Add "b" 2 }}{{ $scratch.Get "b" }}'
+ - '4'
Querify:
Aliases:
- querify
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 }}'
+ - - '{{ (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?{{ (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: null
- Description: ""
- Examples: 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.\n\nExamples:\n\n\t3 => 1, 2, 3\n\t1 2 4 => 1, 3\n\t-3
- => -1, -2, -3\n\t1 4 => 1, 2, 3, 4\n\t1 -2 => 1, 0, -1, -2"
+ 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]'
- uniq
Args:
- l
- Description: Uniq returns a new list with duplicate elements in the list l
- removed.
+ Description: Uniq returns a new list with duplicate elements in the list l removed.
Examples:
- - '{{ slice 1 2 3 2 | uniq }}'
- '[1 2 3]'
Args:
- first
- others
- Description: Eq returns the boolean truth of arg1 == arg2 || arg1 == arg3
- || arg1 == arg4.
+ Description: Eq returns the boolean truth of arg1 == arg2 || arg1 == arg3 || arg1 == arg4.
Examples:
- - '{{ if eq .Section "blog" }}current-section{{ end }}'
- current-section
Args:
- first
- others
- Description: Ge returns the boolean truth of arg1 >= arg2 && arg1 >= arg3
- && arg1 >= arg4.
+ 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!
Args:
- first
- others
- Description: Gt returns the boolean truth of arg1 > arg2 && arg1 > arg3 &&
- arg1 > arg4.
+ Description: Gt returns the boolean truth of arg1 > arg2 && arg1 > arg3 && arg1 > arg4.
Examples: []
Le:
Aliases:
Args:
- first
- others
- Description: Le returns the boolean truth of arg1 <= arg2 && arg1 <= arg3
- && arg1 <= arg4.
+ Description: Le returns the boolean truth of arg1 <= arg2 && arg1 <= arg3 && arg1 <= arg4.
Examples: []
Lt:
Aliases:
Args:
- first
- others
- Description: Lt returns the boolean truth of arg1 < arg2 && arg1 < arg3 &&
- arg1 < arg4.
+ Description: Lt returns the boolean truth of arg1 < arg2 && arg1 < arg3 && arg1 < arg4.
Examples: []
LtCollate:
Aliases: null
- Args: null
- Description: ""
- Examples: 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.
+ Description: Ne returns the boolean truth of arg1 != arg2 && arg1 != arg3 && arg1 != arg4.
Examples: []
crypto:
- FNV32a:
- Aliases: null
- Args: null
- Description: ""
- Examples: null
HMAC:
Aliases:
- hmac
Examples: []
Quoted:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - v
+ Description: Quoted returns a string that needs to be quoted in CSS.
+ Examples: []
Sass:
Aliases:
- toCSS
Examples: []
TailwindCSS:
Aliases: null
- Args: null
- Description: ""
- Examples: null
- Unquoted:
- Aliases: null
- Args: null
- Description: ""
- Examples: null
- data:
- GetCSV:
- Aliases:
- - getCSV
Args:
- - sep
- args
- Description: |-
- GetCSV expects the separator sep and one or n-parts of a URL to a resource which
- can either be a local or a remote one.
- The data separator can be a comma, semi-colon, pipe, etc, but only one character.
- If you provide multiple parts for the URL they will be joined together to the final URL.
- GetCSV returns nil or a slice slice to use in a short code.
+ Description: TailwindCSS processes the given Resource with tailwindcss.
Examples: []
- GetJSON:
- Aliases:
- - getJSON
+ Unquoted:
+ Aliases: null
Args:
- - args
- Description: |-
- GetJSON expects one or n-parts of a URL in args to a resource which can either be a local or a remote one.
- If you provide multiple parts they will be joined together to the final URL.
- GetJSON returns nil or parsed JSON to use in a short code.
+ - v
+ Description: Unquoted returns a string that does not need to be quoted in CSS.
Examples: []
debug:
Dump:
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 }}
- {{ $m.Set "Hugo" "Rocks!" }}
- {{ $m.Values | debug.Dump | safeHTML }}
- - |-
- {
- "Hugo": "Rocks!"
- }
+ - - '{{ $m := newScratch }}\n{{ $m.Set "Hugo" "Rocks!" }}\n{{ $m.Values | debug.Dump | safeHTML }}'
+ - '{\n "Hugo": "Rocks!"\n}'
TestDeprecationErr:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - item
+ - alternative
+ Description: Internal template func, used in tests only.
+ Examples: []
TestDeprecationInfo:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - item
+ - alternative
+ Description: Internal template func, used in tests only.
+ Examples: []
TestDeprecationWarn:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - item
+ - alternative
+ Description: Internal template func, used in tests only.
+ Examples: []
Timer:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - name
+ Description: ''
+ Examples: []
VisualizeSpaces:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - val
+ Description: VisualizeSpaces returns a string with spaces replaced by a visible string.
+ Examples: []
diagrams:
Goat:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - v
+ Description: Goat creates a new SVG diagram from input v.
+ Examples: []
encoding:
Base64Decode:
Aliases:
- - '{{ "SGVsbG8gd29ybGQ=" | base64Decode }}'
- Hello world
- - '{{ 42 | base64Encode | base64Decode }}'
- - "42"
+ - '42'
Base64Encode:
Aliases:
- base64Encode
- - '{{ (slice "A" "B" "C") | jsonify }}'
- '["A","B","C"]'
- - '{{ (slice "A" "B" "C") | jsonify (dict "indent" " ") }}'
- - |-
- [
- "A",
- "B",
- "C"
- ]
+ - '[\n "A",\n "B",\n "C"\n]'
fmt:
Errorf:
Aliases:
It returns an empty string.
Examples:
- - '{{ errorf "%s." "failed" }}'
- - ""
+ - ''
Erroridf:
Aliases:
- erroridf
It returns an empty string.
Examples:
- - '{{ erroridf "my-err-id" "%s." "failed" }}'
- - ""
+ - ''
Errormf:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - m
+ - format
+ - args
+ Description: Errormf is experimental and subject to change at any time.
+ Examples: []
Print:
Aliases:
- print
Args:
- format
- args
- Description: Printf returns string representation of args formatted with the
- layout in format.
+ Description: Printf returns string representation of args formatted with the layout in format.
Examples:
- - '{{ printf "%s!" "works" }}'
- works!
- println
Args:
- args
- Description: Println returns string representation of args ending with a
- newline.
+ Description: Println returns string representation of args ending with a newline.
Examples:
- - '{{ println "works!" }}'
- |
It returns an empty string.
Examples:
- - '{{ warnf "%s." "warning" }}'
- - ""
+ - ''
Warnidf:
Aliases:
- warnidf
It returns an empty string.
Examples:
- - '{{ warnidf "my-warn-id" "%s." "warning" }}'
- - ""
+ - ''
Warnmf:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - m
+ - format
+ - args
+ Description: Warnmf is experimental and subject to change at any time.
+ Examples: []
hash:
FNV32a:
Aliases: null
Description: FNV32a hashes v using fnv32a algorithm.
Examples:
- - '{{ hash.FNV32a "Hugo Rocks!!" }}'
- - "1515779328"
+ - '1515779328'
XxHash:
Aliases:
- xxhash
Deps:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Generator:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
IsDevelopment:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
IsExtended:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
IsMultiHost:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
IsMultihost:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
IsMultilingual:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
IsProduction:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
IsServer:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Store:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Version:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
WorkingDir:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
images:
AutoOrient:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Brightness:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
ColorBalance:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Colorize:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Config:
Aliases:
Contrast:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Dither:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Filter:
Aliases: null
- Args: null
- Description: ""
- Examples: 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: ""
+ Description: ''
Examples: null
GaussianBlur:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Grayscale:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Hue:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Invert:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Mask:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Opacity:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Overlay:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Padding:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Pixelate:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Process:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
QR:
Aliases: null
- Args: null
- Description: ""
- Examples: 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: ""
+ Description: ''
Examples: null
Sepia:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Sigmoid:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Text:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
UnsharpMask:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
inflect:
Humanize:
Examples: []
Batch:
Aliases: null
- Args: null
- Description: ""
- Examples: 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: null
- Description: ""
- Examples: null
+ Args:
+ - args
+ Description: Build processes the given Resource with ESBuild.
+ Examples: []
lang:
FormatAccounting:
Aliases: null
Args:
- precision
- number
- Description: FormatNumber formats number with the given precision for the
- current language.
+ Description: FormatNumber formats number with the given precision for the current language.
Examples:
- - '{{ 512.5032 | lang.FormatNumber 2 }}'
- - "512.50"
+ - '512.50'
FormatNumberCustom:
Aliases: null
Args:
- precision
- number
- options
- Description: |-
- FormatNumberCustom formats a number with the given precision. The first
- options parameter is a space-delimited string of characters to represent
- negativity, the decimal point, and grouping. The default value is `- . ,`.
- The second options parameter defines an alternate delimiting character.
-
- Note that numbers are rounded up at 5 or greater.
- So, with precision set to 0, 1.5 becomes `2`, and 1.4 becomes `1`.
-
- For a simpler function that adapts to the current language, see FormatNumber.
+ 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"
+ - '-12345.678900'
- - '{{ lang.FormatNumberCustom 0 -12345.6789 "- . ," }}'
- -12,346
- - '{{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }}'
- 512.50%
Merge:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - p2
+ - p1
+ Description: Merge creates a union of pages from two languages.
+ Examples: []
Translate:
Aliases:
- i18n
Abs:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: Abs returns the absolute value of n.
Examples:
- - '{{ math.Abs -2.1 }}'
- - "2.1"
+ - '2.1'
Acos:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: Acos returns the arccosine, in radians, of n.
Examples:
- - '{{ math.Acos 1 }}'
- - "0"
+ - '0'
Add:
Aliases:
- add
Description: Add adds the multivalued addends n1 and n2 or more values.
Examples:
- - '{{ add 1 2 }}'
- - "3"
+ - '3'
Asin:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: Asin returns the arcsine, in radians, of n.
Examples:
- - '{{ math.Asin 1 }}'
- - "1.5707963267948966"
+ - '1.5707963267948966'
Atan:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: Atan returns the arctangent, in radians, of n.
Examples:
- - '{{ math.Atan 1 }}'
- - "0.7853981633974483"
+ - '0.7853981633974483'
Atan2:
Aliases: null
Args:
- - "n"
+ - '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.
+ 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"
+ - '0.4636476090008061'
Ceil:
Aliases: null
Args:
- - "n"
- Description: Ceil returns the least integer value greater than or equal to
- n.
+ - 'n'
+ Description: Ceil returns the least integer value greater than or equal to n.
Examples:
- - '{{ math.Ceil 2.1 }}'
- - "3"
+ - '3'
Cos:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: Cos returns the cosine of the radian argument n.
Examples:
- - '{{ math.Cos 1 }}'
- - "0.5403023058681398"
+ - '0.5403023058681398'
Counter:
Aliases: null
Args: null
- Description: ""
- Examples: 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
Description: Div divides n1 by n2.
Examples:
- - '{{ div 6 3 }}'
- - "2"
+ - '2'
Floor:
Aliases: null
Args:
- - "n"
- Description: Floor returns the greatest integer value less than or equal to
- n.
+ - 'n'
+ Description: Floor returns the greatest integer value less than or equal to n.
Examples:
- - '{{ math.Floor 1.9 }}'
- - "1"
+ - '1'
Log:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: Log returns the natural logarithm of the number n.
Examples:
- - '{{ math.Log 1 }}'
- - "0"
+ - '0'
Max:
Aliases: null
Args:
- inputs
- Description: Max returns the greater of all numbers in inputs. Any slices
- in inputs are flattened.
+ Description: Max returns the greater of all numbers in inputs. Any slices in inputs are flattened.
Examples:
- - '{{ math.Max 1 2 }}'
- - "2"
+ - '2'
MaxInt64:
Aliases: null
Args: null
Description: MaxInt64 returns the maximum value for a signed 64-bit integer.
Examples:
- - '{{ math.MaxInt64 }}'
- - "9223372036854775807"
+ - '9223372036854775807'
Min:
Aliases: null
Args:
- inputs
- Description: Min returns the smaller of all numbers in inputs. Any slices
- in inputs are flattened.
+ Description: Min returns the smaller of all numbers in inputs. Any slices in inputs are flattened.
Examples:
- - '{{ math.Min 1 2 }}'
- - "1"
+ - '1'
Mod:
Aliases:
- mod
Description: Mod returns n1 % n2.
Examples:
- - '{{ mod 15 3 }}'
- - "0"
+ - '0'
ModBool:
Aliases:
- modBool
Args:
- n1
- n2
- Description: ModBool returns the boolean of n1 % n2. If n1 % n2 == 0, return
- true.
+ Description: ModBool returns the boolean of n1 % n2. If n1 % n2 == 0, return true.
Examples:
- - '{{ modBool 15 3 }}'
- - "true"
+ - 'true'
Mul:
Aliases:
- mul
Description: Mul multiplies the multivalued numbers n1 and n2 or more values.
Examples:
- - '{{ mul 2 3 }}'
- - "6"
+ - '6'
Pi:
Aliases: null
Args: null
Description: Pi returns the mathematical constant pi.
Examples:
- - '{{ math.Pi }}'
- - "3.141592653589793"
+ - '3.141592653589793'
Pow:
Aliases:
- pow
Description: Pow returns n1 raised to the power of n2.
Examples:
- - '{{ math.Pow 2 3 }}'
- - "8"
+ - '8'
Product:
Aliases: null
- Args: null
- Description: ""
- Examples: 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).
+ Description: Rand returns, as a float64, a pseudo-random number in the half-open interval [0.0,1.0).
Examples:
- - '{{ math.Rand }}'
- - "0.6312770459590062"
+ - '0.6312770459590062'
Round:
Aliases: null
Args:
- - "n"
- Description: Round returns the integer nearest to n, rounding half away from
- zero.
+ - 'n'
+ Description: Round returns the integer nearest to n, rounding half away from zero.
Examples:
- - '{{ math.Round 1.5 }}'
- - "2"
+ - '2'
Sin:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: Sin returns the sine of the radian argument n.
Examples:
- - '{{ math.Sin 1 }}'
- - "0.8414709848078965"
+ - '0.8414709848078965'
Sqrt:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: Sqrt returns the square root of the number n.
Examples:
- - '{{ math.Sqrt 81 }}'
- - "9"
+ - '9'
Sub:
Aliases:
- sub
Description: Sub subtracts multivalued.
Examples:
- - '{{ sub 3 2 }}'
- - "1"
+ - '1'
Sum:
Aliases: null
- Args: null
- Description: ""
- Examples: 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"
+ - 'n'
Description: Tan returns the tangent of the radian argument n.
Examples:
- - '{{ math.Tan 1 }}'
- - "1.557407724654902"
+ - '1.557407724654902'
ToDegrees:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: ToDegrees converts radians into degrees.
Examples:
- - '{{ math.ToDegrees 1.5707963267948966 }}'
- - "90"
+ - '90'
ToRadians:
Aliases: null
Args:
- - "n"
+ - 'n'
Description: ToRadians converts degrees into radians.
Examples:
- - '{{ math.ToRadians 90 }}'
- - "1.5707963267948966"
+ - '1.5707963267948966'
openapi3:
Unmarshal:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: []
os:
FileExists:
Description: FileExists checks whether a file exists under the given path.
Examples:
- - '{{ fileExists "foo.txt" }}'
- - "false"
+ - 'false'
Getenv:
Aliases:
- getenv
- readDir
Args:
- i
- Description: ReadDir lists the directory contents relative to the configured
- WorkingDir.
+ Description: ReadDir lists the directory contents relative to the configured WorkingDir.
Examples:
- - '{{ range (readDir "files") }}{{ .Name }}{{ end }}'
- README.txt
- Hugo Rocks!
Stat:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - i
+ Description: Stat returns the os.FileInfo structure describing file.
+ Examples: []
partials:
Include:
Aliases:
path:
Base:
Aliases: null
- Args: null
- Description: ""
- Examples: 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: null
- Description: ""
- Examples: 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: null
- Description: ""
- Examples: null
+ Args:
+ - path
+ Description: |-
+ Clean replaces the separators used with standard slashes and then
+ extraneous slashes are removed.
+ Examples: []
Dir:
Aliases: null
- Args: null
- Description: ""
- Examples: 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: null
- Description: ""
- Examples: 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:
- - '{{ "/my/path/filename.txt" | path.Split }}'
- /my/path/|filename.txt
reflect:
+ IsImageResource:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
IsMap:
Aliases: null
Args:
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:
- - '{{ if reflect.IsSlice (slice 1 2 3) }}Slice{{ end }}'
- Slice
resources:
- Babel:
- Aliases: null
- Args: null
- Description: ""
- Examples: null
ByType:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - typ
+ Description: ByType returns resources of a given resource type (e.g. "image").
+ Examples: []
Concat:
Aliases: null
- Args: null
- Description: ""
- Examples: 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: null
- Description: ""
- Examples: null
+ Args:
+ - s
+ - r
+ Description: Copy copies r to the new targetPath in s.
+ Examples: []
ExecuteAsTemplate:
Aliases: null
- Args: null
- Description: ""
- Examples: 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
Examples: []
FromString:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - targetPathIn
+ - contentIn
+ Description: FromString creates a Resource from a string published to the relative target path.
+ Examples: []
Get:
Aliases: null
Args:
GetMatch:
Aliases: null
Args: null
- Description: ""
+ 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: |-
- GetRemote gets the URL (via HTTP(s)) in the first argument in args and creates Resource object that can be used for
- further transformations.
+ 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.
- A second argument may be provided with an option map.
+ 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".
- Note: This method does not return any error as a second return value,
- for any error situations the error can be checked in .Err.
+ 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: []
- Match:
- Aliases: null
- Args: null
- Description: ""
- Examples: null
Minify:
Aliases:
- minify
Minify minifies the given Resource using the MediaType to pick the correct
minifier.
Examples: []
- PostCSS:
- Aliases: null
- Args: null
- Description: ""
- Examples: null
PostProcess:
Aliases: null
- Args: null
- Description: ""
- Examples: null
- ToCSS:
- Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - r
+ Description: PostProcess processes r after the build.
+ Examples: []
safe:
CSS:
Aliases:
AllPages:
Aliases: null
Args: null
- Description: ""
- Examples: null
- Author:
- Aliases: null
- Args: null
- Description: ""
- Examples: null
- Authors:
- Aliases: null
- Args: null
- Description: ""
+ Description: ''
Examples: null
BaseURL:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
BuildDrafts:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
CheckReady:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Config:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Copyright:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Current:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Data:
Aliases: null
Args: null
- Description: ""
+ Description: ''
+ Examples: null
+ Dimension:
+ Aliases: null
+ Args: null
+ Description: ''
Examples: null
ForEeachIdentityByName:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
GetPage:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Home:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Hugo:
Aliases: null
Args: null
- Description: ""
- Examples: null
- IsMultiLingual:
- Aliases: null
- Args: null
- Description: ""
+ Description: ''
Examples: null
Key:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Language:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
LanguageCode:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
LanguagePrefix:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Languages:
Aliases: null
Args: null
- Description: ""
- Examples: null
- LastChange:
- Aliases: null
- Args: null
- Description: ""
+ Description: ''
Examples: null
Lastmod:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
MainSections:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Menus:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Pages:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Param:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Params:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
RegularPages:
Aliases: null
Args: null
- Description: ""
+ Description: ''
+ Examples: null
+ Role:
+ Aliases: null
+ Args: null
+ Description: ''
Examples: null
Sections:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
ServerPort:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Sites:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
- Social:
+ Store:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
- Store:
+ String:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Taxonomies:
Aliases: null
Args: null
- Description: ""
+ Description: ''
Examples: null
Title:
Aliases: null
Args: null
- Description: ""
+ Description: ''
+ Examples: null
+ Version:
+ Aliases: null
+ Args: null
+ Description: ''
Examples: null
strings:
Chomp:
- chomp
Args:
- s
- Description: Chomp returns a copy of s with all trailing newline characters
- removed.
+ Description: Chomp returns a copy of s with all trailing newline characters removed.
Examples:
- - '{{ chomp "<p>Blockhead</p>\n" | safeHTML }}'
- <p>Blockhead</p>
Description: Contains reports whether substr is in s.
Examples:
- - '{{ strings.Contains "abc" "b" }}'
- - "true"
+ - 'true'
- - '{{ strings.Contains "abc" "d" }}'
- - "false"
+ - 'false'
ContainsAny:
Aliases: null
Args:
- s
- chars
- Description: ContainsAny reports whether any Unicode code points in chars
- are within s.
+ Description: ContainsAny reports whether any Unicode code points in chars are within s.
Examples:
- - '{{ strings.ContainsAny "abc" "bcd" }}'
- - "true"
+ - 'true'
- - '{{ strings.ContainsAny "abc" "def" }}'
- - "false"
+ - 'false'
ContainsNonSpace:
Aliases: null
- Args: null
- Description: ""
- Examples: 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:
If substr is an empty string, Count returns 1 + the number of Unicode code points in s.
Examples:
- - '{{ "aabab" | strings.Count "a" }}'
- - "3"
+ - '3'
CountRunes:
Aliases:
- countrunes
Examples: []
Diff:
Aliases: null
- Args: null
- Description: ""
- Examples: 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
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
- }}'
+ - - '{{ findRE "[G|g]o" "Hugo is a static side generator written in Go." 1 }}'
- '[go]'
FindRESubmatch:
Aliases:
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 }}'
+ - - '{{ 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
Description: HasPrefix tests whether the input s begins with prefix.
Examples:
- - '{{ hasPrefix "Hugo" "Hu" }}'
- - "true"
+ - 'true'
- - '{{ hasPrefix "Hugo" "Fu" }}'
- - "false"
+ - 'false'
HasSuffix:
Aliases:
- hasSuffix
Description: HasSuffix tests whether the input s begins with suffix.
Examples:
- - '{{ hasSuffix "Hugo" "go" }}'
- - "true"
+ - 'true'
- - '{{ hasSuffix "Hugo" "du" }}'
- - "false"
+ - 'false'
Repeat:
Aliases: null
Args:
- - "n"
+ - 'n'
- s
- Description: Repeat returns a new string consisting of n copies of the string
- s.
+ Description: Repeat returns a new string consisting of n copies of the string s.
Examples:
- - '{{ "yo" | strings.Repeat 4 }}'
- yoyoyoyo
- pattern
- repl
- s
- - "n"
+ - '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
Args:
- a
- delimiter
- Description: Split slices an input string into all substrings separated by
- delimiter.
+ Description: Split slices an input string into all substrings separated by delimiter.
Examples: []
Substr:
Aliases:
Args:
- a
- nums
- Description: |-
- Substr extracts parts of a string, beginning at the character at the specified
- position, and returns the specified number of characters.
-
- It normally takes two parameters: start and length.
- It can also take one parameter: start, i.e. length is omitted, in which case
- the substring starting from start until the end of the string will be returned.
-
- To extract characters from the end of the string, use a negative start number.
-
- In addition, borrowing from the extended behavior described at http://php.net/substr,
- if length is given and is negative, then that many characters will be omitted from
- the end of string.
+ 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
- aabb
TrimSpace:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - s
+ Description: |-
+ TrimSpace returns the given string, removing leading and trailing whitespace
+ as defined by Unicode.
+ Examples: []
TrimSuffix:
Aliases: null
Args:
templates:
Current:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - ctx
+ Description: Get information about the currently executing template.
+ Examples: []
Defer:
Aliases: null
Args:
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 }}'
+ - - '{{ if (templates.Exists "_partials/header.html") }}Yes!{{ end }}'
- Yes!
- - - '{{ if not (templates.Exists "partials/doesnotexist.html") }}No!{{ end
- }}'
+ - - '{{ 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
a time.Time interface.
Examples:
- - '{{ (time "2015-01-21").Year }}'
- - "2015"
+ - '2015'
Duration:
Aliases:
- duration
- 'dateFormat: Wednesday, Jan 21, 2015'
In:
Aliases: null
- Args: null
- Description: ""
- Examples: 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
Aliases: null
Args:
- s
- Description: |-
- ParseDuration parses the duration string s.
- A duration string is a possibly signed sequence of
- decimal numbers, each with optional fraction and a unit suffix,
- such as "300ms", "-1.5h" or "2h45m".
- Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
- See https://golang.org/pkg/time/#ParseDuration
+ 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: null
- Description: ""
- Examples: null
+ Args:
+ - language
+ Description: CanHighlight returns whether the given code language is supported by the Chroma highlighter.
+ Examples: []
Emojify:
Aliases:
- emojify
- htmlEscape
Args:
- s
- Description: HTMLEscape returns a copy of s with reserved HTML characters
- escaped.
+ Description: HTMLEscape returns a copy of s with reserved HTML characters escaped.
Examples:
- - - '{{ htmlEscape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" |
- safeHTML }}'
+ - - '{{ 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 }}'
+ - - '{{ 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
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 }}'
+ - - '{{ 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 &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 &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 }}'
+ - - '{{ htmlUnescape "Cathal Garvey & The Sunshine Band <cathal@foo.bar>" | htmlEscape | safeHTML }}'
- Cathal Garvey & The Sunshine Band <cathal@foo.bar>
Highlight:
Aliases:
Examples: []
HighlightCodeBlock:
Aliases: null
- Args: null
- Description: ""
- Examples: null
+ Args:
+ - ctx
+ - opts
+ Description: HighlightCodeBlock highlights a code block on the form received in the codeblock render hooks.
+ Examples: []
Markdownify:
Aliases:
- markdownify
- Hello world, gophers!
PortableText:
Aliases: null
- Args: null
- Description: ""
- Examples: 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:
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
- }}'
- - |
- {
- "title": "Hello World"
- }
+ - - '{{ "title = \"Hello World\"" | transform.Remarshal "json" | safeHTML }}'
+ - '{\n "title": "Hello World"\n}\n'
ToMath:
Aliases: null
- Args: null
- Description: ""
- Examples: 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
Examples:
- - '{{ "hello = \"Hello World\"" | transform.Unmarshal }}'
- map[hello:Hello World]
- - - '{{ "hello = \"Hello World\"" | resources.FromString "data/greetings.toml"
- | transform.Unmarshal }}'
+ - - '{{ "hello = \"Hello World\"" | resources.FromString "data/greetings.toml" | transform.Unmarshal }}'
- map[hello:Hello World]
XMLEscape:
Aliases: null
- a/b
Parse:
Aliases: null
- Args: null
- Description: ""
- Examples: 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.
+ Description: Ref returns the absolute URL path to a given content item from Page p.
Examples: []
RelLangURL:
Aliases:
Args:
- p
- args
- Description: RelRef returns the relative URL path to a given content item
- from Page p.
+ Description: RelRef returns the relative URL path to a given content item from Page p.
Examples: []
RelURL:
Aliases:
# will decrease over time, though the initial implementation will require some
# effort.
+- decorator
+- filter
- highlight
- menu
+- metadata
+- process
- random
- resource
-[[banners]]
- name = "Linode"
- link = "https://www.linode.com/"
- logo = "images/sponsors/linode-logo.svg"
- utm_campaign = "hugosponsor"
- bgcolor = "#ffffff"
-
[[banners]]
name = "GoLand"
title = "The complete IDE crafted for professional Go developers."
logo = "images/sponsors/cloudcannon-cms-logo.svg"
no_query_params = true
bgcolor = "#ffffff"
+
+[[banners]]
+ name = "Your Company?"
+ link = "https://bep.is/en/hugo-sponsor-2023-01/"
+ utm_campaign = "hugosponsor"
+ show_on_hover = true
+ bgcolor = "#4e4f4f"
+ link_attr = "style='color: #ffffff; font-weight: bold; text-decoration: none; text-align: center'"
# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below).
disableAliases = true
-# See https://github.com/gohugoio/hugo/issues/13806.
-ignoreLogs = ['warning-frontmatter-params-overrides']
-
[build]
[build.buildStats]
disableIDs = true
[markup]
[markup.goldmark]
[markup.goldmark.extensions]
- [markup.goldmark.extensions.typographer]
- disable = false
[markup.goldmark.extensions.passthrough]
enable = true
[markup.goldmark.extensions.passthrough.delimiters]
inline = [['\(', '\)']]
[markup.goldmark.parser]
autoDefinitionTermID = true
+ wrapStandAloneImageWithinParagraph = false
[markup.goldmark.parser.attribute]
block = true
[markup.highlight]
source = "assets"
target = "assets"
[[module.mounts]]
- lang = 'en'
source = 'content/en'
target = 'content'
+ [module.mounts.sites.matrix]
+ languages = ['en']
[[module.mounts]]
disableWatch = true
source = "hugo_stats.json"
category = 'categories'
######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES ########
+
[menus]
[[menus.global]]
identifier = 'news'
{{ end }}
</div>
<div
- class=" relative flex flex-grow basis-0 items-center min-w-24 max-w-3xl overflow-x-auto">
+ class="relative hidden sm:flex flex-grow basis-0 items-center min-w-24 max-w-3xl overflow-x-auto">
{{ range .Site.Menus.global }}
<a
href="{{ .URL }}"
</div>
</div>
- <div class="-my-5 pl-2 grow-0">
+ <div class="-my-5 pl-0 sm:pl-2 grow-0 flex items-center gap-0">
{{/* Search. */}}
{{ partial "layouts/search/input.html" . }}
+ {{/* Theme selector - shown inline on mobile */}}
+ <div class="sm:hidden">
+ {{ partial "layouts/header/theme.html" . }}
+ </div>
</div>
<div
- class="relative ml-0 md:ml-8 flex content-center basis-0 justify-end gap-0 sm:gap-1 xl:grow-1">
+ class="relative hidden sm:flex ml-0 md:ml-8 content-center basis-0 justify-end gap-0 sm:gap-1 xl:grow-1">
{{/* QR code. */}}
{{ partial "layouts/header/qr.html" . }}
- {{/* Theme selector. */}}
+ {{/* Theme selector - hidden on mobile (shown above) */}}
{{ partial "layouts/header/theme.html" . }}
{{/* Social. */}}
{{ partial "layouts/header/mastodon.html" . }}
</div>
</div>
+
+ {{/* Mobile menu hamburger button - only visible on small screens */}}
+ <button
+ @click="$store.nav.mobileMenu.toggle()"
+ class="sm:hidden p-2 ml-2 text-gray-300 hover:text-white rounded-md hover:bg-blue-900 transition-colors"
+ aria-label="Open menu"
+ :aria-expanded="$store.nav.mobileMenu.open">
+ <svg class="w-6 h-6">
+ <use href="#icon--bars-3"></use>
+ </svg>
+ </button>
</header>
+
+{{/* Mobile menu panel */}}
+{{ partial "layouts/header/mobilemenu.html" . }}
--- /dev/null
+{{/* Mobile menu overlay and panel - only visible on small screens */}}
+<div
+ x-data
+ x-show="$store.nav.mobileMenu.open"
+ x-transition:enter="transition-opacity ease-out duration-200"
+ x-transition:enter-start="opacity-0"
+ x-transition:enter-end="opacity-100"
+ x-transition:leave="transition-opacity ease-in duration-150"
+ x-transition:leave-start="opacity-100"
+ x-transition:leave-end="opacity-0"
+ class="sm:hidden fixed inset-0 z-50 bg-gray-900/50 backdrop-blur-sm"
+ @click="$store.nav.mobileMenu.close()"
+ x-cloak>
+</div>
+
+{{/* Mobile menu panel */}}
+<div
+ x-data
+ x-show="$store.nav.mobileMenu.open"
+ x-transition:enter="transition ease-out duration-200"
+ x-transition:enter-start="translate-x-full"
+ x-transition:enter-end="translate-x-0"
+ x-transition:leave="transition ease-in duration-150"
+ x-transition:leave-start="translate-x-0"
+ x-transition:leave-end="translate-x-full"
+ class="sm:hidden fixed top-0 right-0 z-50 h-full w-72 bg-blue-950 shadow-xl"
+ @keydown.escape.window="$store.nav.mobileMenu.close()"
+ x-cloak>
+
+ {{/* Header with close button */}}
+ <div class="flex items-center justify-between px-4 py-5">
+ <span class="text-white text-xl font-bold">Menu</span>
+ <button
+ @click="$store.nav.mobileMenu.close()"
+ class="p-2 text-gray-300 hover:text-white rounded-md hover:bg-blue-900 transition-colors"
+ aria-label="Close menu">
+ <svg class="w-6 h-6">
+ <use href="#icon--x-mark"></use>
+ </svg>
+ </button>
+ </div>
+
+ {{/* Navigation links */}}
+ <nav class="px-4 py-2">
+ <ul class="space-y-1">
+ {{ range .Site.Menus.global }}
+ <li>
+ <a
+ href="{{ .URL }}"
+ @click="$store.nav.mobileMenu.close()"
+ class="block px-3 py-3 text-gray-200 hover:text-white hover:bg-blue-900 rounded-md font-medium transition-colors">
+ {{ .Name }}
+ </a>
+ </li>
+ {{ end }}
+ </ul>
+ </nav>
+
+ {{/* Divider */}}
+ <div class="mx-4 my-4 border-t border-blue-800"></div>
+
+ {{/* Search trigger */}}
+ <div class="px-4 py-2">
+ <button
+ @click="$dispatch('search-toggle'); $store.nav.mobileMenu.close()"
+ class="w-full flex items-center gap-3 px-3 py-3 text-gray-200 hover:text-white hover:bg-blue-900 rounded-md font-medium transition-colors">
+ <svg class="w-5 h-5 fill-current">
+ <use href="#icon--search"></use>
+ </svg>
+ Search
+ </button>
+ </div>
+
+ {{/* Divider */}}
+ <div class="mx-4 my-4 border-t border-blue-800"></div>
+
+ {{/* Social links */}}
+ <div class="px-4 py-2 space-y-1">
+ {{/* GitHub */}}
+ {{ with partialCached "helpers/funcs/get-github-info.html" . "-" }}
+ <a
+ href="{{ .html_url | safeURL }}"
+ target="_blank"
+ class="flex items-center gap-3 px-3 py-3 text-gray-200 hover:text-white hover:bg-blue-900 rounded-md font-medium transition-colors">
+ <svg class="w-5 h-5 fill-current">
+ <use href="#icon--github"></use>
+ </svg>
+ GitHub
+ <span class="ml-auto text-sm text-gray-400">{{ .stargazers_count }} stars</span>
+ </a>
+ {{ end }}
+
+ {{/* Mastodon */}}
+ {{ with site.Params.social.mastodon.url }}
+ <a
+ href="{{ . }}"
+ target="_blank"
+ class="flex items-center gap-3 px-3 py-3 text-gray-200 hover:text-white hover:bg-blue-900 rounded-md font-medium transition-colors">
+ <svg class="w-5 h-5" viewBox="0 0 75 79" fill="currentColor">
+ <path d="M73.8393 17.4898C72.6973 9.00165 65.2994 2.31235 56.5296 1.01614C55.05 0.797115 49.4441 0 36.4582 0H36.3612C23.3717 0 20.585 0.797115 19.1054 1.01614C10.5798 2.27644 2.79399 8.28712 0.904997 16.8758C-0.00358524 21.1056 -0.100549 25.7949 0.0682394 30.0965C0.308852 36.2651 0.355538 42.423 0.91577 48.5665C1.30307 52.6474 1.97872 56.6957 2.93763 60.6812C4.73325 68.042 12.0019 74.1676 19.1233 76.6666C26.7478 79.2728 34.9474 79.7055 42.8039 77.9162C43.6682 77.7151 44.5217 77.4817 45.3645 77.216C47.275 76.6092 49.5123 75.9305 51.1571 74.7385C51.1797 74.7217 51.1982 74.7001 51.2112 74.6753C51.2243 74.6504 51.2316 74.6229 51.2325 74.5948V68.6416C51.2321 68.6154 51.2259 68.5896 51.2142 68.5661C51.2025 68.5426 51.1858 68.522 51.1651 68.5058C51.1444 68.4896 51.1204 68.4783 51.0948 68.4726C51.0692 68.4669 51.0426 68.467 51.0171 68.4729C45.9835 69.675 40.8254 70.2777 35.6502 70.2682C26.7439 70.2682 24.3486 66.042 23.6626 64.2826C23.1113 62.762 22.7612 61.1759 22.6212 59.5646C22.6197 59.5375 22.6247 59.5105 22.6357 59.4857C22.6466 59.4609 22.6633 59.4391 22.6843 59.422C22.7053 59.4048 22.73 59.3929 22.7565 59.3871C22.783 59.3813 22.8104 59.3818 22.8367 59.3886C27.7864 60.5826 32.8604 61.1853 37.9522 61.1839C39.1768 61.1839 40.3978 61.1839 41.6224 61.1516C46.7435 61.008 52.1411 60.7459 57.1796 59.7621C57.3053 59.7369 57.431 59.7154 57.5387 59.6831C65.4861 58.157 73.0493 53.3672 73.8178 41.2381C73.8465 40.7606 73.9184 36.2364 73.9184 35.7409C73.9219 34.0569 74.4606 23.7949 73.8393 17.4898Z" />
+ </svg>
+ Mastodon
+ </a>
+ {{ end }}
+ </div>
+</div>
<path d="M10 1a6 6 0 0 0-3.815 10.631C7.237 12.5 8 13.443 8 14.456v.644a.75.75 0 0 0 .572.729 6.016 6.016 0 0 0 2.856 0A.75.75 0 0 0 12 15.1v-.644c0-1.013.762-1.957 1.815-2.825A6 6 0 0 0 10 1ZM8.863 17.414a.75.75 0 0 0-.226 1.483 9.066 9.066 0 0 0 2.726 0 .75.75 0 0 0-.226-1.483 7.553 7.553 0 0 1-2.274 0Z" />
</symbol>
</svg>
+
+{{/* https://heroicons.com/outline bars-3 (hamburger menu) */}}
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--bars-3" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+ <path stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" d="M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25h16.5" />
+ </symbol>
+</svg>
+
+{{/* https://heroicons.com/outline x-mark (close) */}}
+<svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
+ <symbol id="icon--x-mark" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+ <path stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" d="M6 18 18 6M6 6l12 12" />
+ </symbol>
+</svg>
Renders the glossary of terms.
When you call this shortcode using the {{% %}} notation, the glossary terms are
-Markdown headings (level 6) which means they are members of .Fragments. This
+description term (dt) elements which means they are members of .Fragments. This
allows the link render hook to verify links to glossary terms.
Yes, the terms themselves are pages, but we don't want to link to the pages, at
{{- $destination = $u.String }}
{{- else }}
{{- with site.GetPage $u.Path }}
- {{- $destination = .Path }}
+ {{- if $u.Fragment }}
+ {{- $destination = printf "%s#%s" .Path $u.Fragment }}
+ {{ else }}
+ {{- $destination = .Path }}
+ {{- end }}
{{- else }}
{{- errorf "The %q shortcode was unable to find the reference link %s: see %s" $.Name . $p.String }}
{{- end }}
[build]
publish = "public"
- command = "hugo --gc --minify"
+ command = "npm ls && hugo --gc --minify"
[build.environment]
- HUGO_VERSION = "0.152.2"
+ HUGO_VERSION = "0.155.3"
[context.production.environment]
HUGO_ENV = "production"
HUGO_ENABLEGITINFO = "true"
[context.split1]
- command = "hugo --gc --minify --enableGitInfo"
+ command = "npm ls && hugo --gc --minify --enableGitInfo"
[context.split1.environment]
HUGO_ENV = "production"
[context.deploy-preview]
- command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL --enableGitInfo"
+ command = "npm ls && hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL --enableGitInfo"
[context.branch-deploy]
- command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
+ command = "npm ls && hugo --gc --minify -b $DEPLOY_PRIME_URL"
[context.next.environment]
HUGO_ENABLEGITINFO = "true"
"tailwindcss": "~4.1.18"
},
"dependencies": {
- "@alpinejs/focus": "~3.15.3",
- "@alpinejs/persist": "~3.15.3",
- "@hotwired/turbo": "~8.0.20",
- "alpinejs": "~3.15.3"
+ "@alpinejs/focus": "3.15.3",
+ "@alpinejs/persist": "3.15.3",
+ "@hotwired/turbo": "8.0.20",
+ "alpinejs": "3.15.3"
}
}
projects / brevno-suite / hugo / commitdiff