Merge commit 'dec8cd4ada29218971743333f8ac662a9c06aad8'

docs/_vendor/modules.txt

@@ -1 +1 @@
-# github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472
+# github.com/gohugoio/gohugoioTheme v0.0.0-20240815082608-66ccd383a90f

docs/content/en/about/features.md

@@ -49,7 +49,7 @@ toc: true
 : Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
 
 [Markdown render hooks]
-: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
+: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
 
 [Diagrams]
 : Use fenced code blocks and Markdown render hooks to include diagrams in your content.

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

@@ -125,7 +125,7 @@ Set any [front matter field] in the map passed to the [`AddPage`](#addpage) meth
 
 This table describes the fields most commonly passed to the `AddPage` method.
 
-Key|Descripion|Required
+Key|Description|Required
 :--|:--|:-:
 `content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.| 
 `content.value`|The content value as a string.| 
@@ -148,7 +148,7 @@ When setting the `path`, Hugo transforms the given string to a logical path. For
 
 Construct the map passed to the [`AddResource`](#addresource) method using the fields below.
 
-Key|Descripion|Required
+Key|Description|Required
 :--|:--|:-:
 `content.mediaType`|The content [media type].|:heavy_check_mark:
 `content.value`|The content value as a string or resource.|:heavy_check_mark:

docs/content/en/content-management/multilingual.md

@@ -21,16 +21,23 @@ This is the default language configuration:
 
 In the above, `en` is the language key.
 
-{{% note %}}
-Each language key must conform to the syntax described in [RFC 5646]. You must use hyphens to separate subtags. For example:
+
+Language keys must conform to the syntax described in [RFC 5646]. For example:
 
 - `en`
-- `en-GB`
-- `pt-BR`
+- `en-US`
 
-[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. Omit the `art-x-` prefix from the language key. For example:
+
+- `hugolang`
+
+{{% note %}}
+Private use subtags must not exceed 8 alphanumeric characters.
 {{% /note %}}
 
+[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
+
 This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration.
 
 {{< code-toggle file=hugo >}}

docs/content/en/content-management/page-resources.md

@@ -1,6 +1,6 @@
 ---
 title: Page resources
-description: Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata.
+description: Use page resources to logically associate assets with a page.
 categories: [content management]
 keywords: [bundle,content,resources]
 menu:
@@ -37,82 +37,83 @@ content
         └── index.md (root of page bundle)
 ```
 
-## Properties
+## Examples
 
-ResourceType
-: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`.
+Use any of these methods on a `Page` object to capture page resources:
 
-Name
-: Default value is the file name (relative to the owning page). Can be set in front matter.
+ - [`Resources.ByType`]
+ - [`Resources.Get`]
+ - [`Resources.GetMatch`]
+ - [`Resources.Match`]
 
-Title
-: Default value is the same as `.Name`. Can be set in front matter.
+ Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action. 
 
-Permalink
-: The absolute URL to the resource. Resources of type `page` will have no value.
+[`Resource`]: /methods/resource
+[`Resources.ByType`]: /methods/page/resources#bytype
+[`Resources.GetMatch`]: /methods/page/resources#getmatch
+[`Resources.Get`]: /methods/page/resources#get
+[`Resources.Match`]: /methods/page/resources#match
 
-RelPermalink
-: The relative URL to the resource. Resources of type `page` will have no value.
+The following examples assume this content structure:
 
-Content
-: The content of the resource itself. For most resources, this returns a string
-with the contents of the file. Use this to create inline resources.
-
-```go-html-template
-{{ with .Resources.GetMatch "script.js" }}
-  <script>{{ .Content | safeJS }}</script>
-{{ end }}
+```text
+content/
+└── example/
+    ├── data/
+    │  └── books.json   <-- page resource
+    ├── images/
+    │  ├── a.jpg        <-- page resource
+    │  └── b.jpg        <-- page resource
+    ├── snippets/
+    │  └── text.md      <-- page resource
+    └── index.md
+```
 
-{{ with .Resources.GetMatch "style.css" }}
-  <style>{{ .Content | safeCSS }}</style>
-{{ end }}
+Render a single image, and throw an error if the file does not exist:
 
-{{ with .Resources.GetMatch "img.png" }}
-  <img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}">
+```go-html-template
+{{ $path := "images/a.jpg" }}
+{{ with .Resources.Get $path }}
+  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ else }}
+  {{ errorf "Unable to get page resource %q" $path }}
 {{ end }}
 ```
 
-MediaType.Type
-: The media type (formerly known as a MIME type) of the resource (e.g., `image/jpeg`).
-
-MediaType.MainType
-: The main type of the resource's media type (e.g., `image`).
-
-MediaType.SubType
-: The subtype of the resource's type (e.g., `jpeg`). This may or may not correspond to the file suffix.
-
-MediaType.Suffixes
-: A slice of possible file suffixes for the resource's media type (e.g., `[jpg jpeg jpe jif jfif]`).
-
-## Methods
-
-ByType
-: Returns the page resources of the given type.
+Render all images, resized to 300 px wide:
 
 ```go-html-template
-{{ .Resources.ByType "image" }}
+{{ range .Resources.ByType "image" }}
+  {{ with .Resize "300x" }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ end }}
+{{ end }}
 ```
-Match
-: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive.
+
+Render the markdown snippet:
 
 ```go-html-template
-{{ .Resources.Match "images/*" }}
+{{ with .Resources.Get "snippets/text.md" }}
+  {{ .Content }}
+{{ end }}
 ```
 
-GetMatch
-: Same as `Match` but will return the first match.
-
-### Pattern matching
+List the titles in the data file, and throw an error if the file does not exist.
 
-```go
-// Using Match/GetMatch to find this images/sunset.jpg ?
-.Resources.Match "images/sun*" ✅
-.Resources.Match "**/sunset.jpg" ✅
-.Resources.Match "images/*.jpg" ✅
-.Resources.Match "**.jpg" ✅
-.Resources.Match "*" 🚫
-.Resources.Match "sunset.jpg" 🚫
-.Resources.Match "*sunset.jpg" 🚫
+```go-html-template
+{{ $path := "data/books.json" }}
+{{ with .Resources.Get $path }}
+  {{ with . | transform.Unmarshal }}
+    <p>Books:</p>
+    <ul>
+      {{ range . }}
+        <li>{{ .title }}</li>
+      {{ end }}
+    </ul>
+  {{ end }}
+{{ else }}
+  {{ errorf "Unable to get page resource %q" $path }}
+{{ end }}
 ```
 
 ## Metadata
@@ -124,21 +125,21 @@ Resources of type `page` get `Title` etc. from their own front matter.
 {{% /note %}}
 
 name
-: Sets the value returned in `Name`.
+: (`string`) Sets the value returned in `Name`.
 
 {{% note %}}
 The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
 {{% /note %}}
 
 title
-: Sets the value returned in `Title`
+: (`string`) Sets the value returned in `Title`
 
 params
-: A map of custom key-value pairs.
+: (`map`) A map of custom key-value pairs.
 
 ### Resources metadata example
 
-{{< code-toggle >}}
+{{< code-toggle file=content/example.md fm=true >}}
 title: Application
 date : 2018-01-25
 resources :
@@ -173,7 +174,7 @@ From the example above:
 - Every docx in the bundle will receive the `word` icon.
 
 {{% note %}}
-The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
+The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
 {{% /note %}}
 
 ### The `:counter` placeholder in `name` and `title`

docs/content/en/contribute/development.md

@@ -48,7 +48,7 @@ For a complete guide to contributing to Hugo, see the [Contribution Guide].
 To build the extended edition of Hugo from source you must:
 
 1. Install [Git]
-1. Install [Go] version 1.20 or later
+1. Install [Go] version 1.23.0 or later
 1. Install a C compiler, either [GCC] or [Clang]
 1. Update your `PATH` environment variable as described in the [Go documentation]
 

docs/content/en/functions/go-template/_common/truthy-falsy.md

@@ -2,4 +2,6 @@
 # Do not remove front matter.
 ---
 
-In Go templates, the falsy values are `false`, `0`, any nil pointer or interface value, and any array, slice, map, or string of length zero. Everything else is truthy.
+The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values.
+
+Everything else is truthy.

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

@@ -34,7 +34,7 @@ Use with the [`else`] statement:
 {{ end }}
 ```
 
-Use `else if` to check multiple conditions.
+Use `else if` to check multiple conditions:
 
 ```go-html-template
 {{ $var := 12 }}

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

@@ -36,6 +36,20 @@ Use with the [`else`] statement:
 {{ end }}
 ```
 
+Use `else with` to check multiple conditions:
+
+```go-html-template
+{{ $v1 := 0 }}
+{{ $v2 := 42 }}
+{{ with $v1 }}
+  {{ . }}
+{{ else with $v2 }}
+  {{ . }} → 42
+{{ else }}
+  {{ print "v1 and v2 are falsy" }}
+{{ end }}
+```
+
 Initialize a variable, scoped to the current block:
 
 ```go-html-template