Clean up shortcode documentation

content/en/content-management/shortcodes.md

@@ -1,91 +1,241 @@
 ---
 title: Shortcodes
-description: Shortcodes are simple snippets inside your content files calling built-in or custom templates.
+description: Use embedded, custom, or inline shortcodes to insert elements such as videos, images, and social media embeds into your content.
 categories: [content management]
-keywords: [markdown,content,shortcodes]
+keywords: []
 menu:
   docs:
     parent: content-management
     weight: 100
 weight: 100
-toc: true
 aliases: [/extras/shortcodes/]
-testparam: "Hugo Rocks!"
+toc: true
 ---
 
-## What a shortcode is
+## Introduction
+
+{{% glossary-term shortcode %}}
+
+There are three types of shortcodes: embedded, custom, and inline.
+
+## Embedded
+
+Hugo's embedded shortcodes are pre-defined templates within the application.  Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+{{< list-pages-in-section path=/shortcodes >}}
+
+## Custom
+
+Create custom shortcodes to simplify and standardize content creation. For example, the following shortcode template generates an audio player using a [global resource](g):
+
+{{< code file=layouts/shortcodes/audio.html >}}
+{{ with resources.Get (.Get "src") }}
+  <audio controls preload="auto" src="{{ .RelPermalink }}"></audio>
+{{ end }}
+{{< /code >}}
+
+Then call the shortcode from within markup:
+
+{{< code file=content/example.md >}}
+{{</* audio src=/audio/test.mp3 */>}}
+{{< /code >}}
+
+Learn more about creating shortcodes in the [shortcode templates] section.
+
+[shortcode templates]: /templates/shortcode/
+
+## Inline
+
+An inline shortcode is a shortcode template defined within content.
+
+Hugo's security model is based on the premise that template and configuration authors are trusted, but content authors are not. This model enables generation of HTML output safe against code injection.
+
+To conform with this security model, creating shortcode templates within content is disabled by default.  If you trust your content authors, you can enable this functionality in your site's configuration:
+
+{{< code-toggle file=hugo >}}
+[security]
+enableInlineShortcodes = true
+{{< /code-toggle >}}
+
+The following example demonstrates an inline shortcode, `date.inline`, that accepts a single positional argument: a date/time [layout string].
+
+[layout string]: /functions/time/format/#layout-string
+
+{{< code file=content/example.md >}}
+Today is
+{{</* date.inline ":date_medium" */>}}
+  {{- now | time.Format (.Get 0) -}}
+{{</* /date.inline */>}}.
+
+Today is {{</* date.inline ":date_full" */>}}.
+{{< /code >}}
+
+In the example above, the inline shortcode is executed twice: once upon definition and again when subsequently called. Hugo renders this to:
+
+```html
+<p>Today is Jan 30, 2025.</p>
+<p>Today is Thursday, January 30, 2025</p>
+```
+
+Inline shortcodes process their inner content within the same context as regular shortcode templates, allowing you to use any available [shortcode method].
+
+[shortcode method]: /templates/shortcode/#methods
+
+{{% note %}}
+You cannot [nest](#nesting) inline shortcodes.
+{{% /note %}}
+
+Learn more about creating shortcodes in the [shortcode templates] section.
+
+## Calling
 
-Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video `<iframe>`'s) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax.
+Shortcode calls involve three syntactical elements: tags, arguments, and notation.
 
-Hugo created **shortcodes** to circumvent these limitations.
+### Tags
 
-A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead.
+Some shortcodes expect content between opening and closing tags. For example, the embedded [`details`] shortcode requires an opening and closing tag:
 
-In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation.
+```text
+{{</* details summary="See the details" */>}}
+This is a **bold** word.
+{{</* /details */>}}
+```
+
+Some shortcodes do not accept content. For example, the embedded [`instagram`] shortcode requires a single _positional_ argument:
+
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
+
+Some shortcodes optionally accept content. For example, you can call the embedded [`qr`] shortcode with content:
+
+```text
+{{</* qr */>}}
+https://gohugo.io
+{{</* /qr */>}}
+```
+
+Or use the self-closing syntax with a trailing slash to pass the text as an argument:
 
-## Use shortcodes
+```text
+{{</* qr text=https://gohugo.io /*/>}}
+```
+
+[`details`]: /shortcodes/details
+[`instagram`]: /shortcodes/instagram
+[`qr`]: /shortcodes/qr
+
+Refer to each shortcode's documentation for specific usage instructions and available arguments.
+
+### Arguments
 
-{{< youtube 2xkNJL4gJ9E >}}
+Shortcode arguments can be either _named_ or _positional_.
 
-In your content files, a shortcode can be called by calling `{{%/* shortcodename arguments */%}}`. Shortcode arguments are space delimited, and arguments with internal spaces must be quoted.
+Named arguments are passed as case-sensitive key-value pairs, as seen in this example with the embedded [`figure`] shortcode.  The `src` argument, for instance, is required.
 
-The first word in the shortcode declaration is always the name of the shortcode. Arguments follow the name. Depending upon how the shortcode is defined, the arguments may be named, positional, or both, although you can't mix argument types in a single call. The format for named arguments models that of HTML with the format `name="value"`.
+[`figure`]: /shortcodes/figure
 
-Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash.
+```text
+{{</* figure src=/images/kitten.jpg */>}}
+```
 
-Here are two examples of paired shortcodes:
+Positional arguments, on the other hand, are determined by their position.  The embedded `instagram` shortcode, for example, expects the first argument to be the Instagram post ID.
 
-```go-html-template
-{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}}
+```text
+{{</* instagram CxOWiQNP2MO */>}}
 ```
 
-```go-html-template
-{{</* highlight go */>}} A bunch of code here {{</* /highlight */>}}
+Shortcode arguments are space delimited, and arguments with internal spaces must be quoted.
+
+```text
+{{</* figure src=/images/kitten.jpg alt="A white kitten" */>}}
 ```
 
-The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second.
+Shortcodes accept [scalar](g) arguments, one of [string](g), [integer](g), [floating point](g), or [boolean](g).
 
-### Shortcodes with raw string arguments
+```text
+{{</* my-shortcode name="John Smith" age=24 married=false */>}}
+```
 
-You can pass multiple lines as arguments to a shortcode by using raw string literals:
+You can optionally use multiple lines when providing several arguments to a shortcode for better readability:
 
-```go-html-template
+```text
+{{</* figure
+  src=/images/kitten.jpg
+  alt="A white kitten"
+  caption="This is a white kitten"
+  loading=lazy
+*/>}}
+```
+
+Use a [raw string literal](g) if you need to pass a multiline string:
+
+```text
 {{</*  myshortcode `This is some <b>HTML</b>,
 and a new line with a "quoted string".` */>}}
 ```
 
-### Shortcodes with Markdown
+Shortcodes can accept named arguments, positional arguments, or both, but you must use either named or positional arguments exclusively within a single shortcode call; mixing them is not allowed.
 
-Shortcodes using the `%` as the outer-most delimiter will be fully rendered when sent to the content renderer. This means that the rendered output from a shortcode can be part of the page's table of contents, footnotes, etc.
+Refer to each shortcode's documentation for specific usage instructions and available arguments.
 
-### Shortcodes without Markdown
+### Notation
 
-The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without Markdown include internal HTML:
+Shortcodes can be called using two different notations, distinguished by their tag delimiters.
 
-```go-html-template
-{{</* myshortcode */>}}<p>Hello <strong>World!</strong></p>{{</* /myshortcode */>}}
-```
+Notation|Example
+:--|:--
+Markdown|`{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}`
+Standard|`{{</* foo */>}} ## Section 2 {{</* /foo */>}}`
+
+###### Markdown notation
+
+Hugo processes the shortcode before the page content is rendered by the Markdown renderer. This means, for instance, that Markdown headings inside a Markdown-notation shortcode will be included when invoking the [`TableOfContents`] method on the `Page` object.
+
+[`TableOfContents`]: /methods/page/tableofcontents/
+
+###### Standard notation
+
+With standard notation, Hugo processes the shortcode separately, merging the output into the page content after Markdown rendering. This means, for instance, that Markdown headings inside a standard-notation shortcode will be excluded when invoking the `TableOfContents` method on the `Page` object.
 
-### Nested shortcodes
+By way of example, with this shortcode template:
 
-You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` method. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps].
+{{< code file=layouts/shortcodes/foo.html >}}
+{{ .Inner }}
+{{< /code >}}
+
+And this markdown:
+
+{{< code file=content/example.md >}}
+{{%/* foo */%}} ## Section 1 {{%/* /foo */%}}
+
+{{</* foo */>}} ## Section 2 {{</* /foo */>}}
+{{< /code >}}
+
+Hugo renders this HTML:
+
+```html
+<h2 id="heading">Section 1</h2>
+
+## Section 2
+```
 
-## Embedded shortcodes
+In the above, "Section 1" will be included when invoking the `TableOfContents` method, while "Section 2" will not.
 
-See the [shortcodes](/shortcodes/) section.
+The shortcode author determines which notation to use.  Consult each shortcode's documentation for specific usage instructions and available arguments.
 
-## Privacy configuration
+## Nesting
 
-To learn how to configure your Hugo site to meet the new EU privacy regulation, see [privacy protections].
+Shortcodes (excluding [inline](#inline) shortcodes) can be nested, creating parent-child relationships. For example, a gallery shortcode might contain several image shortcodes:
 
-## Create custom shortcodes
+{{< code file=content/example.md >}}
+{{</* gallery class="content-gallery" */>}}
+  {{</* image src="/images/a.jpg" */>}}
+  {{</* image src="/images/b.jpg" */>}}
+  {{</* image src="/images/c.jpg" */>}}
+{{</* /gallery */>}}
+{{< /code >}}
 
-To learn more about creating custom shortcodes, see the [shortcode template documentation].
+The [shortcode templates][nesting] section provides a detailed explantion and examples.
 
-[privacy protections]: /about/privacy/
-[partials]: /templates/partial/
-[quickstart]: /getting-started/quick-start/
-[sctemps]: /templates/shortcode/
-[shortcode template documentation]: /templates/shortcode/
-[Vimeo]: https://vimeo.com/
-[YouTube Videos]: https://www.youtube.com/
+[nesting]: /templates/shortcode/#nesting

content/en/getting-started/glossary/shortcode.md

@@ -3,4 +3,4 @@ title: shortcode
 reference: /content-management/shortcodes
 ---
 
-A [template](g)  called from within Markdown, taking zero or more [arguments](g).
+A _shortcode_ is a [_template_](g) invoked within markup, accepting any number of [_arguments_](g). They can be used with any [content format](g) to insert elements such as videos, images, and social media embeds into your content.

content/en/methods/page/Scratch.md

@@ -1,6 +1,6 @@
 ---
 title: Scratch
-description: Returns a "scratch pad" on the given page to store and manipulate data.
+description: Returns a "scratch pad" to store and manipulate data, scoped to the current page.
 categories: []
 keywords: []
 action:

content/en/methods/shortcode/Scratch.md

@@ -1,6 +1,6 @@
 ---
 title: Scratch
-description: Returns a "scratch pad" scoped to the shortcode to store and manipulate data. 
+description: Returns a "scratch pad" to store and manipulate data, scoped to the current shortcode.
 categories: []
 keywords: []
 action:

content/en/templates/home.md

@@ -1,5 +1,5 @@
 ---
-title: Home templates
+title: Home page templates
 description: The home page of a website is often formatted differently than the other pages. For this reason, Hugo makes it easy for you to define your new site's home page as a unique template.
 categories: [templates]
 keywords: []
@@ -12,43 +12,53 @@ toc: true
 aliases: [/layout/homepage/,/templates/homepage-template/,/templates/homepage/]
 ---
 
-The home template is the *only* required template for building a site and therefore useful when bootstrapping a new site and template. It is also the only required template if you are developing a single-page website.
+## Introduction
 
-{{< youtube ut1xtRZ1QOA >}}
+A home page template is used to render your site's home page, and is the only template required for a single-page website.  For example, the home page template below inherits the site's shell from the base template and renders the home page content, such as a list of other pages.
 
-## Home template lookup order
+{{< code file=layouts/_default/home.html >}}
+{{ define "main" }}
+  {{ .Content }}
+  {{ range site.RegularPages }}
+    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+  {{ end }}
+{{ end }}
+{{< /code >}}
+
+{{% include "templates/_common/filter-sort-group.md" %}}
+
+## Lookup order
 
-See [Template Lookup](/templates/lookup-order/).
+Hugo's [template lookup order] determines the template path, allowing you to create unique templates for any page.
 
-## Add content and front matter to the home page
+[template lookup order]: /templates/lookup-order/#home-templates
 
-The home page accepts content and front matter from an&nbsp;`_index.md`&nbsp;file. This file should live at the root of your `content` directory (i.e., `content/_index.md`). You can then add body copy and metadata to your home page the way you would any other content file.
+{{% note %}}
+You must have thorough understanding of the template lookup order when creating templates. Template selection is based on template type, page kind, content type, section, language, and output format.
+{{% /note %}}
 
-See the home template below or [Content Organization][contentorg] for more information on the role of `_index.md` in adding content and front matter to list pages.
+## Content and front matter
 
-## Example home template
+The home page template uses content and front matter from an&nbsp;`_index.md`&nbsp;file located in the root of your content directory.
+
+{{< code-toggle file=content/_index.md fm=true >}}
+---
+title: The Home Page
+date: 2025-01-30T03:36:57-08:00
+draft: false
+params:
+  subtitle: The Subtitle
+---
+{{< /code-toggle >}}
+
+The home page template below inherits the site's shell from the base template, renders the subtitle and content as defined in the&nbsp;`_index.md`&nbsp;file, then renders of list of the site's [regular pages](g).
 
 {{< code file=layouts/_default/home.html >}}
 {{ define "main" }}
-  <main aria-role="main">
-    <header class="home-page-header">
-      <h1>{{ .Title }}</h1>
-      {{ with .Params.subtitle }}
-        <span class="subtitle">{{ . }}</span>
-      {{ end }}
-    </header>
-    <div class="home-page-content">
-      <!-- Note that the content for index.html, as a sort of list page, will pull from content/_index.md -->
-      {{ .Content }}
-    </div>
-    <div>
-      {{ range first 10 .Site.RegularPages }}
-        {{ .Render "summary" }}
-      {{ end }}
-    </div>
-  </main>
+  <h3>{{ .Params.Subtitle }}</h3>
+  {{ .Content }}
+  {{ range site.RegularPages }}
+    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+  {{ end }}
 {{ end }}
 {{< /code >}}
-
-[contentorg]: /content-management/organization/
-[lookup]: /templates/lookup-order/