From 047ac71412d4876d29fcacdeb7ca0638e4e6a830 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sun, 24 May 2026 12:17:18 -0700 Subject: [PATCH] content: Updates for v0.162.0 Closes #3231 --- .../en/_common/embedded-get-page-images.md | 7 + .../reflect/image-reflection-functions.md | 2 +- .../methods/resource/processing-spec.md | 8 +- content/en/configuration/imaging.md | 53 +++-- content/en/configuration/introduction.md | 38 +++- content/en/configuration/security.md | 5 + content/en/content-management/formats.md | 3 + content/en/content-management/front-matter.md | 14 -- .../en/functions/collections/Dictionary.md | 14 +- content/en/functions/images/Mask.md | 4 +- content/en/functions/images/Opacity.md | 2 +- content/en/functions/images/Padding.md | 2 +- content/en/functions/resources/GetRemote.md | 2 +- content/en/functions/templates/Defer.md | 4 +- content/en/functions/transform/Highlight.md | 20 +- .../functions/transform/HighlightCodeBlock.md | 48 +++- .../en/quick-reference/glossary/media-type.md | 2 +- .../glossary/processable-image.md | 1 + content/en/render-hooks/code-blocks.md | 15 +- content/en/templates/embedded.md | 207 ++++++++++++++---- data/docs.yaml | 63 +++--- 21 files changed, 369 insertions(+), 145 deletions(-) create mode 100644 content/en/_common/embedded-get-page-images.md diff --git a/content/en/_common/embedded-get-page-images.md b/content/en/_common/embedded-get-page-images.md new file mode 100644 index 0000000000..bd178e5139 --- /dev/null +++ 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 index 2b49b19eb3..2aefd9f9c8 100644 --- 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 index 140a4eb347..d9f5e3c3d0 100644 --- 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 index e6798929d7..51957fc3a9 100644 --- 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 to `['**']` 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 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. + [`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 index 7383b2ff3c..7dc59c8f06 100644 --- 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 index a1cdc9e086..af5480e8dc 100644 --- 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 index 0f9fe7f1cb..f97ed5e5b2 100644 --- 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 index 81e3da075b..abaa9ceefa 100644 --- 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 index 621adb8a23..da5a6b84e9 100644 --- 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 index ecc489d8a4..4633381fc9 100644 --- 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 index 2105aea783..aa59fb8525 100644 --- 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 index 8e6d05c01c..af45a2f710 100644 --- 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" }} diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md index 8080e31a40..28d59b5ad4 100644 --- a/content/en/functions/resources/GetRemote.md +++ b/content/en/functions/resources/GetRemote.md @@ -222,7 +222,7 @@ Although the allowlist contains entries for common media types, you may encounte {{< code-toggle file=hugo >}} [security.http] -mediaTypes = ['^image/avif$','^application/vnd\.api\+json$'] +mediaTypes = ['^application/vnd\.api\+json$'] {{< /code-toggle >}} Note that the entry above is: diff --git a/content/en/functions/templates/Defer.md b/content/en/functions/templates/Defer.md index 70ff8dce5a..f51030130f 100644 --- a/content/en/functions/templates/Defer.md +++ b/content/en/functions/templates/Defer.md @@ -12,9 +12,7 @@ aliases: [/functions/templates.defer] --- > [!note] -> This feature should only be used in the main template, typically `layouts/baseof.html`. Using it in _shortcode_, _partial_, or _render hook_ templates may lead to unpredictable results. For further details, please refer to [this issue]. - -[this issue]: https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391 +> Do not call this function within a `partialCached` template. This restriction applies transitively: if `partialCached` calls a partial that calls `templates.Defer`, Hugo returns an error. Using this function within shortcode or render hook templates may also lead to unpredictable results. In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/configuration/build/) to determine which classes and other HTML identifiers are being used in the final output: diff --git a/content/en/functions/transform/Highlight.md b/content/en/functions/transform/Highlight.md index a2f78d2b94..095d281f3c 100644 --- a/content/en/functions/transform/Highlight.md +++ b/content/en/functions/transform/Highlight.md @@ -7,7 +7,7 @@ params: functions_and_methods: aliases: [highlight] returnType: template.HTML - signatures: ['transform.Highlight CODE LANG [OPTIONS]'] + signatures: ['transform.Highlight CODE [LANG] [OPTIONS]'] aliases: [/functions/highlight] --- @@ -15,16 +15,14 @@ The `transform.Highlight` function uses the [`alecthomas/chroma`][] package to g ## Arguments -The `transform.Highlight` function takes three arguments. - `CODE` : (`string`) The code to highlight. `LANG` -: (`string`) The [language][] of the code to highlight. This value is case-insensitive. +: (`string`) The [language][] of the code to highlight. This value is case-insensitive. Optional; you can also set the language with the `type` key in OPTIONS. {{< new-in 0.162.0 />}} `OPTIONS` -: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. You can set default values for each option in your [project configuration][]. The key names are case-insensitive. +: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. See the [options](#options-1) below; you can set default values for each option in your [project configuration][]. The key names are case-insensitive. ## Examples @@ -40,12 +38,24 @@ The `transform.Highlight` function takes three arguments. {{ $lang := "bash" }} {{ $opts := dict "lineNos" "table" "style" "dracula" }} {{ transform.Highlight $input $lang $opts }} + +{{ $input := `print("Hello World!")` }} +{{ $opts := dict "type" "python" "style" "dracula" }} +{{ transform.Highlight $input $opts }} ``` ## Options {{% include "_common/syntax-highlighting-options.md" %}} +`code` +: {{< new-in 0.162.0 />}} +: (`string`) Overrides the `CODE` argument. + +`type` +: {{< new-in 0.162.0 />}} +: (`string`) Overrides the `LANG` argument. + [`alecthomas/chroma`]: https://github.com/alecthomas/chroma [language]: /content-management/syntax-highlighting#languages [options]: #options-1 diff --git a/content/en/functions/transform/HighlightCodeBlock.md b/content/en/functions/transform/HighlightCodeBlock.md index 31081290ab..bd0d0a0947 100644 --- a/content/en/functions/transform/HighlightCodeBlock.md +++ b/content/en/functions/transform/HighlightCodeBlock.md @@ -10,27 +10,63 @@ params: signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]'] --- -This function is only useful within a code block render hook. +The `transform.HighlightCodeBlock` function uses the [`alecthomas/chroma`][] package to generate syntax-highlighted HTML from code received in context within a code block render hook. This function is only useful within a code block render hook. -Given the context passed into a code block render hook, `transform.HighlightCodeBlock` returns a `HighlightResult` object with two methods. +## Arguments + +CONTEXT +: The [context] passed into a code block render hook. + +OPTIONS +: (`map`) A map of key-value pairs. See the [options](#options-1) below. The key names are case-insensitive. + +## Return value + +`transform.HighlightCodeBlock` returns a `HighlightResult` object with two methods. `Wrapped` -: (`template.HTML`) Returns highlighted code wrapped in `
`, `
`, and `` elements. This is identical to the value returned by the transform.Highlight function.
+: (`template.HTML`) Returns highlighted code wrapped in `
`, `
`, and `` elements. This is identical to the value returned by the `transform.Highlight` function.
 
 `Inner`
 : (`template.HTML`) Returns highlighted code without any wrapping elements, allowing you to create your own wrapper.
 
+## Examples
+
 ```go-html-template
 {{ $result := transform.HighlightCodeBlock . }}
 {{ $result.Wrapped }}
 ```
 
-To override the default [highlighting options]:
+To override the default options:
 
 ```go-html-template
-{{ $opts := merge .Options (dict "linenos" true) }}
+{{ $opts := merge .Options (dict "lineNos" true) }}
 {{ $result := transform.HighlightCodeBlock . $opts }}
 {{ $result.Wrapped }}
 ```
 
-[highlighting options]: /functions/transform/highlight/#options
+To fall back to plain text when the language is not supported by the highlighter:
+
+```go-html-template
+{{ $opts := dict }}
+{{ if not (transform.CanHighlight .Type) }}
+  {{ $opts = dict "type" "text" }}
+{{ end }}
+{{ $result := transform.HighlightCodeBlock . $opts }}
+{{ $result.Wrapped }}
+```
+
+## Options
+
+{{% include "_common/syntax-highlighting-options.md" %}}
+
+`code`
+: {{< new-in 0.162.0 />}}
+: (`string`) Overrides the code received from the code block context.
+
+`type`
+: {{< new-in 0.162.0 />}}
+: (`string`) Overrides the language received from the code block context.
+
+[`alecthomas/chroma`]: https://github.com/alecthomas/chroma
+[context]: /render-hooks/code-blocks/#context
diff --git a/content/en/quick-reference/glossary/media-type.md b/content/en/quick-reference/glossary/media-type.md
index 2994360ef3..f10c6dc710 100644
--- a/content/en/quick-reference/glossary/media-type.md
+++ b/content/en/quick-reference/glossary/media-type.md
@@ -3,4 +3,4 @@ title: media type
 reference: /configuration/media-types/
 ---
 
-A _media type_ (formerly known as a MIME type) is a two-part identifier for file formats and transmitted content. For example, the media type for JSON data is `application/json`.
+A _media type_ (formerly known as a MIME type) is a two-part identifier for file formats and transmitted content. For example, the media type for HTML content is `text/html`.
diff --git a/content/en/quick-reference/glossary/processable-image.md b/content/en/quick-reference/glossary/processable-image.md
index eed69f105f..bcbc02aa91 100644
--- a/content/en/quick-reference/glossary/processable-image.md
+++ b/content/en/quick-reference/glossary/processable-image.md
@@ -4,6 +4,7 @@ title: processable image
 
 A _processable image_ is an image file characterized by one of the following [_media types_](g):
 
+  - `image/avif`
   - `image/bmp`
   - `image/gif`
   - `image/jpeg`
diff --git a/content/en/render-hooks/code-blocks.md b/content/en/render-hooks/code-blocks.md
index 01c31e4c5d..e63336d351 100755
--- a/content/en/render-hooks/code-blocks.md
+++ b/content/en/render-hooks/code-blocks.md
@@ -25,7 +25,7 @@ A fenced code block consists of:
 - A code sample
 - A trailing code fence
 
-In the previous example, the info string contains:
+In the example above, the info string contains:
 
 - The language of the code sample (the first word)
 - An optional space-delimited or comma-delimited list of attributes (everything within braces)
@@ -50,7 +50,7 @@ Code block _render hook_ templates receive the following [context](g):
 : (`string`) The content between the leading and trailing code fences, excluding the info string.
 
 `Options`
-: (`map`) The highlighting options from the info string. This map is empty if [`Type`](#type) is an empty string or an unsupported code language. However, in this case, the highlighting options are available in the [`Attributes`](#attributes) map.
+: (`map`) The highlighting options from the info string.
 
 `Ordinal`
 : (`int`) The zero-based ordinal of the code block on the page.
@@ -76,6 +76,17 @@ By default, Hugo renders fenced code blocks using its built-in syntax highlighte
 {{ $result.Wrapped }}
 ```
 
+To fall back to plain text when the language is not specified or not supported by the highlighter:
+
+```go-html-template {file="layouts/_markup/render-codeblock.html" copy=true}
+{{- $opts := dict }}
+{{- if not (transform.CanHighlight .Type) }}
+  {{- $opts = dict "type" "text" }}
+{{- end }}
+{{- $result := transform.HighlightCodeBlock . $opts }}
+{{- $result.Wrapped }}
+```
+
 Although you can use one template with conditional logic to control the behavior on a per-language basis, you can also create language-specific templates.
 
 ```text
diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md
index 0c1ad71bb9..a5923e0c11 100644
--- a/content/en/templates/embedded.md
+++ b/content/en/templates/embedded.md
@@ -7,16 +7,14 @@ weight: 180
 aliases: [/templates/internal]
 ---
 
-{{< newtemplatesystem >}}
-
 ## Disqus
 
 > [!note]
-> To override Hugo's embedded Disqus template, copy the [source code](<{{% eturl disqus %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+> To override Hugo's embedded Disqus template, copy the [source code](<{{% eturl disqus %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`][] function:
 >
 > `{{ partial "disqus.html" . }}`
 
-Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service.
+Hugo includes an embedded template for [Disqus][], a commenting system for both static and dynamic websites. To use this template, you must first obtain a Disqus shortname by [signing up][] for the free service.
 
 To include the embedded template:
 
@@ -33,17 +31,26 @@ To use Hugo's Disqus template, first set up a single configuration value:
 shortname = 'your-disqus-shortname'
 {{}}
 
-Hugo's Disqus template accesses this value with:
+You can also set the following in the [front matter][] for a given page:
 
-```go-html-template
-{{ .Site.Config.Services.Disqus.Shortname }}
-```
+`disqus_identifier`
+: (`string`) A unique identifier for the page's discussion thread. Set this to preserve comment threads across URL changes.
 
-You can also set the following in the front matter for a given piece of content:
+`disqus_title`
+: (`string`) The title of the discussion thread.
 
-- `disqus_identifier`
-- `disqus_title`
-- `disqus_url`
+`disqus_url`
+: (`string`) The canonical URL for the discussion thread. Use this to override the URL Disqus uses to identify the thread, for example when the same content is served at multiple URLs.
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
+[params]
+disqus_identifier = 'unique-identifier'
+disqus_title = 'Post title'
+disqus_url = 'https://example.org/blog/my-post/'
+{{}}
+
+> [!note]
+> When previewing your site locally, Hugo replaces the Disqus widget with the message "Disqus comments not available by default when the website is previewed locally."
 
 ### Privacy {#privacy-disqus}
 
@@ -57,11 +64,11 @@ Adjust the relevant privacy settings in your project configuration.
 ## Google Analytics
 
 > [!note]
-> To override Hugo's embedded Google Analytics template, copy the [source code](<{{% eturl google_analytics %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+> To override Hugo's embedded Google Analytics template, copy the [source code](<{{% eturl google_analytics %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`][] function:
 >
 > `{{ partial "google_analytics.html" . }}`
 
-Hugo includes an embedded template supporting [Google Analytics 4].
+Hugo includes an embedded template for [Google Analytics 4][].
 
 To include the embedded template:
 
@@ -78,7 +85,8 @@ Provide your tracking ID in your configuration file:
 id = 'G-MEASUREMENT_ID'
 {{}}
 
-To use this value in your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`.
+> [!note]
+> If the configured ID begins with `ua-` (case-insensitive), Hugo logs a warning and renders nothing. Google Universal Analytics (UA) was replaced by Google Analytics 4 (GA4) effective 1 July 2023. Create a GA4 property and data stream, then update your project configuration with the new measurement ID.
 
 ### Privacy {#privacy-google-analytics}
 
@@ -95,12 +103,11 @@ Adjust the relevant privacy settings in your project configuration.
 ## Open Graph
 
 > [!note]
-> To override Hugo's embedded Open Graph template, copy the [source code](<{{% eturl opengraph %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+> To override Hugo's embedded Open Graph template, copy the [source code](<{{% eturl opengraph %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`][] function:
 >
 > `{{ partial "opengraph.html" . }}`
 
-Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph.
-This format is used for Facebook and some other sites.
+Hugo includes an embedded template for the [Open Graph protocol][]. This metadata transforms your pages into rich objects when shared across major social media and messaging platforms.
 
 To include the embedded template:
 
@@ -110,15 +117,15 @@ To include the embedded template:
 
 ### Configuration {#configuration-open-graph}
 
-Hugo's Open Graph template is configured using a mix of configuration settings and [front matter](/content-management/front-matter/) on individual pages.
+Hugo's Open Graph template is configured using a mix of configuration settings and [front matter][] values on individual pages.
 
 {{< code-toggle file=hugo >}}
+title = 'My cool site'
 [params]
   description = 'Text about my cool site'
   images = ['site-feature-image.jpg']
-  title = 'My cool site'
   [params.social]
-  facebook_admin = 'jsmith'
+  facebook_app_id = '12345678'
 [taxonomies]
   series = 'series'
 {{}}
@@ -132,31 +139,78 @@ audio = []
 videos = []
 series = []
 tags = []
+locale = 'en-US'
 {{}}
 
-Hugo uses the page title and description for the title and description metadata. The first 6 URLs from the `images` array are used for image metadata. If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata.
+### Metadata {#metadata-open-graph}
+
+Hugo emits the following metadata:
+
+`og:url`
+: The page permalink.
+
+`og:site_name`
+: The site title, falling back to the site configuration's `params.title` value.
+
+`og:title`
+: The page title, falling back to the site title, then the site configuration's `params.title` value.
+
+`og:description`
+: The page description, falling back to the page summary, then the site configuration's `params.description` value.
+
+`og:locale`
+: The `locale` front matter value, falling back to the site language's `locale`; hyphens are replaced with underscores (e.g. `en-US` → `en_US`).
+
+`og:type`
+: The value is `article` for pages and `website` for list and home pages.
 
-Various optional metadata can also be set:
+For article pages, Hugo also emits:
 
-- Date, published date, and last modified data are used to set the published time metadata if specified.
-- `audio` and `videos` are URL arrays like `images` for the audio and video metadata tags, respectively.
-- The first 6 `tags` on the page are used for the tags metadata.
-- The `series` taxonomy is used to specify related "see also" pages by placing them in the same series.
+`article:section`
+: The page's top-level section.
 
-If using YouTube this will produce a og:video tag like ``. Use the `https://youtu.be/` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`).
+`article:published_time`
+: The page's publish date.
+
+`article:modified_time`
+: The page's last modified date.
+
+`article:tag`
+: The first 6 tags.
+
+For image metadata, Hugo emits up to 6 `og:image` tags.
+
+{{% include "/_common/embedded-get-page-images.md" %}}
+
+`audio` and `videos` are `[]string` front matter parameters. Hugo emits up to 6 `og:audio` and `og:video` tags, passing each value through `absURL`, which converts relative paths to absolute URLs. Unlike `images`, Hugo does not search page resources or global resources for these values.
+
+The `series` taxonomy is used to populate `og:see_also` metadata. Hugo emits up to 7 `og:see_also` tags using the first 7 pages in the same series as the current page, excluding the current page itself.
+
+For Facebook metadata, if the site configuration's `params.social.facebook_app_id` value is set, Hugo emits `fb:app_id`. Otherwise, if the site configuration's `params.social.facebook_admin` value is set, Hugo emits `fb:admins`.
 
 ## Pagination
 
-See [details](/templates/pagination/).
+> [!note]
+> To override Hugo's embedded pagination template, copy the [source code](<{{% eturl pagination %}}>) 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" . }}`
+
+Hugo includes an embedded template for rendering navigation links between pagers. To include the embedded template:
+
+```go-html-template
+{{ partial "pagination.html" . }}
+```
+
+The embedded pagination template has two formats: `default` and `terse`. The `terse` format has fewer controls and page slots, consuming less space when styled as a horizontal list. See [pagination][] for details.
 
 ## Schema
 
 > [!note]
-> To override Hugo's embedded Schema template, copy the [source code](<{{% eturl schema %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+> To override Hugo's embedded Schema template, copy the [source code](<{{% eturl schema %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`][] function:
 >
 > `{{ partial "schema.html" . }}`
 
-Hugo includes an embedded template to render [microdata] `meta` elements within the `head` element of your templates.
+Hugo includes an embedded template to render [microdata][] `meta` elements within the `head` element of your templates.
 
 To include the embedded template:
 
@@ -164,14 +218,63 @@ To include the embedded template:
 {{ partial "schema.html" . }}
 ```
 
+### Configuration {#configuration-schema}
+
+Hugo's Schema template uses a mix of page data and [front matter][] values on individual pages.
+
+{{< code-toggle file=hugo >}}
+title = 'My cool site'
+[params]
+  description = 'Text about my cool site'
+{{}}
+
+{{< code-toggle file=content/blog/my-post.md fm=true >}}
+title = 'Post title'
+description = 'Text about this post'
+date = 2024-03-08T08:18:11-08:00
+lastmod = 2024-03-09T12:00:00-08:00
+images = ['post-cover.png']
+keywords = ['ssg', 'hugo']
+{{}}
+
+### Metadata {#metadata-schema}
+
+Hugo emits the following microdata:
+
+`name`
+: The page title, falling back to the site title.
+
+`description`
+: The page description, falling back to the page summary, then the site configuration's `params.description` value.
+
+`datePublished`
+: The page's publish date.
+
+`dateModified`
+: The page's last modified date.
+
+`wordCount`
+: The page's word count.
+
+For image metadata, Hugo emits up to 6 `image` tags.
+
+{{% include "/_common/embedded-get-page-images.md" %}}
+
+For keyword metadata, Hugo uses the following order of precedence:
+
+1. Titles of `keywords` taxonomy terms, if `keywords` is defined as a taxonomy
+1. The `keywords` front matter value, if `keywords` is not a taxonomy
+1. Titles of `tags` taxonomy terms
+1. Titles of all taxonomy terms
+
 ## X (Twitter) Cards
 
 > [!note]
-> To override Hugo's embedded Twitter Cards template, copy the [source code](<{{% eturl twitter_cards %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`] function:
+> To override Hugo's embedded Twitter Cards template, copy the [source code](<{{% eturl twitter_cards %}}>) to a file with the same name in the `layouts/_partials` directory, then call it from your templates using the [`partial`][] function:
 >
 > `{{ partial "twitter_cards.html" . }}`
 
-Hugo includes an embedded template for [X (Twitter) Cards](https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards), metadata used to attach rich media to Tweets linking to your site.
+Hugo includes an embedded template for [X (Twitter) Cards][], metadata used to attach rich media to Tweets linking to your site.
 
 To include the embedded template:
 
@@ -181,12 +284,14 @@ To include the embedded template:
 
 ### Configuration {#configuration-x-cards}
 
-Hugo's X (Twitter) Card template is configured using a mix of configuration settings and [front-matter](/content-management/front-matter/) values on individual pages.
+Hugo's X (Twitter) Card template is configured using a mix of configuration settings and [front matter][] values on individual pages.
 
 {{< code-toggle file=hugo >}}
 [params]
-  images = ["site-feature-image.jpg"]
   description = 'Text about my cool site'
+  images = ["site-feature-image.jpg"]
+  [params.social]
+  twitter = 'GoHugoIO'
 {{}}
 
 {{< code-toggle file=content/blog/my-post.md fm=true >}}
@@ -195,25 +300,33 @@ description = 'Text about this post'
 images = ["post-cover.png"]
 {{}}
 
-If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. If no image resources with those names are found, the images defined in your [project configuration](/configuration/) are used instead. If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`.
+### Metadata {#metadata-x-cards}
 
-Hugo uses the page title and description for the card's title and description fields. The page summary is used if no description is given.
+If an image is found, Hugo sets `twitter:card` to `summary_large_image` and emits a `twitter:image` tag using the first image found. If no image is found, Hugo sets `twitter:card` to `summary` and omits the image tag.
 
-Set the value of `twitter:site` in your project configuration:
+{{% include "/_common/embedded-get-page-images.md" %}}
 
-{{< code-toggle file=hugo >}}
-[params.social]
-twitter = 'GoHugoIO'
-{{}}
+Hugo also emits the following metadata:
 
-NOTE: The `@` will be added for you
+`twitter:title`
+: The page title, falling back to the site title, then the site configuration's `params.title` value.
 
-```html
-
-```
+`twitter:description`
+: The page description, falling back to the page summary, then the site configuration's `params.description` value.
+
+`twitter:site`
+: The site configuration's `params.social.twitter` value. The `@` prefix is added automatically if not already present. For example, with `twitter = 'GoHugoIO'` in your configuration, Hugo renders:
+
+  ```html
+  
+  ```
 
-[`partial`]: /functions/partials/include/
 [Disqus]: https://disqus.com
+[pagination]: /templates/pagination/
 [Google Analytics 4]: https://support.google.com/analytics/answer/10089681
+[Open Graph protocol]: https://ogp.me/
+[X (Twitter) Cards]: https://developer.x.com/en/docs/twitter-for-websites/cards/overview/abouts-cards
+[`partial`]: /functions/partials/include/
+[front matter]: /content-management/front-matter/
 [microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata
 [signing up]: https://disqus.com/profile/signup/
diff --git a/data/docs.yaml b/data/docs.yaml
index 1313895c1e..d94e3c275e 100644
--- a/data/docs.yaml
+++ b/data/docs.yaml
@@ -1272,6 +1272,8 @@ config:
   ignoreVendorPaths: ''
   imaging:
     anchor: smart
+    avif:
+      encoderSpeed: 10
     bgColor: ffffff
     compression: lossy
     exif:
@@ -2043,6 +2045,8 @@ config:
       weight: 0
   sectionPagesMenu: ''
   security:
+    allowContent:
+    - '! ^text/html$'
     enableInlineShortcodes: false
     exec:
       allow:
@@ -2251,12 +2255,12 @@ tpl:
         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:
@@ -2277,11 +2281,11 @@ tpl:
         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") }}'
@@ -2317,6 +2321,7 @@ tpl:
           Dictionary creates a new map from the given parameters by
           treating values as key-value pairs.  The number of values must be even.
           The keys can be string slices, which will create the needed nested structure.
+          If no values are provided, nil will be returned.
         Examples: []
       First:
         Aliases:
@@ -2356,9 +2361,9 @@ tpl:
           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:
@@ -2408,7 +2413,7 @@ tpl:
         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 }}'
@@ -2455,9 +2460,9 @@ tpl:
         - 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
@@ -2546,7 +2551,7 @@ tpl:
         - 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 }}'
@@ -2722,10 +2727,10 @@ tpl:
           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:
@@ -3147,7 +3152,7 @@ tpl:
         - 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:
@@ -3211,7 +3216,7 @@ tpl:
         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" }}'
@@ -3225,7 +3230,7 @@ tpl:
         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" }}'
@@ -3833,16 +3838,16 @@ tpl:
           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:
@@ -4188,7 +4193,7 @@ tpl:
           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.
@@ -4562,7 +4567,7 @@ tpl:
         - 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 }}'
@@ -4612,11 +4617,15 @@ tpl:
         - highlight
         Args:
         - s
-        - lang
-        - opts
+        - args
         Description: |-
-          Highlight returns a copy of s as an HTML string with syntax
+          Highlight returns a copy of CODE as an HTML string with syntax
           highlighting applied.
+          
+          	transform.Highlight CODE [LANG] [OPTIONS]
+          
+          LANG is optional; it can also be set via the type option in OPTIONS, which
+          makes this work the same way as HighlightCodeBlock.
         Examples: []
       HighlightCodeBlock:
         Aliases: null