blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-24 15:28:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '8f3c066d23f431fb2c53d97ea489e4c28b42bd82'

Browse Source 
# Conflicts:
#	docs/data/docs.yaml
This commit is contained in:
Bjørn Erik Pedersen
2026-02-14 12:14:33 +01:00
parent 7850e7ceb5 8f3c066d23
commit 30a20122b7
226 changed files with 2727 additions and 1790 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.codespellrc
+1 -1
View File
@@ -4,7 +4,7 @@
[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
docs/.cspell.json
+2 -2
View File
@@ -23,8 +23,7 @@
"**/emojis.md",
"**/commands/*",
"**/showcase/*",
"**/tools/*",
"data/docs.yaml"
"**/tools/*"
],
"ignoreRegExpList": [
"# cspell: ignore fenced code blocks",
@@ -182,6 +181,7 @@
"dring",
"fleqn",
"inor",
"iptc",
"jausten",
"jdoe",
"jsmith",
docs/.gitignore
+1
View File
@@ -1,5 +1,6 @@
.DS_Store
.hugo_build.lock
.hvm
/.idea
/.vscode
/dist
docs/.markdownlint-cli2.yaml
+4 -1
View File
@@ -80,7 +80,7 @@ config:
url_inline: false
MD055:
style: consistent
MD056: true
MD056: false # interferes with Markdown attributes
# MD057 deprecated
MD058: true
MD059:
@@ -89,3 +89,6 @@ config:
- here
- link
- more
MD060:
aligned_delimiter: false
style: any
docs/AGENTS.md
+25
View File
@@ -0,0 +1,25 @@
## 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.
docs/CLAUDE.md
+1
View File
@@ -0,0 +1 @@
@AGENTS.md
docs/README.md
-2
View File
@@ -23,5 +23,3 @@ Please see the [contributing] section for guidelines, examples, and process.
npm i
hugo server
```
**Note:** We're working on removing the need to run `npm i` for local development. Stay tuned.
docs/assets/css/styles.css
+9 -2
View File
@@ -77,8 +77,9 @@
/* 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 {
@@ -134,3 +135,9 @@ body {
: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;
}
docs/assets/js/alpinejs/stores/nav.js
+10
View File
@@ -31,6 +31,16 @@ export const navStore = (Alpine) => ({
atTop: true,
},
mobileMenu: {
open: false,
toggle() {
this.open = !this.open;
},
close() {
this.open = false;
},
},
userSettings: {
// settings gets persisted between page navigations.
settings: Alpine.$persist({
docs/content/en/_common/functions/js/options.md
-2
View File
@@ -84,11 +84,9 @@ sourcesContent
: (`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.:
docs/content/en/_common/installation/01-editions.md
+6 -4
View File
@@ -2,15 +2,17 @@
_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&nbsp;[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/
docs/content/en/_common/installation/02-prerequisites.md
+7 -6
View File
@@ -12,7 +12,7 @@ Git is required to:
- 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:
@@ -27,16 +27,17 @@ Please refer to the relevant documentation for installation instructions:
- [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/
docs/content/en/_common/methods/output-formats/to-use-this-method.md
+9
View File
@@ -0,0 +1,9 @@
---
_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/
docs/content/en/_common/methods/page/output-format-methods.md
-35
View File
@@ -1,35 +0,0 @@
---
_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.
docs/content/en/_common/methods/resource/processing-spec.md
+60 -23
View File
@@ -2,35 +2,72 @@
_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&nbsp;[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&nbsp;[details](/content-management/image-processing/#anchor).
rotation
: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See&nbsp;[details](/content-management/image-processing/#rotation).
target format
: Specify zero or one of `gif`, `jpeg`, `png`, `tiff`, or `webp`. See&nbsp;[details](/content-management/image-processing/#target-format).
quality
: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See&nbsp;[details](/content-management/image-processing/#quality).
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&nbsp;[details](/content-management/image-processing/#hint).
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
: 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.
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&nbsp;[details](/content-management/image-processing/#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.
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.
dimensions
: The dimensions of the resulting image, in pixels. The format is `WIDTHxHEIGHT` where `WIDTH` and `HEIGHT` are whole numbers. When resizing an image, you may specify only the width (such as `600x`) or only the height (such as `x400`) for proportional scaling. Specifying both width and height when resizing an image may result in non-proportional scaling. When cropping, fitting, or filling, you must provide both width and height such as `600x400`.
format
: The format of the resulting image. Valid options include `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image.
hint
: The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your site configuration.
Value|Example
:--|:--
`drawing`|Hand or line drawing with high-contrast details
`icon`|Small colorful image
`photo`|Outdoor photograph with natural lighting
`picture`|Indoor photograph such as a portrait
`text`|Image that is primarily text
quality
: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your site configuration.
resampling filter
: Typically specify zero or one of `Box`, `Lanczos`, `CatmullRom`, `MitchellNetravali`, `Linear`, or `NearestNeighbor`. Other resampling filters are available. See&nbsp;[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
docs/content/en/_common/render-hooks/pageinner.md
-2
View File
@@ -4,8 +4,6 @@ _comment: Do not remove front matter.
## 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}
docs/content/en/about/features.md
+5 -1
View File
@@ -60,6 +60,9 @@ weight: 20
## 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.
@@ -78,7 +81,7 @@ weight: 20
## Asset pipelines
[Image processing]
: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract EXIF data.
: Convert, resize, crop, rotate, adjust colors, apply filters, overlay text and images, and extract metadata.
[JavaScript bundling]
: Transpile TypeScript and JSX to JavaScript, bundle, tree shake, minify, create source maps, and perform SRI hashing.
@@ -120,6 +123,7 @@ weight: 20
[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/
docs/content/en/configuration/all.md
+130 -61
View File
@@ -19,7 +19,7 @@ baseURL
: (`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`.
@@ -34,20 +34,19 @@ cacheDir
: (`string`) The designated cache directory. See&nbsp;[details](#cache-directory).
caches
: See [configure file caches](/configuration/caches/).
: See [configure file caches][].
canonifyURLs
: (`bool`) See&nbsp;[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 %}}
@@ -59,23 +58,43 @@ dataDir
: (`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`.
@@ -84,19 +103,19 @@ disableKinds
: (`[]string`) A slice of page [kinds](g) to disable during the build process, any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
disableLanguages
: (`[]string`) A slice of language keys representing the languages to disable during the build process. Although this is functional, consider using the [`disabled`] key under each language instead.
: (`[]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`.
@@ -108,13 +127,13 @@ environment
: (`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 %}}
@@ -123,49 +142,49 @@ ignoreCache
: (`bool`) Whether to ignore the cache directory. Default is `false`.
ignoreFiles
: (`[]string`) A slice of [regular expressions](g) used to exclude specific files from a build. These expressions are matched against the absolute file path and apply to files within the `content`, `data`, and `i18n` directories. For more advanced file exclusion options, see the section on [module mounts].
: (`[]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.
@@ -180,25 +199,25 @@ noTimes
: (`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`.
@@ -213,7 +232,7 @@ printUnusedTemplates
: (`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`.
@@ -225,47 +244,49 @@ refLinksNotFoundURL
: (`string`) The URL to return when the `ref` and `relref` functions, methods, and shortcodes are unable to resolve a reference to a page.
related
: See [configure related content](/configuration/related-content/).
: See [configure related content][].
relativeURLs
: (`bool`) See&nbsp;[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&nbsp;[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&nbsp;[details](/troubleshooting/performance/#template-metrics).
@@ -280,26 +301,29 @@ themesDir
: (`string`) The designated directory for themes. Default is `themes`.
timeout
: (`string`) The timeout for generating page content, either as a [duration] or in seconds. This timeout is used to prevent infinite recursion during content generation. You may need to increase this value if your pages take a long time to generate, for example, due to extensive image processing or reliance on remote content. Default is `60s`.
: (`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&nbsp;[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&nbsp;[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`:
@@ -310,13 +334,13 @@ hugo config | grep cachedir
## Title case style
Hugo's [`titleCaseStyle`] setting governs capitalization for automatically generated section titles and the [`strings.Title`] function. By default, it follows the capitalization rules published in the Associated Press Stylebook. Change this setting to use other capitalization rules.
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.
@@ -329,15 +353,24 @@ none
## 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/
@@ -345,16 +378,52 @@ Some configuration settings, such as menus and custom parameters, can be defined
[`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
docs/content/en/configuration/caches.md
+33 -5
View File
@@ -10,21 +10,49 @@ This is the default configuration:
{{< code-toggle config=caches />}}
## Purpose
Hugo uses file caches to store data on disk, avoiding repeated operations within the same build and persisting data from one build to the next.
assets
: Caches processed CSS and Sass resources.
getresource
: Caches files fetched from remote URLs via the [`resources.GetRemote`][] function.
images
: Caches processed images.
misc
: Caches miscellaneous data.
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&nbsp;[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&nbsp;[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/
docs/content/en/configuration/cascade.md
+5 -5
View File
@@ -23,7 +23,7 @@ color = 'red'
<!-- 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:
@@ -40,16 +40,16 @@ path = '{/articles,/articles/**}'
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
docs/content/en/configuration/deployment.md
+2 -2
View File
@@ -53,13 +53,13 @@ cloudFrontDistributionID
: (`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.
docs/content/en/configuration/http-cache.md
+6 -6
View File
@@ -57,10 +57,10 @@ respectCacheControlNoStoreInResponse
: (`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.
@@ -75,10 +75,10 @@ polls.low
: (`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
@@ -109,10 +109,10 @@ polls.low
: (`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
docs/content/en/configuration/imaging.md
+87 -24
View File
@@ -14,56 +14,119 @@ These are the default settings for processing images:
[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`.
: (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`.
[hexadecimal]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
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&nbsp;[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&nbsp;[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`.
## EXIF data
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
These are the default settings for extracting EXIF data from images:
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
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`.
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.
includeFields
: (`string`) A [regular expression](g) matching the tags to include when extracting EXIF data. To include all available tags, set this value to&nbsp;`".*"`.
: (`string`) A [regular expression](g) matching the fields to exclude when extracting metadata.
> [!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.
> 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`.
[`Crop`]: /methods/resource/crop/
[`Fill`]: /methods/resource/fill/
includeFields
: (`string`) A [regular expression](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set&nbsp;to&nbsp;`'.*'`&nbsp;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&nbsp;to&nbsp;`['**']`&nbsp;to include all fields.
> [!note]
> By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
sources
: (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance.
[`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
docs/content/en/configuration/introduction.md
+1 -2
View File
@@ -235,7 +235,7 @@ The above sets the [`baseURL`], [`enableGitInfo`], and [`environment`] configura
> [!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_`.
@@ -253,7 +253,6 @@ HUGO_FILE_LOG_FORMAT
: (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`.
HUGO_MEMORYLIMIT
: {{< 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
docs/content/en/configuration/languages.md
+26 -16
View File
@@ -18,14 +18,14 @@ disableLanguages = []
{{< /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.
@@ -42,25 +42,30 @@ disabled
: (`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
@@ -87,7 +92,7 @@ Any key not defined in a `languages` object will fall back to the global value i
## 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'
@@ -99,7 +104,7 @@ 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'
@@ -145,7 +150,7 @@ subtitle = 'Reference, Tutorials, and Explanations'
{{< /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
@@ -179,15 +184,20 @@ public
└── 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
docs/content/en/configuration/markup.md
+5 -9
View File
@@ -136,7 +136,6 @@ Markdown|Replaced by|Description
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]
@@ -169,30 +168,27 @@ parser.attribute.title
<!-- 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
@@ -216,7 +212,7 @@ backend
: (`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`.
docs/content/en/configuration/minify.md
-2
View File
@@ -13,8 +13,6 @@ This is the default configuration:
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
docs/content/en/configuration/module.md
+29 -22
View File
@@ -30,13 +30,13 @@ auth
: (`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.
@@ -76,8 +76,18 @@ You can omit any of the settings above.
extended
: (`bool`) Whether the extended edition of Hugo is required, satisfied by installing either the extended or extended/deploy edition.
> [!note]
> The extended version check is disabled in v0.153.2 and later.
>
> Historically, certain features—specifically WebP encoding and LibSass—required the Hugo Extended binary. However, as of v0.153.0:
>
> - WebP encoding is now supported in all Hugo editions.
> - LibSass has been deprecated in favor of [Dart Sass][], which is compatible with any Hugo edition.
>
> Because these dependencies no longer require a specialized binary, the internal enforcement check for the extended version has been removed. Site and theme authors are encouraged to use Dart Sass to ensure cross-edition compatibility.
max
: (`string`) The maximum Hugo version supported, for example `0.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`.
@@ -123,14 +133,6 @@ version
> [!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.
@@ -153,16 +155,13 @@ disableWatch
: {{< 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
@@ -171,7 +170,7 @@ excludeFiles
[[module.mounts]]
source="content"
target="content"
excludeFiles="docs/*"
files=["! docs/*"]
[[module.mounts]]
source="node_modules"
target="assets"
@@ -180,4 +179,12 @@ excludeFiles
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
docs/content/en/configuration/output-formats.md
+4 -3
View File
@@ -41,7 +41,7 @@ baseName
: (`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`.
@@ -59,13 +59,13 @@ path
: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing.
permalinkable
: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. See&nbsp;[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`.
@@ -196,6 +196,7 @@ Output format|Template path
[`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/
docs/content/en/configuration/related-content.md
+1 -1
View File
@@ -46,7 +46,7 @@ weight
: (`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.
docs/content/en/configuration/roles.md
+24
View File
@@ -0,0 +1,24 @@
---
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.
docs/content/en/configuration/segments.md
+7 -9
View File
@@ -6,8 +6,6 @@ categories: []
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.
@@ -23,7 +21,7 @@ Segmented rendering offers several advantages:
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
@@ -31,16 +29,17 @@ Each segment is defined by include and exclude filters:
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
@@ -74,4 +73,3 @@ hugo --renderSegments segment1,segment2
```
[`renderSegments`]: /configuration/all/#rendersegments
[page language]: /methods/page/language/
docs/content/en/configuration/server.md
+2 -2
View File
@@ -29,11 +29,11 @@ force
: (`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 />}}
docs/content/en/configuration/services.md
-9
View File
@@ -26,12 +26,6 @@ googleAnalytics.id
{{ .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&nbsp;[details](/templates/rss/). To access this value from a template:
@@ -39,9 +33,6 @@ rss.limit
{{ .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&nbsp;[details](/shortcodes/x/#privacy). Default is `false`. To access this value from a template:
docs/content/en/configuration/sitemap.md
-1
View File
@@ -14,7 +14,6 @@ changefreq
: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See&nbsp;[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
docs/content/en/configuration/versions.md
+26
View File
@@ -0,0 +1,26 @@
---
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/
docs/content/en/content-management/comments.md
+2
View File
@@ -41,6 +41,7 @@ Disqus has its own [internal template](/templates/embedded/#disqus) available, t
Commercial commenting systems:
- [Commentix](https://www.commentix.com/)
- [Emote](https://emote.com/)
- [Graph Comment](https://graphcomment.com/)
- [Hyvor Talk](https://talk.hyvor.com/)
@@ -60,6 +61,7 @@ Open-source commenting systems:
- [Staticman](https://staticman.net/)
- [Talkyard](https://blog-comments.talkyard.io/)
- [Utterances](https://utteranc.es/)
- [Zoomment](https://zoomment.com/)
[configuration]: /configuration/
[disquspartial]: /templates/embedded/#disqus
docs/content/en/content-management/content-adapters.md
+11 -1
View File
@@ -99,7 +99,9 @@ Returns a persistent "scratch pad" to store and manipulate data. The main use ca
### 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 }}
@@ -116,6 +118,14 @@ By default, Hugo executes the content adapter for the language defined by the `_
{{ .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.
docs/content/en/content-management/front-matter.md
+35 -11
View File
@@ -41,7 +41,7 @@ The most common front matter fields are `date`, `draft`, `title`, and `weight`,
[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].
@@ -68,7 +68,7 @@ isCJKLanguage
: (`bool`) Whether the content language is in the [CJK](g) family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object.
keywords
: (`string 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.
@@ -83,16 +83,15 @@ markup
: (`string`) An identifier corresponding to one of the supported [content formats]. If not provided, Hugo determines the content renderer based on the file extension.
menus
: (`string`, `string 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
@@ -110,6 +109,24 @@ resources
sitemap
: (`map`) A map of sitemap options. See the [sitemap templates] page for details. Access these values from a template using the [`Sitemap`] method on a `Page` object.
sites
: {{< new-in 0.153.0 />}}
: (`map`) A map to define [sites matrix](g) and [sites complements](g) for the page.
<!-- markdownlint-disable MD049 -->
{{< code-toggle file=content/_index.md fm=true >}}
title = 'Home'
[sites.matrix]
languages = ["en","fr"]
versions = ["v1.2.*","v2.*.*"]
roles = ["**"]
[sites.complements]
versions = ["v3.*.*"]
{{< /code-toggle >}}
<!-- markdownlint-enable MD049 -->
slug
: (`string`) Overrides the last segment of the URL path. Not applicable to `home`, `section`, `taxonomy`, or `term` pages. See the [URL management] page for details. Access this value from a template using the [`Slug`] method on a `Page` object.
@@ -136,8 +153,6 @@ weight
## 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 >}}
@@ -219,12 +234,15 @@ title = 'Home'
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:
@@ -237,18 +255,24 @@ title = 'Home'
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
docs/content/en/content-management/image-processing/index.md
+67 -335
View File
@@ -1,15 +1,17 @@
---
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" %}}
@@ -21,13 +23,13 @@ content/
└── 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" %}}
@@ -37,34 +39,34 @@ assets/
└── 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" }}
@@ -81,7 +83,7 @@ Example 3: A more concise way to skip image rendering if the resource is not fou
{{ 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" }}
@@ -96,350 +98,80 @@ Example 4: Skips rendering if there's problem accessing a remote resource.
{{ end }}
```
## Image processing methods
## Processing
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:
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
{{/* 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.
```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.
```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.
> [!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.
### Anchor
Each method serves a specific transformation or metadata requirement:
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
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.
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" }}
## Performance
### Caching
Hugo processes images on demand and returns a new resource object. To ensure subsequent builds remain fast, Hugo caches the results in the directory specified in the [file cache] section of your site configuration.
If you host your site with Netlify, include the following in your site configuration to persist the image cache between builds:
```toml
[caches]
[caches.images]
dir = ':cacheDir/images'
```
### Background color
### Garbage collection
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.
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:
Use either a 3-digit or 6-digit hexadecimal color code (e.g., `#00f` or `#0000ff`).
The default value is `#ffffff` (white). You may override the default value in the [site configuration].
```go-html-template
{{ $image.Resize "600x jpg #b31280" }}
```text
hugo --gc
```
### Resampling filter
### Resource usage
You may specify the resampling filter used when resizing an image. Commonly used resampling filters include:
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.
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" }}
```
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" />}}
{{< imgproc path="sunset.jpg" spec="fill 120x150 right" alt="A sunset" />}}
{{< 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/
docs/content/en/content-management/markdown-attributes.md
+11 -2
View File
@@ -16,19 +16,26 @@ This is a paragraph.
{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.
@@ -106,3 +113,5 @@ This is a paragraph.
````
As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options](/functions/transform/highlight/#options).
[render hook templates]: /render-hooks/introduction/
docs/content/en/content-management/page-resources.md
-2
View File
@@ -193,8 +193,6 @@ the `Name` and `Title` will be assigned to the resource files as follows:
## 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]
docs/content/en/content-management/shortcodes.md
+2 -1
View File
@@ -203,7 +203,8 @@ Hugo renders this HTML:
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
docs/content/en/content-management/urls.md
+49 -52
View File
@@ -40,7 +40,7 @@ Set the `url` in front matter to override the entire path. Use this with either
> [!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.
@@ -96,7 +96,7 @@ https://example.org/articles/my-first-article.html
#### 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
:--|:--|:--
@@ -138,7 +138,7 @@ Hugo provides two mutually exclusive configuration options to alter URLs _after_
#### 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.
@@ -181,83 +181,80 @@ relativeURLs = true
## 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:
> [!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.
{{< code-toggle file=content/posts/new-file-name.de.md fm=true >}}
aliases = ['/de/posts/previous-file-name']
{{< /code-toggle >}}
#### Client-side redirection
### How aliases work
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.
Using the first example above, Hugo generates the following site structure:
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`.
```text
public/
├── posts/
│ ├── new-file-name/
│ │ └── index.html
│ ├── previous-file-name/
│ │ └── index.html
│ └── index.html
└── index.html
```
Unless you provide a custom layout, Hugo uses its [embedded alias template][] to generate the redirect files:
The alias from the previous URL to the new URL is a client-side redirect:
```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:
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.
`Permalink`
: (`string`) The absolute URL of the destination page.
Hugo renders alias files before rendering pages. A new page with the previous file name will overwrite the alias, as expected.
`Page`
: (`page.Page`) The full `Page` object of the destination.
### Customize
#### Server-side redirection
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:
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.
Permalink
: The link to the page being aliased.
To implement this, you typically create a single template to generate the necessary rules for your specific host or server. Common examples include:
Page
: The Page data for the page being aliased.
- A `_redirects` file for hosting services such as Cloudflare, GitLab Pages, and Netlify.
- An `.htaccess` file for web servers such as Apache and LiteSpeed.
See the [`Aliases`][aliases_method] method page for a complete example of how to iterate through pages to generate these rules.
If you implement server-side redirects, you should disable the generation of individual HTML files by setting [`disableAliases`][] to `true` in your 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 %}}>
docs/content/en/contribute/development.md
+1 -1
View File
@@ -143,7 +143,7 @@ CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
To build and install a specific release:
```sh
CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.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:
docs/content/en/functions/collections/After.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/Append.md
+4 -4
View File
@@ -1,15 +1,15 @@
---
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
returnType: '[]any'
signatures:
- collections.Append ELEMENT [ELEMENT...] COLLECTION
- collections.Append COLLECTION1 COLLECTION2
- collections.Append ELEMENT [ELEMENT...] SLICE
- collections.Append SLICE1 SLICE2
aliases: [/functions/append]
---
docs/content/en/functions/collections/Apply.md
+4 -4
View File
@@ -1,19 +1,19 @@
---
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" }}
docs/content/en/functions/collections/Complement.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/D.md
+27 -9
View File
@@ -1,19 +1,36 @@
---
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&nbsp;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
@@ -27,6 +44,12 @@ The example above generates the _same_ random numbers each time it is called. To
{{ 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
@@ -54,11 +77,6 @@ Same result per day|`time.Now.YearDay`
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&ndash;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/
docs/content/en/functions/collections/Delimit.md
+2 -2
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/Dictionary.md
+1 -1
View File
@@ -1,6 +1,6 @@
---
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:
docs/content/en/functions/collections/First.md
+4 -4
View File
@@ -1,13 +1,13 @@
---
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]
---
@@ -39,7 +39,7 @@ To use the `collections.First` function with a page collection:
{{ 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 }}
docs/content/en/functions/collections/Group.md
+2 -2
View File
@@ -1,12 +1,12 @@
---
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]
---
docs/content/en/functions/collections/In.md
+2 -14
View File
@@ -1,33 +1,21 @@
---
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
docs/content/en/functions/collections/IndexFunction.md
+2 -2
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/Intersect.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/IsSet.md
+2 -2
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/KeyVals.md
+1 -1
View File
@@ -1,6 +1,6 @@
---
title: collections.KeyVals
description: Returns a KeyVals struct.
description: Returns a KeyVals struct by pairing a given key and values.
categories: []
keywords: []
params:
docs/content/en/functions/collections/Last.md
+4 -4
View File
@@ -1,13 +1,13 @@
---
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]
---
@@ -39,7 +39,7 @@ To use the `collections.Last` function with a page collection:
{{ 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 }}
docs/content/en/functions/collections/Merge.md
+2 -2
View File
@@ -1,12 +1,12 @@
---
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]
---
docs/content/en/functions/collections/Querify.md
+2 -2
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/Reverse.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/Seq.md
+1 -1
View File
@@ -1,6 +1,6 @@
---
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:
docs/content/en/functions/collections/Shuffle.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/Slice.md
+2 -2
View File
@@ -1,12 +1,12 @@
---
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]
---
docs/content/en/functions/collections/Sort.md
+2 -2
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/SymDiff.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/Union.md
+4 -7
View File
@@ -1,25 +1,22 @@
---
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 }} → []
```
docs/content/en/functions/collections/Uniq.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
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]
---
docs/content/en/functions/collections/Where.md
+21 -21
View File
@@ -1,20 +1,20 @@
---
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
collections.Where SLICE KEY [OPERATOR] VALUE
--------------------
comparison condition
```
@@ -30,8 +30,8 @@ Hugo will test for equality if you do not provide an `OPERATOR` argument. For ex
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:
@@ -133,7 +133,7 @@ Compare the value of the given field to a [`bool`](g):
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" }}
@@ -142,7 +142,7 @@ For example, to return a collection of pages where the `color` page parameter is
{{ $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" }}
@@ -153,9 +153,9 @@ To return a collection of pages where the "color" page parameter is neither "red
## Intersection comparison
Compare a `slice` to a `slice`, returning collection elements with common values. This is frequently used when comparing taxonomy terms.
Compare a `slice` to a `slice`, returning 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" }}
@@ -166,7 +166,7 @@ For example, to return a collection of pages where any of the terms in the "genr
## 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` }}
@@ -175,7 +175,7 @@ To return a collection of pages where the "author" page parameter begins with ei
{{% include "/_common/functions/regular-expressions.md" %}}
> [!note]
> Use the `like` operator to compare string values. Comparing other data types will result in an empty collection.
> Use the `like` operator to compare string values. Comparing other data types will result in an empty slice.
## Date comparison
@@ -183,7 +183,7 @@ To return a collection of pages where the "author" page parameter begins with ei
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) }}
@@ -208,14 +208,14 @@ eventDate = 2024-04-01
+++
```
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" }}
@@ -229,13 +229,13 @@ When working with YAML or JSON, or quoted TOML values, custom dates are strings;
## 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 }}
@@ -368,9 +368,9 @@ Is rendered to:
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:
docs/content/en/functions/collections/_index.md
+1 -1
View File
@@ -1,7 +1,7 @@
---
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: []
---
docs/content/en/functions/css/Quoted.md
+1 -1
View File
@@ -15,7 +15,7 @@ params:
> [!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:
docs/content/en/functions/css/Sass.md
+22 -13
View File
@@ -10,10 +10,11 @@ params:
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
@@ -47,6 +48,9 @@ targetPath
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/).
@@ -58,7 +62,7 @@ vars
@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
@@ -86,7 +90,7 @@ vars
## 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.
@@ -96,7 +100,7 @@ Dart Sass is compatible with Hugo v0.114.0 and later.
If you have been using Embedded Dart Sass[^1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.
If you install Hugo as a [Snap package] there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.
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.
@@ -121,23 +125,24 @@ Run `hugo env` to list the active transpilers.
### 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/
@@ -146,6 +151,7 @@ For examples of how to install Dart Sass in a production environment, see these
[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
@@ -155,5 +161,8 @@ For examples of how to install Dart Sass in a production environment, see these
[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/
docs/content/en/functions/css/Unquoted.md
+1 -1
View File
@@ -15,7 +15,7 @@ params:
> [!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:
docs/content/en/functions/data/GetCSV.md
-145
View File
@@ -1,145 +0,0 @@
---
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 -->
docs/content/en/functions/data/GetJSON.md
-147
View File
@@ -1,147 +0,0 @@
---
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 -->
docs/content/en/functions/data/_index.md
-7
View File
@@ -1,7 +0,0 @@
---
title: Data functions
linkTitle: data
description: Use these functions to read local or remote data files.
categories: []
keywords: []
---
docs/content/en/functions/fmt/Warnidf.md
-2
View File
@@ -11,8 +11,6 @@ params:
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.
docs/content/en/functions/go-template/and.md
+6
View File
@@ -12,6 +12,8 @@ params:
{{% 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)
@@ -19,4 +21,8 @@ params:
{{ 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" %}}
docs/content/en/functions/go-template/or.md
+10 -6
View File
@@ -12,13 +12,17 @@ params:
{{% include "/_common/functions/truthy-falsy.md" %}}
```go-html-template
{{ or 0 1 2 }} → 1
{{ or false "a" 1 }} → a
{{ or 0 true "a" }} → true
The `or` function evaluates the arguments from left to right, and returns when the result is determined.
{{ or false "" 0 }} → 0
{{ or 0 "" false }} → false
```go-html-template
{{ 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 true (math.Div 1 0) }} → true (bool)
```
{{% include "/_common/functions/go-template/text-template.md" %}}
docs/content/en/functions/go-template/range.md
-2
View File
@@ -192,8 +192,6 @@ Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map
### 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
docs/content/en/functions/hugo/Generator.md
+1 -1
View File
@@ -11,5 +11,5 @@ params:
---
```go-html-template
{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.152.2">
{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.155.3">
```
docs/content/en/functions/hugo/IsMultihost.md
-2
View File
@@ -10,8 +10,6 @@ params:
signatures: [hugo.IsMultihost]
---
{{< new-in 0.124.0 />}}
Site configuration:
{{< code-toggle file=hugo >}}
docs/content/en/functions/hugo/IsMultilingual.md
-2
View File
@@ -10,8 +10,6 @@ params:
signatures: [hugo.IsMultilingual]
---
{{< new-in 0.124.0 />}}
Site configuration:
{{< code-toggle file=hugo >}}
docs/content/en/functions/hugo/Version.md
+1 -1
View File
@@ -11,5 +11,5 @@ params:
---
```go-html-template
{{ hugo.Version }} → 0.152.2
{{ hugo.Version }} → 0.155.3
```
docs/content/en/functions/images/AutoOrient.md
+1 -1
View File
@@ -1,6 +1,6 @@
---
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:
docs/content/en/functions/images/Dither.md
+1 -3
View File
@@ -10,12 +10,10 @@ 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
docs/content/en/functions/images/Filter.md
+1 -1
View File
@@ -2,7 +2,7 @@
title: images.Filter
description: Applies one or more image filters to the given image resource.
categories: []
keywords: []
keywords: [filter]
params:
functions_and_methods:
aliases: []
docs/content/en/functions/images/Process.md
+18 -76
View File
@@ -1,98 +1,36 @@
---
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&nbsp;[details](content-management/image-processing/#image-processing-methods).
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 "resize 300x" }}
{{ 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 }}
```
dimensions
: Required if you specify an action. Provide width _or_ height when using `resize`, else provide both width _and_ height. See&nbsp;[details](/content-management/image-processing/#dimensions).
In the example above, `"crop 200x200 TopRight webp q50"` is the _processing specification_.
```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&nbsp;[details](/content-management/image-processing/#anchor).
```go-html-template
{{ $filter := images.Process "crop 200x200 center" }}
```
rotation
: Typically specify zero or one of `r90`, `r180`, or `r270`. Also supports arbitrary rotation angles. See&nbsp;[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&nbsp;[details](/content-management/image-processing/#target-format).
```go-html-template
{{ $filter := images.Process "webp" }}
{{ $filter := images.Process "crop 200x200 center r90 webp" }}
```
quality
: Applicable to JPEG and WebP images. Optionally specify `qN` where `N` is an integer in the range [0, 100]. Default is `75`. See&nbsp;[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&nbsp;[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&nbsp;[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&nbsp;[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" %}}
@@ -103,6 +41,10 @@ Create a filter:
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
docs/content/en/functions/lang/Translate.md
+6 -4
View File
@@ -18,7 +18,7 @@ If the key is not found in the translation table for the current language, the `
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.
@@ -28,10 +28,10 @@ Create translation tables in the `i18n` directory, naming each file according to
```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:
@@ -238,8 +238,10 @@ Then in your templates:
[`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
docs/content/en/functions/openapi3/Unmarshal.md
+56 -17
View File
@@ -1,44 +1,84 @@
---
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.
```go-html-template
### 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`.
## 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>
@@ -54,11 +94,6 @@ To list the GET and POST operations for each of the API paths:
{{ 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
@@ -75,3 +110,7 @@ Hugo renders this to:
<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
docs/content/en/functions/reflect/IsImageResource.md
+71
View File
@@ -0,0 +1,71 @@
---
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 }}
```
docs/content/en/functions/reflect/IsPage.md
+23
View File
@@ -0,0 +1,23 @@
---
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 }}
```
docs/content/en/functions/reflect/IsResource.md
+65
View File
@@ -0,0 +1,65 @@
---
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 }}
```
docs/content/en/functions/reflect/IsSite.md
+23
View File
@@ -0,0 +1,23 @@
---
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 }}
```
docs/content/en/functions/resources/FromString.md
+3 -3
View File
@@ -22,9 +22,9 @@ Let's say you need to publish a file named "site.json" in the root of your `publ
```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"
}
```
docs/content/en/functions/resources/GetMatch.md
+1 -1
View File
@@ -21,7 +21,7 @@ params:
>
> 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" %}}
docs/content/en/functions/strings/Diff/index.md
-2
View File
@@ -9,8 +9,6 @@ params:
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
docs/content/en/functions/templates/Inner.md
+71
View File
@@ -0,0 +1,71 @@
---
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/

Some files were not shown because too many files have changed in this diff Show More