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
+ignore-words-list = abl,edn,ist,januar,te,trys,ue,womens
# Check file names as well.
check-filenames = true
"**/tools/*"
],
"ignoreRegExpList": [
- "# cspell: ignore fenced code blocks",
+ // cspell: ignore fenced code blocks
"^(\\s*`{3,}).*[\\s\\S]*?^\\1$",
- "# cspell: ignore words joined with dot",
+ // cspell: ignore words joined with dot
"\\w+\\.\\w+",
- "# cspell: ignore strings within backticks",
+ // cspell: ignore strings within backticks
"`.+`",
- "# cspell: ignore strings within double quotes",
+ // cspell: ignore strings within double quotes
"\".+\"",
- "# cspell: ignore strings within brackets",
+ // cspell: ignore strings within brackets
"\\[.+\\]",
- "# cspell: ignore strings within parentheses",
+ // cspell: ignore strings within parentheses
"\\(.+\\)",
- "# cspell: ignore words that begin with a slash",
+ // cspell: ignore words that begin with a slash
"/\\w+",
- "# cspell: ignore everything within action delimiters",
+ // cspell: ignore everything within action delimiters
"\\{\\{.+\\}\\}",
- "# cspell: ignore everything after a right arrow",
- "\\s+→\\s+.+"
+ // cspell: ignore everything after a right arrow
+ "\\s+→\\s+.+",
],
"language": "en",
"words": [
"unmarshaled",
"unmarshaling",
"unmarshals",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore hugo terminology",
- "# ----------------------------------------------------------------------",
+ // ------------------------------------------------------------------------
+ // cspell: ignore hugo terminology",
+ // ------------------------------------------------------------------------
"alignx",
"aligny",
"attrlink",
"unmarshal",
"unpublishdate",
"zgotmplz",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore foreign language words",
- "# ----------------------------------------------------------------------",
+ // ------------------------------------------------------------------------
+ // cspell: ignore foreign language words",
+ // ------------------------------------------------------------------------
"bezpieczeństwo",
"blatt",
"buch",
"prywatność",
"referenz",
"régime",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore names",
- "# ----------------------------------------------------------------------",
+ // ------------------------------------------------------------------------
+ // cspell: ignore names",
+ // ------------------------------------------------------------------------
"Atishay",
"Cosette",
"Eliott",
"Ninke",
"Noll",
"Pastorius",
+ "Pontmercy",
"Samsa",
"Stucki",
"Thénardier",
"Vitter",
"WASI",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore operating systems and software packages",
- "# ----------------------------------------------------------------------",
+ // ------------------------------------------------------------------------
+ // cspell: ignore operating systems and software packages",
+ // ------------------------------------------------------------------------
"asciidoctor",
"brotli",
"cifs",
"pkgin",
"rclone",
"xubuntu",
- "# ----------------------------------------------------------------------",
- "# cspell: ignore miscellaneous",
- "# ----------------------------------------------------------------------",
+ // ------------------------------------------------------------------------
+ // cspell: ignore miscellaneous",
+ // ------------------------------------------------------------------------
"achristie",
"ccpa",
"cpra",
_comment: Do not remove front matter.
---
-Hugo uses Go's [text/template] and [html/template] packages.
+Hugo uses Go's [`text/template`][] and [`html/template`][] packages.
-The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
+The `text/template` package implements data-driven templates for generating textual output, while the `html/template` package implements data-driven templates for generating HTML output safe against code injection.
-By default, Hugo uses the html/template package when rendering HTML files.
+By default, Hugo uses the `html/template` package when rendering HTML files.
-To generate HTML output that is safe against code injection, the html/template package escapes strings in certain contexts.
+To generate HTML output that is safe against code injection, the `html/template` package escapes strings in certain contexts.
-[text/template]: https://pkg.go.dev/text/template
-[html/template]: https://pkg.go.dev/html/template
+[`text/template`]: https://pkg.go.dev/text/template
+[`html/template`]: https://pkg.go.dev/html/template
_comment: Do not remove front matter.
---
-See Go's [text/template] documentation for more information.
+See Go's [`text/template`][] documentation for more information.
-[text/template]: https://pkg.go.dev/text/template
+[`text/template`]: https://pkg.go.dev/text/template
Note that this is meant for small data sets, e.g., configuration settings. For larger data sets, please put/mount the files into `assets` and import them directly.
minify
-: (`bool`) Whether to let `js.Build` handle the minification.
+: (`bool`) Whether to minify the generated CSS code. Default is `false`.
loaders
: {{< new-in 0.140.0 />}}
: See <https://esbuild.github.io/api/#drop>
sourceMap
-: (`string`) Whether to generate `inline`, `linked`, or `external` source maps from esbuild. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file. By default, source maps are not created. Note that the `linked` option was added in Hugo 0.140.0.
+: (`string`) The type of source map to generate. One of `external`, `inline`, `linked`, or `none`. Default is `none`. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file.
sourcesContent
: {{< new-in 0.140.0 />}}
-: (`bool`) Whether to include the content of the source files in the source map. By default, this is `true`.
+: (`bool`) Whether to include the content of the source files in the source map. Default is `true`.
JSX
: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See <https://esbuild.github.io/api/#jsx>.
--- /dev/null
+---
+_comment: Do not remove front matter.
+---
+
+## Image operations
+
+Use these functions to determine which operations Hugo supports for a given resource. While Hugo classifies a variety of file types as image resources, its ability to process them or extract metadata varies by format.
+
+- [`reflect.IsImageResource`][]: {{% get-page-desc "/functions/reflect/isimageresource" %}}
+- [`reflect.IsImageResourceProcessable`][]: {{% get-page-desc "/functions/reflect/isimageresourceprocessable" %}}
+- [`reflect.IsImageResourceWithMeta`][]: {{% get-page-desc "/functions/reflect/isimageresourcewithmeta" %}}
+
+The table below shows the values these functions return for various file formats. Use it to determine which checks are required before calling specific methods in your templates.
+
+|Format|IsImageResource|IsImageResourceProcessable|IsImageResourceWithMeta|
+|:-----|:--------------|:-------------------------|:----------------------|
+|AVIF |true |**false** |true |
+|BMP |true |true |true |
+|GIF |true |true |true |
+|HEIC |true |**false** |true |
+|HEIF |true |**false** |true |
+|ICO |true |**false** |**false** |
+|JPEG |true |true |true |
+|PNG |true |true |true |
+|SVG |true |**false** |**false** |
+|TIFF |true |true |true |
+|WebP |true |true |true |
+
+This contrived example demonstrates how to iterate through resources and use these functions to apply the appropriate handling for each image format.
+
+```go-html-template
+{{ range resources.Match "**" }}
+ {{ if reflect.IsImageResource . }}
+ {{ if reflect.IsImageResourceProcessable . }}
+ {{ with .Process "resize 300x webp" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+ {{ else if reflect.IsImageResourceWithMeta . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ <img src="{{ .RelPermalink }}" alt="">
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+[`reflect.IsImageResource`]: /functions/reflect/isimageresource/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
+[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
To build the extended or extended/deploy edition from source you must:
1. Install [Git]
-1. Install [Go] version 1.24.0 or later
+1. Install [Go] version 1.25.0 or later
1. Install a C compiler, either [GCC] or [Clang]
1. Update your `PATH` environment variable as described in the [Go documentation]
: 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
-: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`smartcrop.js`][] library to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your project configuration.
+: The focal point used when cropping or filling an image. Valid options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`muesli/smartcrop`][] package to identify the most interesting area of the image. This defaults to the [`anchor`][] parameter in your project configuration.
background color
: The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. This defaults to the [`bgColor`][] parameter in your project configuration.
[`bgcolor`]: /configuration/imaging/#bgcolor
[`compression`]: /configuration/imaging/#compression
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
+[`muesli/smartcrop`]: https://github.com/muesli/smartcrop
[`hint`]: /configuration/imaging/#hint
[`images.AutoOrient`]: /functions/images/autoorient/
[`images.Process`]: /functions/images/process/
[`Process`]: /methods/resource/process
[`quality`]: /configuration/imaging/#quality
[`resampleFilter`]: /configuration/imaging/#resamplefilter
-[`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
: The `slug` as defined in front matter, else the `title` as defined in front matter, else the automatic title. Hugo generates titles automatically for section, taxonomy, and term pages that are not backed by a file.
`:filename`
-: The content's file name without extension, applicable to the `page` page kind.
-
- {{< deprecated-in v0.144.0 >}}
- The `:filename` token has been deprecated. Use `:contentbasename` instead.
- {{< /deprecated-in >}}
+: {{< deprecated-in v0.144.0 />}}
+: Use `:contentbasename` instead.
`:slugorfilename`
-: The `slug` as defined in front matter, else the content's file name without extension, applicable to the `page` page kind.
-
- {{< deprecated-in v0.144.0 >}}
- The `:slugorfilename` token has been deprecated. Use `:slugorcontentbasename` instead.
- {{< /deprecated-in >}}
+: {{< deprecated-in v0.144.0 />}}
+: Use `:slugorcontentbasename` instead.
`:contentbasename`
: {{< new-in 0.144.0 />}}
: Localize your project for each language and region, including translations, images, dates, currencies, numbers, percentages, and collation sequence. Hugo's multilingual framework supports single-host and multihost configurations.
[Output formats]
-: Render each page of your site to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
+: Render each page of your project to one or more output formats, with granular control by page kind, section, and path. While HTML is the default output format, you can add JSON, RSS, CSV, and more. For example, create a REST API to access content.
[Templates]
: Create templates using variables, functions, and methods to transform your content, resources, and data into a published page. While HTML templates are the most common, you can create templates for any output format.
: Reduce development time and cost by using one of the hundreds of themes contributed by the Hugo community. Themes are available for corporate sites, documentation projects, image portfolios, landing pages, personal and professional blogs, resumes, CVs, and more.
[Modules]
-: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site.
+: Reduce development time and cost by creating or importing packaged combinations of archetypes, assets, content, data, templates, translation tables, static files, or configuration settings. A module may serve as the basis for a new project, or to augment an existing project.
[Privacy]
-: Configure your site to help comply with regional privacy regulations.
+: Configure your project to help comply with regional privacy regulations.
[Security]
: Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection. Other protections prevent "shelling out" to arbitrary applications, limit access to specific environment variables, prevent connections to arbitrary remote data sources, and more.
: Reduce build time and cost by rendering a _partial_ template once then cache the result, either globally or within a given context. For example, cache the result of an asset pipeline to prevent reprocessing on every rendered page.
[Segmentation]
-: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire site once a week.
+: Reduce build time and cost by partitioning your sites into segments. For example, render the home page and the "news section" every hour, and render the entire project once a week.
[Minification]
: Minify HTML, CSS, and JavaScript to reduce file size, bandwidth consumption, and loading times.
---
title: Command line interface
linkTitle: CLI
-description: Use the command line interface (CLI) to manage your site.
+description: Use the command line interface (CLI) to manage your project.
categories: []
keywords: []
weight: 10
Generate CSS stylesheet for the Chroma code highlighter for a given style. This stylesheet is needed if markup.highlight.noClasses is disabled in config.
-See https://xyproto.github.io/splash/docs/all.html for a preview of the available styles
+See https://gohugo.io/quick-reference/syntax-highlighting-styles/ for a preview of the available styles.
```
hugo gen chromastyles [flags] [args]
--lineNumbersTableStyle string foreground and background colors for table line numbers, e.g. --lineNumbersTableStyle "#fff000 bg:#000fff"
--omitClassComments omit CSS class comment prefixes in the generated CSS
--omitEmpty omit empty CSS rules (deprecated, no longer needed)
- --style string highlighter style (see https://xyproto.github.io/splash/docs/) (default "friendly")
+ --style string highlighter style (default "friendly")
```
### Options inherited from parent commands
: (`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`) Whether to retrieve commit metadata from the Git history of your local project and any [modules](g). This enables the [`GitInfo`][] method on a `Page` object. With the default front matter configuration, the [`Lastmod`][] method on a `Page` object returns the Git author date of the last commit for that file. Default is `false`.
enableMissingTranslationPlaceholders
: (`bool`) Whether to show a placeholder instead of the default value or an empty string if a translation is missing. Default is `false`.
imaging
: See [configure imaging][].
-languageCode
+locale
: (`string`) The site's language tag, conforming to the syntax described in [RFC 5646][]. This value does not affect translations or localization. Hugo uses this value to populate:
- The `language` element in the [embedded RSS template][]
Some configuration settings, such as menus and custom parameters, can be defined separately for each language. See [configure languages][].
+[Associated Press Stylebook]: https://www.apstylebook.com/
+[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html
+[IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/
+[`FuzzyWordCount`]: /methods/page/fuzzywordcount/
+[`GitInfo`]: /methods/page/gitinfo/
+[`Lastmod`]: /methods/page/lastmod/
+[`MainSections`]: /methods/site/mainsections/
+[`Summary`]: /methods/page/summary/
+[`WordCount`]: /methods/page/wordcount/
[`cacheDir`]: #cachedir
-[`defaultContentLanguage`]: #defaultcontentlanguage
[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
-[`defaultContentRole`]: #defaultcontentrole
+[`defaultContentLanguage`]: #defaultcontentlanguage
[`defaultContentRoleInSubdir`]: #defaultcontentroleinsubdir
-[`defaultContentVersion`]: #defaultcontentversion
+[`defaultContentRole`]: #defaultcontentrole
[`defaultContentVersionInSubdir`]: #defaultcontentversioninsubdir
-[`disabled`]: /configuration/languages/#disabled
+[`defaultContentVersion`]: #defaultcontentversion
[`disableDefaultSiteRedirect`]: #disabledefaultsiteredirect
+[`disabled`]: /configuration/languages/#disabled
[`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/
[`time.Format`]: /functions/time/format/
[`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 HTTP cache]: /configuration/http-cache/
[configure build]: /configuration/build/
[configure cascade]: /configuration/cascade/
[configure deployment]: /configuration/deployment/
[configure file caches]: /configuration/caches/
[configure front matter]: /configuration/front-matter/
-[configure HTTP cache]: /configuration/http-cache/
[configure imaging]: /configuration/imaging/
[configure languages]: /configuration/languages/
[configure markup]: /configuration/markup/
[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
+[embedded alias template]: <{{% eturl alias %}}>
[module mounts]: /configuration/module/#mounts
[non-spacing marks]: https://www.compart.com/en/unicode/category/Mn
[os.UserCacheDir]: https://pkg.go.dev/os#UserCacheDir
-[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
[this configuration]: https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml
-[XDG base directory specification]: https://specifications.freedesktop.org/basedir-spec/latest/
[build.buildStats]
enable = true
[[build.cachebusters]]
- source = "assets/watching/hugo_stats\\.json"
- target = "styles\\.css"
+ source = 'assets/watching/hugo_stats\.json'
+ target = 'styles\.css'
[[build.cachebusters]]
- source = "(postcss|tailwind)\\.config\\.js"
- target = "css"
+ source = '(postcss|tailwind)\.config\.js'
+ target = 'css'
[[build.cachebusters]]
- source = "assets/.*\\.(js|ts|jsx|tsx)"
- target = "js"
+ source = 'assets/.*\.(js|ts|jsx|tsx)'
+ target = 'js'
[[build.cachebusters]]
- source = "assets/.*\\.(.*)$"
- target = "$1"
+ source = 'assets/.*\.(.*)$'
+ target = '$1'
{{< /code-toggle >}}
<!-- markdownlint-enable MD049 -->
misc
: Caches miscellaneous data.
+modulegitinfo
+: Caches Git information for modules.
+
modulequeries
: Caches the results of module resolution queries.
Method|Description
:--|:--
-[`Date`]|Returns the date of the given page.
-[`ExpiryDate`]|Returns the expiry date of the given page.
-[`Lastmod`]|Returns the last modification date of the given page.
-[`PublishDate`]|Returns the publish date of the given page.
+[`Date`][]|Returns the date of the given page.
+[`ExpiryDate`][]|Returns the expiry date of the given page.
+[`Lastmod`][]|Returns the last modification date of the given page.
+[`PublishDate`][]|Returns the publish date of the given page.
[`Date`]: /methods/page/date
[`ExpiryDate`]: /methods/page/expirydate
Within the `YYYY-MM-DD-HH-MM-SS` format, the date and time values may be separated by any character including a space (e.g., `2025-02-01T14-30-00`).
- Hugo resolves the extracted date to the [`timeZone`] defined in your project configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`], but only if you haven't already specified a slug in the page's front matter.
+ Hugo resolves the extracted date to the [`timeZone`][] defined in your project configuration, falling back to the system time zone. After extracting the date, Hugo uses the remaining part of the file name to generate the page's [`slug`][], but only if you haven't already specified a slug in the page's front matter.
For example, if you name your file `2025-02-01-article.md`, Hugo will set the date to `2025-02-01` and the slug to `article`.
`:git`
-: The Git author date for the file's last revision. To enable access to the Git author date, set [`enableGitInfo`] to `true`, or use the `--enableGitInfo` flag when building your project.
+: The Git author date for the file's last revision. To enable access to the Git author date, set [`enableGitInfo`][] to `true`.
## Example
keywords: []
---
-## Processing options
-
These are the default settings for processing images:
-{{< code-toggle file=hugo >}}
-[imaging]
-anchor = 'Smart'
-bgColor = '#ffffff'
-compression = 'lossy'
-quality = 75
-resampleFilter = 'box'
-{{< /code-toggle >}}
+{{< code-toggle config=imaging />}}
+
+## Top-level options
+
+These global settings define how Hugo handles the fundamental aspects of image manipulation, such as cropping logic, background colors, and general output quality.
anchor
-: (`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`.
+: (`string`) The focal point used when cropping or filling an image. Valid case-insensitive options include `TopLeft`, `Top`, `TopRight`, `Left`, `Center`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`, or `Smart`. The `Smart` option utilizes the [`muesli/smartcrop`][] package to identify the most interesting area of the image. Default is `smart`.
bgColor
: (string) The background color used when converting transparent images to formats that do not support transparency, such as PNG to JPEG. This color also fills the empty space created when rotating an image by a non-orthogonal angle if the space is not transparent and a background color is not specified in the processing specification. The value must be an RGB [hexadecimal color][]. Default is `#ffffff`.
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
+## Exif method
+
+{{< deprecated-in 0.155.0 >}}
+Use [`Meta`](/methods/resource/meta/) instead.
+{{< /deprecated-in >}}
+
+## Meta method
{{< new-in 0.155.0 />}}
-These are the default settings specific to processing WebP images:
+The following parameters allow you to control how Hugo extracts and filters metadata when using the [`Meta`][] method, helping you balance data granularity with build performance.
+
+fields
+: (`[]string`) A [glob slice](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `['**']` to include all fields.
+
+ > [!note]
+ > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
+
+sources
+: (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance.
+
+## WebP images
+
+{{< new-in 0.155.0 />}}
-{{< code-toggle file=hugo >}}
-[imaging.webp]
-hint = 'photo'
-method = 4
-useSharpYuv = true
-{{< /code-toggle >}}
+These specialized settings provide granular control over the WebP encoding process, allowing you to optimize compression based on the specific visual characteristics of your imagery.
hint
: (`string`) The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. Default is `photo`.
`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`.
+: (`int`) The effort level of the compression algorithm. Expressed as a whole number from `0` to `6`, inclusive, equivalent to the `-m` flag for the [`cwebp`][] CLI. Lower numbers prioritize processing speed, while higher numbers prioritize compression efficiency. Default is `2`.
useSharpYuv
-: (`bool`) The conversion method used for RGB-to-YUV encoding, equivalent to the `-sharp_yuv` flag for the [`cwebp`][] CLI. Enabling this prioritizes image sharpness at the expense of processing speed. Default is `true`.
-
-## Exif method
-
-These are the default settings for the [`Exif`] method on an image `Resource` object:
-
-{{< code-toggle file=hugo >}}
-[imaging.exif]
-disableDate = false
-disableLatLong = false
-excludeFields = ""
-includeFields = ""
-{{< /code-toggle >}}
-
-disableDate
-: (`bool`) Whether to disable the [`Date`][] method by returning its zero value. Default is `false`.
-
-disableLatLong
-: (`bool`) Whether to disable the [`Lat`][] and [`Long`][] methods by returning their zero values. Default is `false`.
-
-excludeFields
-: (`string`) A [regular expression](g) matching the fields to exclude when extracting metadata.
-
- > [!note]
- > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
-
-includeFields
-: (`string`) A [regular expression](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `'.*'` to include all fields.
-
-## Meta method
-
-{{< new-in 0.155.0 />}}
-
-These are the default settings for the [`Meta`] method on an image `Resource` object:
-
-{{< code-toggle file=hugo >}}
-[imaging.meta]
-fields = []
-sources = ['exif', 'iptc']
-{{< /code-toggle >}}
-
-fields
-: (`[]string`) A [glob slice](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set to `['**']` to include all fields.
-
- > [!note]
- > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
-
-sources
-: (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance.
+: (`bool`) The conversion method used for RGB-to-YUV encoding, equivalent to the `-sharp_yuv` flag for the [`cwebp`][] CLI. Enabling this prioritizes image sharpness at the expense of processing speed. Default is `false`.
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
-[`Exif`]: /methods/resource/exif/
-[`Meta`]: /methods/resource/meta/
-[`smartcrop.js`]: https://github.com/jwagner/smartcrop.js
+[`muesli/smartcrop`]: https://github.com/muesli/smartcrop
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
[source documentation]: https://github.com/disintegration/imaging#image-resizing
## Sensible defaults
-Hugo offers many configuration options, but its defaults are often sufficient. A new site requires only these settings:
+Hugo offers many configuration options, but its defaults are often sufficient. A new project requires only these settings:
{{< code-toggle file=hugo >}}
baseURL = 'https://example.org/'
-languageCode = 'en-us'
+locale = 'en-us'
title = 'My New Hugo Site'
{{< /code-toggle >}}
{{< code-toggle file=hugo >}}
baseURL = 'https://example.org/'
-languageCode = 'en-us'
+locale = 'en-us'
title = 'ABC Widgets, Inc.'
[params]
subtitle = 'The Best Widgets on Earth'
{{< code-toggle file=hugo >}}
baseURL = 'https://example.org/'
-languageCode = 'en-us'
+locale = 'en-us'
title = 'My New Hugo Site'
theme = ['theme-a','theme-b']
{{< /code-toggle >}}
---
title: Configure languages
linkTitle: Languages
-description: Configure the languages in your multilingual site.
+description: Configure the languages in your multilingual project.
categories: []
keywords: []
---
## Base settings
-Configure the following base settings within the site's root configuration:
+Configure the following base settings:
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
In the above, `en` is the [language key](#language-keys).
+direction
+: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.Direction`][] method on a `Site` or `Page` object. Default is `ltr`.
+
disabled
: (`bool`) Whether to disable this language when building the site. Default is `false`.
+label
+: (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.Label`][] method on a `Site` or `Page` object.
+
languageCode
+: {{<deprecated-in 0.158.0 />}}
+: Use [`locale`](#locale) instead.
+
+languageDirection
+: {{<deprecated-in 0.158.0 />}}
+: Use [`direction`](#direction) instead.
+
+languageName
+: {{<deprecated-in 0.158.0 />}}
+: Use [`label`](#label) instead.
+
+locale
: (`string`) The language tag as described in [RFC 5646][]. This is the primary value used by the [`language.Translate`][] function to select a translation table, falling back to the language key if a matching translation table does not exist.
Hugo also uses this value to populate:
> [!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. Default is `ltr`.
-
-languageName
-: (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.LanguageName`][] method on a `Site` or `Page` object.
+ Access this value from a template using the [`Language.Locale`][] method on a `Site` or `Page` object.
title
: (`string`) The site title for this language. Access this value from a template using the [`Title`][] method on a `Site` object.
weight
-: (`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.
## Sort order
{{< code-toggle file=hugo >}}
[languages.en]
-languageCode = 'en-US'
-languageName = 'English'
-weight = 1
-title = 'Project Documentation'
+label = 'English'
+locale = 'en-US'
timeZone = 'America/New_York'
+title = 'Project Documentation'
+weight = 1
[languages.en.pagination]
path = 'page'
[languages.en.params]
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'de'
[languages.de]
- weight = 1
+weight = 1
[languages.en-US]
- weight = 2
+weight = 2
[languages.pt-BR]
- weight = 3
+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:
[languages.de]
contentDir = 'content/de'
+direction = 'ltr'
disabled = false
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
+label = 'Deutsch'
+locale = 'de-DE'
title = 'Projekt Dokumentation'
weight = 1
[languages.en]
contentDir = 'content/en'
+direction = 'ltr'
disabled = false
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
+label = 'English'
+locale = 'en-US'
title = 'Project Documentation'
weight = 2
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'fr'
-[languages]
- [languages.en]
- baseURL = 'https://en.example.org/'
- languageName = 'English'
- title = 'In English'
- weight = 2
- [languages.fr]
- baseURL = 'https://fr.example.org'
- languageName = 'Français'
- title = 'En Français'
- weight = 1
+[languages.en]
+baseURL = 'https://en.example.org/'
+label = 'English'
+title = 'In English'
+weight = 2
+[languages.fr]
+baseURL = 'https://fr.example.org'
+label = 'Français'
+title = 'En Français'
+weight = 1
{{</ code-toggle >}}
With the above, Hugo publishes two sites, each with their own root:
└── fr
```
-[`defaultContentLanguage`]: #defaultcontentlanguage
+[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[`Language.Direction`]: /methods/site/language/#direction
+[`Language.Label`]: /methods/site/language/#label
+[`Language.Locale`]: /methods/site/language/#locale
+[`Title`]: /methods/site/title/
[`defaultContentLanguageInSubdir`]: #defaultcontentlanguageinsubdir
+[`defaultContentLanguage`]: #defaultcontentlanguage
[`dir`]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
[`disableDefaultSiteRedirect`]: /configuration/all/#disabledefaultsiteredirect
-[`Language.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 %}}>
+[embedded alias template]: <{{% eturl alias %}}>
[language keys]: #language-keys
-[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
-[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
[translating by file name]: /content-management/multilingual/#translation-by-file-name
Most of the Goldmark settings above are self-explanatory, but some require explanation.
duplicateResourceFiles
-: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host sites. See [multilingual page resources] for details. Default is `false`.
+: (`bool`) Whether to duplicate shared page resources for each language on multilingual single-host projects. See [multilingual page resources] for details. Default is `false`.
> [!note]
- > With multilingual single-host sites, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host sites.
+ > With multilingual single-host projects, setting this parameter to `false` will enable Hugo's [embedded link render hook] and [embedded image render hook]. This is the default configuration for multilingual single-host projects.
parser.wrapStandAloneImageWithinParagraph
: (`bool`) Whether to wrap image elements without adjacent content within a `p` element when rendered. This is the default Markdown behavior. Set to `false` when using an [image render hook] to render standalone images as `figure` elements. Default is `true`.
{{< code-toggle file=hugo >}}
[markup.asciidocExt]
- extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
- workingFolderCurrent = true
- [markup.asciidocExt.attributes]
- my-base-url = "https://example.com/"
- my-attribute-name = "my value"
+extensions = ['asciidoctor-html5s','asciidoctor-diagram']
+workingFolderCurrent = true
+[markup.asciidocExt.attributes]
+my-base-url = 'https://example.com/'
+my-attribute-name = 'my value'
{{< /code-toggle >}}
### Syntax highlighting
To support these custom output formats, register a custom media type with no suffix or delimiter:
{{< code-toggle file=hugo >}}
-[mediaTypes."text/netlify"]
-delimiter = ""
+[mediaTypes.'text/netlify']
+delimiter = ''
{{< /code-toggle >}}
The custom output format definitions would look something like this:
{{< code-toggle file=hugo >}}
[outputFormats.redir]
-baseName = "_redirects"
+baseName = '_redirects'
isPlainText = true
-mediatype = "text/netlify"
+mediatype = 'text/netlify'
[outputFormats.headers]
-baseName = "_headers"
+baseName = '_headers'
isPlainText = true
-mediatype = "text/netlify"
+mediatype = 'text/netlify'
notAlternative = true
{{< /code-toggle >}}
{{< code-toggle config=minify />}}
-See the [tdewolff/minify] project page for details, but note the following:
+See the [`tdewolff/minify`][] project page for details, but note the following:
- `css.inline` is for internal use. Changing this setting has no effect.
- `html.keepConditionalComments` has been deprecated. Use `html.keepSpecialComments` instead.
-[tdewolff/minify]: https://github.com/tdewolff/minify
+[`tdewolff/minify`]: https://github.com/tdewolff/minify
: (`string`) Configures `GOAUTH` when running the Go command for module operations. This is a semicolon-separated list of authentication commands for go-import and HTTPS module mirror interactions. This is useful for private repositories. See `go help goauth` for more information.
noProxy
-: (`string`) A comma-separated list of [glob patterns](g),s matching paths that should not use the [configured proxy server](#proxy).
+: (`string`) A comma-separated list of [glob patterns](g), matching paths that should not use the [configured proxy server](#proxy).
noVendor
: (`string`) A [glob pattern](g) matching module paths to skip when vendoring.
private
-: (`string`) A comma-separated list of [glob patterns](g),s matching paths that should be treated as private.
+: (`string`) A comma-separated list of [glob patterns](g), matching paths that should be treated as private.
proxy
: (`string`) The proxy server to use to download remote modules. Default is `direct`, which means `git clone` and similar.
disable = false
ignoreConfig = false
ignoreImports = false
-path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v"
+path = 'github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v'
[[module.imports]]
-path = "my-shortcodes"
+path = 'my-shortcodes'
{{< /code-toggle >}}
disable
: (`string`) Where the mount will reside within Hugo's [unified file system](g). It must begin with one of Hugo's [component](g) directories: archetypes, assets, content, data, i18n, layouts, or static. For example, content/blog.
disableWatch
-: {{< new-in 0.128.0 />}}
: (`bool`) Whether to disable watching in watch mode for this mount. Default is `false`.
files
{{< code-toggle file=hugo >}}
[module]
[[module.mounts]]
- source="content"
- target="content"
- files=["! docs/*"]
+source = 'content'
+target = 'content'
+files = ['! docs/*']
[[module.mounts]]
- source="node_modules"
- target="assets"
+source = 'node_modules'
+target = 'assets'
[[module.mounts]]
- source="assets"
- target="assets"
+source = 'assets'
+target = 'assets'
{{< /code-toggle >}}
[`archetypeDir`]: /configuration/all/#archetypedir
: (`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`.
+: (`bool`) Whether to parse templates for this output format with Go's [`text/template`][] package instead of the [`html/template`][] package. Default is `false`.
mediaType
: (`string`) The [media type](g) of the published file. This must match one of the [configured media types][].
See [configure outputs][] for more information.
Step 4
-: Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path:
+: Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order][] to find the correct template path:
```text
layouts/list.atom.atom
[configured media types]: /configuration/media-types/
[default media types]: /configuration/media-types/
[embedded RSS template]: <{{% eturl rss %}}>
-[html/template]: https://pkg.go.dev/html/template
+[`html/template`]: https://pkg.go.dev/html/template
[template lookup order]: /templates/lookup-order/
-[text/template]: https://pkg.go.dev/text/template
+[`text/template`]: https://pkg.go.dev/text/template
path
: (`string`) The segment of each pager URL indicating that the target page is a pager. Default is `page`.
-With multilingual sites you can define the pagination behavior for each language:
+With multilingual projects you can define the pagination behavior for each language:
{{< code-toggle file=hugo >}}
[languages.en]
contentDir = 'content/en'
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
weight = 1
[languages.en.pagination]
disableAliases = true
path = 'page'
[languages.de]
contentDir = 'content/de'
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
weight = 2
[languages.de.pagination]
disableAliases = true
{{< code-toggle file=hugo >}}
baseURL = 'https://example.org/'
+locale = 'en-US'
title = 'Project Documentation'
-languageCode = 'en-US'
[params]
subtitle = 'Reference, Tutorials, and Explanations'
[params.contact]
{{ .Site.params.kebab-case.foo }}
```
-## Multilingual sites
+## Multilingual projects
-For multilingual sites, create a `params` key under each language:
+For multilingual projects, create a `params` key under each language:
{{< code-toggle file=hugo >}}
baseURL = 'https://example.org/'
defaultContentLanguage = 'en'
[languages.de]
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
title = 'Projekt Dokumentation'
weight = 1
phone = '+49 30 1234567'
[languages.en]
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
title = 'Project Documentation'
weight = 2
{{< code-toggle file=hugo >}}
[permalinks.page]
-"/" = "/:year/:month/:slug/"
+'/' = '/:year/:month/:slug/'
{{< /code-toggle >}}
Use the same approach with taxonomy terms. For example, to omit the taxonomy segment of the URL:
[languages.en]
contentDir = 'content/en'
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
weight = 1
[languages.en.permalinks.page]
-books = "/books/:slug/"
+books = '/books/:slug/'
[languages.en.permalinks.section]
-books = "/books/"
+books = '/books/'
[languages.es]
contentDir = 'content/es'
-languageCode = 'es-ES'
-languageDirection = 'ltr'
-languageName = 'Español'
+direction = 'ltr'
+label = 'Español'
+locale = 'es-ES'
weight = 2
[languages.es.permalinks.page]
-books = "/libros/:slug/"
+books = '/libros/:slug/'
[languages.es.permalinks.section]
-books = "/libros/"
+books = '/libros/'
{{< /code-toggle >}}
The structure of the published site will be:
## Embedded templates
-Hugo provides [embedded templates](g) to simplify site and content creation. Some of these templates interact with external services. For example, the `youtube` shortcode connects with YouTube's servers to embed videos on your site.
+Hugo provides [embedded templates](g) to simplify project and content creation. Some of these templates interact with external services. For example, the `youtube` shortcode connects with YouTube's servers to embed videos.
Some of these templates include settings to enhance privacy.
{{< code-toggle file=hugo >}}
[segments.segment1]
[[segments.segment1.excludes]]
- lang = "n*"
+ lang = 'n*'
[[segments.segment1.excludes]]
- lang = "en"
- output = "rss"
+ lang = 'en'
+ output = 'rss'
[[segments.segment1.includes]]
- kind = "{home,term,taxonomy}"
+ kind = '{home,term,taxonomy}'
[[segments.segment1.includes]]
- path = "{/docs,/docs/**}"
+ path = '{/docs,/docs/**}'
{{< /code-toggle >}}
## Rendering segments
{{< code-toggle file=config/development/server >}}
[[headers]]
-for = "/**"
+for = '/**'
[headers.values]
-X-Frame-Options = "DENY"
-X-XSS-Protection = "1; mode=block"
-X-Content-Type-Options = "nosniff"
-Referrer-Policy = "strict-origin-when-cross-origin"
-Content-Security-Policy = "script-src localhost:1313"
+X-Frame-Options = 'DENY'
+X-XSS-Protection = '1; mode=block'
+X-Content-Type-Options = 'nosniff'
+Referrer-Policy = 'strict-origin-when-cross-origin'
+Content-Security-Policy = 'script-src localhost:1313'
{{< /code-toggle >}}
## Redirects
{{< code-toggle file=config/development/server >}}
[[redirects]]
-from = "/myspa/**"
-to = "/myspa/"
+from = '/myspa/**'
+to = '/myspa/'
status = 200
force = false
{{< /code-toggle >}}
{{< code-toggle file=config/development/server >}}
[[redirects]]
force = false
-from = "/**"
-to = "/404.html"
+from = '/**'
+to = '/404.html'
status = 404
{{< /code-toggle >}}
-For multilingual sites, ensure the default language 404 redirect is defined last:
+For multilingual projects, ensure the default language 404 redirect is defined last:
{{< code-toggle file=config/development/server >}}
defaultContentLanguage = 'en'
{{ end }}
```
-## Multilingual sites
+## Multilingual projects
-With multilingual sites you can:
+With multilingual projects you can:
1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above.
1. Create content adapters unique to each language. See the examples below.
{{< /code-toggle >}}
> [!note]
-> For multilingual sites, defining cascade values in your project configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/).
+> For multilingual projects, defining cascade values in your project configuration is often more efficient. This avoids repeating the same cascade values on the home, section, taxonomy, or term page for each language. See [details](/configuration/cascade/).
>
-> If you choose to define cascade values in front matter for a multilingual site, you must create a corresponding home, section, taxonomy, or term page for every language.
+> If you choose to define cascade values in front matter for a multilingual project, you must create a corresponding home, section, taxonomy, or term page for every language.
## Emacs Org Mode
---
title: Image processing
-description: Process, transform, and analyze images.
+description: Transform images to change their size, shape, and appearance.
categories: []
keywords: []
---
-Hugo provides methods to transform and analyze images during the build process. The results are cached to ensure subsequent builds remain fast.
+Hugo provides methods to transform and analyze images during the build process. While Hugo can manage any image format as a resource, only [processable images](g) can be transformed using the methods below. The results are cached to ensure subsequent builds remain fast.
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
## Resources
{{ end }}
```
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
+
## Processing
To transform an image, apply a processing method to the image resource. Hugo generates the processed image on demand, caches the result, and returns a new resource object.
```
> [!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.
-
-Each method serves a specific transformation or metadata requirement:
+> Metadata is not preserved during image transformation. Use the [`Meta`][] method with the original image resource to extract metadata from supported formats.
-Method|Description
-:--|:--
-[`Colors`]|Returns a slice of the most dominant colors using a simple histogram method.
-[`Crop`]|Returns a new image resource cropped according to the given processing specification.
-[`Exif`]|Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif metadata.
-[`Fill`]|Returns a new image resource cropped and resized according to the given processing specification.
-[`Filter`]|Applies one or more image filters to the given image resource.
-[`Fit`]|Returns a new image resource downscaled to fit according to the given processing specification.
-[`Meta`]|Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif, IPTC, and XMP metadata.
-[`Process`]|Returns a new image resource processed according to the given processing specification.
-[`Resize`]|Returns a new image resource resized according to the given processing specification.
-{class="!mt-0"}
+Select a method from the table below for syntax and usage examples, depending on your specific transformation or metadata requirements:
-Select a method from the table above for syntax and usage examples.
+{{% render-table-of-pages-in-section
+ path=/methods/resource
+ filter=methods_resource_image_processing
+ filterType=include
+ headingColumn1=Method
+ headingColumn2=Description
+%}}{class="!mt-0"}
## Performance
See [configure imaging](/configuration/imaging).
-[`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/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
[file cache]: /configuration/caches/
To automatically define a menu entry for each top-level [section](g) of your site, enable the section pages menu in your project configuration.
{{< code-toggle file=hugo >}}
-sectionPagesMenu = "main"
+sectionPagesMenu = 'main'
{{< /code-toggle >}}
This creates a menu structure that you can access with `site.Menus.main` in your templates. See [menu templates] for details.
This system uses different content directories for each of the languages. Each language's `content` directory is set using the `contentDir` parameter.
{{< code-toggle file=hugo >}}
-languages:
- en:
- weight: 10
- languageName: "English"
- contentDir: "content/english"
- fr:
- weight: 20
- languageName: "Français"
- contentDir: "content/french"
+[languages.en]
+contentDir = 'content/english'
+label = "English"
+weight = 10
+
+[languages.fr]
+contentDir = 'content/french'
+label = "Français"
+weight = 20
{{< /code-toggle >}}
The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap.
> [!note]
> Page Bundle resources follow the same language assignment logic as content files, both by file name (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`).
-## Reference translated content
-
-To create a list of links to translated content, use a template similar to the following:
-
-```go-html-template {file="layouts/_partials/i18nlist.html"}
-{{ if .IsTranslated }}
-<h4>{{ i18n "translations" }}</h4>
-<ul>
- {{ range .Translations }}
- <li>
- <a href="{{ .RelPermalink }}">{{ .Language.Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
- </li>
- {{ end }}
-</ul>
-{{ end }}
-```
-
-The above can be put in a _partial_ template then included in any template. It will not print anything if there are no translations for a given page.
-
-The above also uses the [`i18n` function][i18func] described in the next section.
-
-### List all available languages
-
-`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator:
-
-```go-html-template {file="layouts/_partials/allLanguages.html"}
-<ul>
-{{ range $.Site.Home.AllTranslations }}
-<li><a href="{{ .RelPermalink }}">{{ .Language.LanguageName }}</a></li>
-{{ end }}
-</ul>
-```
-
## Translation of strings
See the [`lang.Translate`] template function.
## Localization
-The following localization examples assume your site's primary language is English, with translations to French and German.
+The following localization examples assume your project's primary language is English, with translations to French and German.
{{< code-toggle file=hugo >}}
defaultContentLanguage = 'en'
[languages]
[languages.en]
contentDir = 'content/en'
-languageName = 'English'
+label = 'English'
weight = 1
[languages.fr]
contentDir = 'content/fr'
-languageName = 'Français'
+label = 'Français'
weight = 2
[languages.de]
contentDir = 'content/de'
-languageName = 'Deutsch'
+label = 'Deutsch'
weight = 3
{{< /code-toggle >}}
{{< code-toggle file=hugo >}}
[languages.de]
-languageCode = 'de-DE'
-languageName = 'Deutsch'
+label = 'Deutsch'
+locale = 'de-DE'
weight = 1
[[languages.de.menus.main]]
weight = 20
[languages.en]
-languageCode = 'en-US'
-languageName = 'English'
+label = 'English'
+locale = 'en-US'
weight = 2
[[languages.en.menus.main]]
[configuration directory]: /configuration/introduction/#configuration-directory
[example menu template]: /templates/menu/#example
[front matter]: /content-management/menus/#define-in-front-matter
-[i18func]: /functions/lang/translate/
[lang.FormatAccounting]: /functions/lang/formataccounting/
[lang.FormatCurrency]: /functions/lang/formatcurrency/
-[lang.FormatNumber]: /functions/lang/formatnumber/
[lang.FormatNumberCustom]: /functions/lang/formatnumbercustom/
+[lang.FormatNumber]: /functions/lang/formatnumber/
[lang.FormatPercent]: /functions/lang/formatpercent/
[lang.Merge]: /functions/lang/merge/
[project configuration]: /content-management/menus/#define-in-project-configuration
{{< code-toggle file=content/inspections/engine/index.md fm=true >}}
title = 'Engine inspections'
[[resources]]
- src = "*specs.pdf"
- title = "Specification #:counter"
+ src = '*specs.pdf'
+ title = 'Specification #:counter'
[[resources]]
- src = "**.pdf"
- name = "pdf-file-:counter"
+ src = '**.pdf'
+ name = 'pdf-file-:counter'
{{</ code-toggle >}}
the `Name` and `Title` will be assigned to the resource files as follows:
## Multilingual
-By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site.
+By default, with a multilingual single-host project, Hugo does not duplicate shared page during the build.
> [!note]
> This behavior is limited to Markdown content. Shared page resources for other [content formats] are copied into each language bundle.
defaultContentLanguageInSubdir = true
[languages.de]
-languageCode = 'de-DE'
-languageName = 'Deutsch'
+label = 'Deutsch'
+locale = 'de-DE'
weight = 1
[languages.en]
-languageCode = 'en-US'
-languageName = 'English'
+label = 'English'
+locale = 'en-US'
weight = 2
{{< /code-toggle >}}
> [!important]
> To resolve Markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method.
>
-> In its default configuration, Hugo automatically uses the [embedded link render hook] and the [embedded image render hook] for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom link or image render hooks are defined by your project, modules, or themes, these will be used instead.
+> In its default configuration, Hugo automatically uses the [embedded link render hook] and the [embedded image render hook] for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link or image render hooks are defined by your project, modules, or themes, these will be used instead.
>
> You can also configure Hugo to `always` use the embedded link or image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
includeNewer = true
toLower = false
[[related.indices]]
-name = "fragmentrefs"
-type = "fragments"
+name = 'fragmentrefs'
+type = 'fragments'
applyFilter = true
weight = 80
{{< /code-toggle >}}
Hugo's embedded shortcodes are pre-defined templates within the application. Refer to each shortcode's documentation for specific usage instructions and available arguments.
-{{% list-pages-in-section path=/shortcodes %}}
+{{% render-list-of-pages-in-section path=/shortcodes %}}
## Custom
{{</* audio src=/audio/test.mp3 */>}}
```
-Learn more about creating shortcodes in the [shortcode templates] section.
+Learn more about creating shortcodes in the [shortcode templates][] section.
## Inline
For more information see [configure security](/configuration/security).
-The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string].
+The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string][].
```text {file="content/example.md"}
Today is
<p>Today is Thursday, January 30, 2025</p>
```
-Inline shortcodes process their inner content within the same context as regular _shortcode_ templates, allowing you to use any available [shortcode method].
+Inline shortcodes process their inner content within the same context as regular _shortcode_ templates, allowing you to use any available [shortcode method][].
> [!note]
> You cannot [nest](#nesting) inline shortcodes.
-Learn more about creating shortcodes in the [shortcode templates] section.
+Learn more about creating shortcodes in the [shortcode templates][] section.
## Calling
### Tags
-Some shortcodes expect content between opening and closing tags. For example, the embedded [`details`] shortcode requires an opening and closing tag:
+Some shortcodes expect content between opening and closing tags. For example, the embedded [`details`][] shortcode requires an opening and closing tag:
```text
{{</* details summary="See the details" */>}}
{{</* /details */>}}
```
-Some shortcodes do not accept content. For example, the embedded [`instagram`] shortcode requires a single _positional_ argument:
+Some shortcodes do not accept content. For example, the embedded [`instagram`][] shortcode requires a single _positional_ argument:
```text
{{</* instagram CxOWiQNP2MO */>}}
```
-Some shortcodes optionally accept content. For example, you can call the embedded [`qr`] shortcode with content:
+Some shortcodes optionally accept content. For example, you can call the embedded [`qr`][] shortcode with content:
```text
{{</* qr */>}}
Shortcode arguments can be either _named_ or _positional_.
-Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`] shortcode. The `src` argument, for instance, is required.
+Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`][] shortcode. The `src` argument, for instance, is required.
```text
{{</* figure src=/images/kitten.jpg */>}}
#### Markdown notation
-Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the [`TableOfContents`] method on the `Page` object.
+Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the [`TableOfContents`][] method on the `Page` object.
#### Standard notation
Then add front matter to each term page:
{{< code-toggle file=content/authors/jsmith/_index.md fm=true >}}
-title = "John Smith"
-affiliation = "University of Chicago"
+title = 'John Smith'
+affiliation = 'University of Chicago'
{{< /code-toggle >}}
Then create a _taxonomy_ template specific to the "authors" taxonomy:
#### 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 projects, `url` values with or without a leading slash are relative to the [`baseURL`][]. With multilingual projects, `url` values with a leading slash are relative to the `baseURL`, and `url` values without a leading slash are relative to the `baseURL` plus the language prefix.
Site type|Front matter `url`|Resulting URL
:--|:--|:--
You can also use tokens when setting the `url` value. This is typically used in `cascade` sections:
{{< code-toggle file=content/foo/bar/_index.md fm=true >}}
-title ="Bar"
+title ='Bar'
[[cascade]]
- url = "/:sections[last]/:slug"
+ url = '/:sections[last]/:slug'
{{< /code-toggle >}}
Use any of these tokens:
```go-html-template
<!DOCTYPE html>
-<html lang="{{ site.Language.LanguageCode }}">
+<html lang="{{ site.Language.Locale }}">
<head>
<title>{{ .Permalink }}</title>
{{ with .OutputFormats.Canonical }}<link rel="{{ .Rel }}" href="{{ .Permalink }}">{{ end }}
To build the extended or extended/deploy edition from source you must:
1. Install [Git]
-1. Install [Go] version 1.24.0 or later
+1. Install [Go] version 1.25.0 or later
1. Install a C compiler, either [GCC] or [Clang]
1. Update your `PATH` environment variable as described in the [Go documentation]
To build and install a specific release:
```sh
-CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.156.0
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.158.0
```
To build and install at the latest commit on the master branch:
- "server side" (noun), "server-side" (adjective)
- "Markdown" (capitalized)
- "open-source" (hyphenated adjective)
+- "Node.js" (first mention per page), "Node" (subsequent mentions), "node" (for the executable), "npm" (always lowercase)
### Template types
If the title in the "See also" sidebar is ambiguous or the same as another page, you can define an alternate title in the front matter:
{{< code-toggle file=hugo >}}
-title = "Long descriptive title"
-linkTitle = "Short title"
+title = 'Long descriptive title'
+linkTitle = 'Short title'
[params]
-alt_title = "Whatever you want"
+alt_title = 'Whatever you want'
{{< /code-toggle >}}
Use of the alternate title is limited to the "See also" sidebar.
```text
{{</* code-toggle file=hugo */>}}
baseURL = 'https://example.org/'
-languageCode = 'en-US'
+locale = 'en-US'
title = 'My Site'
{{</* /code-toggle */>}}
```
```text
{{</* code-toggle file=hugo copy=true */>}}
baseURL = 'https://example.org/'
-languageCode = 'en-US'
+locale = 'en-US'
title = 'My Site'
{{</* /code-toggle */>}}
```
Use the `deprecated-in` shortcode to indicate that a feature is deprecated:
```text
-{{</* deprecated-in 0.144.0 */>}}
+{{</* deprecated-in 0.144.0 /*/>}}
+```
-Use [`hugo.IsServer`] instead.
+You can also include details:
-[`hugo.IsServer`]: /functions/hugo/isserver/
+```text
+{{</* deprecated-in 0.144.0 */>}}
+Use [`hugo.IsServer`](/functions/hugo/isserver/) instead.
{{</* /deprecated-in */>}}
```
## New features
-Use the [new-in shortcode](#new-in) to indicate a new feature:
-
-```text
-{{</* new-in 0.144.0 */>}}
-```
+Use the [new-in](#new-in) shortcode to indicate a new feature.
-The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_shortcodes/new-in.html).
+The new-in shortcode will trigger a build warning if the specified version is older than a predefined threshold, based on differences in major and minor versions. This serves as a reminder to remove this shortcode call. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/_partials/layouts/blocks/feature-state.html).
## Deprecated features
-Use the [deprecated-in shorcode](#deprecated-in) shortcode to indicate that a feature is deprecated:
+Use the [deprecated-in](#deprecated-in) shortcode to indicate that a feature is deprecated.
-```text
-{{</* deprecated-in 0.144.0 */>}}
-Use [`hugo.IsServer`] instead.
-
-[`hugo.IsServer`]: /functions/hugo/isserver/
-{{</* /deprecated-in */>}}
-```
-
-When deprecating a function or method, add something like this to front matter:
+The deprecated-in shortcode will trigger a build warning if the specified version is older than a predefined threshold, based on differences in major and minor versions. This serves as a reminder to remove this shortcode call and the associated content. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/_partials/layouts/blocks/feature-state.html).
-{{< code-toggle file=content/something/foo.md fm=true >}}
-expiryDate: 2027-02-17 # deprecated 2025-02-17 in v0.144.0
-{{< /code-toggle >}}
+When deprecating a feature that has its own page, also set the `expiryDate` in front matter to two years from the date of deprecation. Include a brief comment to explain the setting:
-Set the `expiryDate` to two years from the date of deprecation, and add a brief front matter comment to explain the setting.
+```yaml
+expiryDate: 2028-03-03 # deprecated 2026-03-03 in v0.157.0
+```
## GitHub workflow
{{< code-toggle file=hugo >}}
[params.authors.a]
-firstName = "Marius"
-lastName = "Pontmercy"
+firstName = 'Marius'
+lastName = 'Pontmercy'
[params.authors.b]
-firstName = "Victor"
-lastName = "Hugo"
+firstName = 'Victor'
+lastName = 'Hugo'
[params.authors.c]
-firstName = "Jean"
-lastName = "Valjean"
+firstName = 'Jean'
+lastName = 'Valjean'
{{< /code-toggle >}}
> [!note]
## Boolean/undefined comparison
-Consider this site content:
+Consider this project structure:
```text
content/
--- /dev/null
+---
+title: css.Build
+description: Bundle, transform, and minify CSS resources.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: resource.Resource
+ signatures: ['css.Build [OPTIONS] RESOURCE']
+---
+
+{{< new-in 0.158.0 />}}
+
+Use the `css.Build` function to:
+
+- Recursively replace `@import` statements in CSS files with the content of the imported files
+- Transform syntax for browser compatibility
+- Apply vendor prefixes for browser compatibility
+- Minify the bundled CSS code
+- Create a source map
+
+If an `@import` statement includes a media query, a feature query, or a cascade layer assignment, the function wraps the imported content in the corresponding `@media`, `@supports`, or `@layer` rule.
+
+## Usage
+
+In this example, Hugo bundles the local files referenced by `@import` statements to create and publish a single resource with inline content.
+
+```text
+assets/
+└── css/
+ ├── components/
+ │ ├── a.css
+ │ └── b.css
+ └── main.css
+```
+
+```css {file="assets/css/main.css" copy=true}
+@import url('https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css');
+
+@import './components/a.css';
+@import './components/b.css';
+
+.c {color: blue; }
+```
+
+```css {file="assets/css/components/a.css" copy=true}
+.a { color: red; }
+```
+
+```css {file="assets/css/components/b.css" copy=true}
+.b { color: green; }
+```
+
+```go-html-template {file="layouts/_partials/css.html" copy=true}
+{{ with resources.Get "css/main.css" | css.Build }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+```go-html-template {file="layouts/baseof.html" copy=true}
+{{ partialCached "css.html" . }}
+```
+
+The generated CSS code:
+
+```css {file="public/css/main.css"}
+@import "https://cdn.jsdelivr.net/npm/the-new-css-reset/css/reset.min.css";
+
+.a {
+ color: red;
+}
+
+.b {
+ color: green;
+}
+
+.c {
+ color: blue;
+}
+```
+
+To minify the generated CSS code, use the [`minify`](#minify) option as described below.
+
+## Options
+
+The `css.Build` function takes an optional map of options based on the underlying [`esbuild`] package. Use these options to fine-tune bundling, minification, and browser compatibility.
+
+externals
+: (`[]string`) A slice of path patterns to exclude from bundling. The `@import` statements for these patterns remain as-is in the generated CSS code. See [details][esb_external].
+
+ ```go-html-template
+ {{ $opts := dict "externals" (slice "./exclude-these/*" "./exclude-these-too/*") }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+loaders
+: (`map`) A map of file extensions to loader types. This determines how files with a given extension are processed during bundling. By default, Hugo uses the `css` loader for `.css` files and the `file` loader for all others. Common loaders include:
+
+ - `css`: Processes the file as a CSS file
+ - `dataurl`: Embeds the file as a base64-encoded data URL
+ - `empty`: Excludes the file from the bundle
+ - `file`: Copies the file to the output directory and rewrites the URL
+ - `text`: Loads the file content as a string
+
+ See [details][esb_loader].
+
+ ```go-html-template
+ {{ $opts := dict "loaders" (dict ".png" "dataurl" ".svg" "dataurl") }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+mainFields
+: (`[]string`) A prioritized slice of field names in a `package.json` file that determine the CSS entry point of a Node package. The default is `["style", "main"]`. See [details][esb_mainfields].
+
+ When an `@import` statement references a Node package, Hugo consults the metadata in the `package.json` file to find the stylesheet. Use this option to support packages that define a CSS entry point using non-standard fields.
+
+ ```go-html-template
+ {{ $opts := dict "mainFields" (slice "css" "style" "main") }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+minify
+: (`bool`) Whether to minify the generated CSS code. Default is `false`. See [details][esb_minify].
+
+ ```go-html-template
+ {{ $opts := dict "minify" true }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+sourceMap
+: (`string`) The type of source map to generate. One of `external`, `inline`, `linked`, or `none`. Default is `none`. See [details][esb_sourcemap].
+
+ ```go-html-template
+ {{ $opts := dict "sourceMap" "linked" }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+sourcesContent
+: (`bool`) Whether to include the content of the source files in the source map. Default is `true`. See [details][esb_sourcesContent].
+
+ ```go-html-template
+ {{ $opts := dict "sourceMap" "linked" "sourcesContent" false }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+target
+: (`[]string`) The target environment for the generated CSS code. This determines which syntax transformations to perform and which vendor prefixes to apply. If unset, no transformations or prefixing are performed. Each element consists of a target name and a version number. Supported targets include `chrome`, `edge`, `firefox`, `ie`, `ios`, `opera`, and `safari`. See [details][esb_target].
+
+ ```go-html-template
+ {{ $target := slice "chrome115" "edge115" "firefox116" "ios16.4" "opera101" "safari16.4" }}
+ {{ $opts := dict "target" $target }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+ In the example above, the target environment is roughly equivalent to the [browserlist][] "baseline widely available" profile as of March 2026.
+
+targetPath
+: (`string`) The path to the generated CSS file, relative to the project's [`publishDir`][]. If unset, this defaults to the asset's original path with a `.css` extension.
+
+ ```go-html-template
+ {{ $opts := dict "targetPath" "css/styles.css" }}
+ {{ $r := resources.Get "css/main.css" | css.Build $opts }}
+ ```
+
+## Example
+
+The example below uses several of the [options](#options) described above to bundle, transform, and minify CSS code.
+
+```go-html-template {file="layouts/_partials/css.html" copy=true}
+{{ with resources.Get "css/main.css" }}
+ {{ $opts := dict
+ "loaders" (dict ".png" "dataurl" ".svg" "dataurl")
+ "minify" (cond hugo.IsDevelopment false true)
+ "sourceMap" (cond hugo.IsDevelopment "linked" "none")
+ "target" (slice "chrome115" "edge115" "firefox116" "ios16.4" "opera101" "safari16.4")
+ }}
+ {{ with . | css.Build $opts }}
+ {{ if hugo.IsDevelopment }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}">
+ {{ else }}
+ {{ with . | fingerprint }}
+ <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+ {{ end }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+Using the options above, Hugo does the following:
+
+- Embeds PNG and SVG images as data URLs in the generated CSS code
+- Minifies the output in production but not in development
+- Generates an external source map in development but not in production
+- Transforms syntax for compatibility with the targeted browser versions
+- Adds vendor prefixes for compatibility with the targeted browser versions
+- Publishes the generated CSS code to `css/styles.css`
+- In production, adds an SRI hash and inserts a file hash into the filename
+
+[`esbuild`]: https://github.com/evanw/esbuild
+[`publishDir`]: /configuration/all/#publishdir
+[browserlist]: https://browsersl.ist
+[esb_external]: https://esbuild.github.io/api/#external
+[esb_loader]: https://esbuild.github.io/api/#loader
+[esb_mainfields]: https://esbuild.github.io/api/#main-fields
+[esb_minify]: https://esbuild.github.io/api/#minify
+[esb_sourcemap]: https://esbuild.github.io/api/#sourcemap
+[esb_sourcesContent]: https://esbuild.github.io/api/#sources-content
+[esb_target]: https://esbuild.github.io/api/#target
+
+## Common patterns
+
+The examples below cover the most frequent use cases for referencing resources within your project or within Node packages. These patterns apply to both `@import` statements and the `url()` functional notation used for images and fonts.
+
+All resources referenced by a path, including images, fonts, and stylesheets, must reside in the `assets` directory of the [unified file system](g), or within a Node package.
+
+### Files in the assets directory
+
+To include a stylesheet from the `assets` directory, you can use a bare path, a relative path, or a root-relative path. When you use a bare path, Hugo searches relative to the current stylesheet, then relative to the `assets` directory.
+
+```css {file="/assets/css/main.css"}
+/* A bare path */
+@import "variables.css";
+
+/* A relative path */
+@import "./theme.css";
+@import "../layout.css";
+
+/* A root-relative path */
+@import "/css/grid.css";
+
+/* A url() reference using the same resolution logic */
+.logo { background: url("/images/logo.svg"); }
+```
+
+### Node packages
+
+When referencing a Node package by name, Hugo consults the `package.json` file within that package to find the entry point.
+
+```css {file="/assets/css/main.css"}
+@import "bootstrap";
+```
+
+### Files within a package
+
+To reference a specific file within a Node package, provide the path starting with the package name.
+
+```css {file="/assets/css/main.css"}
+@import "bootstrap/dist/css/bootstrap-grid.css";
+```
aliases: [postCSS]
returnType: resource.Resource
signatures: ['css.PostCSS [OPTIONS] RESOURCE']
+aliases: [/functions/resources/postcss/]
---
-{{< new-in 0.128.0 />}}
-
```go-html-template
{{ with resources.Get "css/main.css" | postCSS }}
<link rel="stylesheet" href="{{ .RelPermalink }}">
: Install [Node.js].
Step 2
-: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
+: Install the required Node packages in the root of your project. For example, to add vendor prefixes to your CSS rules:
```sh
npm i -D postcss postcss-cli autoprefixer
: (`bool`) Whether to enable inlining of import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. Default is `false`.
skipInlineImportsNotFound
-: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set this option to `true`. Default is `false`."
+: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set this option to `true`. Default is `false`.
```go-html-template
{{ $opts := dict "config" "config-directory" "noMap" true }}
aliases: [toCSS]
returnType: resource.Resource
signatures: ['css.Sass [OPTIONS] RESOURCE']
+aliases: [/functions/resources/tocss/]
---
Transpile Sass to CSS using the LibSass transpiler included in Hugo's extended and extended/deploy editions, or [install Dart Sass](#dart-sass) to use the latest features of the Sass language.
signatures: ['css.TailwindCSS [OPTIONS] RESOURCE']
---
-{{< new-in 0.128.0 />}}
-
Use the `css.TailwindCSS` function to process your Tailwind CSS files. This function uses the Tailwind CSS CLI to:
1. Scan your templates for Tailwind CSS utility class usage.
{{< new-in 0.141.0 />}}
-The `try` statement is a non-standard extension to Go's [text/template] package. It introduces a mechanism for handling errors within templates, mimicking the `try-catch` constructs found in other programming languages.
+The `try` statement is a non-standard extension to Go's [`text/template`][] package. It introduces a mechanism for handling errors within templates, mimicking the `try-catch` constructs found in other programming languages.
## Methods
## Example
-Error handling is essential when using the [`resources.GetRemote`] function to capture remote resources such as data or images. When calling this function, if the HTTP request fails, Hugo will fail the build.
+Error handling is essential when using the [`resources.GetRemote`][] function to capture remote resources such as data or images. When calling this function, if the HTTP request fails, Hugo will fail the build.
Instead of failing the build, we can catch the error and emit a warning:
{{ end }}
```
-In the above, note that the [context](g) within the last conditional block is the `TryValue` object returned by the `try` statement. At this point neither the `Err` nor `Value` methods returned anything, so the current context is not useful. Use the `$` to access the [template context] if needed.
+In the above, note that the [context](g) within the last conditional block is the `TryValue` object returned by the `try` statement. At this point neither the `Err` nor `Value` methods returned anything, so the current context is not useful. Use the `$` to access the [template context][] if needed.
> [!note]
> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
[`resources.GetRemote`]: /functions/resources/getremote/
[template context]: /templates/introduction/#template-context
-[text/template]: https://pkg.go.dev/text/template
+[`text/template`]: https://pkg.go.dev/text/template
---
```go-html-template
-{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.156.0">
+{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.158.0">
```
[languages]
[languages.de]
baseURL = 'https://de.example.org/'
- languageCode = 'de-DE'
- languageName = 'Deutsch'
+ label = 'Deutsch'
+ locale = 'de-DE'
title = 'Projekt Dokumentation'
weight = 1
[languages.en]
baseURL = 'https://en.example.org/'
- languageCode = 'en-US'
- languageName = 'English'
+ label = 'English'
+ locale = 'en-US'
title = 'Project Documentation'
weight = 2
{{< /code-toggle >}}
defaultContentLanguageInSubdir = true
[languages]
[languages.de]
- languageCode = 'de-DE'
- languageName = 'Deutsch'
+ label = 'Deutsch'
+ locale = 'de-DE'
title = 'Projekt Dokumentation'
weight = 1
[languages.en]
- languageCode = 'en-US'
- languageName = 'English'
+ label = 'English'
+ locale = 'en-US'
title = 'Project Documentation'
weight = 2
{{< /code-toggle >}}
[languages.de]
contentDir = 'content/de'
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
title = 'Projekt Dokumentation'
weight = 1
[languages.en]
contentDir = 'content/en'
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
title = 'Project Documentation'
weight = 2
---
```go-html-template
-{{ hugo.Version }} → 0.156.0
+{{ hugo.Version }} → 0.158.0
```
aliases: [/functions/imageconfig]
---
-See [image processing] for an overview of Hugo's image pipeline.
+> [!note]
+> This is a legacy function, superseded by the [`Width`][] and [`Height`][] methods for [global resources](g), [page resources](g), and [remote resources](g). See the [image processing][] section for details.
```go-html-template
{{ $ic := images.Config "/static/images/a.jpg" }}
{{ $ic.Height }} → 400 (int)
```
-Supported image formats include GIF, JPEG, PNG, TIFF, and WebP.
-
-> [!note]
-> This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global resources](g), [page resources](g), and [remote resources](g). See the [image processing] section for details.
+Supported image formats include AVIF, BMP, GIF, HEIC, HEIF, JPEG, PNG, TIFF, and WebP.
[`Height`]: /methods/resource/height/
[`Width`]: /methods/resource/width/
functions_and_methods:
aliases: []
returnType: images.ImageResource
- signatures: [images.Filter FILTERS... IMAGE]
+ signatures: [images.Filter FILTER... RESOURCE]
---
-Apply one or more [image filters](#image-filters) to the given image.
+{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
+
+The `images.Filter` function returns a new resource from a [processable image](g) after applying one or more [image filters](#image-filters).
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+Use the `images.Filter` function to apply effects such as blurring, sharpening, or grayscale conversion. You can pass a single filter or a slice of filters. When providing a slice, Hugo applies the filters from left to right.
To apply a single filter:
{{ end }}
```
-You can also apply image filters using the [`Filter`] method on a `Resource` object.
-
-[`Filter`]: /methods/resource/filter/
+You can also apply image filters using the [`Filter`][] method on a `Resource` object.
## Example
Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object.
-{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
+{{% render-list-of-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
+
+[`Filter`]: /methods/resource/filter/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
{{ end }}
```
-In the example above, `"crop 200x200 TopRight webp q50"` is the _processing specification_.
+In the example above, `"crop 200x200 TopRight webp q50"` is the processing specification.
{{% include "/_common/methods/resource/processing-spec.md" %}}
aliases: [babel]
returnType: resource.Resource
signatures: ['js.Babel [OPTIONS] RESOURCE']
+aliases: [/functions/resources/babel/]
---
```go-html-template
: Install [Node.js](https://nodejs.org/en/download)
Step 2
-: Install the required Node.js packages in the root of your project.
+: Install the required Node packages in the root of your project.
```sh
npm install --save-dev @babel/core @babel/cli
```go-html-template
{{ with resources.Get "js/main.js" }}
{{$opts := dict
- "minify" (not hugo.IsDevelopment)
- "sourceMap" (cond hugo.IsDevelopment "external" "")
- "targetPath" "js/main.js"
+ "minify" (cond hugo.IsDevelopment false true)
+ "sourceMap" (cond hugo.IsDevelopment "linked" "none")
}}
{{ with . | js.Build $opts }}
{{ if hugo.IsDevelopment }}
## Import JS code from the assets directory
-`js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
+`js.Build` has full support for Hugo's [unified file system](g). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
```js
import { hello } from 'my/module';
## Node.js dependencies
-Use the `js.Build` function to include Node.js dependencies.
+Use the `js.Build` function to include Node dependencies.
Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo build`.
i18n/pt-BR.toml
```
-The base name must match the [`languageCode`][] or [language key][] as defined in your project configuration. Hugo selects the translation table based on the `languageCode`, falling back to the language key if a matching translation table does not exist.
+The base name must match the [`locale`][] or [language key][] as defined in your project configuration. Hugo selects the translation table based on the `locale`, falling back to the language key if a matching translation table does not exist.
Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7][] are also supported. You may omit the `art-x-` prefix for brevity. For example:
## Simple translations
-Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
+Let's say your multilingual project supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
```text
i18n/
## Translations with pluralization
-Let's say your multilingual site supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
+Let's say your multilingual project supports two languages, English and Polish. Create a translation table for each language in the `i18n` directory.
```text
i18n/
[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
[`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders
-[`languageCode`]: /configuration/languages/#languagecode
+[`locale`]: /configuration/languages/#locale
[`printI18nWarnings`]: /configuration/all/#printi18nwarnings
[CLDR]: https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html
[go-i18n]: https://github.com/nicksnyder/go-i18n
signatures: [math.Counter]
---
-The counter is global for both monolingual and multilingual sites, and its initial value for each build is 1.
+The counter is global for both monolingual and multilingual projects, and its initial value for each build is 1.
```go-html-template {file="layouts/page.html"}
{{ warnf "page.html called %d times" math.Counter }}
---
title: reflect.IsImageResource
-description: Reports whether the given value is a Resource object representing a processable image.
+description: Reports whether the given value is a Resource object representing an image as defined by its media type.
categories: []
keywords: []
params:
{{< new-in 0.154.0 />}}
-{{% glossary-term "processable image" %}}
+## Usage
-With this project structure:
+This example iterates through all project resources and uses `reflect.IsImageResource` to decide whether to render an image tag or provide a download link for non-image files.
-```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
+```go-html-template
+{{ range resources.Match "**" }}
+ {{ if reflect.IsImageResource . }}
+ <img src="{{ .RelPermalink }}" alt="Image">
+ {{ else }}
+ <a href="{{ .RelPermalink }}">Download</a>
+ {{ end }}
{{ 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 }}
-```
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
--- /dev/null
+---
+title: reflect.IsImageResourceProcessable
+description: Reports whether the given value is a Resource object representing an image from which Hugo can extract dimensions and perform processing such as converting, resizing, cropping, or filtering.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsImageResourceProcessable INPUT]
+---
+
+{{< new-in 0.157.0 />}}
+
+{{% glossary-term "processable image" %}}
+
+## Usage
+
+This example iterates through all project resources and uses `reflect.IsImageResourceProcessable` to ensure the image pipeline can perform transformations like resizing before processing begins.
+
+```go-html-template
+{{ range resources.Match "**" }}
+ {{ if reflect.IsImageResourceProcessable . }}
+ {{ with .Process "resize 300x webp" }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="Processed Image">
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
--- /dev/null
+---
+title: reflect.IsImageResourceWithMeta
+description: Reports whether the given value is a Resource object representing an image from which Hugo can extract dimensions and, if present, Exif, IPTC, and XMP data.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: bool
+ signatures: [reflect.IsImageResourceWithMeta INPUT]
+---
+
+{{< new-in 0.157.0 />}}
+
+## Usage
+
+This example iterates through all project resources and uses `reflect.IsImageResourceWithMeta` to safely display image dimensions and metadata only for supported formats.
+
+```go-html-template
+{{ range resources.Match "**" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="Image with Meta">
+ {{ with .Meta }}
+ <p>Taken on: {{ .Date }}</p>
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
+
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
+++ /dev/null
----
-title: resources.Babel
-description: Compiles the given JavaScript resource with Babel.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- aliases: []
- returnType: resource.Resource
- signatures: ['resources.Babel [OPTIONS] RESOURCE']
-expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0
----
-
-{{< deprecated-in 0.128.0 >}}
-Use [`js.Babel`] instead.
-
-[`js.Babel`]: /functions/js/babel/
-{{< /deprecated-in >}}
```json
{
- "build_date": "2026-01-11T11:27:49-08:00",
- "hugo_version": "0.156.0",
- "last_modified": "2026-01-11T11:27:59-08:00"
+ "build_date": "2026-03-16T13:56:25-07:00",
+ "hugo_version": "0.158.0",
+ "last_modified": "2026-02-16T12:04:52-07:00"
}
```
responseHeaders
: {{< new-in 0.143.0 />}}
-: (`[]string`) The headers to extract from the server's response, accessible through the resource's [`Data.Headers`] method. Header name matching is case-insensitive.
+: (`[]string`) The headers to extract from the server's response, accessible through the resource's [`Data.Headers`][] method. Header name matching is case-insensitive.
-[`Data.Headers`]: /methods/resource/data/#headers
+timeout
+: {{< new-in 0.157.0 />}}
+: (`string`) The duration after which the request is cancelled if it does not complete, expressed as a [duration](g). If not specified, the request will timeout after 2 minutes.
## Options examples
> [!note]
-> For brevity, the examples below do not include [error handling].
+> For brevity, the examples below do not include [error handling][].
To include a header:
{{ $resource := resources.GetRemote $url $opts }}
```
-## Remote data
+Use the `timeout` option to prevent slow external requests from stalling the build when fetching multiple remote feeds:
-When retrieving remote data, use the [`transform.Unmarshal`] function to [unmarshal](g) the response.
+```go-html-template
+{{ $url := "https://example.org/feed.rss" }}
+{{ $opts := dict "timeout" "10s" }}
+{{ with try (resources.GetRemote $url $opts) }}
+ {{ with .Err }}
+ {{ warnf "Failed to fetch feed: %s" . }}
+ {{ else with .Value }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ end }}
+```
-[`transform.Unmarshal`]: /functions/transform/unmarshal/
+## Remote data
+
+When retrieving remote data, use the [`transform.Unmarshal`][] function to [unmarshal](g) the response.
```go-html-template
{{ $data := dict }}
```
> [!note]
-> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
+> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type][]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`.
>
> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead:
>
## Error handling
-Use the [`try`] statement to capture HTTP request errors. If you do not handle the error yourself, Hugo will fail the build.
+Use the [`try`][] statement to capture HTTP request errors. If you do not handle the error yourself, Hugo will fail the build.
> [!note]
> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
## HTTP response
-The [`Data`] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response.
-
-[`Data`]: /methods/resource/data/
+The [`Data`][] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response.
## Caching
-Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details.
+Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches][] for details.
By default, Hugo derives the cache key from the arguments passed to the function. Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource.
To protect against malicious intent, the `resources.GetRemote` function inspects the server response including:
-- The [Content-Type] in the response header
+- The [Content-Type][] in the response header
- The file extension, if any
- The content itself
-If Hugo is unable to resolve the media type to an entry in its [allowlist], the function throws an error:
+If Hugo is unable to resolve the media type to an entry in its [allowlist][], the function throws an error:
```text
ERROR error calling resources.GetRemote: failed to resolve media type...
- An _addition_ to the allowlist; it does not _replace_ the allowlist
- An array of [regular expressions](g)
+[`Data.Headers`]: /methods/resource/data/#headers
+[`Data`]: /methods/resource/data/
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
[`try`]: /functions/go-template/try
[allowlist]: https://en.wikipedia.org/wiki/Whitelist
[configure file caches]: /configuration/caches/
+++ /dev/null
----
-title: resources.PostCSS
-description: Processes the given resource with PostCSS using any PostCSS plugin.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- aliases: []
- returnType: resource.Resource
- signatures: ['resources.PostCSS [OPTIONS] RESOURCE']
-expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0
----
-
-{{< deprecated-in 0.128.0 >}}
-Use [`css.PostCSS`] instead.
-
-[`css.PostCSS`]: /functions/css/postcss/
-{{< /deprecated-in >}}
: Install [Node.js].
Step 2
-: Install the required Node.js packages in the root of your project:
+: Install the required Node packages in the root of your project:
```sh {copy=true}
npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss
+++ /dev/null
----
-title: resources.ToCSS
-description: Transpiles Sass to CSS.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- aliases: []
- returnType: resource.Resource
- signatures: ['resources.ToCSS [OPTIONS] RESOURCE']
-expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0
----
-
-{{< deprecated-in 0.128.0 >}}
-Use [`css.Sass`] instead.
-
-[`css.Sass`]: /functions/css/sass/
-{{< /deprecated-in >}}
--- /dev/null
+---
+title: strings.ReplacePairs
+description: Returns a copy of a string with multiple replacements performed in a single pass, using a slice of old and new string pairs.
+categories: []
+keywords: []
+params:
+ functions_and_methods:
+ aliases: []
+ returnType: string
+ signatures: ['strings.ReplacePairs OLD NEW [OLD NEW ...] INPUT']
+---
+
+{{< new-in 0.158.0 />}}
+
+Use the `strings.ReplacePairs` function to perform multiple replacements on a string in a single operation. This approach is faster than sequentially calling the [`strings.Replace`][] function.
+
+Replacing strings sequentially requires multiple function calls and variable re-assignments.
+
+```go-html-template
+{{ $s := "aabbcc" }}
+{{ $s = strings.Replace $s "a" "x" }}
+{{ $s = strings.Replace $s "b" "y" }}
+{{ $s = strings.Replace $s "c" "z" }}
+{{ $s }} → xxyyzz
+```
+
+Using `strings.ReplacePairs` produces the same result with fewer function calls in less time.
+
+```go-html-template
+{{ "aabbcc" | strings.ReplacePairs "a" "x" "b" "y" "c" "z" }} → xxyyzz
+```
+
+Pairs may also be passed as a single slice:
+
+```go-html-template
+{{ $pairs := slice
+ "a" "x"
+ "b" "y"
+ "c" "z"
+}}
+{{ "aabbcc" | strings.ReplacePairs $pairs }} → xxyyzz
+```
+
+## Examples
+
+Observe that replacements are not applied recursively because the function scans the string only once.
+
+```go-html-template
+{{ $pairs := slice
+ "a" "b"
+ "b" "c"
+}}
+{{ "a" | strings.ReplacePairs $pairs }} → b
+```
+
+Apply the first match when multiple old strings could match at the same position.
+
+```go-html-template
+{{ $pairs := slice
+ "app" "pear"
+ "apple" "orange"
+}}
+{{ "apple" | strings.ReplacePairs $pairs }} → pearle
+```
+
+Delete specific strings by providing an empty string as the second value in a pair.
+
+```go-html-template
+{{ $pairs := slice "b" "" }}
+{{ "abc" | strings.ReplacePairs $pairs }} → ac
+```
+
+## Edge cases
+
+The table below outlines how the function handles various input scenarios.
+
+Scenario|Result
+:--|:--
+Fewer than two arguments|Error
+Odd number of slice elements|Error
+Empty slice|Returns the input string
+Empty input string|Returns an empty string
+Empty old string|Returns the input string [interleaved](g) with the new string
+
+## Performance
+
+While `strings.Replace` and `strings.ReplacePairs` can produce the same results, they handle data differently. Choosing the right one can noticeably reduce the time Hugo takes to build your project.
+
+### Single pass vs. multiple passes
+
+When using `strings.Replace`, Hugo must scan the text from start to finish to find a match. If you chain three replacements together, Hugo performs three separate passes over the entire string.
+
+The `strings.ReplacePairs` function is more efficient because it performs a single pass. Hugo looks through the text once and applies all replacements simultaneously.
+
+### Caching
+
+Unlike `strings.Replace`, which performs a direct substitution, `strings.ReplacePairs` requires an initialization step to prepare the single-pass replacement logic. To make this efficient, Hugo manages this logic using a cache:
+
+- During the initial call, Hugo initializes and stores the logic for that specific set of pairs.
+- During subsequent calls, Hugo retrieves the stored logic, skipping the initialization step and reducing the duration of the call.
+
+### Choosing the right function
+
+The efficiency of `strings.ReplacePairs` increases as the text gets longer or the number of pairs grows. Consider these scenarios when deciding which function to use:
+
+- For a single replacement on a short string like a title, `strings.Replace` is efficient.
+- For multiple replacements or long strings like a long-form article, `strings.ReplacePairs` is much faster.
+
+For a document with about 8000 characters, which is roughly the length of a long-form article, `strings.ReplacePairs` outperforms five sequential `strings.Replace` calls during the initial call. Once cached, it is the faster choice for almost any situation with two or more pairs.
+
+[`strings.Replace`]: /functions/strings/replace/
aliases: [/functions/templates.defer]
---
-{{< new-in 0.128.0 />}}
-
> [!note]
> This feature should only be used in the main template, typically `layouts/baseof.html`. Using it in _shortcode_, _partial_, or _render hook_ templates may lead to unpredictable results. For further details, please refer to [this issue].
: Optional map to pass as data to the deferred template. This will be available in the deferred template as `.` or `$`.
```go-html-template
-Language Outside: {{ site.Language.Lang }}
+Language Outside: {{ site.Language.Name }}
Page Outside: {{ .RelPermalink }}
I18n Outside: {{ i18n "hello" }}
{{ $data := (dict "page" . )}}
{{ with (templates.Defer (dict "data" $data )) }}
- Language Inside: {{ site.Language.Lang }}
+ Language Inside: {{ site.Language.Name }}
Page Inside: {{ .page.RelPermalink }}
I18n Inside: {{ i18n "hello" }}
{{ end }}
```
-The [output format](/configuration/output-formats/), [site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Lang` and `.RelPermalink` will be the same on the inside and the outside of the deferred template.
+The [output format](/configuration/output-formats/), [site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Name` and `.RelPermalink` will be the same on the inside and the outside of the deferred template.
aliases: [/functions/htmlunescape]
---
-The `transform.HTMLUnescape` function replaces [HTML entities] with their corresponding characters.
+The `transform.HTMLUnescape` function replaces [HTML entities][] with their corresponding characters.
```go-html-template
{{ htmlUnescape "Lilo & Stitch" }} → Lilo & Stitch
{{ htmlUnescape "7 > 6" }} → 7 > 6
```
-In most contexts Go's [html/template] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`] function.
+In most contexts Go's [`html/template`][] package will escape special characters. To bypass this behavior, pass the unescaped string through the [`safeHTML`][] function.
```go-html-template
{{ htmlUnescape "Lilo & Stitch" | safeHTML }}
[`safehtml`]: /functions/safe/html/
[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
-[html/template]: https://pkg.go.dev/html/template
+[`html/template`]: https://pkg.go.dev/html/template
```go-html-template
{{ $s := `
baseURL = 'https://example.org/'
- languageCode = 'en-US'
+ locale = 'en-US'
title = 'ABC Widgets'
`}}
<pre>{{ transform.Remarshal "json" $s }}</pre>
```html
<pre>{
"baseURL": "https://example.org/",
- "languageCode": "en-US",
+ "locale": "en-US",
"title": "ABC Widgets"
}
</pre>
```text
{
"baseURL": "https://example.org/",
- "languageCode": "en-US",
+ "locale": "en-US",
"title": "ABC Widgets"
}
```
signatures: [transform.XMLEscape INPUT]
---
-The `transform.XMLEscape` function removes [disallowed characters] as defined in the XML specification, then escapes the result by replacing the following characters with [HTML entities]:
+The `transform.XMLEscape` function removes [disallowed characters][] as defined in the XML specification, then escapes the result by replacing the following characters with [HTML entities]:
- `"` → `"`
- `'` → `'`
{{ transform.XMLEscape "<p>abc</p>" }} → <p>abc</p>
```
-When using `transform.XMLEscape` in a template rendered by Go's [html/template] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template:
+When using `transform.XMLEscape` in a template rendered by Go's [`html/template`][] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template:
```xml {file="layouts/rss.xml"}
<description>{{ .Summary | transform.XMLEscape | safeHTML }}</description>
[disallowed characters]: https://www.w3.org/TR/xml/#charsets
[html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity
-[html/template]: https://pkg.go.dev/html/template
+[`html/template`]: https://pkg.go.dev/html/template
---
title: urls.PathEscape
-description: Returns the given string, replacing all percent-encoded sequences with the corresponding unescaped characters.
+description: Returns the given string, applying percent-encoding to special characters and reserved delimiters so it can be safely used as a segment within a URL path.
categories: []
keywords: []
params:
The `urls.PathEscape` function does the inverse transformation of [`urls.PathUnescape`][].
```go-html-template
-{{ urls.PathEscape "A/b/c?d=é&f=g+h" }} → A%2Fb%2Fc%3Fd=%C3%A9&f=g+h
+{{ urls.PathEscape "my café" }} → my%20caf%C3%A9
```
+Use this function to escape a string so that it can be safely used as an individual segment within a URL path.
+
[`urls.PathUnescape`]: /functions/urls/PathUnescape/
---
title: urls.PathUnescape
-description: Returns the given string, applying percent-encoding to special characters and reserved delimiters so it can be safely used as a segment within a URL path.
+description: Returns the given string, replacing all percent-encoded sequences with the corresponding unescaped characters.
categories: []
keywords: []
params:
{{ urls.PathUnescape "A%2Fb%2Fc%3Fd=%C3%A9&f=g+h" }} → A/b/c?d=é&f=g+h
```
+Use this function to decode an individual segment within a URL path.
+
[`urls.PathEscape`]: /functions/urls/PathEscape/
themes
: The `themes` directory contains one or more [themes](g), each in its own subdirectory.
-## Union file system
+## Unified file system
-Hugo creates a union file system, allowing you to mount two or more directories to the same location. For example, let's say your home directory contains a Hugo project in one directory, and shared content in another:
+Hugo creates a [unified file system](g), allowing you to mount two or more directories to the same location. For example, let's say your home directory contains a Hugo project in one directory, and shared content in another:
```text
home/
{{< /code-toggle >}}
> [!note]
-> When you overlay one directory on top of another, you must mount both directories.
+> Defining a custom mount replaces the default mounting for that [component](g). To overlay an external directory on top of the project default, you must explicitly mount both.
>
-> Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's union file system instead.
+> Hugo does not follow symbolic links. If you need the functionality provided by symbolic links, use Hugo's unified file system instead.
-After mounting, the union file system has this structure:
+After mounting, the unified file system has this structure:
```text
home/
└── hugo.toml
```
-> [!note]
-> When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's `content` directory was mounted first.
+When two or more files share the same path, the version in the highest layer takes precedence. In the example above, if the `shared-content` directory contains `books/book-1.md`, it is ignored because the project's `content` directory is the first (highest) mount.
You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/configuration/module/#mounts).
└── hugo.toml
```
-Using the union file system described above, Hugo mounts each of these directories to the corresponding location in the project. When two files have the same path, the file in the project directory takes precedence. This allows you, for example, to override a theme's template by placing a copy in the same location within the project directory.
+Using the unified file system described above, Hugo mounts each of these directories to the corresponding location in the project. When two files have the same path, the file in the project directory takes precedence. This allows you, for example, to override a theme's template by placing a copy in the same location within the project directory.
If you are simultaneously using components from two or more themes or modules, and there's a path collision, the first mount takes precedence.
```text
baseURL = 'https://example.org/'
-languageCode = 'en-us'
+locale = 'en-us'
title = 'My New Hugo Project'
theme = 'ananke'
```
Make the following changes:
1. Set the `baseURL` for your project. This value must begin with the protocol and end with a slash, as shown above.
-1. Set the `languageCode` to your locale.
+1. Set the `locale` to your locale.
1. Set the `title` for your project.
Start Hugo's development server to see your changes, remembering to include draft content.
You should see something like:
```text
-hugo v0.155.3-8a858213b73907e823e2be2b5640a0ce4c04d295+extended linux/amd64 BuildDate=2026-02-08T16:40:42Z VendorInfo=gohugoio
+hugo v0.158.0-f41be7959a44108641f1e081adf5c4be7fc1bb63+extended linux/amd64 BuildDate=2026-03-16T17:42:04Z VendorInfo=gohugoio
```
## Display available commands
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
-1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
1. Commit the changes to your local Git repository and push to your GitHub repository.
## Procedure
env:
variables:
# Application versions
- DART_SASS_VERSION: 1.97.3
- GO_VERSION: 1.26.0
- HUGO_VERSION: 0.156.0
+ DART_SASS_VERSION: 1.98.0
+ GO_VERSION: 1.26.1
+ HUGO_VERSION: 0.158.0
# Time zone
TZ: Europe/Oslo
# Cache
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
-1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
## Procedure
: Create a `wrangler.toml` file in the root of your project.
```toml {file="wrangler.toml" copy=true}
- name = "hosting-cloudflare-worker"
- compatibility_date = "2025-07-31"
+ name = 'hosting-cloudflare-worker'
+ compatibility_date = '2025-07-31'
[build]
- command = "chmod a+x build.sh && ./build.sh"
+ command = 'chmod a+x build.sh && ./build.sh'
[assets]
- directory = "./public"
- not_found_handling = "404-page"
+ directory = './public'
+ not_found_handling = '404-page'
```
Step 2
main() {
- DART_SASS_VERSION=1.97.3
- GO_VERSION=1.26.0
- HUGO_VERSION=0.156.0
- NODE_VERSION=24.13.1
+ DART_SASS_VERSION=1.98.0
+ GO_VERSION=1.26.1
+ HUGO_VERSION=0.158.0
+ NODE_VERSION=24.14.0
export TZ=Europe/Oslo
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
-1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
1. Commit the changes to your local Git repository and push to your GitHub repository
## Procedure
{{< code-toggle file=hugo copy=true >}}
[caches.images]
- dir = ":cacheDir/images"
+ dir = ':cacheDir/images'
{{< /code-toggle >}}
See [configure file caches] for more information.
build:
runs-on: ubuntu-latest
env:
- DART_SASS_VERSION: 1.97.3
- GO_VERSION: 1.26.0
- HUGO_VERSION: 0.156.0
- NODE_VERSION: 24.13.1
+ DART_SASS_VERSION: 1.98.0
+ GO_VERSION: 1.26.1
+ HUGO_VERSION: 0.158.0
+ NODE_VERSION: 24.14.0
TZ: Europe/Oslo
steps:
- name: Checkout
In the future, whenever you push a change from your local Git repository, GitHub Pages will rebuild and deploy your site.
-## Customize the workflow
-
-The example workflow above includes this step, which typically takes 10‑15 seconds:
-
-```yaml
-- name: Install Dart Sass
- run: sudo snap install dart-sass
-```
-
-You may remove this step if your site, themes, and modules do not transpile Sass to CSS using the [Dart Sass] transpiler.
-
## Other resources
- [Learn more about GitHub Actions](https://docs.github.com/en/actions)
[`cacheDir`]: /configuration/all/#cachedir
[configure file caches]: /configuration/caches/
-[Dart Sass]: /functions/css/sass/#dart-sass
[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites
```yaml {file=".gitlab-ci.yml" copy=true}
variables:
# Application versions
- DART_SASS_VERSION: 1.97.3
- HUGO_VERSION: 0.156.0
- NODE_VERSION: 24.13.1
+ DART_SASS_VERSION: 1.98.0
+ HUGO_VERSION: 0.158.0
+ NODE_VERSION: 24.14.0
# Git
GIT_DEPTH: 0
GIT_STRATEGY: clone
TZ: Europe/Oslo
image:
- name: golang:1.26.0-bookworm
+ name: golang:1.26.1-bookworm
pages:
stage: deploy
script:
- # Create directory for user-specific executable files
- - echo "Creating directory for user-specific executable files..."
- - mkdir -p "${HOME}/.local"
-
- # Install utilities
- - echo "Installing utilities..."
- - apt-get update
- - apt-get install -y brotli xz-utils zstd
-
- # Install Dart Sass
- - echo "Installing Dart Sass ${DART_SASS_VERSION}..."
- - curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- - tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- - rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
- - export PATH="${HOME}/.local/dart-sass:${PATH}"
-
- # Install Hugo
- - echo "Installing Hugo ${HUGO_VERSION}..."
- - curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- - mkdir "${HOME}/.local/hugo"
- - tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- - rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz"
- - export PATH="${HOME}/.local/hugo:${PATH}"
-
- # Install Node.js
- - echo "Installing Node.js ${NODE_VERSION}..."
- - curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
- - tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
- - rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
- - export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
-
- # Verify installations
- - echo "Verifying installations..."
- - "echo Dart Sass: $(sass --version)"
- - "echo Go: $(go version)"
- - "echo Hugo: $(hugo version)"
- - "echo Node.js: $(node --version)"
- - "echo brotli: $(brotli --version)"
- - "echo xz: $(xz --version)"
- - "echo zstd: $(zstd --version)"
-
- # Install Node.js dependencies
- - echo "Installing Node.js dependencies..."
- - "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true"
-
- # Configure Git
- - echo "Configuring Git..."
- - git config core.quotepath false
-
- # Build site
- - echo "Building site..."
- - hugo build --gc --minify --baseURL "${CI_PAGES_URL}"
-
- # Compress published files
- - echo "Compressing published files..."
- - find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
- - time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
- - time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
+ - |
+ # Create directory for user-specific executable files
+ echo "Creating directory for user-specific executable files..."
+ mkdir -p "${HOME}/.local"
+
+ # Install utilities
+ echo "Installing utilities..."
+ apt-get update
+ apt-get install -y brotli xz-utils zstd
+
+ # Install Dart Sass
+ echo "Installing Dart Sass ${DART_SASS_VERSION}..."
+ curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz"
+ export PATH="${HOME}/.local/dart-sass:${PATH}"
+
+ # Install Hugo
+ echo "Installing Hugo ${HUGO_VERSION}..."
+ curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ mkdir -p "${HOME}/.local/hugo"
+ tar -C "${HOME}/.local/hugo" -xf "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ rm "hugo_${HUGO_VERSION}_linux-amd64.tar.gz"
+ export PATH="${HOME}/.local/hugo:${PATH}"
+
+ # Install Node.js
+ echo "Installing Node.js ${NODE_VERSION}..."
+ curl -sLJO "https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz"
+ tar -C "${HOME}/.local" -xf "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ rm "node-v${NODE_VERSION}-linux-x64.tar.xz"
+ export PATH="${HOME}/.local/node-v${NODE_VERSION}-linux-x64/bin:${PATH}"
+
+ # Verify installations
+ echo "Verifying installations..."
+ echo "Dart Sass: $(sass --version)"
+ echo "Go: $(go version)"
+ echo "Hugo: $(hugo version)"
+ echo "Node.js: $(node --version)"
+ echo "brotli: $(brotli --version)"
+ echo "xz: $(xz --version)"
+ echo "zstd: $(zstd --version)"
+
+ # Install Node.js dependencies
+ echo "Installing Node.js dependencies..."
+ [[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci --prefer-offline || true
+
+ # Configure Git
+ echo "Configuring Git..."
+ git config core.quotepath false
+
+ # Build site
+ echo "Building site..."
+ hugo --gc --minify --baseURL "${CI_PAGES_URL}"
+
+ # Compress published files
+ echo "Compressing published files..."
+ find public/ -type f -regextype posix-extended -regex '.+\.(css|html|js|json|mjs|svg|txt|xml)$' -print0 > files.txt
+ time xargs --null --max-procs=0 --max-args=1 brotli --quality=10 --force --keep < files.txt
+ time xargs --null --max-procs=0 --max-args=1 gzip -9 --force --keep < files.txt
artifacts:
paths:
- public
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
-1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
1. Commit the changes to your local Git repository and push to your GitHub repository.
## Procedure
```text {file="netlify.toml" copy=true}
[build.environment]
- DART_SASS_VERSION = "1.97.3"
- GO_VERSION = "1.26.0"
- HUGO_VERSION = "0.156.0"
- NODE_VERSION = "24.13.1"
+ DART_SASS_VERSION = "1.98.0"
+ GO_VERSION = "1.26.1"
+ HUGO_VERSION = "0.158.0"
+ NODE_VERSION = "24.14.0"
TZ = "Europe/Oslo"
[build]
```text {file="netlify.toml" copy=true}
[build.environment]
- DART_SASS_VERSION = "1.97.3"
- GO_VERSION = "1.26.0"
- HUGO_VERSION = "0.156.0"
- NODE_VERSION = "24.13.1"
+ DART_SASS_VERSION = "1.98.0"
+ GO_VERSION = "1.26.1"
+ HUGO_VERSION = "0.158.0"
+ NODE_VERSION = "24.14.0"
TZ = "Europe/Oslo"
[build]
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
-1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
## Procedure
staticPublishPath: public
envVars:
- key: DART_SASS_VERSION
- value: 1.97.3
+ value: 1.98.0
- key: GO_VERSION
- value: 1.26.0
+ value: 1.26.1
- key: HUGO_VERSION
- value: 0.156.0
+ value: 0.158.0
- key: NODE_VERSION
- value: 24.13.1
+ value: 24.14.0
- key: TZ
value: Europe/Oslo
```
site: <YourUsername>.srht.site
tasks:
- package: |
- DART_SASS_VERSION=1.97.1 # Latest version as of 20/12/2025
+ DART_SASS_VERSION=1.98.0
mkdir -p $HOME/.local
curl -L https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64-musl.tar.gz -o dart-sass.tar.gz
tar -xzf dart-sass.tar.gz -C $HOME/.local
1. [Log in](https://github.com/login) to your GitHub account
1. [Create](https://github.com/new) a GitHub repository for your project
1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository
-1. Create a Hugo site within your local Git repository and test it with the `hugo server` command
+1. Create a Hugo project within your local Git repository and test it with the `hugo server` command
## Procedure
main() {
- DART_SASS_VERSION=1.97.3
- GO_VERSION=1.26.0
- HUGO_VERSION=0.156.0
- NODE_VERSION=24.13.1
+ DART_SASS_VERSION=1.98.0
+ GO_VERSION=1.26.1
+ HUGO_VERSION=0.158.0
+ NODE_VERSION=24.14.0
export TZ=Europe/Oslo
A `.work` file example:
```text
-go 1.24
+go 1.25
use .
use ../my-hugo-module
weight = 20
{{< /code-toggle >}}
-This example uses the `Identifier` method when querying the translation table on a multilingual site, falling back the `name` property if a matching key in the translation table does not exist:
+This example uses the `Identifier` method when querying the translation table on a multilingual project, falling back the `name` property if a matching key in the translation table does not exist:
```go-html-template
<ul>
weight = 20
{{< /code-toggle >}}
-This example uses the `KeyName` method when querying the translation table on a multilingual site, falling back the `name` property if a matching key in the translation table does not exist:
+This example uses the `KeyName` method when querying the translation table on a multilingual project, falling back the `name` property if a matching key in the translation table does not exist:
```go-html-template
<ul>
defaultContentLanguageInSubdir = true
[languages.en]
- languageCode = 'en-US'
- languageDirection = 'ltr'
- languageName = 'English'
+ locale = 'en-US'
+ direction = 'ltr'
+ name = 'English'
weight = 1
title = 'My Site in English'
[languages.de]
- languageCode = 'de-DE'
- languageDirection = 'ltr'
- languageName = 'Deutsch'
+ locale = 'de-DE'
+ direction = 'ltr'
+ name = 'Deutsch'
weight = 2
title = 'My Site in German'
---
title: AllTranslations
-description: Returns all translations of the given page, including the current language, sorted by language weight.
+description: Returns all translations of the given page, including the current language, sorted by language weight then language name.
categories: []
keywords: []
params:
[languages.en]
contentDir = 'content/en'
-languageCode = 'en-US'
-languageName = 'English'
+label = 'English'
+locale = 'en-US'
weight = 1
[languages.de]
contentDir = 'content/de'
-languageCode = 'de-DE'
-languageName = 'Deutsch'
+label = 'Deutsch'
+locale = 'de-DE'
weight = 2
[languages.fr]
contentDir = 'content/fr'
-languageCode = 'fr-FR'
-languageName = 'Français'
+label = 'Français'
+locale = 'fr-FR'
weight = 3
{{< /code-toggle >}}
<ul>
{{ range . }}
<li>
- <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a>
+ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.Locale }}">{{ .LinkTitle }} ({{ or .Language.Label .Language.Name }})</a>
</li>
{{ end }}
</ul>
---
title: GitInfo
-description: Returns Git information related to the last commit of the given page.
+description: Provides access to commit metadata for a given page.
categories: []
keywords: []
params:
signatures: [PAGE.GitInfo]
---
-The `GitInfo` method on a `Page` object returns an object with additional methods.
+The `GitInfo` method on a `Page` object provides access to commit metadata from your Git history, such as the author's name, the commit hash, and the commit message.
> [!note]
-> Hugo's Git integration is performant, but may increase build times on large sites.
+> Hugo's Git integration is performant, but may increase build times for large projects.
## Prerequisites
Install Git, create a repository, and commit your project files.
-You must also allow Hugo to access your repository. In your project configuration:
+You must also allow Hugo to access your repository by adding this to your project configuration:
{{< code-toggle file=hugo >}}
enableGitInfo = true
{{< /code-toggle >}}
-Alternatively, use the command line flag when building your project:
-
-```sh
-hugo build --enableGitInfo
-```
-
> [!note]
-> When you set `enableGitInfo` to `true`, or enable the feature with the command line flag, the last modification date for each content page will be the Author Date of the last commit for that file.
+> When you set [`enableGitInfo`][] to `true`, the last modification date for each content page will automatically be the Author Date of the last commit for that file.
>
-> This is configurable. See [details].
+> This is configurable. See [details][].
+
+## Scope
+
+Commit metadata is available for content stored in your local repository and for content provided by [modules](g).
+
+### Local content
+
+Hugo retrieves commit metadata for files tracked within your project's local repository. This includes all content files managed by Git in your main project directory.
+
+### Module content
+
+{{< new-in 0.157.0 />}}
+
+Hugo also retrieves commit metadata for content provided by modules. This allows you to display commit data for remote repositories that are mounted as content directories, such as when aggregating documentation from multiple sources.
## Methods
### AbbreviatedHash
-(`string`) The abbreviated commit hash.
+(`string`) Returns the seven-character shortened version of the commit hash.
```go-html-template
{{ with .GitInfo }}
- {{ .AbbreviatedHash }} → aab9ec0b3
+ {{ .AbbreviatedHash }} → aab9ec0
{{ end }}
```
### AuthorDate
-(`time.Time`) The author date.
+(`time.Time`) Returns the date the author originally created the commit.
```go-html-template
{{ with .GitInfo }}
### AuthorEmail
-(`string`) The author's email address, respecting [gitmailmap].
+(`string`) Returns the author's email address, respecting [gitmailmap][].
```go-html-template
{{ with .GitInfo }}
### AuthorName
-(`string`) The author's name, respecting [gitmailmap].
+(`string`) Returns the author's name, respecting [gitmailmap][].
```go-html-template
{{ with .GitInfo }}
### CommitDate
-(`time.Time`) The commit date.
+(`time.Time`) Returns the date the commit was applied to the branch.
```go-html-template
{{ with .GitInfo }}
### Hash
-(`string`) The commit hash.
+(`string`) Returns the full SHA-1 commit hash.
```go-html-template
{{ with .GitInfo }}
### Subject
-(`string`) The commit message subject.
+(`string`) Returns the first line of the commit message (the summary).
```go-html-template
{{ with .GitInfo }}
### Body
-(`string`) The commit message body.
+(`string`) Returns the full content of the commit message, excluding the subject line.
```go-html-template
{{ with .GitInfo }}
- {{ .Body }} → - Two new pages added.
+ {{ .Body }} → Two new pages added.
{{ end }}
```
### Ancestors
-(`gitmap.GitInfos`) A slice of file-filtered ancestor commits, if any, ordered from most recent to least recent.
+(`gitmap.GitInfos`) Returns a list of previous commits for this specific file, ordered from most recent to oldest.
For example, to list the last 5 commits:
### Parent
-(`*gitmap.GitInfo`) The first file-filtered ancestor commit, if any.
+(`*gitmap.GitInfo`) Returns the most recent ancestor commit for the file, if any.
## Last modified date
By default, when `enableGitInfo` is `true`, the `Lastmod` method on a `Page` object returns the Git AuthorDate of the last commit that included the file.
-You can change this behavior in your [project configuration].
+You can change this behavior in your [project configuration][].
## Hosting considerations
[^3]: To perform a deep clone when hosting on GitLab Pages, set the `GIT_DEPTH` environment variable to `0` in the workflow file. See [example](/host-and-deploy/host-on-gitlab-pages/#configure-gitlab-cicd).
+[`enableGitInfo`]: /configuration/all/#enablegitinfo
[details]: /configuration/front-matter/#dates
[gitmailmap]: https://git-scm.com/docs/gitmailmap
[project configuration]: /configuration/front-matter/
[languages.en]
contentDir = 'content/en'
-languageCode = 'en-US'
-languageName = 'English'
+label = 'English'
+locale = 'en-US'
weight = 1
[languages.de]
contentDir = 'content/de'
-languageCode = 'de-DE'
-languageName = 'Deutsch'
+label = 'Deutsch'
+locale = 'de-DE'
weight = 2
{{< /code-toggle >}}
## Methods
-The examples below assume the following in your project configuration:
+The examples below assume the following language definition.
{{< code-toggle file=hugo >}}
[languages.de]
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
weight = 2
{{< /code-toggle >}}
+### Direction
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`direction`][] from the language definition.
+
+```go-html-template
+{{ .Language.Direction }} → ltr
+```
+
### IsDefault
{{< new-in 0.153.0 />}}
{{ .Language.IsDefault }} → true
```
-### Lang
+### Label
-(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration.
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`label`][] from the language definition.
```go-html-template
-{{ .Language.Lang }} → de
+{{ .Language.Label }} → Deutsch
```
+### Lang
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Name`](#name) instead.
+
### LanguageCode
-(`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined.
+{{<deprecated-in 0.158.0 />}}
-```go-html-template
-{{ .Language.LanguageCode }} → de-DE
-```
+Use [`Locale`](#locale) instead.
### LanguageDirection
-(`string`) Returns the [`languageDirection`][] from your project configuration.
+{{<deprecated-in 0.158.0 />}}
-```go-html-template
-{{ .Language.LanguageDirection }} → ltr
-```
+Use [`Direction`](#direction) instead.
### LanguageName
-(`string`) Returns the [`languageName`][] from your project configuration.
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Label`](#label) instead.
+
+### Locale
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`locale`][] from the language definition, falling back to [`Name`](#name).
```go-html-template
-{{ .Language.LanguageName }} → Deutsch
+{{ .Language.Locale }} → de-DE
```
### Name
{{< new-in 0.153.0 />}}
-(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`.
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from the language definition.
```go-html-template
{{ .Language.Name }} → de
### Weight
-(`int`) Returns the language [`weight`][] from your project configuration.
+{{<deprecated-in 0.158.0 />}}
-```go-html-template
-{{ .Language.Weight }} → 2
-```
-
-[`languageCode`]: /configuration/languages/#languagecode
-[`languageDirection`]: /configuration/languages/#languagedirection
-[`languageName`]: /configuration/languages/#languagename
-[`weight`]: /configuration/languages/#weight
-[default language]: /quick-reference/glossary/#default-language
-[details]: /methods/page/language/
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
+[`direction`]: /configuration/languages/#direction
+[`label`]: /configuration/languages/#label
+[`locale`]: /configuration/languages/#locale
+[default language]: /quick-reference/glossary/#default-language
+[details]: /methods/site/language/
+
+## Example
+
+Use the code below to create a language selector, allowing users to navigate between the different translated versions of the current page.
+
+```go-html-template {file="layouts/_partials/language-selector.html" copy=true}
+{{ with .Rotate "language" }}
+ <nav class="language-selector">
+ <ul>
+ {{ range . }}
+ {{ if eq .Language $.Language }}
+ <li class="active">
+ <a aria-current="page" href="{{ .Permalink }}" hreflang="{{ .Language.Locale }}">{{ .Language.Label }}</a>
+ </li>
+ {{ else }}
+ <li>
+ <a href="{{ .Permalink }}" hreflang="{{ .Language.Locale }}">{{ .Language.Label }}</a>
+ </li>
+ {{ end }}
+ {{ end }}
+ </ul>
+ </nav>
+{{ end }}
+```
## Examples
-### Monolingual site
+### Monolingual project
Note that the logical path is independent of content format and URL modifiers.
signatures: [PAGE.Plain]
---
-The `Plain` method on a `Page` object renders Markdown and [shortcodes](g) to HTML, then strips the HTML [tags]. It does not strip HTML [entities].
+The `Plain` method on a `Page` object renders Markdown and [shortcodes](g) to HTML, then strips the HTML [tags][]. It does not strip HTML [entities][].
-To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function.
+To prevent Go's [`html/template`][] package from escaping HTML entities, pass the result through the [`htmlUnescape`][] function.
```go-html-template
{{ .Plain | htmlUnescape }}
```
-[html/template]: https://pkg.go.dev/html/template
+[`html/template`]: https://pkg.go.dev/html/template
[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag
[`htmlUnescape`]: /functions/transform/htmlunescape/
{{ printf "Estimated reading time: %d minutes" .ReadingTime }}
```
-Reading speed varies by language. Create language-specific estimated reading times on your multilingual site using site parameters.
+Reading speed varies by language. Create language-specific estimated reading times on your multilingual project using site parameters.
{{< code-toggle file=hugo >}}
[languages]
[languages.de]
contentDir = 'content/de'
- languageCode = 'de-DE'
- languageName = 'Deutsch'
+ label = 'Deutsch'
+ locale = 'de-DE'
weight = 2
[languages.de.params]
reading_speed = 179
[languages.en]
contentDir = 'content/en'
- languageCode = 'en-US'
- languageName = 'English'
+ label = 'English'
+ locale = 'en-US'
weight = 1
[languages.en.params]
reading_speed = 228
---
title: Sitemap
-description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in the site configuration.
+description: Returns the sitemap settings for the given page as defined in front matter, falling back to the sitemap settings as defined in your project configuration.
categories: []
keywords: []
params:
---
{{< deprecated-in 0.156.0 >}}
-Use [`hugo.Sites`] instead.
-
-[`hugo.Sites`]: /functions/hugo/sites/
+Use [`hugo.Sites`](/functions/hugo/sites/) instead.
{{< /deprecated-in >}}
-
-{{% include "/_common/functions/hugo/sites-collection.md" %}}
-
-With this project configuration:
-
-{{< code-toggle file=hugo >}}
-defaultContentLanguage = 'de'
-defaultContentLanguageInSubdir = true
-defaultContentVersionInSubdir = true
-
-[languages.de]
-contentDir = 'content/de'
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
-title = 'Projekt Dokumentation'
-weight = 1
-
-[languages.en]
-contentDir = 'content/en'
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
-title = 'Project Documentation'
-weight = 2
-
-[versions.'v1.0.0']
-[versions.'v2.0.0']
-[versions.'v3.0.0']
-{{< /code-toggle >}}
-
-This template:
-
-```go-html-template
-<ul>
- {{ range .Sites }}
- <li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
- {{ end }}
-</ul>
-```
-
-Produces a list of links to each home page:
-
-```html
-<ul>
- <li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
- <li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
- <li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
- <li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
- <li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
- <li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
-</ul>
-```
-
-To render a link to the home page of the [default site](g):
-
-```go-html-template
-{{ with .Sites.Default }}
- <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
-{{ end }}
-```
-
-This is equivalent to:
-
-```go-html-template
-{{ with index .Sites 0 }}
- <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
-{{ end }}
-```
[languages.en]
contentDir = 'content/en'
-languageCode = 'en-US'
-languageName = 'English'
+label = 'English'
+locale = 'en-US'
weight = 1
[languages.de]
contentDir = 'content/de'
-languageCode = 'de-DE'
-languageName = 'Deutsch'
+label = 'Deutsch'
+locale = 'de-DE'
weight = 2
{{< /code-toggle >}}
---
title: Translations
-description: Returns all translations of the given page, excluding the current language, sorted by language weight.
+description: Returns all translations of the given page, excluding the current language, sorted by language weight then language name.
categories: []
keywords: []
params:
[languages.en]
contentDir = 'content/en'
-languageCode = 'en-US'
-languageName = 'English'
+label = 'English'
+locale = 'en-US'
weight = 1
[languages.de]
contentDir = 'content/de'
-languageCode = 'de-DE'
-languageName = 'Deutsch'
+label = 'Deutsch'
+locale = 'de-DE'
weight = 2
[languages.fr]
contentDir = 'content/fr'
-languageCode = 'fr-FR'
-languageName = 'Français'
+label = 'Français'
+locale = 'fr-FR'
weight = 3
{{< /code-toggle >}}
<ul>
{{ range . }}
<li>
- <a href="{{ .RelPermalink }}" hreflang="{{ .Language.LanguageCode }}">{{ .LinkTitle }} ({{ or .Language.LanguageName .Language.Lang }})</a>
+ <a href="{{ .RelPermalink }}" hreflang="{{ .Language.Locale }}">{{ .LinkTitle }} ({{ or .Language.Label .Language.Name }})</a>
</li>
{{ end }}
</ul>
+++ /dev/null
----
-title: PageSize
-description: Returns the number of pages per pager.
-categories: []
-keywords: []
-params:
- functions_and_methods:
- returnType: int
- signatures: [PAGER.PageSize]
-expiryDate: 2026-06-09 # deprecated 2024-06-09 in v0.128.0
----
-
-{{< deprecated-in 0.128.0 >}}
-Use [`PAGER.PagerSize`] instead.
-
-[`PAGER.PagerSize`]: /methods/pager/pagersize/
-{{< /deprecated-in >}}
functions_and_methods:
returnType: int
signatures: [PAGER.PagerSize]
+aliases: [/methods/pager/pagesize/]
---
-{{< new-in 0.128.0 />}}
-
The number of pages per pager is determined by the optional second argument passed to the [`Paginate`] method, falling back to the `pagerSize` as defined in your [project configuration].
[`Paginate`]: /methods/page/paginate/
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-The `Colors` method on a `Resource` image object returns a slice of the most dominant colors in an image, ordered from most dominant to least dominant. This method is fast, but if you also downsize your image you can improve performance by extracting the colors from the scaled image.
+The `Colors` method returns a slice of the most dominant colors in a [processable image](g), ordered from most dominant to least dominant.
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+This method is fast, but if you downscale your image first, you can further improve performance by extracting colors from the smaller resource.
## Methods
-Each color is an object with the following methods:
+Each color in the slice is an object with the following methods:
### ColorHex
-(`string`) Returns the [hexadecimal color] value, prefixed with a hash sign.
+(`string`) Returns the [hexadecimal color][] value, prefixed with a hash sign.
### Luminance
-(`float64`) Returns the [relative luminance] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.
+(`float64`) Returns the [relative luminance][] of the color in the sRGB colorspace in the range [0, 1]. A value of `0` represents the darkest black, while a value of `1` represents the lightest white.
> [!note]
-> Image filters such as [`images.Dither`], [`images.Padding`], and [`images.Text`] accept either hexadecimal color values or `images.Color` objects as arguments.
->
-> Hugo renders an `images.Color` object as a hexadecimal color value.
+> Image filters such as [`images.Dither`][], [`images.Padding`][], and [`images.Text`][] accept either hexadecimal color values or `images.Color` objects as arguments. Hugo renders an `images.Color` object as a hexadecimal color value.
## Sorting
### WCAG contrast ratio
-In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG] guidelines for either the [minimum] or the [enhanced] contrast ratio?
+In the previous example we placed light text on a dark background, but does this color combination conform to [WCAG][] guidelines for either the [minimum][] or the [enhanced][] contrast ratio?
-The WCAG defines the [contrast ratio] as:
+The WCAG defines the [contrast ratio][] as:
$$contrast\ ratio = { L_1 + 0.05 \over L_2 + 0.05 }$$
-where $L_1$ is the relative luminance of the lightest color and $L_2$ is the relative luminance of the darkest color.
+where \(L_1\) is the relative luminance of the lightest color and \(L_2\) is the relative luminance of the darkest color.
Calculate the contrast ratio to determine WCAG conformance:
{{ end }}
```
+[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
[`images.Dither`]: /functions/images/dither/
[`images.Padding`]: /functions/images/padding/
[`images.Text`]: /functions/images/text/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
[minimum]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-minimum
[relative luminance]: https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
-[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Crop an image according to the given [processing specification][]. When cropping, you must provide both width and height (such as `200x200`) within the specification. This method does not perform any resizing; it simply extracts a region of the image based on the dimensions and the [anchor](#anchor) provided, if any.
+The `Crop` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+When cropping, you must provide both width and height (such as `200x200`) within the specification. This method does not perform any resizing; it simply extracts a region of the image based on the dimensions and the [anchor](#anchor) provided, if any.
```go-html-template
{{ with resources.Get "images/original.jpg" }}
{{ end }}
```
-In the example above, `"200x200 TopRight"` is the _processing specification_.
+In the example above, `"200x200 TopRight"` is the processing specification.
{{% include "/_common/methods/resource/processing-spec.md" %}}
example=true
>}}
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
[processing specification]: #processing-specification
[example]: /functions/go-template/try/#example
{{< /deprecated-in >}}
-
-The `Err` method on a resource returned by the [`resources.GetRemote`] function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build.
-
-[`resources.GetRemote`]: /functions/resources/getremote/
-
-In this example we send an HTTP request to a nonexistent domain:
-
-```go-html-template
-{{ $url := "https://broken-example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
- {{ with .Err }}
- {{ errorf "%s" . }}
- {{ else }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
- {{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
-{{ end }}
-```
-
-The code above captures the error from the HTTP request, then fails the build:
-
-```text
-ERROR error calling resources.GetRemote: Get "https://broken-example.org/images/a.jpg": dial tcp: lookup broken-example.org on 127.0.0.53:53: no such host
-```
-
-To log an error as a warning instead of an error:
-
-```go-html-template
-{{ $url := "https://broken-example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
- {{ with .Err }}
- {{ warnf "%s" . }}
- {{ else }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
- {{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
-{{ end }}
-```
-
-> [!note]
-> An HTTP response with a 404 status code is not an HTTP request error. To handle 404 status codes, code defensively using the nested `with-else-end` construct as shown above.
---
title: Exif
-description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif metadata.
+description: Returns an object containing Exif metadata for supported image formats.
categories: []
keywords: ['metadata']
params:
functions_and_methods:
returnType: meta.ExifInfo
signatures: [RESOURCE.Exif]
+expiryDate: 2028-01-28 # deprecated 2026-01-28 in v0.155.0
---
-{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-
-Applicable to JPEG, PNG, TIFF, and WebP images, the `Exif` method on an image `Resource` object returns an object containing [Exif][Exif_Definition] metadata.
-
-To extract [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata, use the [`Meta`] method instead.
-
-> [!note]
-> Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from JPEG, PNG, TIFF, and WebP images.
-
-## Methods
-
-### Date
-
-(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function.
-
-### Lat
-
-(`float64`) Returns the GPS latitude in degrees from Exif metadata.
-
-### Long
-
-(`float64`) Returns the GPS longitude in degrees from Exif metadata.
-
-### Tags
-
-(`meta.Tags`) Returns a collection of available Exif fields for this image. Availability is determined by the [`includeFields`][] and [`excludeFields`][] settings in your project configuration.
-
-## Examples
-
-To list the creation date, latitude, and longitude:
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ with .Exif }}
- <pre>
- {{ printf "%-25s %v\n" "Date" .Date }}
- {{ printf "%-25s %v\n" "Latitude" .Lat }}
- {{ printf "%-25s %v\n" "Longitude" .Long }}
- </pre>
- {{ end }}
-{{ end }}
-```
-
-To list the available Exif fields:
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ with .Exif }}
- <pre>
- {{ range $k, $v := .Tags -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
- {{ end }}
-{{ end }}
-```
-
-To list specific Exif fields:
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ with .Exif }}
- <pre>
- {{ with .Tags.ApertureValue }}{{ printf "%-25s %v\n" "ApertureValue" . }}{{ end }}
- {{ with .Tags.BrightnessValue }}{{ printf "%-25s %v\n" "BrightnessValue" . }}{{ end }}
- </pre>
- {{ end }}
-{{ end }}
-```
-
-[`excludeFields`]: /configuration/imaging/#excludefields
-[`includeFields`]: /configuration/imaging/#includefields
-[`Meta`]: /methods/resource/meta/
-[`time.Format`]: /functions/time/format/
-[Exif_Definition]: https://en.wikipedia.org/wiki/Exif
-[IPTC_Definition]: https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model
-[XMP_Definition]: https://en.wikipedia.org/wiki/Extensible_Metadata_Platform
+{{< deprecated-in 0.155.0 >}}
+Use [`Meta`](/methods/resource/meta/) instead.
+{{< /deprecated-in >}}
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Crop and resize an image according to the given [processing specification][]. You must provide both width and height (such as `500x200`) within the specification. Unlike [`Resize`][], which may stretch the image, `Fill` maintains the original aspect ratio by cropping the image to the target ratio before resizing. The operation uses the [anchor](#anchor) and [resampling filter](#resampling-filter) provided, if any.
+The `Fill` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+When filling, you must provide both width and height (such as `500x200`) within the specification. `Fill` maintains the original aspect ratio by resizing the image to cover the target area and cropping any overflowing pixels based on the [anchor](#anchor) provided.
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Fill "500x200 TopRight lanczos" }}
+ {{ with .Fill "500x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```
-In the example above, `"500x200 TopRight lanczos"` is the _processing specification_.
+In the example above, `"500x200 TopRight"` is the _processing specification.
{{% include "/_common/methods/resource/processing-spec.md" %}}
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Fill "500x200 TopRight lanczos webp q85" }}
+ {{ with .Fill "500x200 TopRight" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
src="images/examples/zion-national-park.jpg"
alt="Zion National Park"
filter="Process"
- filterArgs="fill 500x200 TopRight lanczos webp q85"
+ filterArgs="fill 500x200 TopRight"
example=true
>}}
-[`Resize`]: /methods/resource/resize/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
[processing specification]: #processing-specification
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Apply one or more [image filters](#image-filters) to the given image.
+The `Filter` method returns a new resource from a [processable image](g) after applying one or more [image filters](#image-filters).
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+Use the `Filter` method to apply effects such as blurring, sharpening, or grayscale conversion. You can pass a single filter or a slice of filters. When providing a slice, Hugo applies the filters from left to right.
To apply a single filter:
{{ end }}
```
-To apply two or more filters, executing from left to right:
+To apply multiple filters:
```go-html-template
{{ $filters := slice
{{ end }}
```
-You can also apply image filters using the [`images.Filter`] function.
-
-[`images.Filter`]: /functions/images/filter/
+You can also apply image filters using the [`images.Filter`][] function.
## Example
Use any of these filters with the `Filter` method.
-{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
+{{% render-list-of-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
+
+[`images.Filter`]: /functions/images/filter/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Downscale an image to fit according to the given [processing specification][] while maintaining the aspect ratio. You must provide both width and height (such as `600x400`) within the specification. Unlike [`Fill`][] or [`Resize`][], this method will never upscale an image; if the source image is smaller than the target dimensions, it remains its original size. The operation uses the [resampling filter](#resampling-filter) provided, if any.
+The `Fit` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+When fitting, you must provide both width and height (such as `300x175`) within the specification. `Fit` maintains the original aspect ratio by downscaling the image until it fits within the specified dimensions. Unlike [`Fill`][] or [`Resize`][], this method will never upscale an image; if the source image is smaller than the target dimensions, the dimensions of the resulting image are the same as the original.
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Fit "300x175 lanczos" }}
+ {{ with .Fit "300x175" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```
-In the example above, `"300x175 lanczos"` is the _processing specification_.
+In the example above, `"300x175"` is the processing specification.
{{% include "/_common/methods/resource/processing-spec.md" %}}
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Fit "300x175 lanczos" }}
+ {{ with .Fit "300x175" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
src="images/examples/zion-national-park.jpg"
alt="Zion National Park"
filter="Process"
- filterArgs="fit 300x175 lanczos"
+ filterArgs="fit 300x175"
example=true
>}}
-[`Resize`]: /methods/resource/resize/
[`Fill`]: /methods/resource/fill/
+[`Resize`]: /methods/resource/resize/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
[processing specification]: #processing-specification
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ .Height }} → 400
-{{ end }}
-```
-
-Use the `Width` and `Height` methods together when rendering an `img` element:
+Use the [`reflect.IsImageResourceWithMeta`][] function to verify that Hugo can determine the dimensions before calling the `Height` method.
```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ with resources.GetMatch "images/featured.*" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ <img src="{{ .RelPermalink }}" alt="">
+ {{ end }}
{{ end }}
```
+
+[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
---
title: Meta
-description: Applicable to JPEG, PNG, TIFF, and WebP images, returns an object containing Exif, IPTC, and XMP metadata.
+description: Applicable to images, returns an object containing Exif, IPTC, and XMP metadata for supported image formats.
categories: []
keywords: ['metadata']
params:
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Applicable to JPEG, PNG, TIFF, and WebP images, the `Meta` method on an image `Resource` object returns an object containing [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata.
+The `Meta` method on an image `Resource` object returns an object containing [Exif][Exif_Definition], [IPTC][IPTC_Definition], and [XMP][XMP_Definition] metadata.
-To extract Exif metadata only, use the [`Exif`] method instead.
+While Hugo classifies many file types as images, only certain formats support metadata extraction. Supported formats include AVIF, BMP, GIF, HEIC, HEIF, JPEG, PNG, TIFF, and WebP.
> [!note]
-> Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from JPEG, PNG, TIFF, and WebP images.
+> Metadata is not preserved during image transformation. Use this method with the _original_ image resource to extract metadata from supported formats.
+
+## Usage
+
+Use the [`reflect.IsImageResourceWithMeta`][] function to verify that a resource supports metadata extraction before calling the `Meta` method.
+
+```go-html-template
+{{ with resources.GetMatch "images/featured.*" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ {{ with .Meta }}
+ {{ .Date.Format "2006-01-02" }}
+ {{ end }}
+ {{ end }}
+{{ end }}
+```
## Methods
### Date
-(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`] function.
+(`time.Time`) Returns the image creation date/time. Format with the [`time.Format`][] function.
### Lat
### Orientation
-(`int`) Returns the value of the Exif `Orientation` tag, one of eight possible values:
+(`int`) Returns the value of the Exif `Orientation` tag, one of eight possible values.
Value|Description
:--|:--
{class="!mt-0"}
> [!tip]
-> Use the [`images.AutoOrient`] image filter to rotate and flip an image as needed per its Exif orientation tag
+> Use the [`images.AutoOrient`][] image filter to rotate and flip an image as needed per its Exif orientation tag
### Exif
To list the creation date, latitude, longitude, and orientation:
```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ printf "%-25s %v\n" "Date" .Date }}
- {{ printf "%-25s %v\n" "Latitude" .Lat }}
- {{ printf "%-25s %v\n" "Longitude" .Long }}
- {{ printf "%-25s %v\n" "Orientation" .Orientation }}
- </pre>
- {{ end }}
-{{ end }}
-```
-
-To list the available Exif fields:
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ range $k, $v := .Exif -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
- {{ end }}
-{{ end }}
-```
-
-To list the available IPTC fields:
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ range $k, $v := .IPTC -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
- {{ end }}
-{{ end }}
-```
-
-To list the available XMP fields:
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ range $k, $v := .XMP -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
- {{ end }}
-{{ end }}
-```
-
-To list the available Exif, IPTC, and XMP fields together:
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ range $k, $v := merge .Exif .IPTC .XMP -}}
- {{ printf "%-25s %v\n" $k $v }}
- {{ end }}
- </pre>
+{{ with resources.GetMatch "images/featured.*" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ {{ with .Meta }}
+ <pre>
+ {{ printf "%-25s %v\n" "Date" .Date }}
+ {{ printf "%-25s %v\n" "Latitude" .Lat }}
+ {{ printf "%-25s %v\n" "Longitude" .Long }}
+ {{ printf "%-25s %v\n" "Orientation" .Orientation }}
+ </pre>
+ {{ end }}
{{ end }}
{{ end }}
```
-To list specific values:
-
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ with .Meta }}
- <pre>
- {{ with .Exif.ApertureValue }}{{ printf "%-25s %v\n" "ApertureValue" . }}{{ end }}
- {{ with .Exif.BrightnessValue }}{{ printf "%-25s %v\n" "BrightnessValue" . }}{{ end }}
-
- {{ with .IPTC.Headline }}{{ printf "%-25s %v\n" "Headline" . }}{{ end }}
- {{ with index .IPTC "Province-State" }}{{ printf "%-25s %v\n" "Province-State" . }}{{ end }}
-
- {{ with .XMP.Creator }}{{ printf "%-25s %v\n" "Creator" . }}{{ end }}
- {{ with .XMP.Subject }}{{ printf "%-25s %v\n" "Subject" . }}{{ end }}
- </pre>
- {{ end }}
-{{ end }}
-```
+{{% include "/_common/functions/reflect/image-reflection-functions.md" %}}
-[`Exif`]: /methods/resource/exif/
[`fields`]: /configuration/imaging/#fields
[`images.AutoOrient`]: /functions/images/autoorient/
+[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
[`sources`]: /configuration/imaging/#sources
[`time.Format`]: /functions/time/format/
[Exif_Definition]: https://en.wikipedia.org/wiki/Exif
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Process an image according to the given [processing specification][]. This versatile method supports the full range of image transformations, including resizing, cropping, rotation, and format conversion, all within a single specification string.
+The `Process` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+This versatile method supports the full range of image transformations including resizing, cropping, rotation, and format conversion within a single specification string. Unlike specialized methods such as [`Resize`][] or [`Crop`][], you must explicitly include the [action](#action) in the specification if you are changing the image dimensions.
```go-html-template
{{ with resources.Get "images/original.jpg" }}
{{ end }}
```
-In the example above, `"crop 200x200 TopRight webp q50"` is the _processing specification_.
+In the example above, `"crop 200x200 TopRight webp q50"` is the processing specification.
You can also use this method to apply simple transformations such as rotation and conversion:
{{ $image := $image.Process "webp" }}
```
-The `Process` method is also available as a filter, which is more effective if you need to apply multiple filters to an image. See [`images.Process`].
+The `Process` method is also available as a filter. This is more effective if you need to apply multiple filters to an image. See [`images.Process`][].
{{% include "/_common/methods/resource/processing-spec.md" %}}
example=true
>}}
+[`Crop`]: /methods/resource/crop/
+[`Resize`]: /methods/resource/resize/
[`images.Process`]: /functions/images/process/
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
[processing specification]: #processing-specification
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-Resize an image according to the given [processing specification][]. You may specify only the width (such as `300x`) or only the height (`such as x150`) for proportional scaling. If you specify both width and height (such as `300x150`), the resulting image will be scaled to those exact dimensions; if the aspect ratio differs from the original, the image will be non-proportionally scaled (stretched or squashed). The operation uses the [resampling filter](#resampling-filter) provided, if any.
+The `Resize` method returns a new resource from a [processable image](g) according to the given [processing specification][].
+
+> [!note]
+> Use the [`reflect.IsImageResourceProcessable`][] function to verify that an image can be processed.
+
+## Usage
+
+Resize an image according to the given processing specification. You may specify only the width (such as `300x`) or only the height (such as `x150`) for proportional scaling.
+
+If you specify both width and height (such as `300x150`), the resulting image will be scaled to those exact dimensions. If the target aspect ratio differs from the original, the image will be non-proportionally scaled (stretched or squashed).
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Resize "300x lanczos" }}
+ {{ with .Resize "300x" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```
-In the example above, `"300x lanczos"` is the _processing specification_.
+In the example above, `"300x"` is the processing specification.
{{% include "/_common/methods/resource/processing-spec.md" %}}
```go-html-template
{{ with resources.Get "images/original.jpg" }}
- {{ with .Resize "300x lanczos" }}
+ {{ with .Resize "300x" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
src="images/examples/zion-national-park.jpg"
alt="Zion National Park"
filter="Process"
- filterArgs="resize 300x lanczos"
+ filterArgs="resize 300x"
example=true
>}}
+[`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
[processing specification]: #processing-specification
{{% include "/_common/methods/resource/global-page-remote-resources.md" %}}
-```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- {{ .Width }} → 600
-{{ end }}
-```
-
-Use the `Width` and `Height` methods together when rendering an `img` element:
+Use the [`reflect.IsImageResourceWithMeta`][] function to verify that Hugo can determine the dimensions before calling the `Width` method.
```go-html-template
-{{ with resources.Get "images/a.jpg" }}
- <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+{{ with resources.GetMatch "images/featured.*" }}
+ {{ if reflect.IsImageResourceWithMeta . }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ <img src="{{ .RelPermalink }}" alt="">
+ {{ end }}
{{ end }}
```
+
+[`reflect.IsImageResourceWithMeta`]: /functions/reflect/isimageresourcewithmeta/
{{< deprecated-in 0.156.0 >}}
See [details](https://discourse.gohugo.io/t/56732).
{{< /deprecated-in >}}
-
-This method returns all page [kinds](g) in all languages, in the [default sort order](g). That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
-
-In most cases you should use the [`RegularPages`] method instead.
-
-[`RegularPages`]: /methods/site/regularpages/
-
-```go-html-template
-{{ range .Site.AllPages }}
- <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
-{{ end }}
-```
{{< deprecated-in 0.156.0 >}}
See [details](https://discourse.gohugo.io/t/56732).
{{< /deprecated-in >}}
-
-By default, draft pages are not published when building a site. You can change this behavior with a command line flag:
-
-```sh
-hugo build --buildDrafts
-```
-
-Or by setting `buildDrafts` to `true` in your project configuration:
-
-{{< code-toggle file=hugo >}}
-buildDrafts = true
-{{< /code-toggle >}}
-
-Use the `BuildDrafts` method on a `Site` object to determine the current configuration:
-
-```go-html-template
-{{ .Site.BuildDrafts }} → true
-```
{{< deprecated-in 0.156.0 >}}
Use [`hugo.Data`](/functions/hugo/data/) instead.
{{< /deprecated-in >}}
-
-Use the `Data` method on a `Site` object to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML.
-
-> [!note]
-> Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method.
-
-Consider this `data` directory:
-
-```text
-data/
-├── books/
-│ ├── fiction.yaml
-│ └── nonfiction.yaml
-├── films.json
-├── paintings.xml
-└── sculptures.toml
-```
-
-And these data files:
-
-```yaml {file="data/books/fiction.yaml"}
-- title: The Hunchback of Notre Dame
- author: Victor Hugo
- isbn: 978-0140443530
-- title: Les Misérables
- author: Victor Hugo
- isbn: 978-0451419439
-```
-
-```yaml {file="data/books/nonfiction.yaml"}
-- title: The Ancien Régime and the Revolution
- author: Alexis de Tocqueville
- isbn: 978-0141441641
-- title: Interpreting the French Revolution
- author: François Furet
- isbn: 978-0521280495
-```
-
-Access the data by [chaining](g) the [identifiers](g):
-
-```go-html-template
-{{ range $category, $books := .Site.Data.books }}
- <p>{{ $category | title }}</p>
- <ul>
- {{ range $books }}
- <li>{{ .title }} ({{ .isbn }})</li>
- {{ end }}
- </ul>
-{{ end }}
-```
-
-Hugo renders this to:
-
-```html
-<p>Fiction</p>
-<ul>
- <li>The Hunchback of Notre Dame (978-0140443530)</li>
- <li>Les Misérables (978-0451419439)</li>
-</ul>
-<p>Nonfiction</p>
-<ul>
- <li>The Ancien Régime and the Revolution (978-0141441641)</li>
- <li>Interpreting the French Revolution (978-0521280495)</li>
-</ul>
-```
-
-To limit the listing to fiction, and sort by title:
-
-```go-html-template
-<ul>
- {{ range sort .Site.Data.books.fiction "title" }}
- <li>{{ .title }} ({{ .author }})</li>
- {{ end }}
-</ul>
-```
-
-To find a fiction book by ISBN:
-
-```go-html-template
-{{ range where .Site.Data.books.fiction "isbn" "978-0140443530" }}
- <li>{{ .title }} ({{ .author }})</li>
-{{ end }}
-```
-
-In the template examples above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function. For example:
-
-```go-html-template
-{{ index .Site.Data.books "historical-fiction" }}
-```
-
-[`index`]: /functions/collections/indexfunction/
-[`transform.Unmarshal`]: /functions/transform/unmarshal/
-[mounted]: /configuration/module/#mounts
To get a page from a different language, query the `Sites` object:
```go-html-template
-{{ with where hugo.Sites "Language.Lang" "eq" "de" }}
+{{ with where hugo.Sites "Language.Name" "eq" "de" }}
{{ with index . 0 }}
{{ with .GetPage "/works/paintings/starry-night" }}
{{ .Title }} → Sternenklare Nacht
{{< code-toggle file=hugo >}}
[languages.de]
contentDir = 'content/de'
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
title = 'Projekt Dokumentation'
weight = 1
[languages.en]
contentDir = 'content/en'
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
title = 'Project Documentation'
weight = 2
## Methods
-The examples below assume the following in your project configuration:
+The examples below assume the following language definition.
{{< code-toggle file=hugo >}}
[languages.de]
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
-weight = 1
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
+weight = 2
{{< /code-toggle >}}
+### Direction
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`direction`][] from the language definition.
+
+```go-html-template
+{{ .Site.Language.Direction }} → ltr
+```
+
### IsDefault
{{< new-in 0.153.0 />}}
{{ .Site.Language.IsDefault }} → true
```
-### Lang
+### Label
-(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration.
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`label`][] from the language definition.
```go-html-template
-{{ .Site.Language.Lang }} → de
+{{ .Site.Language.Label }} → Deutsch
```
+### Lang
+
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Name`](#name) instead.
+
### LanguageCode
-(`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined.
+{{<deprecated-in 0.158.0 />}}
-```go-html-template
-{{ .Site.Language.LanguageCode }} → de-DE
-```
+Use [`Locale`](#locale) instead.
### LanguageDirection
-(`string`) Returns the [`languageDirection`][] from your project configuration.
+{{<deprecated-in 0.158.0 />}}
-```go-html-template
-{{ .Site.Language.LanguageDirection }} → ltr
-```
+Use [`Direction`](#direction) instead.
### LanguageName
-(`string`) Returns the [`languageName`][] from your project configuration.
+{{<deprecated-in 0.158.0 />}}
+
+Use [`Label`](#label) instead.
+
+### Locale
+
+{{< new-in 0.158.0 />}}
+
+(`string`) Returns the [`locale`][] from the language definition, falling back to [`Name`](#name).
```go-html-template
-{{ .Site.Language.LanguageName }} → Deutsch
+{{ .Site.Language.Locale }} → de-DE
```
### Name
{{< new-in 0.153.0 />}}
-(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`.
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from the language definition.
```go-html-template
{{ .Site.Language.Name }} → de
### Weight
-(`int`) Returns the language [`weight`][] from your project configuration.
-
-```go-html-template
-{{ .Site.Language.Weight }} → 1
-```
+{{<deprecated-in 0.158.0 />}}
## Example
```go-html-template
<html
- lang="{{ .Site.Language.LanguageCode }}"
- dir="{{ or .Site.Language.LanguageDirection `ltr` }}"
+ lang="{{ .Site.Language.Locale }}"
+ dir="{{ or .Site.Language.Direction `ltr` }}"
>
```
-[`languageCode`]: /configuration/languages/#languagecode
-[`languageDirection`]: /configuration/languages/#languagedirection
-[`languageName`]: /configuration/languages/#languagename
-[`weight`]: /configuration/languages/#weight
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
+[`direction`]: /configuration/languages/#direction
+[`label`]: /configuration/languages/#label
+[`locale`]: /configuration/languages/#locale
[default language]: /quick-reference/glossary/#default-language
[details]: /methods/page/language/
-[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
defaultContentLanguageInSubdir = false
[languages.de]
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
+direction = 'ltr'
+label = 'Deutsch'
+locale = 'de-DE'
title = 'Projekt Dokumentation'
weight = 1
[languages.en]
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
+direction = 'ltr'
+label = 'English'
+locale = 'en-US'
title = 'Project Documentation'
weight = 2
{{< /code-toggle >}}
{{ .Site.LanguagePrefix }} → /de
```
-You may use the `LanguagePrefix` method with both monolingual and multilingual sites.
+You may use the `LanguagePrefix` method with both monolingual and multilingual projects.
{{< deprecated-in 0.156.0 >}}
See [details](https://discourse.gohugo.io/t/56732).
{{< /deprecated-in >}}
-
-The `Languages` method on a `Site` object returns a collection of language objects for all sites, ordered by language weight. Each language object points to its language definition in your project configuration.
-
-To inspect the data structure:
-
-```go-html-template
-<pre>{{ debug.Dump .Site.Languages }}</pre>
-```
-
-With this project configuration:
-
-{{< code-toggle file=hugo >}}
-defaultContentLanguage = 'de'
-defaultContentLanguageInSubdir = false
-
-[languages.de]
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
-title = 'Projekt Dokumentation'
-weight = 1
-
-[languages.en]
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
-title = 'Project Documentation'
-weight = 2
-{{< /code-toggle >}}
-
-This template:
-
-```go-html-template
-<ul>
- {{ range .Site.Languages }}
- <li>{{ .Title }} ({{ .LanguageName }})</li>
- {{ end }}
-</ul>
-```
-
-Is rendered to:
-
-```html
-<ul>
- <li>Projekt Dokumentation (Deutsch)</li>
- <li>Project Documentation (English)</li>
-</ul>
-```
---
{{< deprecated-in 0.156.0 >}}
-Use [`hugo.Sites`] instead.
-
-[`hugo.Sites`]: /functions/hugo/sites/
+Use [`hugo.Sites`](/functions/hugo/sites/) instead.
{{< /deprecated-in >}}
-
-{{% include "/_common/functions/hugo/sites-collection.md" %}}
-
-With this project configuration:
-
-{{< code-toggle file=hugo >}}
-defaultContentLanguage = 'de'
-defaultContentLanguageInSubdir = true
-defaultContentVersionInSubdir = true
-
-[languages.de]
-contentDir = 'content/de'
-languageCode = 'de-DE'
-languageDirection = 'ltr'
-languageName = 'Deutsch'
-title = 'Projekt Dokumentation'
-weight = 1
-
-[languages.en]
-contentDir = 'content/en'
-languageCode = 'en-US'
-languageDirection = 'ltr'
-languageName = 'English'
-title = 'Project Documentation'
-weight = 2
-
-[versions.'v1.0.0']
-[versions.'v2.0.0']
-[versions.'v3.0.0']
-{{< /code-toggle >}}
-
-This template:
-
-```go-html-template
-<ul>
- {{ range .Site.Sites }}
- <li><a href="{{ .Home.RelPermalink }}">{{ .Title }} {{ .Version.Name }}</a></li>
- {{ end }}
-</ul>
-```
-
-Produces a list of links to each home page:
-
-```html
-<ul>
- <li><a href="/v3.0.0/de/">Projekt Dokumentation v3.0.0</a></li>
- <li><a href="/v2.0.0/de/">Projekt Dokumentation v2.0.0</a></li>
- <li><a href="/v1.0.0/de/">Projekt Dokumentation v1.0.0</a></li>
- <li><a href="/v3.0.0/en/">Project Documentation v3.0.0</a></li>
- <li><a href="/v2.0.0/en/">Project Documentation v2.0.0</a></li>
- <li><a href="/v1.0.0/en/">Project Documentation v1.0.0</a></li>
-</ul>
-```
-
-To render a link to the home page of the [default site](g):
-
-```go-html-template
-{{ with .Site.Sites.Default }}
- <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
-{{ end }}
-```
-
-This is equivalent to:
-
-```go-html-template
-{{ with index .Site.Sites 0 }}
- <a href="{{ .Home.RelPermalink }}">{{ .Title }}</a>
-{{ end }}
-```
--- /dev/null
+---
+title: interleave
+---
+
+To _interleave_ (verb) is to insert a string at the beginning, the end, and between every character of another string.
reference: /configuration/module
---
-A _mount_ is a configuration object that maps a file system path (source) to a [_component_](g) path (target) within Hugo's [_unified file system_](g).
+A _mount_ is a configuration object that maps a file path (source) to a [_component_](g) path (target) within Hugo's [_unified file system_](g).
A _processable image_ is an image file characterized by one of the following [_media types_](g):
+ - `image/bmp`
- `image/gif`
- `image/jpeg`
- `image/png`
- `image/tiff`
- `image/webp`
- Hugo can decode and encode these image formats, allowing you to use any of the [resource methods][] applicable to images such as `Width`, `Height`, `Crop`, `Fill`, `Fit`, `Resize`, etc.
+ Hugo can decode and encode these image formats, allowing you to use any of the [resource methods][] applicable to images such as `Width`, `Height`, `Crop`, `Fill`, `Fit`, `Filter`, `Process`, `Resize`, etc.
+ Use the [`reflect.IsImageResourceProcessable`][] function to determine if an image can be processed.
+
+ [`reflect.IsImageResourceProcessable`]: /functions/reflect/isimageresourceprocessable/
[resource methods]: /methods/resource
---
title: segment
+params:
+ reference: /configuration/segments/
---
A _segment_ is a subset of a site, filtered by [_logical path_](g), [_sites matrix_](g), [_page kind_](g), or [_output format_](g).
title: unified file system
---
-Hugo's _unified file system_ provides a layered view for each of its seven [_component_](g) types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files. Project component directories are layered over [_module_](g) component directories. Hugo searches these layers in order to locate files.
+Hugo's _unified file system_ provides a layered view for each of its seven [_component_](g) types: [_archetypes_](g), assets, content, data, templates, [_translation tables_](g), and static files. Project component directories are layered over [_module_](g) component directories. When multiple layers contain the same file, Hugo uses the version from the highest layer.
Use these `Page` methods when rendering lists on [section pages](g), [taxonomy pages](g), [term pages](g), and the home page.
-{{% list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=PAGE. %}}
+{{% render-list-of-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=PAGE. %}}
## Site
Use these `Site` methods when rendering lists on any page.
-{{% list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=SITE. %}}
+{{% render-list-of-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=SITE. %}}
## Filter
-Use the [`where`] function to filter page collections.
+Use the [`where`][] function to filter page collections.
## Sort
Use these methods to sort page collections by different criteria.
-{{% list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. titlePrefix=PAGES. %}}
+{{% render-list-of-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. titlePrefix=PAGES. %}}
## Group
Use these methods to group page collections.
-{{% list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. titlePrefix=PAGES. %}}
+{{% render-list-of-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. titlePrefix=PAGES. %}}
[`where`]: /functions/collections/where/
useEmbedded = 'auto'
{{< /code-toggle >}}
-When set to `auto` as shown above, Hugo automatically uses the embedded image render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
+When set to `auto` as shown above, Hugo automatically uses the embedded image render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom image render hooks are defined by your project, modules, or themes, these will be used instead.
You can also configure Hugo to `always` use the embedded image render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhooksimageuseembedded).
useEmbedded = 'auto'
{{< /code-toggle >}}
-When set to `auto` as shown above, Hugo automatically uses the embedded link render hook for multilingual single-host sites, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such sites. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
+When set to `auto` as shown above, Hugo automatically uses the embedded link render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
> [!note]
> When working with Markdown this shortcode is obsolete. Instead, to properly resolve Markdown link destinations, use the [embedded link render hook] or create your own.
>
-> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host 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.
+> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
>
> You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
> [!note]
> When working with Markdown this shortcode is obsolete. Instead, to properly resolve Markdown link destinations, use the [embedded link render hook] or create your own.
>
-> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host 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.
+> In its default configuration, Hugo automatically uses the embedded link render hook for multilingual single-host projects, specifically when the [duplication of shared page resources] feature is disabled. This is the default behavior for such projects. If custom link render hooks are defined by your project, modules, or themes, these will be used instead.
>
> You can also configure Hugo to `always` use the embedded link render hook, use it only as a `fallback`, or `never` use it. See [details](/configuration/markup/#renderhookslinkuseembedded).
To display a Vimeo video with this URL:
```text
-https://vimeo.com/channels/staffpicks/55073825
+https://vimeo.com/19899678
```
Include this in your Markdown:
```text
-{{</* vimeo 55073825 */>}}
+{{</* vimeo 19899678 */>}}
```
Hugo renders this to:
-{{< vimeo 55073825 >}}
+{{< vimeo 19899678 >}}
## Arguments
Here's an example using some of the available arguments:
```text
-{{</* vimeo id=55073825 allowFullScreen=false loading=lazy */>}}
+{{</* vimeo id=19899678 allowFullScreen=false loading=lazy */>}}
```
## Privacy
{{ end }}
```
-For multilingual sites, add the language key to the file name:
+For multilingual projects, add the language key to the file name:
```text
layouts/
{{< code-toggle file=hugo >}}
[services.googleAnalytics]
-id = "G-MEASUREMENT_ID"
+id = 'G-MEASUREMENT_ID'
{{</ code-toggle >}}
To use this value in your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
{{</ code-toggle >}}
{{< code-toggle file=content/blog/my-post.md fm=true >}}
-title = "Post title"
-description = "Text about this post"
+title = 'Post title'
+description = 'Text about this post'
date = 2024-03-08T08:18:11-08:00
images = ["post-cover.png"]
audio = []
{{< code-toggle file=hugo >}}
[params]
images = ["site-feature-image.jpg"]
- description = "Text about my cool site"
+ description = 'Text about my cool site'
{{</ code-toggle >}}
{{< code-toggle file=content/blog/my-post.md fm=true >}}
-title = "Post title"
-description = "Text about this post"
+title = 'Post title'
+description = 'Text about this post'
images = ["post-cover.png"]
{{</ code-toggle >}}
{{< code-toggle file=hugo >}}
[params.social]
-twitter = "GoHugoIO"
+twitter = 'GoHugoIO'
{{</ code-toggle >}}
NOTE: The `@` will be added for you
{{% glossary-term template %}}
-Templates use [variables], [functions], and [methods] to transform your content, resources, and data into a published page.
+Templates use [variables][], [functions][], and [methods][] to transform your content, resources, and data into a published page.
> [!note]
-> Hugo uses Go's [text/template] and [html/template] packages.
+> Hugo uses Go's [`text/template`][] and [`html/template`][] packages.
>
-> The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection.
+> The `text/template` package implements data-driven templates for generating textual output, while the `html/template` package implements data-driven templates for generating HTML output safe against code injection.
>
-> By default, Hugo uses the html/template package when rendering HTML files.
+> By default, Hugo uses the `html/template` package when rendering HTML files.
For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph.
<h2>{{ .Title }}</h2>
```
-In the example above the dot represents the `Page` object, and we call its [`Title`] method to return the title as defined in [front matter].
+In the example above the dot represents the `Page` object, and we call its [`Title`][] method to return the title as defined in [front matter][].
-The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we rebind the context to another value or object within [`range`] or [`with`] blocks.
+The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we rebind the context to another value or object within [`range`][] or [`with`][] blocks.
```go-html-template {file="layouts/page.html"}
<h2>{{ .Title }}</h2>
Variables initialized inside of an `if`, `range`, or `with` block are scoped to the block. Variables initialized outside of these blocks are scoped to the template.
-With variables that represent a slice or map, use the [`index`] function to return the desired value.
+With variables that represent a slice or map, use the [`index`][] function to return the desired value.
```go-html-template
{{ $slice := slice "foo" "bar" "baz" }}
Used within a template action, a function takes one or more arguments and returns a value. Unlike methods, functions are not associated with an object.
-Go's text/template and html/template packages provide a small set of functions, operators, and statements for general use. See the [go-templates] section of the function documentation for details.
+Go's `text/template` and `html/template` packages provide a small set of functions, operators, and statements for general use. See the [go-templates][] section of the function documentation for details.
-Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other functions:
+Hugo provides hundreds of custom [functions][] categorized by namespace. For example, the `strings` namespace includes these and other functions:
Function|Alias
:--|:--
Used within a template action and associated with an object, a method takes zero or more arguments and either returns a value or performs an action.
-The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object.
+The most commonly accessed objects are the [`Page`][] and [`Site`][] objects. This is a small sampling of the [methods][] available to each object.
Object|Method|Description
:--|:--|:--
`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in your project configuration.
`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the your project configuration.
-Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context].
+Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context][].
```go-html-template {file="layouts/page.html"}
{{ .Site.Title }} → My Site Title
You may not nest one comment inside of another.
-To render an HTML comment, pass a string through the [`safeHTML`] template function. For example:
+To render an HTML comment, pass a string through the [`safeHTML`][] template function. For example:
```go-html-template
{{ "<!-- I am an HTML comment. -->" | safeHTML }}
## Include
-Use the [`template`] function to include one or more of Hugo's [embedded templates]:
+Use the [`template`][] function to include one or more of Hugo's [embedded templates]:
```go-html-template
{{ partial "google_analytics.html" . }}
{{ partial "twitter_cards.html" . }}
```
-Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
+Use the [`partial`][] or [`partialCached`][] function to include one or more [partial templates][]:
```go-html-template
{{ partial "breadcrumbs.html" . }}
## Examples
-This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions], [methods], and [templates] documentation for specific examples.
+This limited set of contrived examples demonstrates some of concepts described above. Please see the [functions][], [methods][], and [templates][] documentation for specific examples.
### Conditional blocks
-See documentation for [`if`], [`else`], and [`end`].
+See documentation for [`if`][], [`else`][], and [`end`][].
```go-html-template
{{ $var := 42 }}
### Logical operators
-See documentation for [`and`] and [`or`].
+See documentation for [`and`][] and [`or`][].
```go-html-template
{{ $v1 := true }}
### Loops
-See documentation for [`range`], [`else`], and [`end`].
+See documentation for [`range`][], [`else`][], and [`end`][].
```go-html-template
{{ $s := slice "foo" "bar" "baz" }}
### Rebind context
-See documentation for [`with`], [`else`], and [`end`].
+See documentation for [`with`][], [`else`][], and [`end`][].
```go-html-template
{{ $var := "foo" }}
name = 'John Smith'
{{< /code-toggle >}}
-The `title` and `date` fields are standard [front matter fields], while the other fields are user-defined.
+The `title` and `date` fields are standard [front matter fields][], while the other fields are user-defined.
Access the custom fields by [chaining](g) the [identifiers](g) when needed:
{{ .Params.author.name }} → John Smith
```
-In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
+In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`][] function:
```go-html-template
{{ index .Params "key-with-hyphens" }} → must use index function
[front matter]: /content-management/front-matter/
[functions]: /functions/
[go-templates]: /functions/go-template/
-[html/template]: https://pkg.go.dev/html/template
+[`html/template`]: https://pkg.go.dev/html/template
[methods]: /methods/
[partial templates]: /templates/types/#partial
[templates]: /templates/
-[text/template]: https://pkg.go.dev/text/template
+[`text/template`]: https://pkg.go.dev/text/template
[variables]: #variables
To paginate a `home`, `section`, `taxonomy`, or `term` page, invoke either of these methods on the `Page` object in the corresponding template:
-- [`Paginate`]
-- [`Paginator`]
+- [`Paginate`][]
+- [`Paginator`][]
The `Paginate` method is more flexible, allowing you to:
## Grouping
-Use pagination with any of the [grouping methods]. For example:
+Use pagination with any of the [grouping methods][]. For example:
```go-html-template
{{ $pages := where site.RegularPages "Type" "posts" }}
```
> [!note]
-> To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+> To override Hugo's embedded pagination template, copy the [source code][] to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`][] function:
>
> `{{ partial "pagination.html" . }}`
Create custom navigation components using any of the `Pager` methods:
-{{% list-pages-in-section path=/methods/pager %}}
+{{% render-list-of-pages-in-section path=/methods/pager %}}
## Structure
{{< newtemplatesystem >}}
> [!note]
-> Before creating custom shortcodes, please review the [shortcodes] page in the [content management] section. Understanding the usage details will help you design and create better templates.
+> Before creating custom shortcodes, please review the [shortcodes][] page in the [content management][] section. Understanding the usage details will help you design and create better templates.
## Introduction
-Hugo provides [embedded shortcodes] for many common tasks, but you'll likely need to create your own for more specific needs. Some examples of custom shortcodes you might develop include:
+Hugo provides [embedded shortcodes][] for many common tasks, but you'll likely need to create your own for more specific needs. Some examples of custom shortcodes you might develop include:
- Audio players
- Video players
Use these methods in your _shortcode_ templates. Refer to each methods's documentation for details and examples.
-{{% list-pages-in-section path=/methods/shortcode %}}
+{{% render-list-of-pages-in-section path=/methods/shortcode %}}
## Examples
This is {{</* year */>}}, and look at how far we've come.
```
-This shortcode can be used inline or as a block on its own line. If a shortcode might be used inline, remove the surrounding [whitespace] by using [template action](g) delimiters with hyphens.
+This shortcode can be used inline or as a block on its own line. If a shortcode might be used inline, remove the surrounding [whitespace][] by using [template action](g) delimiters with hyphens.
### Insert image
The example above uses:
-- The [`with`] statement to rebind the [context](g) after each successful operation
-- The [`Get`] method to retrieve arguments by name
+- The [`with`][] statement to rebind the [context](g) after each successful operation
+- The [`Get`][] method to retrieve arguments by name
- The `$` to access the template context
> [!note]
> Make sure that you thoroughly understand the concept of context. The most common templating errors made by new users relate to context.
>
-> Read more about context in the [introduction to templating].
+> Read more about context in the [introduction to templating][].
### Insert image with error handling
This template throws an error and gracefully fails the build if the author neglected to provide a `path` or `width` argument, and it emits a warning if it cannot find the image at the specified path. If the author does not provide an `alt` argument, the `alt` attribute is set to an empty string.
-The [`Name`] and [`Position`] methods provide helpful context for errors and warnings. For example, a missing `width` argument causes the shortcode to throw this error:
+The [`Name`][] and [`Position`][] methods provide helpful context for errors and warnings. For example, a missing `width` argument causes the shortcode to throw this error:
```text
ERROR The "image" shortcode requires a 'width' argument: see "/home/user/project/content/example/index.md:7:1"
### Positional arguments
-Shortcode arguments can be [named or positional]. We used named arguments previously; let's explore positional arguments. Here's the named argument version of our example:
+Shortcode arguments can be [named or positional][]. We used named arguments previously; let's explore positional arguments. Here's the named argument version of our example:
```text {file="content/example/index.md"}
{{</* image path=a.jpg width=300 alt="A white kitten" */>}}
### Named and positional arguments
-You can create a shortcode that will accept both named and positional arguments, but not at the same time. Use the [`IsNamedParams`] method to determine whether the shortcode call used named or positional arguments:
+You can create a shortcode that will accept both named and positional arguments, but not at the same time. Use the [`IsNamedParams`][] method to determine whether the shortcode call used named or positional arguments:
```go-html-template {file="layouts/_shortcodes/image.html"}
{{ $path := cond (.IsNamedParams) (.Get "path") (.Get 0) }}
{{ $alt := cond (.IsNamedParams) (.Get "alt") (.Get 2) }}
```
-This example uses the `cond` alias for the [`compare.Conditional`] function to get the argument by name if `IsNamedParams` returns `true`, otherwise get the argument by position.
+This example uses the `cond` alias for the [`compare.Conditional`][] function to get the argument by name if `IsNamedParams` returns `true`, otherwise get the argument by position.
### Argument collection
-Use the [`Params`] method to access the arguments as a collection.
+Use the [`Params`][] method to access the arguments as a collection.
When using named arguments, the `Params` method returns a map:
{{ index .Params 1 }} → A white kitten
```
-Combine the `Params` method with the [`collections.IsSet`] function to determine if a parameter is set, even if its value is falsy.
+Combine the `Params` method with the [`collections.IsSet`][] function to determine if a parameter is set, even if its value is falsy.
### Inner content
-Extract the content enclosed within shortcode tags using the [`Inner`] method. This example demonstrates how to pass both content and a title to a shortcode. The shortcode then generates a `div` element containing an `h2` element (displaying the title) and the provided content.
+Extract the content enclosed within shortcode tags using the [`Inner`][] method. This example demonstrates how to pass both content and a title to a shortcode. The shortcode then generates a `div` element containing an `h2` element (displaying the title) and the provided content.
```text {file="content/example.md"}
{{</* contrived title="A Contrived Example" */>}}
</div>
```
-The preceding example called the shortcode using [standard notation], requiring us to process the inner content with the [`RenderString`] method to convert the Markdown to HTML. This conversion is unnecessary when calling a shortcode using [Markdown notation].
+The preceding example called the shortcode using [standard notation][], requiring us to process the inner content with the [`RenderString`][] method to convert the Markdown to HTML. This conversion is unnecessary when calling a shortcode using [Markdown notation][].
### Nesting
-The [`Parent`] method provides access to the parent shortcode context when the shortcode in question is called within the context of a parent shortcode. This provides an inheritance model.
+The [`Parent`][] method provides access to the parent shortcode context when the shortcode in question is called within the context of a parent shortcode. This provides an inheritance model.
The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` argument:
### Other examples
-For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub], can provide a useful model.
+For guidance, consider examining Hugo's embedded shortcodes. The source code, available on [GitHub][], can provide a useful model.
## Detection
-The [`HasShortcode`] method allows you to check if a specific shortcode has been called on a page. For example, consider a custom audio shortcode:
+The [`HasShortcode`][] method allows you to check if a specific shortcode has been called on a page. For example, consider a custom audio shortcode:
```text {file="content/example.md"}
{{</* audio src=/audio/test.mp3 */>}}
```go-html-template {file="layouts/baseof.html"}
<!DOCTYPE html>
-<html lang="{{ site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
+<html lang="{{ site.Language.Locale }}" dir="{{ or site.Language.Direction `ltr` }}">
<head>
{{ partial "head.html" . }}
</head>
[BloggerToHugo](https://github.com/huanlin/blogger-to-hugo)
: Yet another tool to import Blogger posts to Hugo. For Windows platform only, and .NET Framework 4.5 is required. See README.md before using this tool.
+[blogger2hugo](https://github.com/noorkhafidzin/blogger2hugo)
+: Converts a Blogger backup file (`.atom`) from [Google Takeout](https://takeout.google.com/takeout/custom/blogger?hl=en) to Markdown (`.md`) files. The tool generates output compatible with the Hugo `content/` structure.
+
## Contentful
[contentful-hugo](https://github.com/ModiiMedia/contentful-hugo)
You can also use template functions to print warnings or errors to the console. These functions are typically used to report data validation errors, missing files, etc.
-{{% list-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include %}}
+{{% render-list-of-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include %}}
## LiveReload
- zig
Name: Zig
styles:
- - RPGLE
- abap
- algol
- algol_nu
- rose-pine
- rose-pine-dawn
- rose-pine-moon
+ - rpgle
- rrt
- solarized-dark
- solarized-dark256
misc:
dir: :cacheDir/:project
maxAge: -1
+ modulegitinfo:
+ dir: :cacheDir/modules
+ maxAge: 24h
modulequeries:
dir: :cacheDir/modules
maxAge: 24h
ignoreLogs: null
ignoreVendorPaths: ''
imaging:
- bgColor: '#ffffff'
+ anchor: smart
+ bgColor: ffffff
compression: lossy
- hint: photo
+ exif:
+ disableDate: false
+ disableLatLong: false
+ excludeFields: GPS|Exif|Exposure[M|P|B]|Contrast|Resolution|Sharp|JPEG|Metering|Sensing|Saturation|ColorSpace|Flash|WhiteBalance
+ includeFields: ''
+ meta:
+ fields:
+ - '! *{GPS,Exif,Exposure[MPB],Contrast,Resolution,Sharp,JPEG,Metering,Sensing,Saturation,ColorSpace,Flash,WhiteBalance}*'
+ sources:
+ - exif
+ - iptc
quality: 75
resampleFilter: box
webp:
- method: 4
- useSharpYuv: true
- languageCode: ''
+ hint: photo
+ method: 2
+ useSharpYuv: false
languages:
en:
+ direction: ''
disabled: false
- languageCode: ''
- languageDirection: ''
- languageName: ''
+ label: ''
+ locale: ''
title: ''
weight: 0
layoutDir: layouts
+ locale: ''
mainSections: null
markup:
asciiDocExt:
delimiter: .
suffixes:
- ttf
+ image/avif:
+ delimiter: .
+ suffixes:
+ - avif
image/bmp:
delimiter: .
suffixes:
delimiter: .
suffixes:
- gif
+ image/heic:
+ delimiter: .
+ suffixes:
+ - heic
+ image/heif:
+ delimiter: .
+ suffixes:
+ - heif
image/jpeg:
delimiter: .
suffixes:
Description: |-
Append appends args up to the last one to the slice in the last argument.
This construct allows template constructs like this:
-
+
{{ $pages = $pages | append $p2 $p1 }}
-
+
Note that with 2 arguments where both are slices of the same type,
the first slice will be appended to the second:
-
+
{{ $pages = $pages | append .Site.RegularPages }}
Examples: []
Apply:
Description: |-
Complement gives the elements in the last element of ls that are not in
any of the others.
-
+
All elements of ls must be slices or arrays of comparable types.
-
+
The reasoning behind this rather clumsy API is so we can do this in the templates:
-
+
{{ $c := .Pages | complement $last4 }}
Examples:
- - '{{ slice "a" "b" "c" "d" "e" "f" | complement (slice "b" "c") (slice "d" "e") }}'
Index returns the result of indexing its first argument by the following
arguments. Thus "index x 1 2 3" is, in Go syntax, x[1][2][3]. Each
indexed item must be a map, slice, or array.
-
+
Adapted from Go stdlib src/text/template/funcs.go.
-
+
We deviate from the stdlib mostly because of https://github.com/golang/go/issues/14751.
Examples: []
Intersect:
Description: |-
Merge creates a copy of the final parameter in params and merges the preceding
parameters into it in reverse order.
-
+
Currently only maps are supported. Key handling is case insensitive.
Examples:
- - '{{ dict "title" "Hugo Rocks!" | collections.Merge (dict "title" "Default Title" "description" "Yes, Hugo Rocks!") | sort }}'
- args
Description: |-
Seq creates a sequence of integers from args. It's named and used as GNU's seq.
-
+
Examples:
-
+
3 => 1, 2, 3
1 2 4 => 1, 3
-3 => -1, -2, -3
- v2
Description: |-
Conditional can be used as a ternary operator.
-
+
It returns v1 if cond is true, else v2.
Examples:
- - '{{ cond (eq (add 2 2) 4) "2+2 is 4" "what?" | safeHTML }}'
- - '{{ sha256 "Hello world, gophers!" }}'
- 6ec43b78da9669f50e4e422575c54bf87536954ccd58280219c393f2ce352b46
css:
+ Build:
+ Aliases: null
+ Args:
+ - args
+ Description: |-
+ Build processes the given CSS Resource with ESBuild.
+ Note that this method is identical to the one in the js Namespace.
+ Examples: []
PostCSS:
Aliases:
- postCSS
Dump returns a object dump of val as a string.
Note that not every value passed to Dump will print so nicely, but
we'll improve on that.
-
+
We recommend using the "go" Chroma lexer to format the output
nicely.
-
+
Also note that the output from Dump may change from Hugo version to the next,
so don't depend on a specific output.
Examples:
- - '{{ hash.XxHash "The quick brown fox jumps over the lazy dog" }}'
- 0b242d361fda71bc
hugo:
+ Data:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
Deps:
Aliases: null
Args: null
Description: ''
Examples: null
+ Environment:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ ForEeachIdentityByName:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
Generator:
Aliases: null
Args: null
Args: null
Description: ''
Examples: null
+ Sites:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
Store:
Aliases: null
Args: null
- v
Description: |-
Humanize returns the humanized form of v.
-
+
If v is either an integer or a string containing an integer
value, the behavior is to add the appropriate ordinal.
Examples:
Aliases: null
Args:
- args
- Description: Build processes the given Resource with ESBuild.
+ Description: Build processes the given JavaScript Resource with ESBuild.
Examples: []
lang:
FormatAccounting:
Description: |-
FormatAccounting returns the currency representation of number for the given currency and precision
for the current language in accounting notation.
-
+
The return value is formatted with at least two decimal places.
Examples:
- - '{{ 512.5032 | lang.FormatAccounting 2 "NOK" }}'
Description: |-
FormatCurrency returns the currency representation of number for the given currency and precision
for the current language.
-
+
The return value is formatted with at least two decimal places.
Examples:
- - '{{ 512.5032 | lang.FormatCurrency 2 "USD" }}'
Args: null
Description: ''
Examples: null
+ IsImageResourceProcessable:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
+ IsImageResourceWithMeta:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
IsMap:
Aliases: null
Args:
so if you organize your resources in sub-folders, you need to be explicit about it, e.g.:
"images/*.png". To match any PNG image anywhere in the bundle you can do "**.png", and
to match all PNG images below the images folder, use "images/**.jpg".
-
+
The matching is case insensitive.
-
+
Match matches by using the files name with path relative to the file system root
with Unix style slashes (/) and no leading slash, e.g. "images/logo.png".
-
+
See https://github.com/gobwas/glob for the full rules set.
-
+
It looks for files in the assets file system.
-
+
See Match for a more complete explanation about the rules used.
Examples: []
Minify:
Args: null
Description: ''
Examples: null
+ IsDefault:
+ Aliases: null
+ Args: null
+ Description: ''
+ Examples: null
Key:
Aliases: null
Args: null
expression in content. Each element is a slice of strings holding the text
of the leftmost match of the regular expression and the matches, if any, of
its subexpressions.
-
+
By default all matches will be included. The number of matches can be
limited with the optional limit parameter. A return value of nil indicates
no match.
- Batman and Catwoman
- - '{{ replace "aabbaabb" "a" "z" 2 }}'
- zzbbaabb
+ ReplacePairs:
+ Aliases: null
+ Args:
+ - args
+ Description: |-
+ ReplacePairs returns a copy of a string with multiple replacements performed
+ in a single pass. The last argument is the source string. Preceding arguments
+ are old/new string pairs, either as a slice or as individual arguments.
+ Examples:
+ - - '{{ "aab" | strings.ReplacePairs "a" "b" "b" "c" }}'
+ - bbc
+ - - '{{ "aab" | strings.ReplacePairs (slice "a" "b" "b" "c") }}'
+ - bbc
ReplaceRE:
Aliases:
- replaceRE
- s
Description: |-
Emojify returns a copy of s with all emoji codes replaced with actual emojis.
-
+
See http://www.emoji-cheat-sheet.com/
Examples:
- - '{{ "I :heart: Hugo" | emojify }}'
-# Do not delete. Required for layouts/_shortcodes/list-pages-in-section.html.
+# Do not delete. This file defines filters that can be applied to lists of
+# pages when rendering. The filters are defined as lists of page paths. A
+# filter can be applied to a list of pages by specifying the filter name and
+# filter type (include or exclude). Used by:
#
-# When calling the list-pages-in-section shortcode, you can specify a page
-# filter, and whether the pages in the filter should be included or excluded
-# from the list.
-#
-# For example:
-#
-# {{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
+# - layouts/_shortcodes/render-list-of-pages-in-section.html
+# - layouts/_shortcodes/render-table-of-pages-in-section.html
functions_fmt_logging:
- /functions/fmt/errorf
- /methods/page/nextinsection
- /methods/page/prev
- /methods/page/previnsection
+methods_resource_image_processing:
+ - /methods/resource/crop
+ - /methods/resource/fill
+ - /methods/resource/filter
+ - /methods/resource/fit
+ - /methods/resource/fit
+ - /methods/resource/resize
[languages]
[languages.en]
- languageCode = "en-US"
- languageName = "English"
- weight = 1
+ direction = 'ltr'
+ label = 'English'
+ locale = 'en-US'
+ weight = 1
[markup]
[markup.goldmark]
block = [['\[', '\]'], ['$$', '$$']]
inline = [['\(', '\)']]
[markup.goldmark.parser]
- autoDefinitionTermID = true
+ autoDefinitionTermID = true
wrapStandAloneImageWithinParagraph = false
[markup.goldmark.parser.attribute]
block = true
[taxonomies]
category = 'categories'
-######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES ########
+ ######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES ########
[menus]
[[menus.global]]
{{- /* There's a better way to handle this, but it works for now. */}}
{{- $cheating := dict
"chaining" "chain"
+ "ci/cd" "cicd"
+ "interleaved" "interleave"
"localize" "localization"
"localized" "localization"
"paginating" "paginate"
"walking" "walk"
- "ci/cd" "cicd"
}}
{{- /* Verify that a glossary term page exists for the given term. */}}
{{- $text := .text | default "" }}
{{- $class := .class | default "mt-6 mb-8" }}
<div
- class="border-l-4 overflow-x-auto border-{{ $color }}-400 bg-{{ $color }}-50 dark:bg-{{ $color }}-800 border-1 dark:border-{{ $color }}-700 p-4 {{ $class }}">
+ class="border-l-4 overflow-x-auto border-{{ $color }}-400 bg-{{ $color }}-50 dark:bg-{{ $color }}-800 border dark:border-{{ $color }}-700 p-4 {{ $class }}">
<div class="flex">
<div class="shrink-0">
<svg class="fill-{{ $color }}-500 dark:fill-{{ $color }}-400 h-7 w-7">
--- /dev/null
+{{/* prettier-ignore-start */ -}}
+{{- /*
+This must be used in conjunction with the "deprecated-in" and "new-in"
+shortcodes. The "deprecated-in" shortcode should be used to indicate when a
+feature was deprecated, and the "new-in" shortcode should be used to indicate
+when a feature was introduced. This template will render the appropriate
+admonition or badge based on the feature status and version information provided
+by the shortcodes.
+
+@param {string} inner The inner content of the shortcode, if any.
+@param {string} name The name of the shortcode.
+@param {string} page The page context in which the shortcode is used.
+@param {string} position The position of the shortcode in the source file.
+@param {string} status The feature status, either "deprecated" or "new".
+@param {string} version The version in which the feature was deprecated or introduced.
+
+@config {int} majorVersionDiffThreshold The major version difference before warning.
+@config {int} minorVersionDiffThresholdDeprecatedFeature Minor versions to wait before warning about a deprecated feature.
+@config {int} minorVersionDiffThresholdNewFeature Minor versions to wait before warning about a "new" feature.
+@config {slice} validStatusValues Allowed values for the status parameter.
+@config {string} classAnchorBase Base classes for the anchor element.
+@config {string} classSpanBase Base classes for the span/badge element.
+
+@example
+
+ {{- partial "layouts/blocks/feature-state.html" (dict
+ "inner" (strings.TrimSpace $.Inner)
+ "name" $.Name
+ "page" $.Page
+ "position" $.Position
+ "status" "deprecated"
+ "version" $version
+ )
+ }}
+
+*/ -}}
+{{/* prettier-ignore-end */ -}}
+
+{{- /* Configuration */ -}}
+{{- $majorVersionDiffThreshold := 0 }}
+{{- $minorVersionDiffThresholdDeprecatedFeature := 30 }}
+{{- $minorVersionDiffThresholdNewFeature := 30 }}
+{{- $validStatusValues := slice "deprecated" "new" }}
+{{- $classAnchorBase := "dark:text-black no-underline" }}
+{{- $classSpanBase := "not-prose inline-flex items-center px-2 mr-1 rounded text-sm font-medium" }}
+
+{{- /* Initialization */ -}}
+{{- $classAnchor := $classAnchorBase }}
+{{- $classSpan := $classSpanBase }}
+{{- $color := "" }}
+{{- $expiryMessage := "" }}
+{{- $icon := "" }}
+{{- $minorVersionDiffThreshold := 0 }}
+{{- $text := "" }}
+
+{{- if and $.name $.page $.position $.status $.version }}
+ {{- if in $validStatusValues $.status }}
+ {{- if eq $.status "deprecated" }}
+ {{- $classAnchor = printf "text-orange-800 hover:text-orange-600 %s" $classAnchor }}
+ {{- $classSpan = printf "bg-orange-200 dark:bg-orange-400 fill-orange-600 %s" $classSpan }}
+ {{- $color = "orange" }}
+ {{- $expiryMessage = "The deprecation period has ended. Remove this shortcode call and the associated content" }}
+ {{- $icon = "exclamation" }}
+ {{- $minorVersionDiffThreshold = $minorVersionDiffThresholdDeprecatedFeature }}
+ {{- $text = "Deprecated in" }}
+ {{- else if eq $.status "new" }}
+ {{- $classAnchor = printf "text-green-800 hover:text-green-600 %s" $classAnchor }}
+ {{- $classSpan = printf "bg-green-200 dark:bg-green-400 fill-green-600 %s" $classSpan }}
+ {{- $color = "green" }}
+ {{- $expiryMessage = "This feature is no longer new. Remove this shortcode call" }}
+ {{- $icon = "exclamation" }}
+ {{- $minorVersionDiffThreshold = $minorVersionDiffThresholdNewFeature }}
+ {{- $text = "New in" }}
+ {{- else }}
+ {{- errorf "BUG: The %q template does not support the %q feature status: see %s" templates.Current.Name $.status $.position }}
+ {{- end }}
+
+ {{- $hv := split hugo.Version "." }}
+ {{- $sv := split $.version "." }}
+ {{- $majorDiff := sub (index $hv 0 | int) (index $sv 0 | int) }}
+ {{- $minorDiff := sub (index $hv 1 | int) (index $sv 1 | int) }}
+
+ {{- if or (gt $majorDiff $majorVersionDiffThreshold) (gt $minorDiff $minorVersionDiffThreshold) }}
+ {{- warnf "%s: %s" $expiryMessage $.position }}
+ {{- end }}
+
+ {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $.version }}
+ {{- if $.inner }}
+ {{- $text = printf "%s [v%s](%s)\n\n%s" $text $.version $href $.inner | $.page.RenderString (dict "display" "block") }}
+ {{- partial "layouts/blocks/alert.html" (dict "color" $color "icon" $icon "text" $text) }}
+ {{- else }}
+ {{- $target := "_blank"}}
+ {{- printf "<span class=%q><a class=%q href=%q target=%q>%s v%s</a></span>" $classSpan $classAnchor $href $target $text $.version | safeHTML }}
+ {{- end }}
+ {{- else }}
+ {{- errorf "The %q template does not support the %q feature status: see %s" templates.Current.Name $.status $.position }}
+ {{- end }}
+{{- else }}
+ {{- errorf "The %q template requires the following context: name, page, position, status, version: see %s" templates.Current.Name $.position }}
+{{- end }}
<nav class="relative flex" aria-label="Tabs">
{{- with $file }}
<div
- class="select-none flex-none text-sm px-2 content-center border-b-1 border-gray-300 dark:border-gray-700"
+ class="select-none flex-none text-sm px-2 content-center border-b border-gray-300 dark:border-gray-700"
aria-label="Filename">
{{ . }}{{ if not $fm }}.{{ end }}
</div>
<button
x-on:click="$store.nav.userSettings.settings.configFileType = '{{ index $langs $i }}'"
aria-label="{{ printf `Toggle %s` . }}"
- class="px-3 py-2 font-semibold text-black dark:text-slate-200 border-l-1 border-t-1 {{ if $isLast }}
- border-r-1
+ class="px-3 py-2 font-semibold text-black dark:text-slate-200 border-l border-t {{ if $isLast }}
+ border-r
{{ end }} border-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 dark:border-gray-700 cursor-pointer relative min-w-0 flex-1 overflow-hidden text-sm no-underline text-center focus:z-10 overflow-x-auto"
- :class="$store.nav.userSettings.settings.configFileType === '{{ index $langs $i }}' ? 'border-b-0 bg-light dark:bg-dark' : 'border-b-1'">
+ :class="$store.nav.userSettings.settings.configFileType === '{{ index $langs $i }}' ? 'border-b-0 bg-light dark:bg-dark' : 'border-b'">
<span class="select-none">
{{ . }}
</span>
{{- if $code }}
{{- range $i, $lang := $langs }}
<div
- class="max-h-96 overflow-y-auto border-l-1 border-b-1 border-r-1 border-gray-300 dark:border-gray-700"
+ class="max-h-96 overflow-y-auto border-l border-b border-r border-gray-300 dark:border-gray-700"
x-ref="{{ $lang }}"
x-cloak
x-transition:enter.opacity.duration.300ms
{{/* prettier-ignore-start */ -}}
{{- /*
-Renders a callout indicating the version in which a feature was deprecated.
+Renders an admonition or badge indicating the version in which a feature was deprecated.
-Include descriptive text between the opening and closing tags, or omit the
-descriptive text and call the shortcode with a self-closing tag.
+To render an admonition, include descriptive text between the opening and closing
+tags. To render a badge, omit the descriptive text and call the shortcode with a
+self-closing tag.
@param {string} 0 The semantic version string, with or without a leading v.
*/ -}}
{{/* prettier-ignore-end */ -}}
{{- with $version := .Get 0 | strings.TrimLeft "vV" }}
- {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}
- {{- $inner := strings.TrimSpace $.Inner }}
- {{- $text := printf "Deprecated in [v%s](%s)\n\n%s" $version $href $inner | $.Page.RenderString (dict "display" "block") }}
- {{- partial "layouts/blocks/alert.html" (dict
- "color" "orange"
- "icon" "exclamation"
- "text" $text
+ {{- partial "layouts/blocks/feature-state.html" (dict
+ "inner" (strings.TrimSpace $.Inner)
+ "name" $.Name
+ "page" $.Page
+ "position" $.Position
+ "status" "deprecated"
+ "version" $version
)
}}
{{- else }}
--- /dev/null
+{{- /*
+Returns the Description of the page specified by the logical path in the first
+positional argument.
+
+@param {string} logicalPath The logical path to the page.
+
+@example {{% get-page-desc "/functions/reflect/isimageresource" %}}
+*/}}
+{{- with $logicalPath := .Get 0 }}
+ {{- with $.Page.GetPage $logicalPath }}
+{{- .Description }}{{/* Do not indent. */}}
+ {{- else }}
+ {{- errorf "The %q shortcode was unable to find %s: see %s" $.Name $logicalPath $.Position }}
+ {{- end }}
+{{- else }}
+ {{- errorf "The %q shortcode requires a positional argument with the logical path to the page: see %s" $.Name $logicalPath $.Position }}
+{{- end -}}
+++ /dev/null
-{{- /*
-Renders a description list of the pages in the given section.
-
-Render a subset of the pages in the section by specifying a predefined filter,
-and whether to include those pages.
-
-Filters are defined in the data directory, in the file named page_filters. Each
-filter is an array of paths to a file, relative to the root of the content
-directory. Hugo will throw an error if the specified filter does not exist, or
-if any of the pages in the filter do not exist.
-
-@param {string} path The path to the section.
-@param {string} [filter=""] The name of filter list.
-@param {string} [filterType=""] The type of filter, either include or exclude.
-@param {string} [titlePrefix=""] The string to prepend to the link title.
-
-@example {{% list-pages-in-section path=/methods/resources %}}
-@example {{% list-pages-in-section path=/functions/images filter=some_filter filterType=exclude %}}
-@example {{% list-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo %}}
-*/}}
-
-{{/* Initialize. */}}
-{{ $filter := or "" (.Get "filter" | lower) }}
-{{ $filterType := or (.Get "filterType") "none" | lower }}
-{{ $filteredPages := slice }}
-{{ $titlePrefix := or (.Get "titlePrefix") "" }}
-
-{{/* Build slice of filtered pages. */}}
-{{ with $filter }}
- {{ with index hugo.Data.page_filters . }}
- {{ range . }}
- {{ with site.GetPage . }}
- {{ $filteredPages = $filteredPages | append . }}
- {{ else }}
- {{ errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }}
- {{ end }}
- {{ end }}
- {{ else }}
- {{ errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }}
- {{ end }}
-{{ end }}
-
-{{/* Render. */}}
-{{ with $sectionPath := .Get "path" }}
- {{ with site.GetPage . }}
- {{ with .RegularPages }}
- {{ range $page := .ByTitle }}
- {{ if or
- (and (eq $filterType "include") (in $filteredPages $page))
- (and (eq $filterType "exclude") (not (in $filteredPages $page)))
- (eq $filterType "none")
- }}
- {{ $linkTitle := .LinkTitle }}
- {{ with $titlePrefix }}
- {{ $linkTitle = printf "%s%s" . $linkTitle }}
- {{ end }}
-{{/* Use page Path as the link destination for render hook to resolve correctly. */}}
-[{{ $linkTitle }}]({{ $page.Path }}){{/* Do not indent. */}}
-: {{ $page.Description }}{{/* Do not indent. */}}
- {{ end }}
- {{ end }}
- {{ else }}
- {{ warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }}
- {{ end }}
- {{ else }}
- {{ errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }}
- {{ end }}
-{{ else }}
- {{ errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }}
-{{ end }}
{{/* prettier-ignore-start */ -}}
{{- /*
-Renders a callout or badge indicating the version in which a feature was added.
+Renders an admonition or badge indicating the version in which a feature was introduced.
-To render a callout, include descriptive text between the opening and closing
-tags. To render a badge,omit the descriptive text and call the shortcode with a
+To render an admonition, include descriptive text between the opening and closing
+tags. To render a badge, omit the descriptive text and call the shortcode with a
self-closing tag.
-When comparing the current version to the specified version, the "new in"
-button will be hidden if any of the following conditions is true:
-
-- The major version difference exceeds the majorVersionDiffThreshold
-- The minor version difference exceeds the minorVersionDiffThreshold
-
@param {string} 0 The semantic version string, with or without a leading v.
-@example {{< new-in 0.100.0 />}}
+@example {{< new-in 0.144.0 />}}
-@example {{{< new-in 0.100.0 >}}
+@example {{< new-in 0.144.0 >}}
Some descriptive text here.
{{< /new-in >}}
*/ -}}
{{/* prettier-ignore-end */ -}}
-{{- $majorVersionDiffThreshold := 0 }}
-{{- $minorVersionDiffThreshold := 30 }}
-{{- $displayExpirationWarning := true }}
-
{{- with $version := .Get 0 | strings.TrimLeft "vV" }}
- {{- $majorVersionDiff := sub (index (split hugo.Version ".") 0 | int) (index (split $version ".") 0 | int) }}
- {{- $minorVersionDiff := sub (index (split hugo.Version ".") 1 | int) (index (split $version ".") 1 | int) }}
- {{- if or (gt $majorVersionDiff $majorVersionDiffThreshold) (gt $minorVersionDiff $minorVersionDiffThreshold) }}
- {{- if $displayExpirationWarning }}
- {{- warnf "This call to the %q shortcode should be removed: %s. The button is now hidden because the specified version (%s) is older than the display threshold." $.Name $.Position $version }}
- {{- end }}
- {{- else }}
- {{- $href := printf "https://github.com/gohugoio/hugo/releases/tag/v%s" $version }}
- {{- with $.Inner }}
- {{- $inner := strings.TrimSpace . }}
- {{- $text := printf "New in [v%s](%s)\n\n%s" $version $href $inner | $.Page.RenderString (dict "display" "block") }}
- {{ partial "layouts/blocks/alert.html" (dict
- "color" "green"
- "icon" "exclamation"
- "text" $text
- )
- }}
- {{- else }}
- <span
- class="not-prose inline-flex items-center px-2 mr-1 rounded text-sm font-medium bg-green-200 dark:bg-green-400 fill-green-600">
- <a
- class="text-green-800 dark:text-black hover:text-green-600 no-underline"
- href="{{ $href }}"
- target="_blank">
- New in
- v{{ $version }}
- </a>
- </span>
- {{- end }}
- {{- end }}
+ {{- partial "layouts/blocks/feature-state.html" (dict
+ "inner" (strings.TrimSpace $.Inner)
+ "name" $.Name
+ "page" $.Page
+ "position" $.Position
+ "status" "new"
+ "version" $version
+ )
+ }}
{{- else }}
{{- errorf "The %q shortcode requires a single positional parameter indicating version. See %s" .Name .Position }}
{{- end }}
(dict "enableEmoji " "/configuration/all/#enableemoji")
(dict "frontmatter" "/configuration/front-matter/")
(dict "hasCJKLanguage" "/configuration/all/#hascjklanguage")
- (dict "languageCode" "/configuration/all/#languagecode")
+ (dict "locale" "/configuration/all/#locale")
(dict "mainSections" "/configuration/all/#mainsections")
(dict "markup" "/configuration/markup/")
(dict "mediaTypes" "/configuration/media-types/")
--- /dev/null
+{{- /*
+Renders a description list of the pages in the given section.
+
+Render a subset of the pages in the section by specifying a predefined filter,
+and whether to include those pages.
+
+Filters are defined in the data directory, in the file named page_filters. Each
+filter is an array of paths to a file, relative to the root of the content
+directory. Hugo will throw an error if the specified filter does not exist, or
+if any of the pages in the filter do not exist.
+
+@param {string} path The path to the section.
+@param {string} [filter=""] The name of filter list.
+@param {string} [filterType=""] The type of filter, either include or exclude.
+@param {string} [titlePrefix=""] The string to prepend to the link title.
+
+@example {{% render-list-of-pages-in-section path=/methods/resource %}}
+@example {{% render-list-of-pages-in-section path=/functions/images filter=some_filter filterType=exclude %}}
+@example {{% render-list-of-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo %}}
+*/}}
+
+{{- /* Initialize. */}}
+{{- $filter := or "" (.Get "filter" | lower) }}
+{{- $filterType := or (.Get "filterType") "none" | lower }}
+{{- $filteredPages := slice }}
+{{- $titlePrefix := or (.Get "titlePrefix") "" }}
+
+{{- /* Build slice of filtered pages. */}}
+{{- with $filter }}
+ {{- with index hugo.Data.page_filters . }}
+ {{- range . }}
+ {{- with site.GetPage . }}
+ {{- $filteredPages = $filteredPages | append . }}
+ {{- else }}
+ {{- errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }}
+ {{- end }}
+ {{- end }}
+ {{- else }}
+ {{- errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }}
+ {{- end }}
+{{- end }}
+
+{{- /* Render. */}}
+{{- with $sectionPath := .Get "path" }}
+ {{- with site.GetPage . }}
+ {{- with .RegularPages }}
+ {{- range $page := .ByTitle }}
+ {{- if or
+ (and (eq $filterType "include") (in $filteredPages $page))
+ (and (eq $filterType "exclude") (not (in $filteredPages $page)))
+ (eq $filterType "none")
+ }}
+ {{- $linkTitle := .LinkTitle }}
+ {{- with $titlePrefix }}
+ {{- $linkTitle = printf "%s%s" . $linkTitle }}
+ {{- end }}
+{{- /* Use page Path as the link destination for render hook to resolve correctly. */}}
+[{{ $linkTitle }}]({{ $page.Path }}){{/* Do not indent. */}}
+: {{ $page.Description }}{{/* Do not indent. */}}
+ {{ end }}
+ {{- end }}
+ {{- else }}
+ {{- warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }}
+ {{- end }}
+ {{- else }}
+ {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }}
+ {{- end }}
+{{- else }}
+ {{- errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }}
+{{- end }}
--- /dev/null
+{{- /*
+Renders a table of the pages in the given section.
+
+Render a subset of the pages in the section by specifying a predefined filter,
+and whether to include those pages.
+
+Filters are defined in the data directory, in the file named page_filters. Each
+filter is an array of paths to a file, relative to the root of the content
+directory. Hugo will throw an error if the specified filter does not exist, or
+if any of the pages in the filter do not exist.
+
+@param {string} path The path to the section.
+@param {string} [filter=""] The name of filter list.
+@param {string} [filterType=""] The type of filter, either include or exclude.
+@param {string} [titlePrefix=""] The string to prepend to the link title.
+@param {string} [headingColumn1="Item"] The heading for the first column of the table.
+@param {string} [headingColumn2="Description"] The heading for the second column of the table.
+
+@example
+
+{{% render-table-of-pages-in-section
+ path=/methods/resource
+ filter=methods_resource_image_processing
+ filterType=include
+ headingColumn1=Method
+ headingColumn2=Description
+%}}
+
+*/}}
+
+{{- /* Initialize. */}}
+{{- $filter := or "" (.Get "filter" | lower) }}
+{{- $filterType := or (.Get "filterType") "none" | lower }}
+{{- $filteredPages := slice }}
+{{- $titlePrefix := or (.Get "titlePrefix") "" }}
+{{- $headingColumn1 := or (.Get "headingColumn1") "Item" }}
+{{- $headingColumn2 := or (.Get "headingColumn2") "Description" }}
+
+{{- /* Build slice of filtered pages. */}}
+{{- with $filter }}
+ {{- with index hugo.Data.page_filters . }}
+ {{- range . }}
+ {{- with site.GetPage . }}
+ {{- $filteredPages = $filteredPages | append . }}
+ {{- else }}
+ {{- errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }}
+ {{- end }}
+ {{- end }}
+ {{- else }}
+ {{- errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }}
+ {{- end }}
+{{- end }}
+
+{{- /* Render. */}}
+{{- with $sectionPath := .Get "path" }}
+ {{- with site.GetPage . }}
+ {{- with .RegularPages }}
+{{ $headingColumn1 }}|{{ $headingColumn2 }}{{/* Do not indent. */}}
+:--|:--{{/* Do not indent. */}}
+ {{- range $page := .ByTitle }}
+ {{- if or
+ (and (eq $filterType "include") (in $filteredPages $page))
+ (and (eq $filterType "exclude") (not (in $filteredPages $page)))
+ (eq $filterType "none")
+ }}
+ {{- $linkTitle := .LinkTitle }}
+ {{- with $titlePrefix }}
+ {{- $linkTitle = printf "%s%s" . $linkTitle }}
+ {{- end }}
+{{- /* Use page Path as the link destination for render hook to resolve correctly. */}}
+[`{{ $linkTitle }}`]({{ $page.Path }})|{{ $page.Description }}{{/* Do not indent. */}}
+ {{- end }}
+ {{- end }}
+ {{- else }}
+ {{- warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }}
+ {{- end }}
+ {{- else }}
+ {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }}
+ {{- end }}
+{{- else }}
+ {{- errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }}
+{{- end }}
<!doctype html>
<html
class="h-full antialiased scheme-light dark:scheme-dark"
- lang="{{ or site.Language.LanguageCode `en-US` }}">
+ lang="{{ site.Language.Locale }}">
<head>
<meta charset="utf-8">
<title>
<description>Recent news about Hugo, a static site generator written in Go, optimized for speed and designed for flexibility.</description>
<link>{{ .Permalink }}</link>
<generator>Hugo {{ hugo.Version }}</generator>
- <language>{{ or site.Language.LanguageCode site.Language.Lang }}</language>
+ <language>{{ site.Language.Locale }}</language>
{{- with site.Copyright }}
<copyright>{{ . }}</copyright>
{{- end }}
command = "npm ls && hugo --gc --minify"
[build.environment]
- HUGO_VERSION = "0.156.0"
+ HUGO_VERSION = "0.158.0"
[context.production.environment]
HUGO_ENV = "production"
projects / brevno-suite / hugo / commitdiff