Update docs for v0.141.0

Closes #2808

Author: jmooring

assets/images/examples/mask.png

@@ -39,11 +39,11 @@ respectDoNotTrack = false
 [privacy.instagram]
 disable = false
 simple = false
-[privacy.twitter]
+[privacy.vimeo]
 disable = false
 enableDNT = false
 simple = false
-[privacy.vimeo]
+[privacy.x]
 disable = false
 enableDNT = false
 simple = false
@@ -64,10 +64,10 @@ disable = true
 disable = true
 [privacy.instagram]
 disable = true
-[privacy.twitter]
-disable = true
 [privacy.vimeo]
 disable = true
+[privacy.x]
+disable = true
 [privacy.youtube]
 disable = true
 {{< /code-toggle >}}
@@ -92,19 +92,19 @@ simple
 disableInlineCSS = true
 {{< /code-toggle >}}
 
-### Twitter
+### X
 
 enableDNT
-: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads.
+: Enabling this for the x shortcode, the post and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads.
 
 simple
-: If simple mode is enabled, a static and no-JS version of a tweet will be built.
+: If simple mode is enabled, a static and no-JS version of a post will be built.
 
-**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inline styles provided by Hugo:
+**Note:** If you use the _simple mode_ for X, you may want to disable the inline styles provided by Hugo:
 
 {{< code-toggle file=hugo >}}
 [services]
-[services.twitter]
+[services.x]
 disableInlineCSS = true
 {{< /code-toggle >}}
 

content/en/about/privacy.md

@@ -72,7 +72,6 @@ hugo [flags]
 * [hugo completion](/commands/hugo_completion/)	 - Generate the autocompletion script for the specified shell
 * [hugo config](/commands/hugo_config/)	 - Display site configuration
 * [hugo convert](/commands/hugo_convert/)	 - Convert front matter to another format
-* [hugo deploy](/commands/hugo_deploy/)	 - Deploy your site to a cloud provider
 * [hugo env](/commands/hugo_env/)	 - Display version and environment info
 * [hugo gen](/commands/hugo_gen/)	 - Generate documentation and syntax highlighting styles
 * [hugo import](/commands/hugo_import/)	 - Import a site from another system

content/en/commands/hugo.md

@@ -193,14 +193,14 @@ Step 3
 {{/* Get remote data. */}}
 {{ $data := dict }}
 {{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "Unable to get remote resource %s: %s" $url . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ $data = . | transform.Unmarshal }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %s" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %s" $url }}
 {{ end }}
 
 {{/* Add pages and page resources. */}}
@@ -223,10 +223,10 @@ Step 3
   {{/* Add page resource. */}}
   {{ $item := . }}
   {{ with $url := $item.cover }}
-    {{ with resources.GetRemote $url }}
+    {{ with try (resources.GetRemote $url) }}
       {{ with .Err }}
         {{ errorf "Unable to get remote resource %s: %s" $url . }}
-      {{ else }}
+      {{ else with .Value }}
         {{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
         {{ $params := dict "alt" $item.title }}
         {{ $resource := dict
@@ -235,9 +235,9 @@ Step 3
           "path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
         }}
         {{ $.AddResource $resource }}
+      {{ else }}
+        {{ errorf "Unable to get remote resource %s" $url }}
       {{ end }}
-    {{ else }}
-      {{ errorf "Unable to get remote resource %s" $url }}
     {{ end }}
   {{ end }}
 

content/en/content-management/content-adapters.md

@@ -88,15 +88,15 @@ Example 3: A more concise way to skip image rendering if the resource is not fou
 Example 4: Skips rendering if there's problem accessing a remote resource.
 
 ```go-html-template
-{{ $u := "https://gohugo.io/img/hugo-logo.png" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://gohugo.io/img/hugo-logo.png" }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $u }}
 {{ end }}
 ```
 

content/en/content-management/image-processing/index.md

@@ -157,22 +157,3 @@ pattern
 
 toLower
 : (`bool`) See above.
-
-## Performance considerations
-
-**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast.
-
-This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread:
-
-{{< tweet user="scott_lowe" id="898398437527363585" >}}
-
-Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog.
-
-He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that:
-
-* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before.
-* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites.
-
-{{% note %}}
-We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
-{{% /note %}}

content/en/content-management/related.md

@@ -498,8 +498,6 @@ Rendered:
 {{% note %}}
 To override Hugo's embedded `twitter` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
 
-You may call the `twitter` shortcode by using its `tweet` alias.
-
 [source code]: {{% eturl twitter %}}
 {{% /note %}}
 

content/en/content-management/shortcodes.md

@@ -134,16 +134,16 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`]
 
 ```go-html-template
 {{ $data := dict }}
-{{ $u := "https://example.org/pets.csv" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://example.org/pets.csv" }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ $opts := dict "delimiter" "," }}
     {{ $data = . | transform.Unmarshal $opts }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $u }}
 {{ end }}
 ```
 

content/en/functions/data/GetCSV.md

@@ -137,15 +137,15 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`]
 
 ```go-html-template
 {{ $data := dict }}
-{{ $u := "https://example.org/books.json" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://example.org/books.json" }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value }}
     {{ $data = . | transform.Unmarshal }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $u }}
 {{ end }}
 ```
 

content/en/functions/data/GetJSON.md

@@ -25,16 +25,16 @@ https://api.github.com/repos/gohugoio/hugo/readme
 To retrieve and render the content:
 
 ```go-html-template
-{{ $u := "https://api.github.com/repos/gohugoio/hugo/readme" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://api.github.com/repos/gohugoio/hugo/readme" }}
+{{ with try (resources.GetRemote $url) }}
   {{ with .Err }}
     {{ errorf "%s" . }}
-  {{ else }}
+  {{ else with .Value}}
     {{ with . | transform.Unmarshal }}
       {{ .content | base64Decode | markdownify }}
     {{ end }}
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
   {{ end }}
-{{ else }}
-  {{ errorf "Unable to get remote resource %q" $u }}
 {{ end }}
 ```

content/en/functions/encoding/Base64Decode.md

@@ -13,7 +13,7 @@ action:
 toc: true
 ---
 
-The `return` statement is a custom addition to Go's [text/template] package. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
+The `return` statement is a non-standard extension to Go's [text/template package]. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
 
 The returned value may be of any data type including, but not limited to, [`bool`], [`float`], [`int`], [`map`], [`resource`], [`slice`], and [`string`].
 

content/en/functions/go-template/return.md

@@ -0,0 +1,110 @@
+---
+title: try
+description: Returns a TryValue object after evaluating the given expression.
+categories: []
+keywords: []
+action:
+  aliases: []
+  related: []
+  returnType: TryValue
+  signatures: ['try EXPRESSION']
+toc: true
+---
+
+{{< 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.
+
+[text/template]: https://pkg.go.dev/text/template
+
+## Methods
+
+The `TryValue` object encapsulates the result of evaluating the expression, and provides two methods:
+
+Err
+: (`string`) Returns a string representation of the error thrown by the expression, if an error occurred, or returns `nil` if the expression evaluated without errors.
+
+Value
+: (`any`) Returns the result of the expression if the evaluation was successful, or returns `nil` if an error occurred while evaluating the expression.
+
+## Explanation
+
+By way of example, let's divide a number by zero:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ $result := div $x $y }}
+{{ printf "%v divided by %v equals %v" $x $y .Value }}
+```
+
+As expected, the example above throws an error and fails the build:
+
+```terminfo
+Error: error calling div: can't divide the value by 0
+```
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ with try (div $x $y) }}
+  {{ with .Err }}
+    {{ warnf "%s" . }}
+  {{ else }}
+    {{ printf "%v divided by %v equals %v" $x $y .Value }}
+  {{ end }}
+{{ end }}
+```
+
+The error thrown by the expression is logged to the console as a warning:
+
+```terminfo
+WARN error calling div: can't divide the value by 0
+```
+
+Now let's change the arguments to avoid dividing by zero:
+
+```go-html-template
+{{ $x := 42 }}
+{{ $y := 6 }}
+{{ with try (div $x $y) }}
+  {{ with .Err }}
+    {{ warnf "%s" . }}
+  {{ else }}
+    {{ printf "%v divided by %v equals %v" $x $y .Value }}
+  {{ end }}
+{{ end }}
+```
+
+Hugo renders the above to:
+
+```html
+42 divided by 6 equals 7
+```
+
+## 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.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+  {{ with .Err }}
+    {{ warnf "%s" . }}
+  {{ else with .Value }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ else }}
+    {{ errorf "Unable to get remote resource %q" $url }}
+  {{ end }}
+{{ end }}
+```
+
+{{% note %}}
+Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
+{{% /note %}}

content/en/functions/go-template/try.md

@@ -0,0 +1,45 @@
+---
+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.
+
+## Usage
+
+Create the filter:
+
+```go-html-template
+{{ $filter := images.Mak "images/mask.png" }}
+```
+
+{{% include "functions/images/_common/apply-image-filter.md" %}}
+
+## 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
+>}}