14 files changed, 196 insertions, 283 deletions
diff --git a/docs/content/en/shortcodes/_index.md b/docs/content/en/shortcodes/_index.md
index 2d9a8fdd6..826ee5796 100644
--- a/docs/content/en/shortcodes/_index.md
+++ b/docs/content/en/shortcodes/_index.md
@@ -1,16 +1,7 @@
 ---
 title: Shortcodes
-
 description: Insert elements such as videos, images, and social media embeds into your content using Hugo's embedded shortcodes.
 categories: []
 keywords: []
-menu:
-  docs:
-    identifier: shortcodes-in-this-section
-    parent: shortcodes
-    weight: 10
 weight: 10
-showSectionMenu: true
 ---
-
-Insert elements such as videos, images, and social media embeds into your content using Hugo's embedded shortcodes.
diff --git a/docs/content/en/shortcodes/comment.md b/docs/content/en/shortcodes/comment.md
deleted file mode 100755
index 1600c09d3..000000000
--- a/docs/content/en/shortcodes/comment.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: Comment
-description: Include hidden comments in your content with the comment shortcode.
-categories: [shortcodes]
-keywords: []
-menu:
-  docs:
-    identifier: shortcodes-comment
-    parent: shortcodes
-    weight:
-weight:
-expiryDate: 2025-01-22 # deprecated 2025-02-01 in v0.143.0 and immediately removed from the documentation
----
-
-{{% note %}}
-To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl comment %}}
-{{% /note %}}
-
-{{< new-in 0.137.1 />}}
-
-Use the `comment` shortcode to include comments in your content. Hugo will ignore the text within these comments when rendering your site.
-
-Use it inline:
-
-```text
-{{%/* comment */%}} rewrite the paragraph below {{%/* /comment */%}}
-```
-
-Or as a block comment:
-
-```text
-{{%/* comment */%}}
-rewrite the paragraph below
-{{%/* /comment */%}}
-```
-
-Although you can call this shortcode using the `{{</* */>}}` notation, computationally it is more efficient to call it using the `{{%/* */%}}` notation as shown above.
diff --git a/docs/content/en/shortcodes/details.md b/docs/content/en/shortcodes/details.md
index f30f81d75..94502ac1c 100755
--- a/docs/content/en/shortcodes/details.md
+++ b/docs/content/en/shortcodes/details.md
@@ -1,23 +1,15 @@
 ---
-title: Details
+title: Details shortcode
+linkTitle: Details
 description: Insert an HTML details element into your content using the details shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
-toc: true
 ---
 
 {{< new-in 0.140.0 />}}
 
-{{% note %}}
-To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl details %}}
-{{% /note %}}
+> [!note]
+> To override Hugo's embedded `details` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
 ## Example
 
@@ -44,7 +36,7 @@ Which looks like this in your browser:
 This is a **bold** word.
 {{< /details >}}
 
-## Parameters
+## Arguments
 
 summary
 : (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`.
@@ -78,3 +70,5 @@ details > summary > * { }
 /* target the content */
 details > :not(summary) { }
 ```
+
+[source code]: {{% eturl details %}}
diff --git a/docs/content/en/shortcodes/figure.md b/docs/content/en/shortcodes/figure.md
index eb98598b6..74af52fe7 100755
--- a/docs/content/en/shortcodes/figure.md
+++ b/docs/content/en/shortcodes/figure.md
@@ -1,21 +1,13 @@
 ---
-title: Figure
+title: Figure shortcode
+linkTitle: Figure
 description: Insert an HTML figure element into your content using the figure shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
-toc: true
 ---
 
-{{% note %}}
-To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl figure %}}
-{{% /note %}}
+> [!note]
+> To override Hugo's embedded `figure` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
 ## Example
 
@@ -57,7 +49,7 @@ Which looks like this in your browser:
   class="ma0 w-75"
 >}}
 
-## Parameters
+## Arguments
 
 src
 : (`string`) The `src` attribute of the `img` element. Typically this is a [page resource](g) or a [global resource](g).
@@ -113,3 +105,5 @@ target = 'assets'
 source = 'static'
 target = 'assets'
 {{< /code-toggle >}}
+
+[source code]: {{% eturl figure %}}
diff --git a/docs/content/en/shortcodes/gist.md b/docs/content/en/shortcodes/gist.md
index 1c740bccb..fd2b468ab 100755
--- a/docs/content/en/shortcodes/gist.md
+++ b/docs/content/en/shortcodes/gist.md
@@ -1,26 +1,20 @@
 ---
-title: Gist
+title: Gist shortcode
+linkTitle: Gist
 description: Embed a GitHub Gist in your content using the gist shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
 expiryDate: 2027-02-01 # deprecated 2025-02-01 in v0.143.0
 ---
 
-{{% deprecated-in 0.143.0 %}}
+{{< deprecated-in 0.143.0 >}}
 The `gist` shortcode was deprecated in version 0.143.0 and will be removed in a future release. To continue embedding GitHub Gists in your content, you'll need to create a custom shortcode:
 
 1. Create a new file: Create a file named `gist.html` within the `layouts/shortcodes` directory.
-2. Copy the source code: Paste the [original source code] of the gist shortcode into the newly created `gist.html` file.
+1. Copy the source code: Paste the [original source code]({{% eturl gist %}}) of the gist shortcode into the newly created `gist.html` file.
 
 This will allow you to maintain the functionality of embedding GitHub Gists in your content after the deprecation of the original shortcode.
-
-[original source code]: {{% eturl gist %}}
-{{% /deprecated-in %}}
+{{< /deprecated-in >}}
 
 To display a GitHub gist with this URL:
 
diff --git a/docs/content/en/shortcodes/highlight.md b/docs/content/en/shortcodes/highlight.md
index 0a35aa4e6..371a3d46e 100755
--- a/docs/content/en/shortcodes/highlight.md
+++ b/docs/content/en/shortcodes/highlight.md
@@ -1,35 +1,20 @@
 ---
-title: Highlight
+title: Highlight shortcode
+linkTitle: Highlight
 description: Insert syntax-highlighted code into your content using the highlight shortcode.
-categories: [shortcodes]
-keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
-toc: true
+categories: []
+keywords: [highlight]
 ---
 
-{{% note %}}
-To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
+> [!note]
+> To override Hugo's embedded `highlight` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
-[source code]: {{% eturl highlight %}}
-{{% /note %}}
-
-{{% note %}}
-With the Markdown [content format], the `highlight` shortcode is rarely needed because, by default, Hugo automatically applies syntax highlighting to fenced code blocks.
+> [!note]
+> With the Markdown [content format], the `highlight` shortcode is rarely needed because, by default, Hugo automatically applies syntax highlighting to fenced code blocks.
+>
+> The primary use case for the `highlight` shortcode in Markdown is to apply syntax highlighting to inline code snippets.
 
-The primary use case for the `highlight` shortcode in Markdown is to apply syntax highlighting to inline code snippets.
-
-[content format]: /content-management/formats/
-{{% /note %}}
-
-The `highlight` shortcode calls the [`transform.Highlight`] function which uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [available styles].
-
-[chroma]: https://github.com/alecthomas/chroma
-[available styles]: https://xyproto.github.io/splash/docs/
-[`transform.Highlight`]: /functions/transform/highlight/
+The `highlight` shortcode calls the [`transform.Highlight`] function which uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [highlighting styles].
 
 ## Arguments
 
@@ -50,13 +35,10 @@ LANG
 OPTIONS
 : (`string`) Zero or more space-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive.
 
-[site configuration]: /getting-started/configuration-markup#highlight
-[supported languages]: /content-management/syntax-highlighting/#list-of-chroma-highlighting-languages
-
 ## Example
 
 ```text
-{{</* highlight go "linenos=inline, hl_Lines=3 6-8, style=emacs" */>}}
+{{</* highlight go "linenos=inline, hl_lines=3 6-8, style=emacs" */>}}
 package main
 
 import "fmt"
@@ -95,12 +77,12 @@ This is some {{< highlight go "hl_inline=true, noClasses=true" >}}fmt.Println("i
 
 Given the verbosity of the example above, if you need to frequently highlight inline code snippets, create your own shortcode using a shorter name with preset options.
 
-{{< code file=layouts/shortcodes/hl.html >}}
+```go-html-template {file="layouts/shortcodes/hl.html"}
 {{ $code := .Inner | strings.TrimSpace }}
-{{ $lang := or (.Get 0) "go"  }}
+{{ $lang := or (.Get 0) "go" }}
 {{ $opts := dict "hl_inline" true "noClasses" true }}
 {{ transform.Highlight $code $lang $opts }}
-{{< /code >}}
+```
 
 ```text
 This is some {{</* hl */>}}fmt.Println("inline"){{</* /hl */>}} code.
@@ -114,4 +96,12 @@ This is some {{< hl >}}fmt.Println("inline"){{< /hl >}} code.
 
 Pass the options when calling the shortcode. You can set their default values in your [site configuration].
 
-{{% include "functions/_common/highlighting-options" %}}
+{{% include "_common/syntax-highlighting-options.md" %}}
+
+[`transform.Highlight`]: /functions/transform/highlight/
+[Chroma]: https://github.com/alecthomas/chroma
+[content format]: /content-management/formats/
+[highlighting styles]: /quick-reference/syntax-highlighting-styles/
+[site configuration]: /configuration/markup/#highlight
+[source code]: {{% eturl highlight %}}
+[supported languages]: /content-management/syntax-highlighting/#languages
diff --git a/docs/content/en/shortcodes/instagram.md b/docs/content/en/shortcodes/instagram.md
index eb2bb7671..3256790c6 100755
--- a/docs/content/en/shortcodes/instagram.md
+++ b/docs/content/en/shortcodes/instagram.md
@@ -1,21 +1,13 @@
 ---
-title: Instagram
+title: Instagram shortcode
+linkTitle: Instagram
 description: Embed an Instagram post in your content using the instagram shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
-toc: true
 ---
 
-{{% note %}}
-To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl instagram %}}
-{{% /note %}}
+> [!note]
+> To override Hugo's embedded `instagram` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
 ## Example
 
@@ -46,3 +38,5 @@ disable
 
 simple
 : (`bool`) Whether to enable simple mode for image card generation. If `true`, Hugo creates a static card without JavaScript. This mode only supports image cards, and the image is fetched directly from Instagram's servers. Default is `false`.
+
+[source code]: {{% eturl instagram %}}
diff --git a/docs/content/en/shortcodes/param.md b/docs/content/en/shortcodes/param.md
index bff659ec1..133b2322a 100755
--- a/docs/content/en/shortcodes/param.md
+++ b/docs/content/en/shortcodes/param.md
@@ -1,24 +1,17 @@
 ---
-title: Param
+title: Param shortcode
+linkTitle: Param
 description: Insert a parameter from front matter or site configuration into your content using the param shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
 ---
 
-{{% note %}}
-To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl param %}}
-{{% /note %}}
+> [!note]
+> To override Hugo's embedded `param` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
 The `param` shortcode renders a parameter from front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist.
 
-{{< code file=example.md lang=text >}}
+```text {file="content/example.md"}
 ---
 title: Example
 date: 2025-01-15T23:29:46-08:00
@@ -28,7 +21,7 @@ params:
 ---
 
 We found a {{%/* param "color" */%}} shirt.
-{{< /code >}}
+```
 
 Hugo renders this to:
 
@@ -41,3 +34,5 @@ Access nested values by [chaining](g) the [identifiers](g):
 ```text
 {{%/* param my.nested.param */%}}
 ```
+
+[source code]: {{% eturl param %}}
diff --git a/docs/content/en/shortcodes/qr.md b/docs/content/en/shortcodes/qr.md
index a7a6d92cb..98d6cee4c 100755
--- a/docs/content/en/shortcodes/qr.md
+++ b/docs/content/en/shortcodes/qr.md
@@ -1,31 +1,20 @@
 ---
-title: QR
+title: QR shortcode
+linkTitle: QR
 description: Insert a QR code into your content using the qr shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
-toc: true
 ---
 
 {{< new-in 0.141.0 />}}
 
-{{% note %}}
-To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl qr %}}
-{{% /note %}}
+> [!note]
+> To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
 The `qr` shortcode encodes the given text into a [QR code] using the specified options and renders the resulting image.
 
 Internally this shortcode calls the `images.QR` function. Please read the [related documentation] for implementation details and guidance.
 
-[QR code]: https://en.wikipedia.org/wiki/QR_code
-[related documentation]: /functions/images/qr/
-
 ## Examples
 
 Use the self-closing syntax to pass the text as an argument:
@@ -56,8 +45,6 @@ To create a QR code for a phone number:
 
 To create a QR code containing contact information in the [vCard] format:
 
-[vCard]: https://en.wikipedia.org/wiki/VCard
-
 ```text
 {{</* qr level="low" scale=2 alt="QR code of vCard for John Smith" */>}}
 BEGIN:VCARD
@@ -84,7 +71,7 @@ EMAIL;TYPE=WORK:jsmith@example.org
 END:VCARD
 {{< /qr >}}
 
-## Parameters
+## Arguments
 
 text
 : (`string`) The text to encode, falling back to the text between the opening and closing shortcode tags.
@@ -98,8 +85,6 @@ scale
 targetDir
 : (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image.
 
-[`publishDir`]: /getting-started/configuration/#publishdir
-
 alt
 : (`string`) The `alt` attribute of the `img` element.
 
@@ -109,5 +94,14 @@ class
 id
 : (`string`) The `id` attribute of the `img` element.
 
+loading
+: (`string`) The `loading` attribute of the `img` element, either `eager` or `lazy`.
+
 title
 : (`string`) The `title` attribute of the `img` element.
+
+[`publishDir`]: /configuration/all/#publishdir
+[QR code]: https://en.wikipedia.org/wiki/QR_code
+[related documentation]: /functions/images/qr/
+[source code]: {{% eturl qr %}}
+[vCard]: https://en.wikipedia.org/wiki/VCard
diff --git a/docs/content/en/shortcodes/ref.md b/docs/content/en/shortcodes/ref.md
index af133447e..2f821254c 100755
--- a/docs/content/en/shortcodes/ref.md
+++ b/docs/content/en/shortcodes/ref.md
@@ -1,48 +1,61 @@
 ---
-title: Ref
+title: Ref shortcode
+linkTitle: Ref
 description: Insert a permalink to the given page reference using the ref shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
 ---
 
-{{% note %}}
-To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
+> [!note]
+> To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
-[source code]: {{% eturl ref %}}
-{{% /note %}}
+> [!note]
+> When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
 
-{{% note %}}
-When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
+## Usage
 
-[content format]: /content-management/formats/
-[link render hooks]: /render-hooks/images/#default
-{{% /note %}}
+The `ref` shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below.
+
+## Arguments
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The `ref` shortcode typically provides the destination for a Markdown link.
+
+> [!note]
+> Always use [Markdown notation] notation when calling this shortcode.
+
+The following examples show the rendered output for a page on the English version of the site:
 
-The `ref` shortcode returns the permalink of the given page reference.
+```md
+[Link A]({{%/* ref "/books/book-1" */%}})
 
-Example usage:
+[Link B]({{%/* ref path="/books/book-1" */%}})
 
-```text
-[Post 1]({{%/* ref "/posts/post-1" */%}})
-[Post 1]({{%/* ref "/posts/post-1.md" */%}})
-[Post 1]({{%/* ref "/posts/post-1#foo" */%}})
-[Post 1]({{%/* ref "/posts/post-1.md#foo" */%}})
+[Link C]({{%/* ref path="/books/book-1" lang="de" */%}})
+
+[Link D]({{%/* ref path="/books/book-1" lang="de" outputFormat="json" */%}})
 ```
 
 Rendered:
 
 ```html
-<a href="https://example.org/posts/post-1/">Post 1</a>
-<a href="https://example.org/posts/post-1/">Post 1</a>
-<a href="https://example.org/posts/post-1/#foo">Post 1</a>
-<a href="https://example.org/posts/post-1/#foo">Post 1</a>
+<a href="https://example.org/en/books/book-1/">Link A</a>
+
+<a href="https://example.org/en/books/book-1/">Link B</a>
+
+<a href="https://example.org/de/books/book-1/">Link C</a>
+
+<a href="https://example.org/de/books/book-1/index.json">Link D</a>
 ```
 
-{{% note %}}
-Always use the `{{%/* */%}}` notation when calling this shortcode.
-{{% /note %}}
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
+
+[content format]: /content-management/formats/
+[link render hooks]: /render-hooks/images/#default
+[Markdown notation]: /content-management/shortcodes/#notation
+[source code]: {{% eturl ref %}}
diff --git a/docs/content/en/shortcodes/relref.md b/docs/content/en/shortcodes/relref.md
index e98e82919..5b413b87e 100755
--- a/docs/content/en/shortcodes/relref.md
+++ b/docs/content/en/shortcodes/relref.md
@@ -1,48 +1,61 @@
 ---
-title: Relref
+title: Relref shortcode
+linkTitle: Relref
 description: Insert a relative permalink to the given page reference using the relref shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
 ---
 
-{{% note %}}
-To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
+> [!note]
+> To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
-[source code]: {{% eturl relref %}}
-{{% /note %}}
+> [!note]
+> When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
 
-{{% note %}}
-When working with the Markdown [content format], this shortcode has become largely redundant. Its functionality is now primarily handled by [link render hooks], specifically the embedded one provided by Hugo. This hook effectively addresses all the use cases previously covered by this shortcode.
+## Usage
 
-[content format]: /content-management/formats/
-[link render hooks]: /render-hooks/links/
-{{% /note %}}
+The `relref` shortcode accepts either a single positional argument (the path) or one or more named arguments, as listed below.
+
+## Arguments
+
+{{% include "_common/ref-and-relref-options.md" %}}
+
+## Examples
+
+The `relref` shortcode typically provides the destination for a Markdown link.
+
+> [!note]
+> Always use [Markdown notation] notation when calling this shortcode.
+
+The following examples show the rendered output for a page on the English version of the site:
 
-The `relref` shortcode returns the relative permalink of the given page reference.
+```md
+[Link A]({{%/* ref "/books/book-1" */%}})
 
-Example usage:
+[Link B]({{%/* ref path="/books/book-1" */%}})
 
-```text
-[Post 1]({{%/* relref "/posts/post-1" */%}})
-[Post 1]({{%/* relref "/posts/post-1.md" */%}})
-[Post 1]({{%/* relref "/posts/post-1#foo" */%}})
-[Post 1]({{%/* relref "/posts/post-1.md#foo" */%}})
+[Link C]({{%/* ref path="/books/book-1" lang="de" */%}})
+
+[Link D]({{%/* ref path="/books/book-1" lang="de" outputFormat="json" */%}})
 ```
 
 Rendered:
 
 ```html
-<a href="/posts/post-1/">Post 1</a>
-<a href="/posts/post-1/">Post 1</a>
-<a href="/posts/post-1/#foo">Post 1</a>
-<a href="/posts/post-1/#foo">Post 1</a>
+<a href="/en/books/book-1/">Link A</a>
+
+<a href="/en/books/book-1/">Link B</a>
+
+<a href="/de/books/book-1/">Link C</a>
+
+<a href="/de/books/book-1/index.json">Link D</a>
 ```
 
-{{% note %}}
-Always use the `{{%/* */%}}` notation when calling this shortcode.
-{{% /note %}}
+## Error handling
+
+{{% include "_common/ref-and-relref-error-handling.md" %}}
+
+[content format]: /content-management/formats/
+[link render hooks]: /render-hooks/links/
+[Markdown notation]: /content-management/shortcodes/#notation
+[source code]: {{% eturl relref %}}
diff --git a/docs/content/en/shortcodes/vimeo.md b/docs/content/en/shortcodes/vimeo.md
index 5ecdf5d02..c354eefe0 100755
--- a/docs/content/en/shortcodes/vimeo.md
+++ b/docs/content/en/shortcodes/vimeo.md
@@ -1,21 +1,13 @@
 ---
-title: Vimeo
+title: Vimeo shortcode
+linkTitle: Vimeo
 description: Embed a Vimeo video in your content using the vimeo shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
-toc: true
 ---
 
-{{% note %}}
-To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl vimeo %}}
-{{% /note %}}
+> [!note]
+> To override Hugo's embedded `vimeo` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
 ## Example
 
@@ -35,7 +27,7 @@ Hugo renders this to:
 
 {{< vimeo 55073825 >}}
 
-## Parameters
+## Arguments
 
 class
 : (`string`) The `class` attribute of the wrapping `div` element. Adding one or more CSS classes disables inline styling.
@@ -70,3 +62,4 @@ simple
 The source code for the simple version of the shortcode is available [here].
 
 [here]: {{% eturl vimeo_simple %}}
+[source code]: {{% eturl vimeo %}}
diff --git a/docs/content/en/shortcodes/x.md b/docs/content/en/shortcodes/x.md
index e27bc996a..f1eebdaf2 100755
--- a/docs/content/en/shortcodes/x.md
+++ b/docs/content/en/shortcodes/x.md
@@ -1,23 +1,15 @@
 ---
-title: X
+title: X shortcode
+linkTitle: X
 description: Embed an X post in your content using the x shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
-toc: true
 ---
 
 {{< new-in 0.141.0 />}}
 
-{{% note %}}
-To override Hugo's embedded `x` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl x %}}
-{{% /note %}}
+> [!note]
+> To override Hugo's embedded `x` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
 ## Example
 
@@ -54,8 +46,9 @@ simple
 
 The source code for the simple version of the shortcode is available [here].
 
-[here]: {{% eturl x_simple %}}
-
 If you enable simple mode you may want to disable the hardcoded inline styles by setting `disableInlineCSS` to `true` in your site configuration. The default value for this setting is `false`.
 
 {{< code-toggle config=services.x />}}
+
+[here]: {{% eturl x_simple %}}
+[source code]: {{% eturl x %}}
diff --git a/docs/content/en/shortcodes/youtube.md b/docs/content/en/shortcodes/youtube.md
index 546529500..18c5ae6c2 100755
--- a/docs/content/en/shortcodes/youtube.md
+++ b/docs/content/en/shortcodes/youtube.md
@@ -1,21 +1,13 @@
 ---
-title: YouTube
+title: YouTube shortcode
+linkTitle: YouTube
 description: Embed a YouTube video in your content using the youtube shortcode.
-categories: [shortcodes]
+categories: []
 keywords: []
-menu:
-  docs:
-    parent: shortcodes
-    weight:
-weight:
-toc: true
 ---
 
-{{% note %}}
-To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
-
-[source code]: {{% eturl youtube %}}
-{{% /note %}}
+> [!note]
+> To override Hugo's embedded `youtube` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
 
 ## Example
 
@@ -27,7 +19,7 @@ https://www.youtube.com/watch?v=0RKpf3rK57I
 
 Include this in your Markdown:
 
-```text
+```texts
 {{</* youtube 0RKpf3rK57I */>}}
 ```
 
@@ -35,44 +27,44 @@ Hugo renders this to:
 
 {{< youtube 0RKpf3rK57I >}}
 
-## Parameters
+## Arguments
 
 id
 : (`string`) The video `id`. Optional if the `id` is provided as a positional argument as shown in the example above.
 
 allowFullScreen
-{{< new-in 0.125.0 />}}
+: {{< new-in 0.125.0 />}}
 : (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
 
 autoplay
- {{< new-in 0.125.0 />}}
+: {{< new-in 0.125.0 />}}
 : (`bool`) Whether to automatically play the video. Forces `mute` to `true`. Default is `false`.
 
 class
 : (`string`) The `class` attribute of the wrapping `div` element. When specified, removes the `style` attributes from the `iframe` element and its wrapping `div` element.
 
 controls
-{{< new-in 0.125.0 />}}
+: {{< new-in 0.125.0 />}}
 : (`bool`) Whether to display the video controls. Default is `true`.
 
 end
-{{< new-in 0.125.0 />}}
+: {{< new-in 0.125.0 />}}
 : (`int`) The time, measured in seconds from the start of the video, when the player should stop playing the video.
 
 loading
-{{< new-in 0.125.0 />}}
+: {{< new-in 0.125.0 />}}
 : (`string`) The loading attribute of the `iframe` element, either `eager` or `lazy`. Default is `eager`.
 
 loop
-{{< new-in 0.125.0 />}}
-: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play.  Default is `false`.
+: {{< new-in 0.125.0 />}}
+: (`bool`) Whether to indefinitely repeat the video. Ignores the `start` and `end` arguments after the first play. Default is `false`.
 
 mute
-{{< new-in 0.125.0 />}}
+: {{< new-in 0.125.0 />}}
 : (`bool`) Whether to mute the video. Always `true` when `autoplay` is `true`. Default is `false`.
 
 start
-{{< new-in 0.125.0 />}}
+: {{< new-in 0.125.0 />}}
 : (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
 
 title
@@ -95,3 +87,5 @@ disable
 
 privacyEnhanced
 : (`bool`) Whether to block YouTube from storing information about visitors on your website unless the user plays the embedded video. Default is `false`.
+
+[source code]: {{% eturl youtube %}}