gohugoio · bep · May 26, 2026 · May 24, 2026
diff --git a/content/en/_common/embedded-get-page-images.md b/content/en/_common/embedded-get-page-images.md
@@ -0,0 +1,7 @@
+---
+_comment: Do not remove front matter.
+---
+
+When the `images` front matter parameter is set, Hugo processes each value. For internal paths, it searches page resources then global resources, using the resource permalink if found or converting the path to an absolute URL if not. External URLs are used as-is.
+
+When `images` is not set, Hugo searches page resources for a name matching `*feature*`, falling back to `*cover*` or `*thumbnail*` if none is found. If still no image is found, Hugo uses the first entry in the site configuration's `params.images` array, if present, and processes it as described above.
diff --git a/content/en/_common/functions/reflect/image-reflection-functions.md b/content/en/_common/functions/reflect/image-reflection-functions.md
@@ -14,7 +14,7 @@ The table below shows the values these functions return for various file formats
 
 |Format|IsImageResource|IsImageResourceProcessable|IsImageResourceWithMeta|
 |:-----|:--------------|:-------------------------|:----------------------|
-|AVIF  |true           |**false**                 |true                   |
+|AVIF  |true           |true                      |true                   |
 |BMP   |true           |true                      |true                   |
 |GIF   |true           |true                      |true                   |
 |HEIC  |true           |**false**                 |true                   |

diff --git a/content/en/_common/methods/resource/processing-spec.md b/content/en/_common/methods/resource/processing-spec.md
@@ -17,13 +17,13 @@ background color
 
 compression
 : {{< new-in 0.153.5 />}}
-: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. This defaults to the [`compression`][] parameter in your project configuration.
+: The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the AVIF and WebP formats. This defaults to the [`compression`][] parameter in your project configuration.
 
 dimensions
 : The dimensions of the resulting image, in pixels. The format is `WIDTHxHEIGHT` where `WIDTH` and `HEIGHT` are whole numbers. When resizing an image, you may specify only the width (such as `600x`) or only the height (such as `x400`) for proportional scaling. Specifying both width and height when resizing an image may result in non-proportional scaling. When cropping, fitting, or filling, you must provide both width and height such as `600x400`.
 
 format
-: The format of the resulting image. Valid options include `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image.
+: The format of the resulting image. Valid options include `avif`, `bmp`, `gif`, `jpeg`, `png`, `tiff`, or `webp`. This defaults to the format of the source image.
 
 hint
 : The encoding preset used when processing WebP images, equivalent to the `-preset` flag for the [`cwebp`][] CLI. Valid options include `drawing`, `icon`, `photo`, `picture`, or `text`. This defaults to the [`hint`][] parameter in your project configuration.
@@ -37,7 +37,7 @@ hint
   `text`|Image that is primarily text
 
 quality
-: The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your project configuration.
+: The visual fidelity of the image, applicable to AVIF, JPEG, and WebP formats when using `lossy` compression. The format is `qQUALITY` where `QUALITY` is a whole number between `1` and `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. This defaults to the [`quality`][] parameter in your project configuration.
 
 resampling filter
 : The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. This defaults to the [`resampleFilter`][] parameter in your project configuration.
@@ -56,7 +56,7 @@ resampling filter
 rotation
 : The number of whole degrees to rotate an image counter-clockwise. The format is `rDEGREES` where `DEGREES` is a whole number. Hugo performs rotation before any other transformations, so your [target dimensions](#dimensions) and any [anchor](#anchor) should refer to the image orientation after rotation. Use `r90`, `r180`, or `r270` for orthogonal rotations, or arbitrary angles such as `r45`. To rotate clockwise, use a negative number such as `r-45`. To automatically rotate an image based on its Exif orientation tag, use the [`images.AutoOrient`][] filter instead of manual rotation.
 
-  Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as PNG or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your project configuration.
+  Rotating by non-orthogonal values increases the image extents to fit the rotated corners. For formats supporting alpha channels such as AVIF, PNG, or WebP, this resulting empty space is transparent by default. If the target format does not support transparency such as JPEG, or if you explicitly specify a [background color](#background-color) in the processing specification, the space is filled. If a color is required but not specified in the processing string, it defaults to the [`bgColor`][] parameter in your project configuration.
 
 [`anchor`]: /configuration/imaging/#anchor
 [`bgcolor`]: /configuration/imaging/#bgcolor

diff --git a/content/en/configuration/imaging.md b/content/en/configuration/imaging.md
@@ -22,10 +22,10 @@ These global settings define how Hugo handles the fundamental aspects of image m
 
 `compression`
 : {{< new-in 0.153.5 />}}
-: (`string`) The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the WebP format. Default is `lossy`.
+: (`string`) The encoding strategy used for the image. Options are `lossy` or `lossless`. Note that `lossless` is only supported by the AVIF and WebP formats. Default is `lossy`.
 
 `quality`
-: (`int`) The visual fidelity of the image, applicable to JPEG and WebP formats when using `lossy` compression. Expressed as a whole number from `1` to `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is `75`.
+: (`int`) The visual fidelity of the image, applicable to AVIF, JPEG, and WebP formats when using `lossy` compression. Expressed as a whole number from `1` to `100`, inclusive. Lower numbers prioritize smaller file size, while higher numbers prioritize visual clarity. Default is `75`.
 
 `resampleFilter`
 : (`string`) The algorithm used to calculate new pixels when resizing, fitting, or filling an image. Common options include `box`, `lanczos`, `catmullRom`, `mitchellNetravali`, `linear`, or `nearestNeighbor`. Default is `box`.
@@ -41,26 +41,20 @@ These global settings define how Hugo handles the fundamental aspects of image m
 
   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.
 
-## Exif method
+## AVIF images
 
-{{< deprecated-in 0.155.0 >}}
-Use [`Meta`](/methods/resource/meta/) instead.
-{{< /deprecated-in >}}
+{{< new-in 0.162.0 />}}
 
-## Meta method
-
-{{< new-in 0.155.0 />}}
-
-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.
+> [!note]
+> When exporting HDR AVIF images from Lightroom, in the Export dialog under File Settings, uncheck Maximize Compatibility to improve Hugo's AVIF decoding speed.
 
-`fields`
-: (`[]string`) A [glob slice](g) matching the fields to include when extracting metadata. If empty, a default set excluding technical metadata is used. Set&nbsp;to&nbsp;`['**']`&nbsp;to include all fields.
+> [!note]
+> Encoding animated images to AVIF produces a single-frame (static) image. Converting an animated AVIF to another format such as GIF works as expected.
 
-  > [!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`.
+Use the following setting to control the AVIF encoding process.
 
-`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.
+`encoderSpeed`
+: (`int`) The encoder speed. Expressed as a whole number from `1` to `10`, inclusive, equivalent to the `-s` flag for the [`avifenc`][] CLI. Lower numbers reduce file size at the cost of build time. At typical web image sizes, quality is indistinguishable across settings. Values below `5` may cause very long build times. Default is `10`.
 
 ## WebP images
 
@@ -80,12 +74,35 @@ These specialized settings provide granular control over the WebP encoding proce
   `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 `2`.
+: (`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 and image quality. 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 `false`.
 
+## Exif method
+
+{{< deprecated-in 0.155.0 >}}
+Use [`Meta`](/methods/resource/meta/) instead.
+{{< /deprecated-in >}}
+
+## Meta method
+
+{{< new-in 0.155.0 />}}
+
+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&nbsp;to&nbsp;`['**']`&nbsp;to include all fields.
+
+  > [!note]
+  > By default, to improve performance and decrease cache size, Hugo excludes the following fields: `ColorSpace`, `Contrast`, `Exif`, `ExposureBias`, `ExposureMode`, `ExposureProgram`, `Flash`, `GPS`, `JPEG`, `Metering`, `Resolution`, `Saturation`, `Sensing`, `Sharp`, and `WhiteBalance`.
+
+`sources`
+: (`[]string`) The metadata sources to include, one or more of `exif`, `iptc`, or `xmp`. Default is `['exif', 'iptc']`. The XMP metadata is excluded by default to improve performance.
+
 [`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
 [`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
+[`Meta`]: /methods/resource/meta/
+[`avifenc`]: https://github.com/aomediacodec/libavif
diff --git a/content/en/configuration/introduction.md b/content/en/configuration/introduction.md
@@ -79,14 +79,11 @@ my-project/
 
 The root configuration keys are {{< root-configuration-keys >}}.
 
-> [!note]
-> You must define `cascade` tables in the root configuration file. You cannot define `cascade` tables in a dedicated file. See issue [#12899] for details.
-
-[#12899]: https://github.com/gohugoio/hugo/issues/12899
+### Root key
 
-### Omit the root key
+{{< new-in 0.162.0 />}}
 
-When splitting the configuration by root key, omit the root key in the component file. For example, these are equivalent:
+When splitting the configuration by root key, you may omit or include the root key in the component file. For example, these are equivalent:
 
 {{< code-toggle file=config/_default/hugo >}}
 [params]
@@ -97,6 +94,35 @@ foo = 'bar'
 foo = 'bar'
 {{< /code-toggle >}}
 
+This also applies to keys whose values are maps of slices, such as `menus`. For example, these are equivalent:
+
+{{< code-toggle file=config/_default/menus >}}
+[[main]]
+name = 'Home'
+pageRef = '/'
+weight = 10
+{{< /code-toggle >}}
+
+{{< code-toggle file=config/_default/menus >}}
+[[menus.main]]
+name = 'Home'
+pageRef = '/'
+weight = 10
+{{< /code-toggle >}}
+
+For pure slice-typed keys such as `cascade` and `permalinks`, including the root key is required. For example:
+
+{{< code-toggle file=config/_default/cascade >}}
+[[cascade]]
+[cascade.params]
+color = 'red'
+[cascade.target]
+path = '/articles/**'
+{{< /code-toggle >}}
+
+> [!note]
+> Hugo unwraps the root key only when it is the sole top-level key in the file and matches the file's basename.
+
 ### Recursive parsing
 
 Hugo parses the `config` directory recursively, allowing you to organize the files into subdirectories. For example:

diff --git a/content/en/configuration/security.md b/content/en/configuration/security.md
@@ -12,6 +12,10 @@ This is the default security configuration:
 
 {{< code-toggle config=security />}}
 
+`allowContent`
+: {{< new-in 0.162.0 />}}
+: (`[]string`) A slice of [regular expressions](g) matching the [media type](g) of [content formats](g) allowed in the `content` directory. By default, the HTML content format (media type `text/html`) is denied. Hugo emits HTML file content verbatim, which could allow arbitrary JavaScript execution. See the [classification] table for a mapping of content formats to media types.
+
 `enableInlineShortcodes`
 : (`bool`) Whether to enable [inline shortcodes]. Default is `false`.
 
@@ -84,6 +88,7 @@ Learn more about [using environment variables] to configure your site.
 
 [`os.Getenv`]: /functions/os/getenv
 [`resources.GetRemote`]: /functions/resources/getremote
+[classification]: /content-management/formats/#classification
 [inline shortcodes]: /content-management/shortcodes/#inline
 [permission model]: https://nodejs.org/api/permissions.html#permission-model
 [using environment variables]: /configuration/introduction/#environment-variables
diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md
@@ -64,6 +64,9 @@ Hugo provides custom Markdown features including:
 
 Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
 
+> [!note]
+> The HTML content format is denied by default. See [`security.allowContent`](/configuration/security/#allowcontent).
+
 [HTML]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content
 
 ### Emacs Org Mode

diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md
@@ -164,16 +164,6 @@ author = 'John Smith'
 
 Access these values from a template using the [`Params`][] or [`Param`][] method on a `Page` object.
 
-Hugo provides [embedded templates][] to optionally insert meta data within the `head` element of your rendered pages. These embedded templates expect the following front matter parameters:
-
-Parameter|Data type|Used by these embedded templates
-:--|:--|:--
-`audio`|`[]string`|[`opengraph.html`][]
-`images`|`[]string`|[`opengraph.html`][], [`schema.html`][], [`twitter_cards.html`][]
-`videos`|`[]string`|[`opengraph.html`][]
-
-The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
-
 ## Taxonomies
 
 Classify content by adding taxonomy terms to front matter. For example, with this project configuration:
@@ -321,15 +311,12 @@ To override the default time zone, set the [`timeZone`](/configuration/all/#time
 [`lastmod`]: /methods/page/date/
 [`layout`]: /methods/page/layout/
 [`linktitle`]: /methods/page/linktitle/
-[`opengraph.html`]: <{{% eturl opengraph %}}>
 [`publishdate`]: /methods/page/publishdate/
 [`readingtime`]: /methods/page/readingtime/
-[`schema.html`]: <{{% eturl schema %}}>
 [`sitemap`]: /methods/page/sitemap/
 [`slug`]: /methods/page/slug/
 [`title`]: /methods/page/title/
 [`translationkey`]: /methods/page/translationkey/
-[`twitter_cards.html`]: <{{% eturl twitter_cards %}}>
 [`type`]: /methods/page/type/
 [`weight`]: /methods/page/weight/
 [`wordcount`]: /methods/page/wordcount/
@@ -340,7 +327,6 @@ To override the default time zone, set the [`timeZone`](/configuration/all/#time
 [content format]: /content-management/formats/
 [content formats]: /content-management/formats/#classification
 [emacs org mode]: https://orgmode.org/
-[embedded templates]: /templates/embedded/
 [json]: https://www.json.org/
 [leaf bundles]: /content-management/page-bundles/#leaf-bundles
 [menus]: /content-management/menus/#define-in-front-matter

diff --git a/content/en/functions/collections/Dictionary.md b/content/en/functions/collections/Dictionary.md
@@ -26,12 +26,6 @@ The above produces this data structure:
 }
 ```
 
-To create an empty map:
-
-```go-html-template
-{{ $m := dict }}
-```
-
 Note that the `key` can be either a `string` or a `[]string`. The latter is useful to create a deeply nested structure, e.g.:
 
 ```go-html-template
@@ -49,3 +43,11 @@ The above produces this data structure:
   }
 }
 ```
+
+{{< new-in 0.162.0 />}}
+
+To create a nil map:
+
+```go-html-template
+{{ $m := dict }}
+```
diff --git a/content/en/functions/images/Mask.md b/content/en/functions/images/Mask.md
@@ -15,7 +15,7 @@ params:
 The `images.Mask` filter applies a mask to an image. Black pixels in the mask make the corresponding areas of the base image transparent, while white pixels keep them opaque. Color images are converted to grayscale for masking purposes. The mask is automatically resized to match the dimensions of the base image.
 
 > [!note]
-> Of the formats supported by Hugo's imaging pipeline, only PNG and WebP have an alpha channel to support transparency. If your source image has a different format and you require transparent masked areas, convert it to either PNG or WebP as shown in the example below.
+> Of the formats supported by Hugo's imaging pipeline, only AVIF, PNG, and WebP have an alpha channel to support transparency. If your source image has a different format and you require transparent masked areas, convert it to AVIF, PNG, or WebP as shown in the example below.
 
 When applying a mask to a non-transparent image format such as JPEG, the masked areas will be filled with the color specified by the `bgColor` parameter in your [project configuration]. You can override that color with a `Process` image filter:
 
@@ -25,7 +25,7 @@ When applying a mask to a non-transparent image format such as JPEG, the masked
 
 ## Usage
 
-Create a slice of filters, one for WebP conversion and the other for mask application:
+Create a slice of filters, one for format conversion and the other for mask application:
 
 ```go-html-template
 {{ $filter1 := images.Process "webp" }}

diff --git a/content/en/functions/images/Opacity.md b/content/en/functions/images/Opacity.md
@@ -22,7 +22,7 @@ Create the filter:
 
 {{% include "/_common/functions/images/apply-image-filter.md" %}}
 
-The `images.Opacity` filter is most useful for target formats such as PNG and WebP that support transparency. If the source image does not support transparency, combine this filter with the `images.Process` filter:
+The `images.Opacity` filter is most useful for target formats such as AVIF, PNG, and WebP that support transparency. If the source image does not support transparency, combine this filter with the `images.Process` filter:
 
 ```go-html-template
 {{ with resources.Get "images/original.jpg" }}

diff --git a/content/en/functions/images/Padding.md b/content/en/functions/images/Padding.md
@@ -52,7 +52,7 @@ Combine with the [`Colors`] method to create a border with one of the image's mo
 
 This example resizes an image to 300px wide, converts it to the WebP format, adds 20px vertical padding and 50px horizontal padding, then sets the canvas color to dark green with 33% opacity.
 
-Conversion to WebP is required to support transparency. PNG and WebP images have an alpha channel; JPEG and GIF do not.
+In the example below, conversion to WebP is required to support transparency. AVIF, PNG, and WebP images have an alpha channel; JPEG and GIF do not.
 
 ```go-html-template
 {{ $img := resources.Get "images/a.jpg" }}