diff --git a/.prettierignore b/.prettierignore index 630782282..f24bbcef0 100644 --- a/.prettierignore +++ b/.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 diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md index 9022d5594..2de387f39 100644 --- a/content/en/content-management/shortcodes.md +++ b/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 diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index 35d9e2517..1d185d21d 100644 --- a/content/en/contribute/documentation.md +++ b/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 -erroneous lexing/highlighting of shortcode calls. +To wrap the code block within an initially-opened `details` element using a non-default summary: + +````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 diff --git a/content/en/functions/images/Filter.md b/content/en/functions/images/Filter.md index c5c8cbd49..1f2c268be 100644 --- a/content/en/functions/images/Filter.md +++ b/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 %}} diff --git a/content/en/methods/resource/Filter.md b/content/en/methods/resource/Filter.md index 79539631e..b83c3d8cb 100644 --- a/content/en/methods/resource/Filter.md +++ b/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 %}} diff --git a/content/en/quick-reference/functions.md b/content/en/quick-reference/functions.md index ee8844775..72235d0f3 100644 --- a/content/en/quick-reference/functions.md +++ b/content/en/quick-reference/functions.md @@ -5,4 +5,4 @@ categories: [] keywords: [] --- -{{< quick-reference section="functions" >}} +{{% quick-reference section="functions" %}} diff --git a/content/en/quick-reference/methods.md b/content/en/quick-reference/methods.md index f8cf6b8c9..524713c1f 100644 --- a/content/en/quick-reference/methods.md +++ b/content/en/quick-reference/methods.md @@ -5,4 +5,4 @@ categories: [] keywords: [] --- -{{< quick-reference section="methods" >}} +{{% quick-reference section="methods" %}} diff --git a/content/en/quick-reference/page-collections.md b/content/en/quick-reference/page-collections.md index 43b7178b3..4c2387bbe 100644 --- a/content/en/quick-reference/page-collections.md +++ b/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/ diff --git a/content/en/templates/pagination.md b/content/en/templates/pagination.md index c755b2521..018ec9271 100644 --- a/content/en/templates/pagination.md +++ b/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 diff --git a/content/en/templates/shortcode.md b/content/en/templates/shortcode.md index cca4f215c..711d342cb 100644 --- a/content/en/templates/shortcode.md +++ b/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 diff --git a/content/en/troubleshooting/logging.md b/content/en/troubleshooting/logging.md index aa658cd12..0cd25d1ae 100644 --- a/content/en/troubleshooting/logging.md +++ b/content/en/troubleshooting/logging.md @@ -14,30 +14,30 @@ Hugo has four logging levels: error : Display error messages only. -```sh -hugo --logLevel error -``` + ```sh + hugo --logLevel error + ``` warn : Display warning and error messages. -```sh -hugo --logLevel warn -``` + ```sh + hugo --logLevel warn + ``` info : Display information, warning, and error messages. -```sh -hugo --logLevel info -``` + ```sh + hugo --logLevel info + ``` debug : Display debug, information, warning, and error messages. -```sh -hugo --logLevel debug -``` + ```sh + 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 diff --git a/data/page_filters.yaml b/data/page_filters.yaml index a4969e9b7..82de6168e 100644 --- a/data/page_filters.yaml +++ b/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 diff --git a/layouts/_default/_markup/render-codeblock.html b/layouts/_default/_markup/render-codeblock.html index 8afc5b076..13725ffcd 100644 --- a/layouts/_default/_markup/render-codeblock.html +++ b/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 }} +
+ {{ $summary }} +{{- end }}
+ +{{- if $details }} +
+{{- end }} diff --git a/layouts/shortcodes/list-pages-in-section.html b/layouts/shortcodes/list-pages-in-section.html index abc5bc2ed..f6dfe7275 100644 --- a/layouts/shortcodes/list-pages-in-section.html +++ b/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. */}} -{{- if in (slice "false" false 0) (.Get "omitElementIDs") }} - {{- $omitElementIDs = false }} -{{- else if in (slice "true" true 1) (.Get "omitElementIDs") }} - {{- $omitElementIDs = true }} -{{- end }} +{{/* Initialize. */}} +{{ $filter := or "" (.Get "filter" | lower) }} +{{ $filterType := or (.Get "filterType") "none" | lower }} +{{ $filteredPages := slice }} +{{ $titlePrefix := or (.Get "titlePrefix") "" }} -{{- /* Build slice of filtered pages. */}} -{{- with $filter }} - {{- with index site.Data.page_filters . }} - {{- range . }} - {{- with site.GetPage . }} - {{- $filteredPages = $filteredPages | append . }} - {{- else }} - {{- errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }} - {{- end }} - {{- end }} - {{- else }} - {{- errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }} - {{- end }} -{{- end }} +{{/* Build slice of filtered pages. */}} +{{ with $filter }} + {{ with index site.Data.page_filters . }} + {{ range . }} + {{ with site.GetPage . }} + {{ $filteredPages = $filteredPages | append . }} + {{ else }} + {{ errorf "The %q shortcode was unable to find %q as specified in the page_filters data file. See %s" $.Name . $.Position }} + {{ end }} + {{ end }} + {{ else }} + {{ errorf "The %q shortcode was unable to find the %q filter in the page_filters data file. See %s" $.Name . $.Position }} + {{ end }} +{{ end }} -{{- /* Render */}} -{{- with $sectionPath := .Get "path" }} - {{- with site.GetPage . }} - {{- with .RegularPages }} -
- {{- range $page := .ByTitle }} - {{- if or +{{/* Render. */}} +{{ with $sectionPath := .Get "path" }} + {{ with site.GetPage . }} + {{ with .RegularPages }} + {{ range $page := .ByTitle }} + {{ if or (and (eq $filterType "include") (in $filteredPages $page)) (and (eq $filterType "exclude") (not (in $filteredPages $page))) (eq $filterType "none") }} - {{- $linkTitle := .LinkTitle }} - {{- with $titlePrefix }} - {{- $linkTitle = printf "%s%s" . $linkTitle }} - {{- end }} - {{- $idAttribute := "" }} - {{- if not $omitElementIDs }} - {{- $id := path.Join .File.Dir .File.ContentBaseName | replaceRE `[\|/]` ":" | lower }} - {{- $idAttribute = printf " id=%q" $id }} - {{- end }} -
- {{ $linkTitle }} -
-
{{- $page.Description | $page.RenderString }}
- {{- end }} - {{- end }} -
- {{- else }} - {{- 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 }} + {{ $linkTitle := .LinkTitle }} + {{ with $titlePrefix }} + {{ $linkTitle = printf "%s%s" . $linkTitle }} + {{ end }} +[{{ $linkTitle }}]({{ $page.RelPermalink }}){{/* Do not indent. */}} +: {{ $page.Description }}{{/* Do not indent. */}} + {{ end }} + {{ end }} + {{ else }} + {{ 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 }} diff --git a/layouts/shortcodes/quick-reference.html b/layouts/shortcodes/quick-reference.html index 174a732d8..0ac544036 100644 --- a/layouts/shortcodes/quick-reference.html +++ b/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 }} -

{{ .LinkTitle }}

+## {{ .LinkTitle }}{{/* Do not indent. */}} +{{ .Description }}{{/* Do not indent. */}} {{ .Content }} {{ with .Pages }} -
- {{ range . }} - {{ $aliases := "" }} - {{ if eq .Section "functions" }} - {{ with .Params.functions_and_methods.aliases }} - {{ $aliases = delimit . " or " }} - {{ end }} - {{ end }} -
- {{ .LinkTitle }} - {{ with $aliases }}({{ . }}){{ end }} -
-
{{ .Description }}
- {{ end }} -
+ {{ range . }} +[{{ .LinkTitle }}]({{ .RelPermalink }}){{/* Do not indent. */}} +: {{ .Description }}{{/* Do not indent. */}} + {{ end }} {{ end }} {{ end }} {{ else }}