theme: Adjust shortcodes

.prettierignore

@@ -7,6 +7,8 @@ layouts/_default/_markup/render-table*
 layouts/shortcodes/glossary-term.html
 layouts/shortcodes/glossary.html
 layouts/shortcodes/highlighting-styles.html
+layouts/shortcodes/list-pages-in-section.html
+layouts/shortcodes/quick-reference.html
 
 # No root node.
 layouts/partials/layouts/head/head.html

content/en/content-management/shortcodes.md

@@ -16,7 +16,7 @@ There are three types of shortcodes: embedded, custom, and inline.
 
 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 >}}
+{{% list-pages-in-section path=/shortcodes %}}
 
 ## Custom
 

content/en/contribute/documentation.md

@@ -210,7 +210,10 @@ With examples of template code:
 
 ### Fenced code blocks
 
-Always specify the language:
+Always specify the language.
+
+When providing a Mardown example, set the code language to "text" to prevent
+erroneous lexing/highlighting of shortcode calls.
 
 ````text
 ```go-html-template
@@ -230,8 +233,15 @@ To include a filename header and copy-to-clipboard button:
 ```
 ````
 
-When providing a Mardown example, set the code language to "text" to prevent
+To wrap the code block within an initially-opened `details` element using a non-default summary:
-erroneous lexing/highlighting of shortcode calls.
+
+````text
+```go-html-template {details=true open=true summary="layouts/partials/foo.html" copy=true}
+{{ if eq $foo "bar" }}
+  {{ print "foo is bar" }}
+{{ end }}
+```
+````
 
 ### Shortcode calls
 

content/en/functions/images/Filter.md

@@ -62,4 +62,4 @@ You can also apply image filters using the [`Filter`] method on a `Resource` obj
 
 Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object.
 
-{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}}
+{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}

content/en/methods/resource/Filter.md

@@ -63,4 +63,4 @@ You can also apply image filters using the [`images.Filter`] function.
 
 Use any of these filters with the `Filter` method.
 
-{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}}
+{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}

content/en/quick-reference/functions.md

@@ -5,4 +5,4 @@ categories: []
 keywords: []
 ---
 
-{{< quick-reference section="functions" >}}
+{{% quick-reference section="functions" %}}

content/en/quick-reference/methods.md

@@ -5,4 +5,4 @@ categories: []
 keywords: []
 ---
 
-{{< quick-reference section="methods" >}}
+{{% quick-reference section="methods" %}}

content/en/quick-reference/page-collections.md

@@ -9,30 +9,30 @@ keywords: []
 
 Use these `Page` methods when rendering lists on [section pages](g), [taxonomy pages](g), [term pages](g), and the home page.
 
-{{< list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=PAGE. >}}
+{{% list-pages-in-section path=/methods/page filter=methods_page_page_collections filterType=include titlePrefix=PAGE. %}}
 
 ## Site
 
 Use these `Site` methods when rendering lists on any page.
 
-{{< list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=SITE. >}}
+{{% list-pages-in-section path=/methods/site filter=methods_site_page_collections filterType=include titlePrefix=SITE. %}}
 
 ## Filter
 
 Use the [`where`] function to filter page collections.
 
-[`where`]: /functions/collections/where/
-
 ## Sort
 
 {{% glossary-term "default sort order" %}}
 
 Use these methods to sort page collections by different criteria.
 
-{{< list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. titlePrefix=PAGES. >}}
+{{% list-pages-in-section path=/methods/pages filter=methods_pages_sort filterType=include titlePrefix=. titlePrefix=PAGES. %}}
 
 ## Group
 
 Use these methods to group page collections.
 
-{{< list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. titlePrefix=PAGES. >}}
+{{% list-pages-in-section path=/methods/pages filter=methods_pages_group filterType=include titlePrefix=. titlePrefix=PAGES. %}}
+
+[`where`]: /functions/collections/where/

content/en/templates/pagination.md

@@ -144,7 +144,7 @@ The `terse` format has fewer controls and page slots, consuming less space when
 
 Create custom navigation components using any of the `Pager` methods:
 
-{{< list-pages-in-section path=/methods/pager >}}
+{{% list-pages-in-section path=/methods/pager %}}
 
 ## Structure
 

content/en/templates/shortcode.md

@@ -70,7 +70,7 @@ foo|json|en|`layouts/shortcodes/foo.json.en.json`
 
 Use these methods in your shortcode templates. Refer to each methods's documentation for details and examples.
 
-{{< list-pages-in-section path=/methods/shortcode >}}
+{{% list-pages-in-section path=/methods/shortcode %}}
 
 ## Examples
 

content/en/troubleshooting/logging.md

@@ -14,30 +14,30 @@ Hugo has four logging levels:
 error
 : Display error messages only.
 
-```sh
+  ```sh
-hugo --logLevel error
+  hugo --logLevel error
-```
+  ```
 
 warn
 : Display warning and error messages.
 
-```sh
+  ```sh
-hugo --logLevel warn
+  hugo --logLevel warn
-```
+  ```
 
 info
 : Display information, warning, and error messages.
 
-```sh
+  ```sh
-hugo --logLevel info
+  hugo --logLevel info
-```
+  ```
 
 debug
 : Display debug, information, warning, and error messages.
 
-```sh
+  ```sh
-hugo --logLevel debug
+  hugo --logLevel debug
-```
+  ```
 
 > [!note]
 > If you do not specify a logging level with the `--logLevel` flag, warnings and errors are always displayed.
@@ -46,7 +46,7 @@ hugo --logLevel debug
 
 You can also use template functions to print warnings or errors to the console. These functions are typically used to report data validation errors, missing files, etc.
 
-{{< list-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include >}}
+{{% list-pages-in-section path=/functions/fmt filter=functions_fmt_logging filterType=include %}}
 
 ## LiveReload
 

data/page_filters.yaml

@@ -6,7 +6,7 @@
 #
 # For example:
 #
-# {{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}}
+# {{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}}
 
 functions_fmt_logging:
   - /functions/fmt/errorf

layouts/_default/_markup/render-codeblock.html

@@ -7,6 +7,9 @@ may also specify the following parameters:
 
 @param {bool} [copy=false] Whether to display a copy-to-clipboard button.
 @param {string} [file] The file name to display above the rendered code.
+@param {bool} [details=false] Whether to wrap the highlighted code block within a details element.
+@param {bool} [open=false] Whether to initially display the content of the details element.
+@param {string} [summary=Details] The content of the details summary element rendered from Markdown to HTML.
 
 @returns {template.HTML}
 
@@ -24,6 +27,9 @@ may also specify the following parameters:
 
 {{- $copy := false }}
 {{- $file := or .Attributes.file "" }}
+{{- $details := false }}
+{{- $open := "" }}
+{{- $summary := or .Attributes.summary "Details" | .Page.RenderString }}
 {{- $ext := strings.TrimPrefix "." (path.Ext $file) }}
 {{- $lang := or .Type $ext "text" }}
 {{- if in (slice "html" "gotmpl") $lang }}
@@ -41,6 +47,26 @@ may also specify the following parameters:
   {{- end }}
 {{- end }}
 
+{{- with .Attributes.details }}
+  {{- if in (slice true "true" 1) . }}
+    {{- $details = true }}
+  {{- else if in (slice false "false" 0) . }}
+    {{- $details = false }}
+  {{- end }}
+{{- end }}
+
+{{- with .Attributes.open }}
+  {{- if in (slice true "true" 1) . }}
+    {{- $open = "open" }}
+  {{- else if in (slice false "false" 0) . }}
+    {{- $open = "" }}
+  {{- end }}
+{{- end }}
+
+{{- if $details }}
+  <details class="cursor-pointer" {{ $open }}>
+  <summary>{{ $summary }}</summary>
+{{- end }}
 
 <div
   x-data
@@ -66,3 +92,7 @@ may also specify the following parameters:
     {{- transform.Highlight (strings.TrimSpace .Inner) $lang .Options }}
   </div>
 </div>
+
+{{- if $details }}
+  </details>
+{{- end }}

layouts/shortcodes/list-pages-in-section.html

@@ -1,4 +1,3 @@
-{{/* prettier-ignore-start */ -}}
 {{- /*
 Renders a description list of the pages in the given section.
 
@@ -10,88 +9,61 @@ filter is an array of paths to a file, relative to the root of the content
 directory. Hugo will throw an error if the specified filter does not exist, or
 if any of the pages in the filter do not exist.
 
-The definition term elements (dt) have an id attribute derived from the title
-of the page. This is probably unique, because pages of the same title in the
-same section is unlikely.
-
-If you render a complete list on a page, then call the shortcode again to
-render a subset, you will generate duplicate element ids. In this case, set
-omitElementIDs to true for the subset.
-
 @param {string} path The path to the section.
 @param {string} [filter=""] The name of filter list.
 @param {string} [filterType=""] The type of filter, either include or exclude.
-@param {string} [omitElementIDs=true] Whether to omit dt element ids.
 @param {string} [titlePrefix=""] The string to prepend to the link title.
 
 @example {{< list-pages-in-section path=/methods/resources >}}
 @example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude >}}
 @example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo >}}
-@example {{< list-pages-in-section path=/functions/images filter=some_filter filterType=exclude titlePrefix=foo omitElementIDs=true >}}
+*/}}
-*/ -}}
-{{/* prettier-ignore-end */ -}}
-{{- /* Initialize. */}}
-{{- $filter := or "" (.Get "filter" | lower) }}
-{{- $filterType := or (.Get "filterType") "none" | lower }}
-{{- $filteredPages := slice }}
-{{- $titlePrefix := or (.Get "titlePrefix") "" }}
-{{- $omitElementIDs := true }}
 
-{{- /* Get boolean parameters. */}}
+{{/* Initialize. */}}
-{{- if in (slice "false" false 0) (.Get "omitElementIDs") }}
+{{ $filter := or "" (.Get "filter" | lower) }}
-  {{- $omitElementIDs = false }}
+{{ $filterType := or (.Get "filterType") "none" | lower }}
-{{- else if in (slice "true" true 1) (.Get "omitElementIDs") }}
+{{ $filteredPages := slice }}
-  {{- $omitElementIDs = true }}
+{{ $titlePrefix := or (.Get "titlePrefix") "" }}
-{{- end }}
 
-{{- /* Build slice of filtered pages. */}}
+{{/* Build slice of filtered pages. */}}
-{{- with $filter }}
+{{ with $filter }}
-  {{- with index site.Data.page_filters . }}
+  {{ with index site.Data.page_filters . }}
-    {{- range . }}
+    {{ range . }}
-      {{- with site.GetPage . }}
+      {{ with site.GetPage . }}
-        {{- $filteredPages = $filteredPages | append . }}
+        {{ $filteredPages = $filteredPages | append . }}
-      {{- else }}
+      {{ else }}
-        {{- errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }}
+        {{ errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }}
-      {{- end }}
+      {{ end }}
-    {{- end }}
+    {{ end }}
-  {{- else }}
+  {{ else }}
-    {{- errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }}
+    {{ errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }}
-  {{- end }}
+  {{ end }}
-{{- end }}
+{{ end }}
 
-{{- /* Render */}}
+{{/* Render. */}}
-{{- with $sectionPath := .Get "path" }}
+{{ with $sectionPath := .Get "path" }}
-  {{- with site.GetPage . }}
+  {{ with site.GetPage . }}
-    {{- with .RegularPages }}
+    {{ with .RegularPages }}
-      <dl>
+        {{ range $page := .ByTitle }}
-        {{- range $page := .ByTitle }}
+          {{ if or
-          {{- if or
             (and (eq $filterType "include") (in $filteredPages $page))
             (and (eq $filterType "exclude") (not (in $filteredPages $page)))
             (eq $filterType "none")
           }}
-            {{- $linkTitle := .LinkTitle }}
+            {{ $linkTitle := .LinkTitle }}
-            {{- with $titlePrefix }}
+            {{ with $titlePrefix }}
-              {{- $linkTitle = printf "%s%s" . $linkTitle }}
+              {{ $linkTitle = printf "%s%s" . $linkTitle }}
-            {{- end }}
+            {{ end }}
-            {{- $idAttribute := "" }}
+[{{ $linkTitle }}]({{ $page.RelPermalink }}){{/* Do not indent. */}}
-            {{- if not $omitElementIDs }}
+: {{ $page.Description }}{{/* Do not indent. */}}
-              {{- $id := path.Join .File.Dir .File.ContentBaseName | replaceRE `[\|/]` ":" | lower }}
+          {{ end }}
-              {{- $idAttribute = printf " id=%q" $id }}
+        {{ end }}
-            {{- end }}
+    {{ else }}
-            <dt {{- $idAttribute | safeHTMLAttr }}>
+      {{ warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }}
-              <a href="{{ $page.RelPermalink }}">{{ $linkTitle }}</a>
+    {{ end }}
-            </dt>
+  {{ else }}
-            <dd>{{- $page.Description | $page.RenderString }}</dd>
+    {{ errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }}
-          {{- end }}
+  {{ end }}
-        {{- end }}
+{{ else }}
-      </dl>
+  {{ errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }}
-    {{- else }}
+{{ end }}
-      {{- warnf "The %q shortcode found no pages in the %q section. See %s" $.Name $sectionPath $.Position }}
-    {{- end }}
-  {{- else }}
-    {{- errorf "The %q shortcode was unable to find %q. See %s" $.Name $sectionPath $.Position }}
-  {{- end }}
-{{- else }}
-  {{- errorf "The %q shortcode requires a 'path' parameter indicating the path to the section. See %s" $.Name $.Position }}
-{{- end }}

layouts/shortcodes/quick-reference.html

@@ -1,40 +1,28 @@
-{{/* prettier-ignore-start */ -}}
 {{- /*
 Renders the child sections of the given top-level section, listing each child's
 immediate descendants.
 
 @param {string} section The top-level section to render.
 
-@example {{< quick-reference section="functions" >}}
+@example {{% quick-reference section="/functions" %}}
 */ -}}
-{{/* prettier-ignore-end */ -}}
 {{ $section := "" }}
 {{ with .Get "section" }}
   {{ $section = . }}
 {{ else }}
-  {{ errorf "The %q shortcodes requires a 'section' parameter. See %s" .Name .Position }}
+  {{ errorf "The %q shortcode requires a 'section' parameter. See %s" .Name .Position }}
 {{ end }}
 
 {{ with site.GetPage $section }}
   {{ range .Sections }}
-    <h2>{{ .LinkTitle }}</h2>
+## {{ .LinkTitle }}{{/* Do not indent. */}}
+{{ .Description }}{{/* Do not indent. */}}
     {{ .Content }}
     {{ with .Pages }}
-      <dl>
+      {{ range . }}
-        {{ range . }}
+[{{ .LinkTitle }}]({{ .RelPermalink }}){{/* Do not indent. */}}
-          {{ $aliases := "" }}
+: {{ .Description }}{{/* Do not indent. */}}
-          {{ if eq .Section "functions" }}
+      {{ end }}
-            {{ with .Params.functions_and_methods.aliases }}
-              {{ $aliases = delimit . " or " }}
-            {{ end }}
-          {{ end }}
-          <dt>
-            <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
-            {{ with $aliases }}<span class="font-normal text-stone-700">({{ . }})</span>{{ end }}
-          </dt>
-          <dd>{{ .Description }}</dd>
-        {{ end }}
-      </dl>
     {{ end }}
   {{ end }}
 {{ else }}