TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-08-03 20:49:41 -04:00
Code Issues Packages Projects Releases Wiki Activity

theme: Adjust shortcodes

Browse Source
This commit is contained in:
Joe Mooring 2025-03-09 12:01:23 -07:00 committed by GitHub
parent 8988704383
commit 8ebaa53f93
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
15 changed files with 123 additions and 121 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.prettierignore
View File

@ -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

2
content/en/content-management/shortcodes.md
View File

@ -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

16
content/en/contribute/documentation.md
View File

@ -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

2
content/en/functions/images/Filter.md
View File

@ -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 %}}

2
content/en/methods/resource/Filter.md
View File

@ -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 %}}

2
content/en/quick-reference/functions.md
View File

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

2
content/en/quick-reference/methods.md
View File

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

12
content/en/quick-reference/page-collections.md
View File

@ -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/

2
content/en/templates/pagination.md
View File

@ -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

2
content/en/templates/shortcode.md
View File

@ -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

26
content/en/troubleshooting/logging.md
View File

@ -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

2
data/page_filters.yaml
View File

@ -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

30
layouts/_default/_markup/render-codeblock.html
View File

@ -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 }}

114
layouts/shortcodes/list-pages-in-section.html
View File

@ -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 }}
<dl>
{{- 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 }}
<dt {{- $idAttribute | safeHTMLAttr }}>
<a href="{{ $page.RelPermalink }}">{{ $linkTitle }}</a>
</dt>
<dd>{{- $page.Description | $page.RenderString }}</dd>
{{- end }}
{{- end }}
</dl>
{{- 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 }}

28
layouts/shortcodes/quick-reference.html
View File

@ -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 . }}
{{ $aliases := "" }}
{{ if eq .Section "functions" }}
{{ 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>
{{ range . }}
[{{ .LinkTitle }}]({{ .RelPermalink }}){{/* Do not indent. */}}
: {{ .Description }}{{/* Do not indent. */}}
{{ end }}
{{ end }}
{{ end }}
{{ else }}