Merge commit '346b60358d'

docs/content/en/functions/go-template/range.md

@@ -43,7 +43,7 @@ Within a range block:
 
 ## Understanding context
 
-At the top of a page template, the [context] (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
+At the top of a page template, the [context](g) (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
 
 With this contrived example that uses the [`seq`] function to generate a slice of integers:
 
@@ -76,7 +76,6 @@ Gaining a thorough understanding of context is critical for anyone writing templ
 {{% /note %}}
 
 [`seq`]: /functions/collections/seq/
-[context]: /getting-started/glossary/#context
 
 ## Array or slice of scalars
 

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

@@ -13,21 +13,12 @@ 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`].
+The returned value may be of any data type including, but not limited to, [`bool`](g), [`float`](g), [`int`](g), [`map`](g), [`resource`](g), [`slice`](g), or [`string`](g).
 
 A `return` statement without a value returns an empty string of type `template.HTML`.
 
-[`bool`]: /getting-started/glossary/#bool
-[`float`]: /getting-started/glossary/#float
-[`int`]: /getting-started/glossary/#int
-[`map`]: /getting-started/glossary/#map
-[`resource`]: /getting-started/glossary/#resource
-[`slice`]: /getting-started/glossary/#slice
-[`string`]: /getting-started/glossary/#string
-[text/template]: https://pkg.go.dev/text/template
-
 {{% note %}}
 Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below.
 {{% /note %}}

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

@@ -0,0 +1,113 @@
+---
+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 }}
+    {{ warnf "Unable to get remote resource %q" $url }}
+  {{ end }}
+{{ end }}
+```
+In the above, note that the [context](g) within the last conditional block is the `TryValue` object returned by the `try` statement. At this point neither the `Err` nor `Value` methods returned anything, so the current context is not useful. Use the `$` to access the [template context] if needed.
+
+[template context]: /templates/introduction/#template-context
+
+{{% note %}}
+Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
+{{% /note %}}

docs/content/en/functions/go-template/with.md

@@ -62,7 +62,7 @@ Initialize a variable, scoped to the current block:
 
 ## Understanding context
 
-At the top of a page template, the [context] (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
+At the top of a page template, the [context](g) (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
 
 With this contrived example:
 
@@ -94,8 +94,6 @@ This template will render the page title as desired:
 Gaining a thorough understanding of context is critical for anyone writing template code.
 {{% /note %}}
 
-[context]: /getting-started/glossary/#context
-
 {{% include "functions/go-template/_common/text-template.md" %}}
 
 [`else`]: /functions/go-template/else/