More updates for v0.123.00

Closes gohugoio#2385
Closes gohugoio#2421

Author: jmooring

content/en/content-management/diagrams.md

@@ -6,8 +6,8 @@ keywords: [diagrams,drawing]
 menu:
   docs:
     parent: content-management
-    weight: 245
-weight: 245
+    weight: 260
+weight: 260
 toc: true
 ---
 {{< new-in 0.93.0 >}}

content/en/content-management/front-matter.md

@@ -36,8 +36,7 @@ date = 2024-02-02T04:14:54-08:00
 draft = false
 weight = 10
 [params]
-myparam = 42
-tags = ['red','blue']
+author = 'John Smith'
 {{< /code-toggle >}}
 
 Front matter fields may be [scalar], [arrays], or [maps] containing [boolean], [integer], [float], or [string] values. Note that the TOML format also supports date/time values using unquoted strings.
@@ -194,6 +193,8 @@ path
 
 ###### params
 
+{{< new-in 0.123.0 >}}
+
 (`map`) A map of custom [page parameters].
 
 [page parameters]: #parameters
@@ -262,23 +263,52 @@ path
 
 ## Parameters
 
-Specify custom page parameters, including taxonomy terms, under the `params` key in front matter:
+{{< new-in 0.123.0 >}}
+
+Specify custom page parameters under the `params` key in front matter:
 
 {{< code-toggle file=content/example.md fm=true >}}
 title = 'Example'
 date = 2024-02-02T04:14:54-08:00
 draft = false
 weight = 10
 [params]
-myparam = 42
-tags = ['red','blue']
+author = 'John Smith'
 {{< /code-toggle >}}
 
 Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object.
 
 [`param`]: /methods/page/param/
 [`params`]: /methods/page/params/
 
+## Taxonomies
+
+Classify content by adding taxonomy terms to front matter. For example, with this site configuration:
+
+{{< code-toggle file=hugo >}}
+[taxonomies]
+tag = 'tags'
+genre = 'genres'
+{{< /code-toggle >}}
+
+Add taxonomy terms as shown below:
+
+{{< code file=content/example.md >}}
+title = 'Example'
+date = 2024-02-02T04:14:54-08:00
+draft = false
+weight = 10
+tags = ['red','blue']
+genres = ['mystery','romance']
+[params]
+author = 'John Smith'
+{{< /code >}}
+
+Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object:
+
+[`Params`]: /methods/page/params/
+[`GetTerms`]: /methods/page/getterms/
+
 ## Cascade
 
 Any [node] can pass down to its descendants a set of front matter values.
@@ -356,7 +386,9 @@ If your [content format] is [Emacs Org Mode], you may provide front matter using
 #+TITLE: Example
 #+DATE: 2024-02-02T04:14:54-08:00
 #+DRAFT: false
-#+MYPARAM: 42
+#+AUTHOR: John Smith
+#+GENRES: mystery
+#+GENRES: romance
 #+TAGS: red
 #+TAGS: blue
 #+WEIGHT: 10

content/en/content-management/markdown-attributes.md

@@ -0,0 +1,115 @@
+---
+title: Markdown attributes
+description: Use mardown attributes to add HTML attributes when rendering markdown to HTML.
+categories: [content management]
+keywords: [goldmark,markdown]
+menu:
+  docs:
+    parent: content-management
+    weight: 240
+weight: 240
+toc: true
+---
+
+## Overview
+
+Hugo supports markdown attributes on images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.
+
+For example:
+
+```text
+This is a paragraph.
+{class="foo bar" id="baz"}
+```
+
+With `class` and `id` you can use shorthand notation:
+
+```text
+This is a paragraph.
+{.foo .bar #baz}
+```
+
+Hugo renders both of these to:
+
+```html
+<p class="foo bar" id="baz">This is a paragraph.</p>
+```
+
+## Block elements
+
+Update your site configuration to enable markdown attributes for block-level elements.
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser.attribute]
+title = true # default is true
+block = true # default is false
+{{< /code-toggle >}}
+
+
+## Standalone images
+
+By default, when the [Goldmark] markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification].
+
+[CommonMark specification]: https://spec.commonmark.org/current/
+[Goldmark]: https://github.com/yuin/goldmark
+
+If you were to place an attribute list beneath an image element, Hugo would apply the attributes to the surrounding paragraph, not the image.
+
+To apply attributes to a standalone image element, you must disable the default wrapping behavior:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.parser]
+wrapStandAloneImageWithinParagraph = false # default is true
+{{< /code-toggle >}}
+
+## Usage
+
+You may add [global HTML attributes], or HTML attributes specific to the current element type. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`.
+
+[global HTML attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
+
+The attribute list consists of one or more key/value pairs, separated by spaces or commas, wrapped by braces. You must quote string values that contain spaces. Unlike HTML, boolean attributes must have both key and value.
+
+For example:
+
+```text
+> This is a blockquote.
+{class="foo bar" hidden=hidden}
+```
+
+Hugo renders this to:
+
+```html
+<blockquote class="foo bar" hidden="hidden">
+  <p>This is a blockquote.</p>
+</blockquote>
+```
+
+In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right.
+
+Element|Position of attribute list
+:--|:--
+blockquote | bottom
+fenced code block | right
+heading | right
+horizontal rule | bottom
+image | bottom
+list  | bottom
+paragraph | bottom
+table | bottom
+
+For example:
+
+````text
+## Section 1 {class=foo}
+
+```bash {class=foo linenos=inline}
+declare a=1
+echo "${a}"
+```
+
+This is a paragraph.
+{class=foo}
+````
+
+As shown above, the attribute list for fenced code blocks is not limited to HTML attributes. You can also configure syntax highlighting by passing one or more of [these options](/functions/transform/highlight/#options).

content/en/content-management/mathematics.md

@@ -7,8 +7,8 @@ keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting]
 menu:
   docs:
     parent: content-management
-    weight: 250
-weight: 250
+    weight: 270
+weight: 270
 toc: true
 math: true
 ---

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

@@ -10,6 +10,7 @@ menu:
 weight: 80
 toc: true
 ---
+
 Page resources are only accessible from [page bundles](/content-management/page-bundles), those directories with `index.md` or
 `_index.md` files at their root. Page resources are only available to the
 page with which they are bundled.
@@ -114,7 +115,7 @@ GetMatch
 .Resources.Match "*sunset.jpg" 🚫
 ```
 
-## Page resources metadata
+## Metadata
 
 The page resources' metadata is managed from the corresponding page's front matter with an array/table parameter named `resources`. You can batch assign values using [wildcards](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm).
 
@@ -201,3 +202,108 @@ the `Name` and `Title` will be assigned to the resource files as follows:
 | guide.pdf         | `"pdf-file-2.pdf` | `"guide.pdf"`         |
 | other\_specs.pdf  | `"pdf-file-3.pdf` | `"Specification #1"` |
 | photo\_specs.pdf  | `"pdf-file-4.pdf` | `"Specification #2"` |
+
+## Multilingual
+
+{{< new-in 0.123.0 >}}
+
+By default, with a multilingual single-host site, Hugo does not duplicate shared page resources when building the site.
+
+{{% note %}}
+This behavior is limited to markdown content. Shared page resources for other [content formats] are copied into each language bundle.
+
+[content formats]: /content-management/formats/
+{{% /note %}}
+
+Consider this site configuration:
+
+{{< code-toggle file=hugo >}}
+defaultContentLanguage = 'de'
+defaultContentLanguageInSubdir = true
+
+[languages.de]
+languageCode = 'de-DE'
+languageName = 'Deutsch'
+weight = 1
+
+[languages.en]
+languageCode = 'en-US'
+languageName = 'English'
+weight = 2
+{{< /code-toggle >}}
+
+And this content:
+
+```text
+content/
+└── my-bundle/
+    ├── a.jpg     <-- shared page resource
+    ├── b.jpg     <-- shared page resource
+    ├── c.de.jpg
+    ├── c.en.jpg
+    ├── index.de.md
+    └── index.en.md
+```
+
+With v0.122.0 and earlier, Hugo duplicated the shared page resources, creating copies for each language:
+
+```text
+public/
+├── de/
+│   ├── my-bundle/
+│   │   ├── a.jpg     <-- shared page resource
+│   │   ├── b.jpg     <-- shared page resource
+│   │   ├── c.de.jpg
+│   │   └── index.html
+│   └── index.html
+├── en/
+│   ├── my-bundle/
+│   │   ├── a.jpg     <-- shared page resource (duplicate)
+│   │   ├── b.jpg     <-- shared page resource (duplicate)
+│   │   ├── c.en.jpg
+│   │   └── index.html
+│   └── index.html
+└── index.html
+
+```
+
+With v0.123.0 and later, Hugo places the shared resources in the page bundle for the default content language:
+
+```text
+public/
+├── de/
+│   ├── my-bundle/
+│   │   ├── a.jpg     <-- shared page resource
+│   │   ├── b.jpg     <-- shared page resource
+│   │   ├── c.de.jpg
+│   │   └── index.html
+│   └── index.html
+├── en/
+│   ├── my-bundle/
+│   │   ├── c.en.jpg
+│   │   └── index.html
+│   └── index.html
+└── index.html
+```
+
+This approach reduces build times, storage requirements, bandwidth consumption, and deployment times, ultimately reducing cost.
+
+{{% note %}}
+To resolve markdown link and image destinations to the correct location, you must use link and image render hooks that capture the page resource with the [`Resources.Get`] method, and then invoke its [`RelPermalink`] method.
+
+By default, with multilingual single-host sites, Hugo enables its [embedded link render hook] and [embedded image render hook] to resolve markdown link and image destinations.
+
+You may override the embedded render hooks as needed, provided they capture the resource as described above.
+
+[embedded link render hook]: /render-hooks/links/#default
+[embedded image render hook]: /render-hooks/images/#default
+[`Resources.Get`]: /methods/page/resources/#get
+[`RelPermalink`]: /methods/resource/relpermalink/
+{{% /note %}}
+
+Although duplicating shared page resources is inefficient, you can enable this feature in your site configuration if desired:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark]
+duplicateResourceFiles = true
+{{< /code-toggle >}}

content/en/content-management/syntax-highlighting.md

@@ -6,8 +6,8 @@ keywords: [highlighting,chroma,code blocks,syntax]
 menu:
   docs:
     parent: content-management
-    weight: 240
-weight: 240
+    weight: 250
+weight: 250
 toc: true
 aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
 ---

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

@@ -80,7 +80,7 @@ See additional examples in the [partial templates] section.
 ## Usage
 
 {{% note %}}
-Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks
+Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks.
 {{% /note %}}
 
 A partial that returns a value must contain only one `return` statement, placed at the end of the template.