Merge commit '346b60358dd8ec2ca228e6635bff9d7914b398b7'

2025-08-19 21:21:39 +02:00 · 2025-01-23 09:47:46 +01:00
parent 7f0f50b133 346b60358d
commit 43307b07f8
384 changed files with 3305 additions and 3271 deletions
--- a/docs/content/en/functions/images/Config.md
+++ b/docs/content/en/functions/images/Config.md
@@ -25,12 +25,9 @@ See [image processing] for an overview of Hugo's image pipeline.
 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], [page], and [remote] resources. See the [image processing] section for details.
+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.

 [`Width`]: /methods/resource/width/
 [`Height`]: /methods/resource/height/
-[global]: /getting-started/glossary/#global-resource
 [image processing]: /content-management/image-processing/
-[page]: /getting-started/glossary/#page-resource
-[remote]: /getting-started/glossary/#remote-resource
 {{% /note %}}
--- a/docs/content/en/functions/images/Dither.md
+++ b/docs/content/en/functions/images/Dither.md
@@ -117,11 +117,10 @@ This example uses the default dithering options.
 Regardless of dithering method, do both of the following to obtain the best results:

 1. Scale the image _before_ dithering
-2. Output the image to a lossless format such as GIF or PNG
+1. Output the image to a lossless format such as GIF or PNG

 The example below does both of these, and it sets the dithering palette to the three most dominant colors in the image.

-
 ```go-html-template
 {{ with resources.Get "original.jpg" }}
  {{ $opts := dict
@@ -157,6 +156,6 @@ For best results, if the dithering palette is grayscale, convert the image to gr
 The example above:

 1. Resizes the image to be 800 px wide
-2. Converts the image to grayscale
-3. Dithers the image using the default (`FloydSteinberg`) dithering method with a grayscale palette
-4. Converts the image to the PNG format
+1. Converts the image to grayscale
+1. Dithers the image using the default (`FloydSteinberg`) dithering method with a grayscale palette
+1. Converts the image to the PNG format
--- a/docs/content/en/functions/images/Mask.md
+++ b/docs/content/en/functions/images/Mask.md
@@ -0,0 +1,80 @@
+---
+title: images.Mask
+description: Returns an image filter that applies a mask to the source image.
+categories: []
+keywords: []
+action:
+  aliases: []
+  related:
+    - functions/images/Filter
+    - methods/resource/Filter
+  returnType: images.filter
+  signatures: [images.Mask RESOURCE]
+toc: true
+---
+
+{{< new-in 0.141.0 >}}
+
+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 pipelie, 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.
+{{% /note %}}
+
+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 [site configuration]. You can override that color with a `Process` image filter:
+
+```go-html-template
+{{ $filter := images.Process "#00ff00" }}
+```
+
+[site configuration]: /content-management/image-processing/#imaging-configuration
+
+## Usage
+
+Create a slice of filters, one for WebP conversion and the other for mask application:
+
+```go-html-template
+{{ $filter1 := images.Process "webp" }}
+{{ $filter2 := images.Mask (resources.Get "images/mask.png") }}
+{{ $filters := slice $filter1 $filter2 }}
+```
+
+Apply the filters using the [`images.Filter`] function:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+  {{ with . | images.Filter $filters }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
+{{ end }}
+```
+
+You can also apply the filter using the [`Filter`] method on a 'Resource' object:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+  {{ with .Filter $filters }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
+{{ end }}
+```
+
+[`images.Filter`]: /functions/images/filter/
+[`Filter`]: /methods/resource/filter/
+
+## Example
+
+Mask
+
+{{< img
+  src="images/examples/mask.png"
+  example=false
+>}}
+
+{{< img
+  src="images/examples/zion-national-park.jpg"
+  alt="Zion National Park"
+  filter="mask"
+  filterArgs="images/examples/mask.png"
+  example=true
+>}}
--- a/docs/content/en/functions/images/Overlay.md
+++ b/docs/content/en/functions/images/Overlay.md
@@ -27,11 +27,7 @@ Capture the overlay image as a resource:
 {{ end }}
 ```

-The overlay image can be a [global resource], a [page resource], or a [remote resource].
-
-[global resource]: /getting-started/glossary/#global-resource
-[page resource]: /getting-started/glossary/#page-resource
-[remote resource]: /getting-started/glossary/#remote-resource
+The overlay image can be a [global resource](g), a [page resource](g), or a [remote resource](g).

 Create the filter:

--- a/docs/content/en/functions/images/Process.md
+++ b/docs/content/en/functions/images/Process.md
@@ -72,7 +72,6 @@ hint

 [`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp

-
 ```go-html-template
 {{ $filter := images.Process "webp" "icon" }}
 {{ $filter := images.Process "crop 200x200 center r90 webp q50 icon" }}
--- a/docs/content/en/functions/images/QR.md
+++ b/docs/content/en/functions/images/QR.md
@@ -109,4 +109,4 @@ https://gohugo.io

 The `qr` shortcode accepts several arguments including `level` and `scale`. See the [related documentation] for details.

-[related documentation]: /content-management/shortcodes/#qr
+[related documentation]: /shortcodes/qr/
--- a/docs/content/en/functions/images/Text.md
+++ b/docs/content/en/functions/images/Text.md
@@ -17,11 +17,15 @@ toc: true

 Although none of the options are required, at a minimum you will want to set the `size` to be some reasonable percentage of the image height.

+alignx
+ {{< new-in 0.141.0 >}}
+: (`string`) The horizontal alignment of the text relative to the horizontal offset, one of `left`, `center`, or `right`. Default is `left`.
+
 color
 : (`string`) The font color, either a 3-digit or 6-digit hexadecimal color code. Default is `#ffffff` (white).

 font
-: (`resource.Resource`) The font can be a [global resource], a [page resource], or a [remote resource]. Default is [Go Regular], a proportional sans-serif TrueType font.
+: (`resource.Resource`) The font can be a [global resource](g), a [page resource](g), or a [remote resource](g). Default is [Go Regular], a proportional sans-serif TrueType font.

 [Go Regular]: https://go.dev/blog/go-fonts#sans-serif

@@ -37,58 +41,74 @@ x
 y
 : (`int`) The vertical offset, in pixels, relative to the top of the image. Default is `10`.

-alignx
- {{< new-in 0.141.0 >}}
-: (`string`) The horizontal alignment of the text relative to the `x` position. One of `left`, `center`, or `right`. Default is `left`.
-
-[global resource]: /getting-started/glossary/#global-resource
-[page resource]: /getting-started/glossary/#page-resource
-[remote resource]: /getting-started/glossary/#remote-resource
-
 ## Usage

+Set the text and paths:
+
+```go-html-template
+{{ $text := "Zion National Park" }}
+{{ $fontPath := "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf" }}
+{{ $imagePath := "images/original.jpg" }}
+```
+
 Capture the font as a resource:

 ```go-html-template
 {{ $font := "" }}
-{{ $path := "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf" }}
-{{ with resources.GetRemote $path }}
+{{ with try (resources.GetRemote $fontPath) }}
  {{ with .Err }}
    {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
    {{ $font = . }}
+  {{ else }}
+    {{ errorf "Unable to get resource %s" $fontPath }}
  {{ end }}
-{{ else }}
-  {{ errorf "Unable to get resource %q" $path }}
 {{ end }}
 ```

-Create the options map:
+Create the filter, centering the text horizontally and vertically:

 ```go-html-template
-{{ $opts := dict
-  "color" "#fbfaf5"
-  "font" $font
-  "linespacing" 8
-  "size" 40
-  "x" 25
-  "y" 190
-}}
+{{ $r := "" }}
+{{ $filter := "" }}
+{{ with $r = resources.Get $imagePath }}
+  {{ $opts := dict
+    "alignx" "center"
+    "color" "#fbfaf5"
+    "font" $font
+    "linespacing" 8
+    "size" 60
+    "x" (mul .Width 0.5 | int)
+    "y" (mul .Height 0.5 | int)
+  }}
+  {{ $filter = images.Text $text $opts }}
+{{ else }}
+  {{ errorf "Unable to get resource %s" $imagePath }}
+{{ end }}
 ```

-Set the text:
+Apply the filter using the [`images.Filter`] function:

 ```go-html-template
-{{ $text := "Zion National Park" }}
+{{ with $r }}
+  {{ with . | images.Filter $filter }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
+{{ end }}
 ```

-Create the filter:
+You can also apply the filter using the [`Filter`] method on a `Resource` object:

 ```go-html-template
-{{ $filter := images.Text $text $opts }}
+{{ with $r }}
+  {{ with .Filter $filter }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
+{{ end }}
 ```

-{{% include "functions/images/_common/apply-image-filter.md" %}}
+[`images.Filter`]: /functions/images/filter/
+[`Filter`]: /methods/resource/filter/

 ## Example