MD049: false
MD050: false
MD053: false
+MD055: false
}
code {
- padding: 0.2em;
+ padding: 2px 3px;
margin: 0;
- font-size: 85%;
+ font-size: 93.75%;
background-color: rgba(27,31,35,0.05);
border-radius: 3px;
}
margin: 0;
}
code {
- padding: 0.2em;
+ padding: 2px 3px;
margin: 0;
- font-size: 85%;
+ font-size: 93.75%;
background-color: rgba(27, 31, 35, .05);
border-radius: 3px;
}
{{ $data := "" }}
{{ $url := urls.JoinPath "https://api.github.com/users" $author }}
- {{ with resources.GetRemote $url }}
+ {{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
- {{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
<div class="tc">
{{ $data := "" }}
{{ $url := urls.JoinPath "https://api.github.com/users" $author }}
- {{ with resources.GetRemote $url }}
+ {{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
- {{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ with $data }}
{{ $url := . }}
{{ $data := dict }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $data = .Content | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ return $data }}
--- /dev/null
+{{- /*
+Returns syntax-highlighted code from the given text.
+
+This is useful as a terse way to highlight inline code snippets. Calling the
+highlight shortcode for inline snippets is verbose.
+*/}}
+
+{{- $code := .Inner | strings.TrimSpace }}
+{{- $lang := or (.Get 0) "go" }}
+{{- $opts := dict "hl_inline" true "noClasses" true }}
+{{- transform.Highlight $code $lang $opts }}
{{- $validFilters := slice
"autoorient" "brightness" "colorbalance" "colorize" "contrast" "dither"
- "gamma" "gaussianblur" "grayscale" "hue" "invert" "none" "opacity" "overlay"
- "padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text"
+ "gamma" "gaussianblur" "grayscale" "hue" "invert" "mask" "none" "opacity"
+ "overlay" "padding" "pixelate" "process" "saturation" "sepia" "sigmoid" "text"
"unsharpmask"
}}
{{- $ctx = merge $ctx (dict "argsRequired" 0) }}
{{- template "validate-arg-count" $ctx }}
{{- $f = images.Invert }}
+{{- else if eq $filter "mask" }}
+ {{- $ctx = merge $ctx (dict "argsRequired" 1) }}
+ {{- template "validate-arg-count" $ctx }}
+ {{- $ctx := dict "src" (index $filterArgs 0) "name" .Name "position" .Position }}
+ {{- $maskImage := partial "inline/get-resource.html" $ctx }}
+ {{- $f = images.Mask $maskImage }}
{{- else if eq $filter "opacity" }}
{{- $ctx = merge $ctx (dict "argsRequired" 1) }}
{{- template "validate-arg-count" $ctx }}
{{- end }}
{{- /* Render. */}}
+{{- $class := "di va b--black-20" }}
+{{- if eq $filter "mask" }}
+ {{- $class = "di va" }}
+{{- end }}
{{- if $example }}
<p>Original</p>
- <img class='di ba b--black-20' style="width: initial;" src="{{ $i.RelPermalink }}" alt="{{ $alt }}">
+ <img class="{{ $class}}" style="width: initial;" src="{{ $i.RelPermalink }}" alt="{{ $alt }}">
<p>Processed</p>
- <img class='di ba b--black-20' style="width: initial;" src="{{ $fi.RelPermalink }}" alt="{{ $alt }}">
+ <img class="{{ $class }}" style="width: initial;" src="{{ $fi.RelPermalink }}" alt="{{ $alt }}">
{{- else -}}
<img class='di' style="width: initial;" src="{{ $fi.RelPermalink }}" alt="{{ $alt }}">
{{- end }}
{{- $u := urls.Parse .src }}
{{- $msg := "The %q shortcode was unable to resolve %s. See %s" }}
{{- if $u.IsAbs }}
- {{- with resources.GetRemote $u.String }}
+ {{- with try (resources.GetRemote $u.String) }}
{{- with .Err }}
{{- errorf "%s" . }}
- {{- else }}
+ {{- else with .Value }}
{{- /* This is a remote resource. */}}
{{- $r = . }}
+ {{- else }}
+ {{- errorf $msg $.name $u.String $.position }}
{{- end }}
- {{- else }}
- {{- errorf $msg $.name $u.String $.position }}
{{- end }}
{{- else }}
{{- with .page.Resources.Get (strings.TrimPrefix "./" $u.Path) }}
-# github.com/gohugoio/gohugoioTheme v0.0.0-20250106044328-feb60697e056
+# github.com/gohugoio/gohugoioTheme v0.0.0-20250116152525-2d382cae7743
--- /dev/null
+---
+title: {{ replace .File.ContentBaseName "-" " " }}
+---
+
+<!--
+You can insert these definitions in other pages using the `glossary-term` shortcode, so they must be self-contained.
+
+Do this:
+
+ A _foo_ is big bar.
+
+Not this:
+
+ A big bar.
+
+Italicize the term whenever you use it in the definition.
+
+An exception to this rule occurs when a term is an alias for another. In such cases, it is sufficient to use the phrase 'See [page kind]'."
+-->
To complete this showcase:
1. Write the story about your site in this file.
-2. Add a summary to the `bio.md` file in this folder.
+2. Add a summary to the `bio.md` file in this directory.
3. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`.
4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls
pageRef = '/render-hooks/'
[[docs]]
-name = 'Hugo Modules'
+name = 'Shortcodes'
weight = 100
+identifier = 'shortcodes'
+pageRef = '/shortcodes/'
+
+[[docs]]
+name = 'Hugo Modules'
+weight = 110
identifier = 'modules'
pageRef = '/hugo-modules/'
[[docs]]
name = 'Hugo Pipes'
-weight = 110
+weight = 120
identifier = 'hugo-pipes'
pageRef = '/hugo-pipes/'
[[docs]]
name = 'CLI'
-weight = 120
+weight = 130
post = 'break'
identifier = 'commands'
pageRef = '/commands/'
[[docs]]
name = 'Troubleshooting'
-weight = 130
+weight = 140
identifier = 'troubleshooting'
pageRef = '/troubleshooting/'
[[docs]]
name = 'Developer tools'
-weight = 140
+weight = 150
identifier = 'developer-tools'
pageRef = '/tools/'
[[docs]]
name = 'Hosting and deployment'
-weight = 150
+weight = 160
identifier = 'hosting-and-deployment'
pageRef = '/hosting-and-deployment/'
[[docs]]
name = 'Contribute'
-weight = 160
+weight = 170
post = 'break'
identifier = 'contribute'
pageRef = '/contribute/'
: Use fenced code blocks and Markdown render hooks to include diagrams in your content.
[Mathematics]
-: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax.
+: Include mathematical equations and expressions in Markdown using LaTeX markup.
[Syntax highlighting]
: Syntactically highlight code examples using Hugo's embedded syntax highlighter, enabled by default for fenced code blocks in Markdown. The syntax highlighter supports hundreds of code languages and dozens of styles.
[Mathematics]: /content-management/mathematics/
[Menus]: /content-management/menus/
[Minification]: /getting-started/configuration/#configure-minify
-[Modules]: https://gohugo.io/hugo-modules/
+[Modules]: /hugo-modules/
[Multilingual]: /content-management/multilingual/
[Multiplatform]: /installation/
[Output formats]: /templates/output-formats/
[Syntax highlighting]: /content-management/syntax-highlighting/
[Tailwind CSS processing]: /functions/css/tailwindcss/
[Taxonomies]: /content-management/taxonomies/
-[Templates]: templates/introduction/
+[Templates]: /templates/introduction/
[Themes]: https://themes.gohugo.io/
[URL management]: /content-management/urls/
[privacy.instagram]
disable = false
simple = false
-[privacy.twitter]
+[privacy.vimeo]
disable = false
enableDNT = false
simple = false
-[privacy.vimeo]
+[privacy.x]
disable = false
enableDNT = false
simple = false
disable = true
[privacy.instagram]
disable = true
-[privacy.twitter]
-disable = true
[privacy.vimeo]
disable = true
+[privacy.x]
+disable = true
[privacy.youtube]
disable = true
{{< /code-toggle >}}
disableInlineCSS = true
{{< /code-toggle >}}
-### Twitter
+### X
enableDNT
-: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads.
+: Enabling this for the x shortcode, the post and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads.
simple
-: If simple mode is enabled, a static and no-JS version of a tweet will be built.
+: If simple mode is enabled, a static and no-JS version of a post will be built.
-**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inline styles provided by Hugo:
+**Note:** If you use the _simple mode_ for X, you may want to disable the inline styles provided by Hugo:
{{< code-toggle file=hugo >}}
[services]
-[services.twitter]
+[services.x]
disableInlineCSS = true
{{< /code-toggle >}}
* [hugo completion](/commands/hugo_completion/) - Generate the autocompletion script for the specified shell
* [hugo config](/commands/hugo_config/) - Display site configuration
* [hugo convert](/commands/hugo_convert/) - Convert front matter to another format
-* [hugo deploy](/commands/hugo_deploy/) - Deploy your site to a cloud provider
* [hugo env](/commands/hugo_env/) - Display version and environment info
* [hugo gen](/commands/hugo_gen/) - Generate documentation and syntax highlighting styles
* [hugo import](/commands/hugo_import/) - Import a site from another system
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--format string preferred file format (toml, yaml or json) (default "toml")
-h, --help help for config
--lang string the language to display config for. Defaults to the first language defined.
+ --printZero include config options with zero values (e.g. false, 0, "") in the output
--renderSegments strings named segments to render (configured in the segments config)
-t, --theme strings themes to use (located in /themes/THEMENAME/)
```
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
-o, --output string filesystem path to write files to
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
-o, --output string filesystem path to write files to
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
-o, --output string filesystem path to write files to
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
--liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1)
--minify minify any supported output format (HTML, XML etc.)
-N, --navigateToChanged navigate to changed content file on live browser reload
- --noBuildLock don't create .hugo_build.lock file
--noChmod don't sync permission mode of files
--noHTTPCache prevent HTTP caching
--noTimes don't sync modification time of files
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
-e, --environment string build environment
--ignoreVendorPaths string ignores any _vendor for module paths matching the given Glob pattern
--logLevel string log level (debug|info|warn|error)
+ --noBuildLock don't create .hugo_build.lock file
--quiet build in quiet mode
-M, --renderToMemory render to memory (mostly useful when running the server)
-s, --source string filesystem path to read files relative from
## Overview
-A content file consists of [front matter] and markup. The markup is typically Markdown, but Hugo also supports other [content formats]. Front matter can be TOML, YAML, or JSON.
+A content file consists of [front matter](g) and markup. The markup is typically Markdown, but Hugo also supports other [content formats](g). Front matter can be TOML, YAML, or JSON.
The `hugo new content` command creates a new file in the `content` directory, using an archetype as a template. This is the default archetype:
draft = true
{{< /code-toggle >}}
-When you create new content, Hugo evaluates the [template actions] within the archetype. For example:
+When you create new content, Hugo evaluates the [template actions](g) within the archetype. For example:
```sh
hugo new content posts/my-first-post.md
draft = true
{{< /code-toggle >}}
-You can create an archetype for one or more [content types]. For example, use one archetype for posts, and use the default archetype for everything else:
+You can create an archetype for one or more [content types](g). For example, use one archetype for posts, and use the default archetype for everything else:
```text
archetypes/
The archetype lookup order is:
-1. archetypes/posts.md
-1. archetypes/default.md
-1. themes/my-theme/archetypes/posts.md
-1. themes/my-theme/archetypes/default.md
+1. `archetypes/posts.md`
+1. `archetypes/default.md`
+1. `themes/my-theme/archetypes/posts.md`
+1. `themes/my-theme/archetypes/default.md`
If none of these exists, Hugo uses a built-in default archetype.
## Functions and context
-You can use any [template function] within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter.
+You can use any template [function](g) within an archetype. As shown above, the default archetype uses the [`replace`](/functions/strings/replace) function to replace hyphens with spaces when populating the title in front matter.
-Archetypes receive the following [context]:
+Archetypes receive the following [context](g):
Date
: (`string`) The current date and time, formatted in compliance with RFC3339.
: (`hugolib.fileInfo`) Returns file information for the current page. See [details](/methods/page/file).
Type
-: (`string`) The [content type] inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command.
-
-[content type]: /getting-started/glossary#content-type
+: (`string`) The [content type](g) inferred from the top-level directory name, or as specified by the `--kind` flag passed to the `hugo new content` command.
Site
: (`page.Site`) The current site object. See [details](/methods/site/).
Additional information to clarify as needed.
{{< /code >}}
-Although you can include [template actions] within the content body, remember that Hugo evaluates these once---at the time of content creation. In most cases, place template actions in a [template] where Hugo evaluates the actions every time you [build](/getting-started/glossary/#build) the site.
+Although you can include [template actions](g) within the content body, remember that Hugo evaluates these once---at the time of content creation. In most cases, place template actions in a [template](g) where Hugo evaluates the actions every time you [build](g) the site.
## Leaf bundles
-You can also create archetypes for [leaf bundles](/getting-started/glossary/#leaf-bundle).
+You can also create archetypes for [leaf bundles](g).
For example, in a photography site you might have a section (content type) for galleries. Each gallery is leaf bundle with content and images.
```sh
hugo new content --kind tutorials articles/something.md
```
-
-[content formats]: /getting-started/glossary/#content-format
-[content types]: /getting-started/glossary/#content-type
-[context]: /getting-started/glossary/#context
-[front matter]: /getting-started/glossary/#front-matter
-[template actions]: /getting-started/glossary/#template-action
-[template]: /getting-started/glossary/#template
-[template function]: /getting-started/glossary/#function
render = 'always'
{{< /code-toggle >}}
-
list
: When to include the page within page collections. Specify one of:
In the example above, note that:
1. Hugo did not publish an HTML file for the page.
-2. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+1. Despite setting `publishResources` to `false` in front matter, Hugo published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
## Example -- headless section
In the example above, note that:
1. Hugo did not publish an HTML file for the page.
-2. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
+1. Despite setting `publishResources` to `false` in front matter, Hugo correctly published the [page resources] because we invoked the [`RelPermalink`] method on each resource. This is the expected behavior.
## Example -- list without publishing
A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML.
-Unlike templates that reside in the layouts directory, content adapters reside in the content directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path] will be relative to the content adapter.
+Unlike templates that reside in the `layouts` directory, content adapters reside in the `content` directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path](g) will be relative to the content adapter.
```text
content/
└── _index.md
```
-Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the layouts directory. You can use any of the [template functions] within a content adapter, as well as the methods described below.
+Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the `layouts` directory. You can use any of the [template functions] within a content adapter, as well as the methods described below.
## Methods
`dates.expiryDate`|The page expiry date as a `time.Time` value.|
`dates.lastmod`|The page last modification date as a `time.Time` value.|
`dates.publishDate`|The page publication date as a `time.Time` value.|
-`kind`|The [page kind]. Default is `page`.|
`params`|A map of page parameters.|
-`path`|The page's [logical path] relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
+`path`|The page's [logical path](g) relative to the content adapter. Do not include a leading slash or file extension.|:heavy_check_mark:
`title`|The page title.|
{{% note %}}
`content.value`|The content value as a string or resource.|:heavy_check_mark:
`name`|The resource name.|
`params`|A map of resource parameters.|
-`path`|The resources's [logical path] relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
+`path`|The resources's [logical path](g) relative to the content adapter. Do not include a leading slash.|:heavy_check_mark:
`title`|The resource title.|
{{% note %}}
{{/* Get remote data. */}}
{{ $data := dict }}
{{ $url := "https://gohugo.io/shared/examples/data/books.json" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "Unable to get remote resource %s: %s" $url . }}
- {{ else }}
+ {{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %s" $url }}
{{ end }}
{{/* Add pages and page resources. */}}
{{/* Add page resource. */}}
{{ $item := . }}
{{ with $url := $item.cover }}
- {{ with resources.GetRemote $url }}
+ {{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "Unable to get remote resource %s: %s" $url . }}
- {{ else }}
+ {{ else with .Value }}
{{ $content := dict "mediaType" .MediaType.Type "value" .Content }}
{{ $params := dict "alt" $item.title }}
{{ $resource := dict
"path" (printf "%s/cover.%s" $item.title .MediaType.SubType)
}}
{{ $.AddResource $resource }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %s" $url }}
{{ end }}
- {{ else }}
- {{ errorf "Unable to get remote resource %s" $url }}
{{ end }}
{{ end }}
With multilingual sites you can:
1. Create one content adapter for all languages using the [`EnableAllLanguages`](#enablealllanguages) method as described above.
-2. Create content adapters unique to each language. See the examples below.
+1. Create content adapters unique to each language. See the examples below.
### Translations by file name
[content formats]: /content-management/formats/#classification
[front matter field]: /content-management/front-matter/#fields
-[logical path]: /getting-started/glossary/#logical-path
[media type]: https://en.wikipedia.org/wiki/Media_type
-[page kind]: /getting-started/glossary/#page-kind
[syntax]: /templates/introduction/
[template functions]: /functions/
{{</* relref "/blog/my-post.md" */>}}
```
-index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder:
+`index.md` can be reference either by its path or by its containing directory without the ending `/`. `_index.md` can be referenced only by its containing directory:
```text
{{</* ref "/about" */>}} <-- References /about/_index.md
aliases: [/extras/datafiles/,/extras/datadrivencontent/,/doc/datafiles/,/templates/data-templates/]
---
-Hugo can access and [unmarshal] local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content.
+Hugo can access and [unmarshal](g) local and remote data sources including CSV, JSON, TOML, YAML, and XML. Use this data to augment existing content or to create new content.
-[unmarshal]: /getting-started/glossary/#unmarshal
-
-A data source might be a file in the data directory, a [global resource], a [page resource], or a [remote resource].
-
-[global resource]: /getting-started/glossary/#global-resource
-[page resource]: /getting-started/glossary/#page-resource
-[remote resource]: /getting-started/glossary/#remote-resource
+A data source might be a file in the `data` directory, a [global resource](g), a [page resource](g), or a [remote resource](g).
## Data directory
-The data directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object.
+The `data` directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object.
-Hugo also merges data directories from themes and modules into this single data structure, where the data directory in the root of your project takes precedence.
+Hugo also merges data directories from themes and modules into this single data structure, where the `data` directory in the root of your project takes precedence.
{{% note %}}
Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead.
```
{{% note %}}
-Do not place CSV files in the data directory. Access CSV files as page, global, or remote resources.
+Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources.
{{% /note %}}
See the documentation for the [`Data`] method on a `Site` object for details and examples.
Regardless of content format, all content must have [front matter], preferably including both `title` and `date`.
-Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification](#classification) table below for a list of markup identifiers and recognized file extensions.
+Hugo selects the content renderer based on the `markup` identifier in front matter, falling back to the file extension. See the [classification] table below for a list of markup identifiers and recognized file extensions.
+
+[classification]: #classification
+[front matter]: /content-management/front-matter/
## Formats
Create your content in [Markdown] preceded by front matter.
-Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can [configure Goldmark] in your site configuration.
+Markdown is Hugo's default content format. Hugo natively renders Markdown to HTML using [Goldmark]. Goldmark is fast and conforms to the [CommonMark] and [GitHub Flavored Markdown] specifications. You can configure Goldmark in your [site configuration][configure goldmark].
Hugo provides custom Markdown features including:
: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
[Mathematics]
-: Include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax.
+: Include mathematical equations and expressions in Markdown using LaTeX markup.
[Render hooks]
: Override the conversion of Markdown to HTML when rendering fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element.
+[Attributes]: /content-management/markdown-attributes/
+[CommonMark]: https://spec.commonmark.org/current/
+[Extensions]: /getting-started/configuration-markup/#goldmark-extensions
+[GitHub Flavored Markdown]: https://github.github.com/gfm/
+[Goldmark]: https://github.com/yuin/goldmark
+[Markdown]: https://daringfireball.net/projects/markdown/
+[Mathematics]: /content-management/mathematics/
+[Render hooks]: /render-hooks/introduction/
+[configure goldmark]: /getting-started/configuration-markup/#goldmark
+
### HTML
Create your content in [HTML] preceded by front matter. The content is typically what you would place within an HTML document's `body` or `main` element.
+[HTML]: https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Your_first_website/Creating_the_content
+
### Emacs Org Mode
-Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details](/content-management/front-matter/#emacs-org-mode).
+Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details].
+
+[details]: /content-management/front-matter/#emacs-org-mode
+[Emacs Org Mode]: https://orgmode.org/
### AsciiDoc
Create your content in the [AsciiDoc] format preceded by front matter. Hugo renders AsciiDoc content to HTML using the Asciidoctor executable. You must install Asciidoctor and its dependencies (Ruby) to use the AsciiDoc content format.
-You can [configure the AsciiDoc renderer] in your site configuration.
+You can configure the AsciiDoc renderer in your [site configuration][configure asciidoc].
In its default configuration, Hugo passes these CLI flags when calling the Asciidoctor executable:
hugo --logLevel info
```
+[AsciiDoc]: https://asciidoc.org/
+[configure the AsciiDoc renderer]: /getting-started/configuration-markup/#asciidoc
+[configure asciidoc]: /getting-started/configuration-markup/#asciidoc
+
### Pandoc
Create your content in the [Pandoc] format preceded by front matter. Hugo renders Pandoc content to HTML using the Pandoc executable. You must install Pandoc to use the Pandoc content format.
--mathjax
```
+[Pandoc]: https://pandoc.org/
+
### reStructuredText
Create your content in the [reStructuredText] format preceded by front matter. Hugo renders reStructuredText content to HTML using [Docutils], specifically rst2html. You must install Docutils and its dependencies (Python) to use the reStructuredText content format.
--leave-comments --initial-header-level=2
```
+[Docutils]: https://docutils.sourceforge.io/
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+
## Classification
Content format|Media type|Identifier|File extensions
- External renderers for AsciiDoc, Pandoc, and reStructuredText
Native renderers are faster than external renderers.
-
-[AsciiDoc]: https://asciidoc.org/
-[Asciidoctor]: https://asciidoctor.org/
-[Attributes]: /content-management/markdown-attributes/
-[CommonMark]: https://spec.commonmark.org/current/
-[Docutils]: https://docutils.sourceforge.io/
-[Emacs Org Mode]: https://orgmode.org/
-[Extensions]: /getting-started/configuration-markup/#goldmark-extensions
-[GitHub Flavored Markdown]: https://github.github.com/gfm/
-[Goldmark]: https://github.com/yuin/goldmark
-[HTML]: https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/HTML_basics
-[Markdown]: https://daringfireball.net/projects/markdown/
-[Mathematics]: /content-management/mathematics/
-[Pandoc]: https://pandoc.org/
-[Render hooks]: https://gohugo.io/render-hooks/introduction/
-[configure Goldmark]: /getting-started/configuration-markup/#goldmark
-[configure the AsciiDoc renderer]: /getting-started/configuration-markup/#asciidoc
-[front matter]: /content-management/front-matter/
-[reStructuredText]: https://docutils.sourceforge.io/rst.html
author = 'John Smith'
{{< /code-toggle >}}
-Front matter fields may be [boolean], [integer], [float], [string], [arrays], or [maps]. Note that the TOML format also supports unquoted date/time values.
-
-[scalar]: /getting-started/glossary/#scalar
-[arrays]: /getting-started/glossary/#array
-[maps]: /getting-started/glossary/#map
-[boolean]: /getting-started/glossary/#boolean
-[integer]: /getting-started/glossary/#integer
-[float]: /getting-started/glossary/#float
-[string]: /getting-started/glossary/#string
+Front matter fields may be [boolean](g), [integer](g), [float](g), [string](g), [arrays](g), or [maps](g). Note that the TOML format also supports unquoted date/time values.
## Fields
(`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Date`] method on a `Page` object.
-
[`date`]: /methods/page/date/
###### description
###### isCJKLanguage
-(`bool`) Set to `true` if the content language is in the [CJK] family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object.
+(`bool`) Set to `true` if the content language is in the [CJK](g) family. This value determines how Hugo calculates word count, and affects the values returned by the [`WordCount`], [`FuzzyWordCount`], [`ReadingTime`], and [`Summary`] methods on a `Page` object.
[`fuzzywordcount`]: /methods/page/wordcount/
[`readingtime`]: /methods/page/readingtime/
[`summary`]: /methods/page/summary/
[`wordcount`]: /methods/page/wordcount/
-[cjk]: /getting-started/glossary/#cjk
###### keywords
-(`string array`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy] to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object.
+(`string array`) An array of keywords, typically rendered within a `meta` element within the `head` element of the published HTML file, or used as a [taxonomy](g) to classify content. Access these values from a template using the [`Keywords`] method on a `Page` object.
[`keywords`]: /methods/page/keywords/
-[taxonomy]: /getting-started/glossary/#taxonomy
-{{% comment %}}
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
<!--
kind
lang
: The language code for this page. This is usually derived from the module mount or filename.
-->
-{{% /comment %}}
###### lastmod
[`layout`]: /methods/page/layout/
[template lookup order]: /templates/lookup-order/
-[target a specific template]: templates/lookup-order/#target-a-template
+[target a specific template]: /templates/lookup-order/#target-a-template
###### linkTitle
[output formats]: /templates/output-formats/
-{{% comment %}}
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
<!--
path
: The canonical page path.
-->
-{{% /comment %}}
###### params
###### type
-(`string`) The [content type], overriding the value derived from the top level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object.
+(`string`) The [content type](g), overriding the value derived from the top level section in which the page resides. Access this value from a template using the [`Type`] method on a `Page` object.
-[content type]: /getting-started/glossary/#content-type
[`type`]: /methods/page/type/
###### unpublishdate
(`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details.
###### weight
-(`int`) The page [weight], used to order the page within a [page collection]. Access this value from a template using the [`Weight`] method on a `Page` object.
+(`int`) The page [weight](g), used to order the page within a [page collection](g). Access this value from a template using the [`Weight`] method on a `Page` object.
-[page collection]: /getting-started/glossary/#page-collection
-[weight]: /getting-started/glossary/#weight
[`weight`]: /methods/page/weight/
## Parameters
`images`|`[]string`|[`opengraph.html`], [`schema.html`], [`twitter_cards.html`]
`videos`|`[]string`|[`opengraph.html`]
-The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
+The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
[`opengraph.html`]: {{% eturl opengraph %}}
[`schema.html`]: {{% eturl schema %}}
author = 'John Smith'
{{< /code-toggle >}}
-You can add taxonomy terms to the front matter of any these [page kinds]:
+You can add taxonomy terms to the front matter of any these [page kinds](g):
- `home`
- `page`
- `taxonomy`
- `term`
-[page kinds]: /getting-started/glossary/#page-kind
-
Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object. For example:
{{< code file=layouts/_default/single.html >}}
## Cascade
-Any [node] can pass down to its descendants a set of front matter values.
-
-[node]: /getting-started/glossary/#node
+Any [node](g) can pass down to its descendants a set of front matter values.
### Target specific pages
To override the default time zone, set the [`timeZone`](https://gohugo.io/getting-started/configuration/#timezone) in your site configuration. The order of precedence for determining the time zone is:
1. The time zone offset in the date/time string
-2. The time zone specified in your site configuration
-3. The `Etc/UTC` time zone
+1. The time zone specified in your site configuration
+1. The `Etc/UTC` time zone
Example 4: Skips rendering if there's problem accessing a remote resource.
```go-html-template
-{{ $u := "https://gohugo.io/img/hugo-logo.png" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://gohugo.io/img/hugo-logo.png" }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $u }}
{{ end }}
```
## Smart cropping of images
-By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or`Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice.
+By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or `Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice.
Examples using the sunset image from above:
hugo --gc
```
-
[`anchor`]: /content-management/image-processing#anchor
[mounted]: /hugo-modules/configuration#module-configuration-mounts
[page bundle]: /content-management/page-bundles/
[`lang.FormatNumber`]: /functions/lang/formatnumber/
[filters]: /functions/images/filter/#image-filters
-[github.com/disintegration/imaging]: <https://github.com/disintegration/imaging#image-resizing>
-[Smartcrop]: <https://github.com/muesli/smartcrop#smartcrop>
-[Exif]: <https://en.wikipedia.org/wiki/Exif>
+[github.com/disintegration/imaging]: https://github.com/disintegration/imaging#image-resizing
+[Smartcrop]: https://github.com/muesli/smartcrop#smartcrop
+[Exif]: https://en.wikipedia.org/wiki/Exif
[`Process`]: #process
[`Colors`]: #colors
[`Crop`]: #crop
block = true # default is false
{{< /code-toggle >}}
-
## Standalone images
By default, when the [Goldmark] Markdown renderer encounters a standalone image element (no other elements or text on the same line), it wraps the image element within a paragraph element per the [CommonMark specification].
---
title: Mathematics in Markdown
linkTitle: Mathematics
-description: Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
+description: Include mathematical equations and expressions in Markdown using LaTeX markup.
categories: [content management]
-keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting]
+keywords: [katex,latex,math,mathjax,typesetting]
menu:
docs:
parent: content-management
{{< new-in 0.122.0 >}}
+## Overview
+
+Mathematical equations and expressions written in [LaTeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX].
+
+For example, with this LaTeX markup:
+
+```text
\[
\begin{aligned}
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
\end{aligned}
\]
+```
-## Overview
-
-Mathematical equations and expressions authored in [LaTeX] or [TeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX].
-
-For example, this is the mathematical markup for the equations displayed at the top of this page:
+The MathJax display engine renders this:
-```text
\[
\begin{aligned}
KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
\end{aligned}
\]
-```
Equations and expressions can be displayed inline with other text, or as standalone blocks. Block presentation is also known as "display" mode.
-Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different. Common delimiter pairs are shown in [Step 1].
+Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different.
-The approach described below avoids reliance on platform-specific features like shortcodes or code block render hooks. Instead, it utilizes a standardized markup format for mathematical equations and expressions, compatible with the rendering engines used by GitHub, GitLab, [Microsoft VS Code], [Obsidian], [Typora], and others.
+{{% note %}}
+You can configure Hugo to render mathematical markup on the client-side using the MathJax or KaTeX display engine, or you can render the markup while building your site with the [`transform.ToMath`]function.
+
+The first approach is described below.
+
+[`transform.ToMath`]: /functions/transform/tomath/
+{{% /note %}}
## Setup
-Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
+Follow these instructions to include mathematical equations and expressions in your Markdown using LaTeX markup.
###### Step 1
###### Step 4
-Include mathematical equations and expressions in your Markdown using LaTeX or TeX typesetting syntax.
+Include mathematical equations and expressions in Markdown using LaTeX markup.
{{< code file=content/math-examples.md copy=true >}}
This is an inline \(a^*=x-b^*\) equation.
## Engines
-MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.9.
+MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.11.
{{% note %}}
If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
{{< code file=layouts/partials/math.html copy=true >}}
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
-<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
<script>
document.addEventListener("DOMContentLoaded", function() {
renderMathInElement(document.body, {
[KaTeX]: https://katex.org/
[LaTeX]: https://www.latex-project.org/
[MathJax]: https://www.mathjax.org/
-[Microsoft VS Code]: https://code.visualstudio.com/
-[Obsidian]: https://obsidian.md/
[Step 1]: #step-1
[Step 2]: #step-2
[Step 3]: #step-3
-[TeX]: https://en.wikipedia.org/wiki/TeX
-[Typora]: https://typora.io/
-[passthrough extension]: https://github.com/gohugoio/hugo-goldmark-extensions
+[passthrough extension]: /getting-started/configuration-markup/#passthrough
To create a menu for your site:
1. Define the menu entries
-2. [Localize] each entry
-3. Render the menu with a [template]
+1. [Localize] each entry
+1. Render the menu with a [template]
Create multiple menus, either flat or nested. For example, create a main menu for the header, and a separate menu for the footer.
## Define automatically
-To automatically define a menu entry for each top-level [section] of your site, enable the section pages menu in your site configuration.
+To automatically define a menu entry for each top-level [section](g) of your site, enable the section pages menu in your site configuration.
{{< code-toggle file=hugo >}}
sectionPagesMenu = "main"
[localize]: /content-management/multilingual/#menus
[menu templates]: /templates/menu/
[multilingual]: /content-management/multilingual/#menus
-[section]: /getting-started/glossary/#section
[template]: /templates/menu/
In the above, `en` is the language key.
-
Language keys must conform to the syntax described in [RFC 5646]. For example:
- `en`
: (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`.
contentDir
-: (`string`) The content directory for this language. Omit if [translating by file name].
+: (`string`) The `content` directory for this language. Omit if [translating by file name].
disabled
: (`bool`) If `true`, Hugo will not render content for this language. Default is `false`.
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
[translating by file name]: #translation-by-file-name
-### Changes in Hugo 0.112.0
-
-{{< new-in 0.112.0 >}}
+### Site parameters
-In Hugo `v0.112.0` we consolidated all configuration options, and improved how the languages and their parameters are merged with the main configuration. But while testing this on Hugo sites out there, we received some error reports and reverted some of the changes in favor of deprecation warnings:
-
-1. `site.Language.Params` is deprecated. Use `site.Params` directly.
-1. Adding custom parameters to the top level language configuration is deprecated. Define custom parameters within `languages.xx.params`. See `color` in the example below.
+Set language-specific site parameters under each language's `params` key:
{{< code-toggle file=hugo >}}
-
-title = "My blog"
-languageCode = "en-us"
+[params]
+color = "red"
[languages]
-[languages.sv]
-title = "Min blogg"
-languageCode = "sv"
-[languages.en.params]
-color = "blue"
+ [languages.de]
+ languageCode = 'de-DE'
+ title = 'Projekt Dokumentation'
+ weight = 1
+ [languages.de.params]
+ color = 'blue'
+ subtitle = 'Referenz, Tutorials und Erklärungen'
+ [languages.en]
+ languageCode = 'en-US'
+ title = 'Project Documentation'
+ weight = 2
+ [languages.en.params]
+ subtitle = 'Reference, Tutorials, and Explanations'
{{< /code-toggle >}}
-In the example above, all settings except `color` below `params` map to predefined configuration options in Hugo for the site and its language, and should be accessed via the documented accessors:
+When building the English site:
+
+```go-html-template
+{{ site.Params.color }} --> red
+{{ site.Params.subtitle }} --> Reference, Tutorials, and Explanations
+```
+
+When building the English site:
```go-html-template
-{{ site.Title }}
-{{ site.Language.LanguageCode }}
-{{ site.Params.color }}
+{{ site.Params.color }} --> blue
+{{ site.Params.subtitle }} --> 'Referenz, Tutorials und Erklärungen'
```
### Disable a language
### Configure multilingual multihost
-
Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`.
{{% note %}}
Considering the following example:
1. `/content/about.en.md`
-2. `/content/about.fr.md`
+1. `/content/about.fr.md`
The first file is assigned the English language and is linked to the second.
The second file is assigned the French language and is linked to the first.
### Translation by content directory
-This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` parameter.
+This system uses different content directories for each of the languages. Each language's `content` directory is set using the `contentDir` parameter.
{{< code-toggle file=hugo >}}
languages:
Considering the following example in conjunction with the configuration above:
1. `/content/english/about.md`
-2. `/content/french/about.md`
+1. `/content/french/about.md`
The first file is assigned the English language and is linked to the second.
The second file is assigned the French language and is linked to the first.
-Their language is __assigned__ according to the content directory they are __placed__ in.
+Their language is __assigned__ according to the `content` directory they are __placed__ in.
-By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages.
+By having the same **path and basename** (relative to their language `content` directory), the content pieces are __linked__ together as translated pages.
### Bypassing default linking
Considering the following example:
1. `/content/about-us.en.md`
-2. `/content/om.nn.md`
-3. `/content/presentation/a-propos.fr.md`
+1. `/content/om.nn.md`
+1. `/content/presentation/a-propos.fr.md`
{{< code-toggle >}}
translationKey: "about"
Page bundles are either _leaf bundles_ or _branch bundles_.
leaf bundle
-: A _leaf bundle_ is a directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
+: A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
branch bundle
-: A _branch bundle_ is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page.
+: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
{{% note %}}
-In the definitions above and the examples below, the extension of the index file depends on the [content format]. For example, use index.md for Markdown content, index.html for HTML content, index.adoc for AsciiDoc content, etc.
-
-[content format]: /getting-started/glossary/#content-format
+In the definitions above and the examples below, the extension of the index file depends on the [content format](g). For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc.
{{% /note %}}
## Comparison
| | Leaf bundle | Branch bundle |
|---------------------|---------------------------------------------------------|---------------------------------------------------------|
-| Index file | index.md | _index.md |
-| Example | content/about/index.md | content/posts/_index.md |
-| [Page kinds] | `page` | `home`, `section`, `taxonomy`, or `term` |
-| Template types | [single] | [home], [section], [taxonomy], or [term] |
+| Index file | `index.md` | `_index.md` |
+| Example | `content/about/index.md` | `content/posts/_index.md ` |
+| [Page kinds](g) | `page` | `home`, `section`, `taxonomy`, or `term` |
+| Template types | [single] | [home], [section], [taxonomy], or [term] |
| Descendant pages | None | Zero or more |
| Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles |
-| [Resource types] | `page`, `image`, `video`, etc. | all but `page` |
+| [Resource types](g) | `page`, `image`, `video`, etc. | all but `page` |
[single]: /templates/types/#single
[home]: /templates/types/#home
[taxonomy]: /templates/types/#taxonomy
[term]: /templates/types/#term
-Files with [resource type] `page` include content written in Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode. In a leaf bundle, excluding the index file, these files are only accessible as page resources. In a branch bundle, these files are only accessible as content pages.
+Files with [resource type](g) `page` include content written in Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode. In a leaf bundle, excluding the index file, these files are only accessible as page resources. In a branch bundle, these files are only accessible as content pages.
## Leaf bundles
-A _leaf bundle_ is a directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
+A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
```text
content/
: This leaf bundle does not contain any page resources.
my-post
-: This leaf bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
+: This leaf bundle contains an index file, two resources of [resource type](g) `page`, and two resources of resource type `image`.
- content-1, content-2
: This leaf bundle does not contain any page resources.
{{% note %}}
-Create leaf bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
+Create leaf bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
{{% /note %}}
## Branch bundles
-A _branch bundle_ is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page.
+A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page.
```text
content/
: This branch bundle contains an index file, two descendant branch bundles, and no resources.
branch-bundle-1
-: This branch bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
+: This branch bundle contains an index file, two resources of [resource type](g) `page`, and two resources of resource type `image`.
branch-bundle-2
: This branch bundle contains an index file and a leaf bundle.
{{% note %}}
-Create branch bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
+Create branch bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
{{% /note %}}
-
## Headless bundles
Use [build options] in front matter to create an unpublished leaf or branch bundle whose content and resources you can include in other pages.
[`Resources`]: /methods/page/resources/
-[build options]: content-management/build-options/
-[page kinds]: /getting-started/glossary/#page-kind
+[build options]: /content-management/build-options/
[page resources]: /content-management/page-resources/
-[resource type]: /getting-started/glossary/#resource-type
-[resource types]: /getting-started/glossary/#resource-type
: (`slice`) The keywords to search for, expressed as a slice of `KeyValues` using the [`keyVals`] function.
fragments
-: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment] identifiers of the documents.
+: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment](g) identifiers of the documents.
-[fragment]: /getting-started/glossary/#fragment
[`keyVals`]: /functions/collections/keyvals/
A fictional example using all of the above options:
## Index content headings in related content
-{{< new-in 0.111.0 >}}
-
Hugo can index the headings in your content and use this to find related content. You can enable this by adding a index of type `fragments` to your `related` configuration:
{{< code-toggle file=hugo >}}
{{< /code-toggle >}}
* The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level.
-* If `applyFilter`is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing:
+* If `applyFilter` is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing:
```go-html-template
{{ $related := .Site.RegularPages.Related . | first 5 }}
name
: (`string`) The index name. This value maps directly to a page parameter. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects.
-type {{< new-in 0.111.0 >}}
+type
: (`string`) One of `basic`(default) or `fragments`.
-applyFilter {{< new-in 0.111.0 >}}
+applyFilter
: (`string`) Apply a `type` specific filter to the result of a search. This is currently only used for the `fragments` type.
weight
: (`int`) An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be `0`, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best.
-cardinalityThreshold {{< new-in 0.111.0 >}}
+cardinalityThreshold
: (`int`) If between 1 and 100, this is a percentage. All keywords that are used in more than this percentage of documents are removed. For example, setting this to `60` will remove all keywords that are used in more than 60% of the documents in the index. If `0`, no keyword is removed from the index. Default is `0`.
pattern
toLower
: (`bool`) See above.
-
-## Performance considerations
-
-**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast.
-
-This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread:
-
-{{< tweet user="scott_lowe" id="898398437527363585" >}}
-
-Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog.
-
-He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that:
-
-* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before.
-* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites.
-
-{{% note %}}
-We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock).
-{{% /note %}}
## Overview
-A section is a top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](/getting-started/glossary/#collection) in [context](/getting-started/glossary/#context).
+A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](g). Section templates receive one or more page [collections](g) in [context](g).
{{% note %}}
-Although top-level directories without _index.md files are sections, we recommend creating _index.md files in _all_ sections.
+Although top-level directories without `_index.md` files are sections, we recommend creating `_index.md` files in _all_ sections.
{{% /note %}}
A typical site consists of one or more sections. For example:
Content directory|Section template
:--|:--
-content/products|layouts/products/list.html
-content/products/product-1|layouts/products/list.html
-content/products/product-1/benefits|layouts/products/list.html
+`content/products`|`layouts/products/list.html`
+`content/products/product-1`|`layouts/products/list.html`
+`content/products/product-1/benefits`|`layouts/products/list.html`
Content directory|Single template
:--|:--
-content/products|layouts/products/single.html
-content/products/product-1|layouts/products/single.html
-content/products/product-1/benefits|layouts/products/single.html
+`content/products`|`layouts/products/single.html`
+`content/products/product-1`|`layouts/products/single.html`
+`content/products/product-1/benefits`|`layouts/products/single.html`
If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter.
## Embedded shortcodes
-Use these embedded shortcodes as needed.
-
-### comment
-
-{{< new-in "0.137.1" >}}
-
-{{% 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 %}}
-
-Use the `comment` shortcode to include comments in your Markdown. Hugo excludes the encapsulated text when rendering your site.
-
-Example usage:
-
-```text
-{{%/* comment */%}} TODO: 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.
-
-### details
-
-{{< 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 %}}
-
-Use the `details` shortcode to create a `details` HTML element. For example:
-
-```text
-{{</* details summary="See the details" */>}}
-This is a **bold** word.
-{{</* /details */>}}
-```
-
-Hugo renders this to:
-
-```html
-<details>
- <summary>See the details</summary>
- <p>This is a <strong>bold</strong> word.</p>
-</details>
-```
-
-The details shortcode accepts these named arguments:
-
-summary
-: (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`.
-
-open
-: (`bool`) Whether to initially display the content of the `details` element. Default is `false`.
-
-class
-: (`string`) The value of the element's `class` attribute.
-
-name
-: (`string`) The value of the element's `name` attribute.
-
-title
-: (`string`) The value of the element's `title` attribute.
-
-### figure
-
-{{% 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 %}}
-
-The `figure` shortcode can use the following named arguments:
-
-src
-: URL of the image to be displayed.
-
-link
-: If the image needs to be hyperlinked, URL of the destination.
-
-target
-: Optional `target` attribute for the URL if `link` argument is set.
-
-rel
-: Optional `rel` attribute for the URL if `link` argument is set.
-
-alt
-: Alternate text for the image if the image cannot be displayed.
-
-title
-: Image title.
-
-caption
-: Image caption. Markdown within the value of `caption` will be rendered.
-
-class
-: `class` attribute of the HTML `figure` tag.
-
-height
-: `height` attribute of the image.
-
-width
-: `width` attribute of the image.
-
-loading
-: `loading` attribute of the image.
-
-attr
-: Image attribution text. Markdown within the value of `attr` will be rendered.
-
-attrlink
-: If the attribution text needs to be hyperlinked, URL of the destination.
-
-Example usage:
-
-```text
-{{</* figure src="elephant.jpg" title="An elephant at sunset" */>}}
-```
-
-Rendered:
-
-```html
-<figure>
- <img src="elephant.jpg">
- <figcaption><h4>An elephant at sunset</h4></figcaption>
-</figure>
-```
-
-### gist
-
-{{% note %}}
-To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
-
-[source code]: {{% eturl gist %}}
-{{% /note %}}
-
-To display a GitHub [gist] with this URL:
-
-[gist]: https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists
-
-```text
-https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
-```
-
-Include this in your Markdown:
-
-```text
-{{</* gist user 50a7482715eac222e230d1e64dd9a89b */>}}
-```
-
-This will display all files in the gist alphabetically by file name.
-
-{{< gist jmooring 23932424365401ffa5e9d9810102a477 >}}
-
-To display a specific file within the gist:
-
-```text
-{{</* gist user 23932424365401ffa5e9d9810102a477 list.html */>}}
-```
-
-Rendered:
-
-{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}
-
-### 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.
-
-[source code]: {{% eturl highlight %}}
-{{% /note %}}
-
-To display a highlighted code sample:
-
-```text
-{{</* highlight go-html-template */>}}
-{{ range .Pages }}
- <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
-{{ end }}
-{{</* /highlight */>}}
-```
-
-Rendered:
-
-{{< highlight go-html-template >}}
-{{ range .Pages }}
- <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
-{{ end }}
-{{< /highlight >}}
-
-To specify one or more [highlighting options], include a quotation-encapsulated, comma-separated list:
-
-[highlighting options]: /functions/transform/highlight/
-
-```text
-{{</* highlight go-html-template "lineNos=inline, lineNoStart=42" */>}}
-{{ range .Pages }}
- <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
-{{ end }}
-{{</* /highlight */>}}
-```
-
-Rendered:
-
-{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}}
-{{ range .Pages }}
- <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
-{{ end }}
-{{< /highlight >}}
-
-### instagram
-
-{{% 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 %}}
-
-To display an Instagram post with this URL:
-
-```text
-https://www.instagram.com/p/CxOWiQNP2MO/
-```
-
-Include this in your Markdown:
-
-```text
-{{</* instagram CxOWiQNP2MO */>}}
-```
-
-Rendered:
-
-{{< instagram CxOWiQNP2MO >}}
-
-### param
-
-{{% 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 %}}
-
-The `param` shortcode renders a parameter from the page's front matter, falling back to a site parameter of the same name. The shortcode throws an error if the parameter does not exist.
-
-Example usage:
-
-```text
-{{</* param testparam */>}}
-```
-
-Access nested values by [chaining] the [identifiers]:
-
-[chaining]: /getting-started/glossary/#chain
-[identifiers]: /getting-started/glossary/#identifier
-
-```text
-{{</* param my.nested.param */>}}
-```
-
-### ref
-
-{{% note %}}
-To override Hugo's embedded `ref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
-
-Always use the `{{%/* */%}}` notation when calling this shortcode.
-
-[source code]: {{% eturl ref %}}
-{{% /note %}}
-
-The `ref` shortcode returns the permalink of the given page reference.
-
-Example usage:
-
-```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" */%}})
-```
-
-Rendered:
-
-```html
-<a href="http://example.org/posts/post-1/">Post 1</a>
-<a href="http://example.org/posts/post-1/">Post 1</a>
-<a href="http://example.org/posts/post-1/#foo">Post 1</a>
-<a href="http://example.org/posts/post-1/#foo">Post 1</a>
-```
-
-### relref
-
-{{% note %}}
-To override Hugo's embedded `relref` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
-
-Always use the `{{%/* */%}}` notation when calling this shortcode.
-
-[source code]: {{% eturl relref %}}
-{{% /note %}}
-
-The `relref` shortcode returns the permalink of the given page reference.
-
-Example usage:
-
-```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" */%}})
-```
-
-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>
-```
-
-### twitter
-
-{{% note %}}
-To override Hugo's embedded `twitter` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
-
-You may call the `twitter` shortcode by using its `tweet` alias.
-
-[source code]: {{% eturl twitter %}}
-{{% /note %}}
-
-To display a Twitter post with this URL:
-
-```txt
-https://x.com/SanDiegoZoo/status/1453110110599868418
-```
-
-Include this in your Markdown:
-
-```text
-{{</* twitter user="SanDiegoZoo" id="1453110110599868418" */>}}
-```
-
-Rendered:
-
-{{< twitter user="SanDiegoZoo" id="1453110110599868418" >}}
-
-### vimeo
-
-{{% 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 %}}
-
-To display a Vimeo video with this URL:
-
-```text
-https://vimeo.com/channels/staffpicks/55073825
-```
-
-Include this in your Markdown:
-
-```text
-{{</* vimeo 55073825 */>}}
-```
-
-Rendered:
-
-{{< vimeo 55073825 >}}
-
-{{% note %}}
-If you want to further customize the visual styling, add a `class` argument when calling the shortcode. The new `class` will be added to the `<div>` that wraps the `<iframe>` *and* will remove the inline styles. Note that you will need to call the `id` as a named argument as well. You can also give the vimeo video a descriptive title with `title`.
-
-```go
-{{</* vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" */>}}
-```
-{{% /note %}}
-
-### youtube
-
-{{% 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 %}}
-
-To display a YouTube video with this URL:
-
-```text
-https://www.youtube.com/watch?v=0RKpf3rK57I
-```
-
-Include this in your Markdown:
-
-```text
-{{</* youtube 0RKpf3rK57I */>}}
-```
-
-Rendered:
-
-{{< youtube 0RKpf3rK57I >}}
-
-The youtube shortcode accepts these named 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 >}}
-: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
-
-autoplay
- {{< 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 >}}
-: (`bool`) Whether to display the video controls. Default is `true`.
-
-end
-{{< 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 >}}
-: (`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`.
-
-mute
-{{< 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 >}}
-: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
-
-title
-: (`string`) The `title` attribute of the `iframe` element. Defaults to "YouTube video".
-
-Example using some of the above:
-
-```text
-{{</* youtube id=0RKpf3rK57I start=30 end=60 loading=lazy */>}}
-```
+See the [shortcodes](/shortcodes/) section.
## Privacy configuration
toc: true
aliases: [/content/summaries/,/content-management/content-summaries/]
---
-{{% comment %}}
+
<!-- Do not remove the manual summary divider below. -->
<!-- If you do, you will break its first literal usage on this page. -->
-{{% /comment %}}
+
<!--more-->
You can define a summary manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
## Highlight shortcode
-Highlighting is carried out via the built-in [`highlight` shortcode](/content-management/shortcodes/#highlight). It takes exactly one required argument for the programming language to be highlighted and requires a closing tag.
+Highlighting is carried out via the built-in [`highlight` shortcode](/shortcodes/highlight/). It takes exactly one required argument for the programming language to be highlighted and requires a closing tag.
Options:
url = "/:sections[last]/:slug"
{{< /code-toggle >}}
-
## Site configuration
### Permalinks
### Customize
-To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the layouts directory. The template receives the following context:
+To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the `layouts` directory. The template receives the following context:
Permalink
: The link to the page being aliased.
[contributing]: CONTRIBUTING.md
[create a proposal]: https://github.com/gohugoio/hugo/issues/new?labels=Proposal%2C+NeedsTriage&template=feature_request.md
[documentation repository]: https://github.com/gohugoio/hugoDocs
-[documentation]: https://gohugo.io/documentation
+[documentation]: /documentation
[forum]: https://discourse.gohugo.io
[issue queue]: https://github.com/gohugoio/hugo/issues
[themes]: https://themes.gohugo.io/
To build and install a specific release:
```sh
-CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.137.1
+CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@v0.141.0
```
To build and install at the latest commit on the master branch:
## Guidelines
+### Style
+
+Please adhere to Google's [developer documentation style guide].
+
+[developer documentation style guide]: https://developers.google.com/style
+
### Markdown
Please follow these guidelines:
- Use [ATX] headings, not [setext] headings, levels 2 through 4
- Use [fenced code blocks], not [indented code blocks]
- Use hyphens, not asterisks, with unordered [list items]
-- Use the [note shortcode] instead of blockquotes
+- Use the [note shortcode] instead of blockquotes or bold text
- Do not mix [raw HTML] within Markdown
- Do not use bold text instead of a heading or description term (`dt`)
- Remove consecutive blank lines (maximum of two)
- Remove trailing spaces
-### Style
+### Glossary of terms
-Please adhere to Google's [developer documentation style guide].
+Each term in the glossary has its own dedicated page located within the `content/en/getting-started/glossary` directory. While these individual glossary pages are not published as standalone web pages during the build process, their content is included in other pages as needed.
-[developer documentation style guide]: https://developers.google.com/style
+To link to a term definition on the glossary page, use this custom link syntax:
+
+```text
+[term](g)
+```
+
+Lookups are case-insensitive, ignore formatting, and support both singular and plural forms. For example, all of these variations will link to the same glossary entry:
+
+```text
+[global resource](g)
+[Global Resource](g)
+[Global Resources](g)
+[`Global Resources`](g)
+```
+
+To insert a term definition, use the [`glossary-term`] shortcode:
+
+```text
+{{%/* glossary-term "global resource" */%}}
+```
+
+[glossary of terms]: /getting-started/glossary/
+[`glossary-term`]: #glossary-term
-#### Terminology
+### Terminology
Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note:
- Capitalize the word "Markdown"
- Hyphenate the term "open-source" when used an adjective.
-#### Page titles and headings
+Use the [glossary link] (`gl`) shortcode to insert a link to the glossary entry for the given term, and use the [glossary term] (`gt`) shortcode to insert the definition of the given term.
+
+### Page titles and headings
Please follow these guidelines for page titles and headings:
- Avoid formatted strings in headings and page titles
- Shorter is better
-#### Use active voice with present tense
+### Use active voice with present tense
In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible.
No → With Hugo you can build a static site.\
Yes → Build a static site with Hugo.
-No → This will cause Hugo to generate HTML files in the public directory.\
-Yes → Hugo generates HTML files in the public directory.
+No → This will cause Hugo to generate HTML files in the `public` directory.\
+Yes → Hugo generates HTML files in the `public` directory.
-#### Use second person instead of third person
+### Use second person instead of third person
No → Users should exercise caution when deleting files.\
Better → You must be cautious when deleting files.\
Best → Be cautious when deleting files.
-#### Avoid adverbs when possible
+### Avoid adverbs when possible
No → Hugo is extremely fast.\
Yes → Hugo is fast.
"It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995).
{{% /note %}}
-#### Level 6 headings
+### Level 6 headings
Level 6 headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
[glossary]: /getting-started/glossary/
-#### Function and method descriptions
+### Function and method descriptions
When adding a page to the [functions] or [methods] section, begin the description with the word "Returns". With functions and methods that return a boolean value, begin the description with the phrase "Reports whether".
[functions]: /functions
[methods]: /methods
-#### Miscellaneous
+### Directory names, file names, and file paths
+
+Enclose directory names, file names, and file paths within backticks, with the following exceptions:
+
+- Page titles
+- Section headings (h1-h6)
+- Definition list terms
+- The description field in front matter
+
+### Miscellaneous
Other guidelines to consider:
```
````
-Rendered:
-
```go-html-template
{{ if eq $foo "bar" }}
{{ print "foo is bar" }}
{{%/*/* foo */*/%}}
```
-Rendered:
-
```text
{{</* foo */>}}
{{%/* foo */%}}
{{</* /code-toggle */>}}
```
-Rendered:
-
{{< code-toggle file=hugo >}}
baseURL = 'https://example.org/'
languageCode = 'en-US'
{{</* /code-toggle */>}}
```
-Rendered:
-
{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
title = 'My first post'
date = 2023-11-09T12:56:07-08:00
{{</* /code */>}}
```
-Rendered:
-
{{< code file=layouts/_default/single.html >}}
{{ range .Site.RegularPages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
### code
-Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
+Use the `code` shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
copy
: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
lang
: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is `html`, sets the code language to `go-html-template`. Default is `text`.
+```text
+{{</* code file=content/something/foo.md lang=text copy=true */>}}
+Some code here
+{{</* /code */>}}
+```
+
+{{< code file=content/something/foo.md lang=text copy=true >}}
+Some code here
+{{< /code >}}
+
### code-toggle
-Use the "code-toggle" shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments:
+Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments:
+
+config
+: (`string`) The section of `site.Data.docs.config` to render.
copy
: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
file
-: (`string`) The file name to display. Omit the file extension for site configuration examples.
+: (`string`) The file name to display. Omit the file extension for site configuration examples. Default is `hugo`
fm
: (`bool`) Whether the example is front matter. Default is `false`.
+skipHeader
+: (`bool`) Whether to omit top level key(s) when rendering a section of `site.Data.docs.config`.
+
+```text
+{{</* code-toggle */>}}
+title: Example
+draft: false
+{{</* /code-toggle */>}}
+```
+
+{{< code-toggle >}}
+title: Example
+draft: false
+{{< /code-toggle >}}
### deprecated-in
-Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
+Use the `deprecated-in` shortcode to indicate that a feature is deprecated:
```text
{{%/* deprecated-in 0.127.0 */%}}
{{%/* /deprecated-in */%}}
```
-Rendered:
-
{{% deprecated-in 0.127.0 %}}
Use [`hugo.IsServer`] instead.
### eturl
-Use the embedded template URL (eturl) shortcode to insert an absolute URL to the source code for an embedded template. The shortcode takes a single argument, the base file name of the template (omit the file extension).
+Use the embedded template URL (`eturl`) shortcode to insert an absolute URL to the source code for an embedded template. The shortcode takes a single argument, the base file name of the template (omit the file extension).
```text
This is a link to the [embedded alias template].
[embedded alias template]: {{%/* eturl alias */%}}
```
-Rendered:
-
This is a link to the [embedded alias template].
[embedded alias template]: {{% eturl alias %}}
+### glossary-term
+
+Use the `glossary-term` shortcode to insert the definition of the given glossary term.
+
+```text
+{{%/* glossary-term scalar */%}}
+```
+
+{{% glossary-term scalar %}}
+
+### include
+
+Use the `include` shortcode to include content from another page.
+
+```text
+{{%/* include "functions/_common/glob-patterns" */%}}
+```
+
### new-in
-Use the "new-in" shortcode to indicate a new feature:
+Use the `new-in` shortcode to indicate a new feature:
```text
{{</* new-in 0.127.0 */>}}
```
-Rendered:
-
{{< new-in 0.127.0 >}}
### note
-Use the "note" shortcode with `{{%/* */%}}` delimiters to call attention to important content:
+Use the `note` shortcode with `{{%/* */%}}` delimiters to call attention to important content:
```text
{{%/* note */%}}
{{%/* /note */%}}
```
-Rendered:
-
{{% note %}}
Use the [`math.Mod`] function to control...
To submit your theme:
1. Read the [submission guidelines]
-2. Open a pull request in the [themes repository]
+1. Open a pull request in the [themes repository]
Other useful theme directories:
--- /dev/null
+---
+_comment: Do not remove front matter.
+---
+
+anchorLineNos
+: (`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
+
+codeFences
+: (`bool`) Whether to highlight fenced code blocks. Default is `true`.
+
+guessSyntax
+: (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer](g). Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
+
+{{% note %}}
+The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
+{{% /note %}}
+
+hl_Lines
+: (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
+
+hl_inline
+: (`bool`) Whether to render the highlighted code without a wrapping container. Default is `false`.
+
+lineAnchors
+: (`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
+
+lineNoStart
+: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
+
+lineNos
+: (`bool`) Whether to display a number at the beginning of each line. Default is `false`.
+
+lineNumbersInTable
+: (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
+
+noClasses
+: (`bool`) Whether to use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and generate the CSS file using the `hugo gen chromastyles` command. Default is `true`.
+
+style
+: (`string`) The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive. Default is `monokai`.
+
+[style gallery]: https://xyproto.github.io/splash/docs/
+
+tabWidth
+: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
+
+wrapperClass
+{{< new-in 0.140.2 >}}
+: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
+
+{{% note %}}
+Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
+
+lineNos=inline
+: equivalent to `lineNos=true` and `lineNumbersInTable=false`
+
+lineNos=table
+: equivalent to `lineNos=true` and `lineNumbersInTable=true`
+{{% /note %}}
You can use `after` in combination with the [`first`] function and Hugo's [powerful sorting methods](/quick-reference/page-collections/#sort). Let's assume you have a `section` page at `example.com/articles`. You have 10 articles, but you want your template to show only two rows:
1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
-2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
+1. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
{{< code file=layouts/section/articles.html >}}
{{ define "main" }}
aliases: [/functions/append]
---
-This function appends all elements, excluding the last, to the last element. This allows [pipe](/getting-started/glossary/#pipeline) constructs as shown below.
+This function appends all elements, excluding the last, to the last element. This allows [pipe](g) constructs as shown below.
Append a single element to a slice:
{{ $m := dict }}
```
-
Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
```go-html-template
aliases: [/functions/in]
---
-The `SET` can be an [array], [slice], or [string].
-
-[array]: /getting-started/glossary/#array
-[slice]: /getting-started/glossary/#slice
-[string]: /getting-started/glossary/#string
+The `SET` can be an [array](g), [slice](g), or [string](g).
```go-html-template
{{ $s := slice "a" "b" "c" }}
signatures: [collections.NewScratch ]
---
-The `collections.NewScratch` function creates a locally scoped [scratch pad] to store and manipulate data. To create a scratch pad that is attached to a `Page` object, use the [`Scratch`] or [`Store`] method.
+The `collections.NewScratch` function creates a locally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad that is attached to a `Page` object, use the [`Scratch`] or [`Store`] method.
[`Scratch`]: /methods/page/scratch/
[`Store`]: /methods/page/store/
-[scratch pad]: /getting-started/glossary/#scratch-pad
## Methods
The where function takes three or four arguments. The `OPERATOR` argument is optional.
COLLECTION
-: (`any`) A [page collection] or a [slice] of [maps].
-
-[maps]: /getting-started/glossary/#map
-[page collection]: /getting-started/glossary/#page-collection
-[slice]: /getting-started/glossary/#slice
+: (`any`) A [page collection](g) or a [slice](g) of [maps](g).
KEY
-: (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain] the subkey as shown below:
+: (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain](g) the subkey as shown below:
```go-html-template
{{ $result := where .Site.RegularPages "Params.foo" "bar" }}
```
-[chain]: /getting-started/glossary/#chain
-
OPERATOR
: (`string`) The logical comparison [operator](#operators).
## String comparison
-Compare the value of the given field to a [`string`]:
-
-[`string`]: /getting-started/glossary/#string
+Compare the value of the given field to a [`string`](g):
```go-html-template
{{ $pages := where .Site.RegularPages "Section" "eq" "books" }}
## Numeric comparison
-Compare the value of the given field to an [`int`] or [`float`]:
-
-[`int`]: /getting-started/glossary/#int
-[`float`]: /getting-started/glossary/#float
+Compare the value of the given field to an [`int`](g) or [`float`](g):
```go-html-template
{{ $books := where site.RegularPages "Section" "eq" "books" }}
## Boolean comparison
-Compare the value of the given field to a [`bool`]:
-
-[`bool`]: /getting-started/glossary/#bool
+Compare the value of the given field to a [`bool`](g):
```go-html-template
{{ $books := where site.RegularPages "Section" "eq" "books" }}
## Member comparison
-Compare a [`scalar`] to a [`slice`].
-
-[`scalar`]: /getting-started/glossary/#scalar
-[`slice`]: /getting-started/glossary/#slice
+Compare a [`scalar`](g) to a [`slice`](g).
For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow":
### Custom dates
-With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON).
+With custom front matter dates, the comparison depends on the front matter data format (TOML, YAML, or JSON).
{{% note %}}
Using TOML for pages with custom front matter dates enables precise date comparisons.
To exclude a page with an undefined field from a boolean _inequality_ test:
1. Create a collection using a boolean comparison
-2. Create a collection using a nil comparison
-3. Subtract the second collection from the first collection using the [`collections.Complement`] function.
+1. Create a collection using a nil comparison
+1. Subtract the second collection from the first collection using the [`collections.Complement`] function.
[`collections.Complement`]: /functions/collections/complement/
For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
-[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository.
+[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository.
#### GitHub Pages
```yaml
variables:
- HUGO_VERSION: 0.137.1
- DART_SASS_VERSION: 1.80.6
+ HUGO_VERSION: 0.141.0
+ DART_SASS_VERSION: 1.83.4
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
```toml
[build.environment]
-HUGO_VERSION = "0.137.1"
-DART_SASS_VERSION = "1.80.6"
+HUGO_VERSION = "0.141.0"
+DART_SASS_VERSION = "1.83.4"
+NODE_VERSION = "22"
TZ = "America/Los_Angeles"
[build]
{{ end }}
```
-The example above publishes the minified CSS file to public/css/main.css.
+The example above publishes the minified CSS file to `public/css/main.css`.
See [this repository] for more information about the integration with Tailwind CSS v4.0.
---
{{% deprecated-in 0.123.0 %}}
-Instead, use [`transform.Unmarshal`] with a [global], [page], or [remote] resource.
+Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g).
See the [remote data example].
[`transform.Unmarshal`]: /functions/transform/unmarshal/
-[global]: /getting-started/glossary/#global-resource
-[page]: /getting-started/glossary/#page-resource
[remote data example]: /functions/resources/getremote/#remote-data
-[remote]: /getting-started/glossary/#remote-resource
{{% /deprecated-in %}}
Given the following directory structure:
{{% note %}}
When working with local data, the file path is relative to the working directory.
-You must not place CSV files in the project's data directory.
+You must not place CSV files in the project's `data` directory.
{{% /note %}}
Access remote data with either of the following:
```go-html-template
{{ $data := dict }}
-{{ $u := "https://example.org/pets.csv" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://example.org/pets.csv" }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $opts := dict "delimiter" "," }}
{{ $data = . | transform.Unmarshal $opts }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $u }}
{{ end }}
```
---
{{% deprecated-in 0.123.0 %}}
-Instead, use [`transform.Unmarshal`] with a [global], [page], or [remote] resource.
+Instead, use [`transform.Unmarshal`] with a [global resource](g), [page resource](g), or [remote resource](g).
See the [remote data example].
[`transform.Unmarshal`]: /functions/transform/unmarshal/
-[global]: /getting-started/glossary/#global-resource
-[page]: /getting-started/glossary/#page-resource
[remote data example]: /functions/resources/getremote/#remote-data
-[remote]: /getting-started/glossary/#remote-resource
{{% /deprecated-in %}}
Given the following directory structure:
```go-html-template
{{ $data := dict }}
-{{ $u := "https://example.org/books.json" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://example.org/books.json" }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $u }}
{{ end }}
```
{{< new-in 0.120.0 >}}
-Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates.
+Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottlenecks in templates.
The timer starts when you instantiate it, and stops when you call its `Stop` method.
To retrieve and render the content:
```go-html-template
-{{ $u := "https://api.github.com/repos/gohugoio/hugo/readme" }}
-{{ with resources.GetRemote $u }}
+{{ $url := "https://api.github.com/repos/gohugoio/hugo/readme" }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value}}
{{ with . | transform.Unmarshal }}
{{ .content | base64Decode | markdownify }}
{{ end }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $u }}
{{ end }}
```
To prevent suppression of duplicate messages when using `warnf` for debugging, make each message unique with the [`math.Counter`] function. For example:
-
```go-html-template
{{ range site.RegularPages }}
{{ .Section | warnf "%#[2]v [%[1]d]" math.Counter }}
aliases: [/functions/page]
---
-{{< new-in 0.111.0 >}}
-
At the top level of a template that receives a `Page` object in context, these are equivalent:
```go-html-template
Hugo almost always passes a `Page` as the data context into the top level template (e.g., `single.html`). The one exception is the multihost sitemap template. This means that you can access the current page with the `.` in the template.
-But when you are deeply nested inside of a [content view], [partial], or [render hook], it is not always practical or possible to access the `Page` object.
+But when you are deeply nested inside of a [content view](g), [partial](g), or [render hook](g), it is not always practical or possible to access the `Page` object.
Use the global `page` function to access the `Page` object from anywhere in any template.
[`Summary`]: /methods/page/summary/
[`partialCached`]: /functions/partials/includecached/
-[content view]: /getting-started/glossary/#content-view
-[partial]: /getting-started/glossary/#partial
-[render hook]: /getting-started/glossary/#render-hook
-[shortcode]: getting-started/glossary/#shortcode
## Understanding context
-At the top of a page template, the [context] (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
+At the top of a page template, the [context](g) (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
With this contrived example that uses the [`seq`] function to generate a slice of integers:
{{% /note %}}
[`seq`]: /functions/collections/seq/
-[context]: /getting-started/glossary/#context
## Array or slice of scalars
toc: true
---
-The `return` statement is a custom addition to Go's [text/template] package. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
+The `return` statement is a non-standard extension to Go's [text/template package]. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
-The returned value may be of any data type including, but not limited to, [`bool`], [`float`], [`int`], [`map`], [`resource`], [`slice`], and [`string`].
+The returned value may be of any data type including, but not limited to, [`bool`](g), [`float`](g), [`int`](g), [`map`](g), [`resource`](g), [`slice`](g), or [`string`](g).
A `return` statement without a value returns an empty string of type `template.HTML`.
-[`bool`]: /getting-started/glossary/#bool
-[`float`]: /getting-started/glossary/#float
-[`int`]: /getting-started/glossary/#int
-[`map`]: /getting-started/glossary/#map
-[`resource`]: /getting-started/glossary/#resource
-[`slice`]: /getting-started/glossary/#slice
-[`string`]: /getting-started/glossary/#string
-[text/template]: https://pkg.go.dev/text/template
-
{{% note %}}
Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below.
{{% /note %}}
--- /dev/null
+---
+title: try
+description: Returns a TryValue object after evaluating the given expression.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: TryValue
+ signatures: ['try EXPRESSION']
+toc: true
+---
+
+{{< new-in 0.141.0 >}}
+
+The `try` statement is a non-standard extension to Go's [text/template] package. It introduces a mechanism for handling errors within templates, mimicking the `try-catch` constructs found in other programming languages.
+
+[text/template]: https://pkg.go.dev/text/template
+
+## Methods
+
+The `TryValue` object encapsulates the result of evaluating the expression, and provides two methods:
+
+Err
+: (`string`) Returns a string representation of the error thrown by the expression, if an error occurred, or returns `nil` if the expression evaluated without errors.
+
+Value
+: (`any`) Returns the result of the expression if the evaluation was successful, or returns `nil` if an error occurred while evaluating the expression.
+
+## Explanation
+
+By way of example, let's divide a number by zero:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ $result := div $x $y }}
+{{ printf "%v divided by %v equals %v" $x $y .Value }}
+```
+
+As expected, the example above throws an error and fails the build:
+
+```terminfo
+Error: error calling div: can't divide the value by 0
+```
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $x := 1 }}
+{{ $y := 0 }}
+{{ with try (div $x $y) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else }}
+ {{ printf "%v divided by %v equals %v" $x $y .Value }}
+ {{ end }}
+{{ end }}
+```
+
+The error thrown by the expression is logged to the console as a warning:
+
+```terminfo
+WARN error calling div: can't divide the value by 0
+```
+
+Now let's change the arguments to avoid dividing by zero:
+
+```go-html-template
+{{ $x := 42 }}
+{{ $y := 6 }}
+{{ with try (div $x $y) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else }}
+ {{ printf "%v divided by %v equals %v" $x $y .Value }}
+ {{ end }}
+{{ end }}
+```
+
+Hugo renders the above to:
+
+```html
+42 divided by 6 equals 7
+```
+
+## Example
+
+Error handling is essential when using the [`resources.GetRemote`] function to capture remote resources such as data or images. When calling this function, if the HTTP request fails, Hugo will fail the build.
+
+[`resources.GetRemote`]: /functions/resources/getremote/
+
+Instead of failing the build, we can catch the error and emit a warning:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with try (resources.GetRemote $url) }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else with .Value }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ warnf "Unable to get remote resource %q" $url }}
+ {{ end }}
+{{ end }}
+```
+In the above, note that the [context](g) within the last conditional block is the `TryValue` object returned by the `try` statement. At this point neither the `Err` nor `Value` methods returned anything, so the current context is not useful. Use the `$` to access the [template context] if needed.
+
+[template context]: /templates/introduction/#template-context
+
+{{% note %}}
+Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
+{{% /note %}}
## Understanding context
-At the top of a page template, the [context] (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
+At the top of a page template, the [context](g) (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
With this contrived example:
Gaining a thorough understanding of context is critical for anyone writing template code.
{{% /note %}}
-[context]: /getting-started/glossary/#context
-
{{% include "functions/go-template/_common/text-template.md" %}}
[`else`]: /functions/go-template/else/
signatures: [hugo.Environment]
---
-The `hugo.Environment` function returns the current running [environment] as defined through the `--environment` command line flag.
+The `hugo.Environment` function returns the current running [environment](g) as defined through the `--environment` command line flag.
```go-html-template
{{ hugo.Environment }} → production
`hugo --environment staging`|`staging`
`hugo server`|`development`
`hugo server --environment staging`|`staging`
-
-[environment]: /getting-started/glossary/#environment
---
```go-html-template
-{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.137.1">
+{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.141.0">
```
{{< new-in 0.139.0 >}}
-The global `hugo.Store` function creates a persistent [scratch pad] to store and manipulate data. To create a locally scoped, use the [`newScratch`] function.
+The global `hugo.Store` function creates a persistent [scratch pad](g) to store and manipulate data. To create a locally scoped, use the [`newScratch`] function.
[`Scratch`]: /functions/hugo/scratch/
[`newScratch`]: /functions/collections/newscratch/
-[scratch pad]: /getting-started/glossary/#scratch-pad
## Methods
The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
-If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable:
-
-[noop]: /getting-started/glossary/#noop
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
```go-html-template
{{ $noop := .Content }}
---
```go-html-template
-{{ hugo.Version }} → 0.137.1
+{{ hugo.Version }} → 0.141.0
```
```go-html-template
{{ hugo.WorkingDir }} → /home/user/projects/my-hugo-site
```
-
-{{< new-in 0.112.0 >}}
Supported image formats include GIF, JPEG, PNG, TIFF, and WebP.
{{% note %}}
-This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global], [page], and [remote] resources. See the [image processing] section for details.
+This is a legacy function, superseded by the [`Width`] and [`Height`] methods for [global resources](g), [page resources](g), and [remote resources](g). See the [image processing] section for details.
[`Width`]: /methods/resource/width/
[`Height`]: /methods/resource/height/
-[global]: /getting-started/glossary/#global-resource
[image processing]: /content-management/image-processing/
-[page]: /getting-started/glossary/#page-resource
-[remote]: /getting-started/glossary/#remote-resource
{{% /note %}}
Regardless of dithering method, do both of the following to obtain the best results:
1. Scale the image _before_ dithering
-2. Output the image to a lossless format such as GIF or PNG
+1. Output the image to a lossless format such as GIF or PNG
The example below does both of these, and it sets the dithering palette to the three most dominant colors in the image.
-
```go-html-template
{{ with resources.Get "original.jpg" }}
{{ $opts := dict
The example above:
1. Resizes the image to be 800 px wide
-2. Converts the image to grayscale
-3. Dithers the image using the default (`FloydSteinberg`) dithering method with a grayscale palette
-4. Converts the image to the PNG format
+1. Converts the image to grayscale
+1. Dithers the image using the default (`FloydSteinberg`) dithering method with a grayscale palette
+1. Converts the image to the PNG format
--- /dev/null
+---
+title: images.Mask
+description: Returns an image filter that applies a mask to the source image.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/images/Filter
+ - methods/resource/Filter
+ returnType: images.filter
+ signatures: [images.Mask RESOURCE]
+toc: true
+---
+
+{{< new-in 0.141.0 >}}
+
+The `images.Mask` filter applies a mask to an image. Black pixels in the mask make the corresponding areas of the base image transparent, while white pixels keep them opaque. Color images are converted to grayscale for masking purposes. The mask is automatically resized to match the dimensions of the base image.
+
+{{% note %}}
+Of the formats supported by Hugo's imaging pipelie, only PNG and WebP have an alpha channel to support transparency. If your source image has a different format and you require transparent masked areas, convert it to either PNG or WebP as shown in the example below.
+{{% /note %}}
+
+When applying a mask to a non-transparent image format such as JPEG, the masked areas will be filled with the color specified by the `bgColor` parameter in your [site configuration]. You can override that color with a `Process` image filter:
+
+```go-html-template
+{{ $filter := images.Process "#00ff00" }}
+```
+
+[site configuration]: /content-management/image-processing/#imaging-configuration
+
+## Usage
+
+Create a slice of filters, one for WebP conversion and the other for mask application:
+
+```go-html-template
+{{ $filter1 := images.Process "webp" }}
+{{ $filter2 := images.Mask (resources.Get "images/mask.png") }}
+{{ $filters := slice $filter1 $filter2 }}
+```
+
+Apply the filters using the [`images.Filter`] function:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with . | images.Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+You can also apply the filter using the [`Filter`] method on a 'Resource' object:
+
+```go-html-template
+{{ with resources.Get "images/original.jpg" }}
+ {{ with .Filter $filters }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
+```
+
+[`images.Filter`]: /functions/images/filter/
+[`Filter`]: /methods/resource/filter/
+
+## Example
+
+Mask
+
+{{< img
+ src="images/examples/mask.png"
+ example=false
+>}}
+
+{{< img
+ src="images/examples/zion-national-park.jpg"
+ alt="Zion National Park"
+ filter="mask"
+ filterArgs="images/examples/mask.png"
+ example=true
+>}}
{{ end }}
```
-The overlay image can be a [global resource], a [page resource], or a [remote resource].
-
-[global resource]: /getting-started/glossary/#global-resource
-[page resource]: /getting-started/glossary/#page-resource
-[remote resource]: /getting-started/glossary/#remote-resource
+The overlay image can be a [global resource](g), a [page resource](g), or a [remote resource](g).
Create the filter:
[`cwebp`]: https://developers.google.com/speed/webp/docs/cwebp
-
```go-html-template
{{ $filter := images.Process "webp" "icon" }}
{{ $filter := images.Process "crop 200x200 center r90 webp q50 icon" }}
--- /dev/null
+---
+title: images.QR
+description: Encodes the given text into a QR code using the specified options, returning an image resource.
+keywords: []
+action:
+ aliases: []
+ related: []
+ returnType: images.ImageResource
+ signatures: ['images.QR TEXT OPTIONS']
+toc: true
+math: true
+---
+
+{{< new-in 0.141.0 >}}
+
+The `images.QR` function encodes the given text into a [QR code] using the specified options, returning an image resource. The size of the generated image depends on three factors:
+
+- Data length: Longer text necessitates a larger image to accommodate the increased information density.
+- Error correction level: Higher error correction levels enhance the QR code's resistance to damage, but this typically results in a slightly larger image size to maintain readability.
+- Pixels per module: The number of image pixels assigned to each individual module (the smallest unit of the QR code) directly impacts the overall image size. A higher pixel count per module leads to a larger, higher-resolution image.
+
+Although the default option values are sufficient for most applications, you should test the rendered QR code both on-screen and in print.
+
+[QR code]: https://en.wikipedia.org/wiki/QR_code
+
+## Options
+
+level
+: (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`.
+
+Error correction level|Redundancy
+:--|:--|:--
+low|20%
+medium|38%
+quartile|55%
+high|65%
+
+scale
+: (`int`) The number of image pixels per QR code module. Must be greater than or equal to `2`. Default is `4`.
+
+targetDir
+: (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image. Use Unix-style slashes (`/`) to separarate path segments. If empty or not provided, the image is placed directly in the `publishDir` root. Hugo automatically creates the necessary subdirectories if they don't exist.
+
+[`publishDir`]: /getting-started/configuration/#publishdir
+
+## Examples
+
+To create a QR code using the default values for `level` and `scale`:
+
+```go-html-template
+{{ $text := "https://gohugo.io" }}
+{{ with images.QR $text }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+{{< qr text="https://gohugo.io" class="qrcode" />}}
+
+Specify `level`, `scale`, and `targetDir` as needed to achieve the desired result:
+
+```go-html-template
+{{ $text := "https://gohugo.io" }}
+{{ $opts := dict
+ "level" "high"
+ "scale" 3
+ "targetDir" "codes"
+}}
+{{ with images.QR $text $opts }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ end }}
+```
+
+{{< qr text="https://gohugo.io" level="high" scale=3 targetDir="codes" class="qrcode" />}}
+
+## Scale
+
+As you decrease the size of a QR code, the maximum distance at which it can be reliably scanned by a device also decreases.
+
+In the example above, we set the `scale` to `2`, resulting in a QR code where each module consists of 2x2 pixels. While this might be sufficient for on-screen display, it's likely to be problematic when printed at 600 dpi.
+
+\[ \frac{2\:px}{module} \times \frac{1\:inch}{600\:px} \times \frac{25.4\:mm}{1\:inch} = \frac{0.085\:mm}{module} \]
+
+This module size is half of the commonly recommended minimum of 0.170 mm.\
+If the QR code will be printed, use the default `scale` value of `4` pixels per module.
+
+Avoid using Hugo's image processing methods to resize QR codes. Resizing can introduce blurring due to anti-aliasing when a QR code module occupies a fractional number of pixels.
+
+{{% note %}}
+Always test the rendered QR code both on-screen and in print.
+{{% /note %}}
+
+## Shortcode
+
+Call the `qr` shortcode to insert a QR code into your content.
+
+Use the self-closing syntax to pass the text as an argument:
+
+```text
+{{</* qr text="https://gohugo.io" /*/>}}
+```
+
+Or insert the text between the opening and closing tags:
+
+```text
+{{</* qr */>}}
+https://gohugo.io
+{{</* /qr */>}}
+```
+
+The `qr` shortcode accepts several arguments including `level` and `scale`. See the [related documentation] for details.
+
+[related documentation]: /shortcodes/qr/
Although none of the options are required, at a minimum you will want to set the `size` to be some reasonable percentage of the image height.
+alignx
+ {{< new-in 0.141.0 >}}
+: (`string`) The horizontal alignment of the text relative to the horizontal offset, one of `left`, `center`, or `right`. Default is `left`.
+
color
: (`string`) The font color, either a 3-digit or 6-digit hexadecimal color code. Default is `#ffffff` (white).
font
-: (`resource.Resource`) The font can be a [global resource], a [page resource], or a [remote resource]. Default is [Go Regular], a proportional sans-serif TrueType font.
+: (`resource.Resource`) The font can be a [global resource](g), a [page resource](g), or a [remote resource](g). Default is [Go Regular], a proportional sans-serif TrueType font.
[Go Regular]: https://go.dev/blog/go-fonts#sans-serif
y
: (`int`) The vertical offset, in pixels, relative to the top of the image. Default is `10`.
-[global resource]: /getting-started/glossary/#global-resource
-[page resource]: /getting-started/glossary/#page-resource
-[remote resource]: /getting-started/glossary/#remote-resource
-
## Usage
+Set the text and paths:
+
+```go-html-template
+{{ $text := "Zion National Park" }}
+{{ $fontPath := "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf" }}
+{{ $imagePath := "images/original.jpg" }}
+```
+
Capture the font as a resource:
```go-html-template
{{ $font := "" }}
-{{ $path := "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf" }}
-{{ with resources.GetRemote $path }}
+{{ with try (resources.GetRemote $fontPath) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $font = . }}
+ {{ else }}
+ {{ errorf "Unable to get resource %s" $fontPath }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get resource %q" $path }}
{{ end }}
```
-Create the options map:
+Create the filter, centering the text horizontally and vertically:
```go-html-template
-{{ $opts := dict
- "color" "#fbfaf5"
- "font" $font
- "linespacing" 8
- "size" 40
- "x" 25
- "y" 190
-}}
+{{ $r := "" }}
+{{ $filter := "" }}
+{{ with $r = resources.Get $imagePath }}
+ {{ $opts := dict
+ "alignx" "center"
+ "color" "#fbfaf5"
+ "font" $font
+ "linespacing" 8
+ "size" 60
+ "x" (mul .Width 0.5 | int)
+ "y" (mul .Height 0.5 | int)
+ }}
+ {{ $filter = images.Text $text $opts }}
+{{ else }}
+ {{ errorf "Unable to get resource %s" $imagePath }}
+{{ end }}
```
-Set the text:
+Apply the filter using the [`images.Filter`] function:
```go-html-template
-{{ $text := "Zion National Park" }}
+{{ with $r }}
+ {{ with . | images.Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
```
-Create the filter:
+You can also apply the filter using the [`Filter`] method on a `Resource` object:
```go-html-template
-{{ $filter := images.Text $text $opts }}
+{{ with $r }}
+ {{ with .Filter $filter }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ end }}
```
-{{% include "functions/images/_common/apply-image-filter.md" %}}
+[`images.Filter`]: /functions/images/filter/
+[`Filter`]: /methods/resource/filter/
## Example
* [Config]
* [SetOptions]
-
## Group
The `Group` method take an `ID` (`string`) as argument. No slashes. It returns an object with these methods:
-
#### Script
The `Script` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter] that can be used to set [script options] for this script.
`SetOptions` takes a [params options] map. The instance options will be passed to any [runner] script in the same group, as JSON.
-
#### Runner
The `Runner` method takes an `ID` (`string`) as argument. No slashes. It returns an [OptionsSetter] that can be used to set [script options] for this runner.
Below is an example of a runner script that uses React to render elements. Note that the export (`default`) must match the `export` option in the [script options] (`default` is the default value for runner scripts) (runnable versions of examples on this page can be found at [js.Batch Demo Repo]):
-
```js
import * as ReactDOM from 'react-dom/client';
import * as React from 'react';
}
```
-
-
#### Config
Returns an [OptionsSetter] that can be used to set [build options] for the batch.
-These are mostly the same as for [js.Build], but note that:
+These are mostly the same as for `js.Build`, but note that:
* `targetPath` is set automatically (there may be multiple outputs).
* `format` must be `esm`, currently the only format supporting [code splitting].
You can pass any object that implements [Resource.Get](/methods/page/resources/#get). Pass a slice to set multiple contexts.
-The example above uses [`Resources.Mount`] to resolve a folder inside `assets` relative to the page bundle.
+The example above uses [`Resources.Mount`] to resolve a directory inside `assets` relative to the page bundle.
### OptionsSetter
{{ end }}
```
-
## Known Issues
In the official documentation for [ESBuild's code splitting], there's a warning note in the header. The two issues are:
We have not seen the ordering issue as a problem during our [extensive testing](https://github.com/bep/hugojsbatchdemo) of this new feature with different libraries. There are two main cases:
1. Undefined execution order of imports, see [this comment](https://github.com/evanw/esbuild/issues/399#issuecomment-1458680887)
-2. Only one execution order of imports, see [this comment](https://github.com/evanw/esbuild/issues/399#issuecomment-735355932)
+1. Only one execution order of imports, see [this comment](https://github.com/evanw/esbuild/issues/399#issuecomment-735355932)
Many would say that both of the above are [code smells](https://en.wikipedia.org/wiki/Code_smell). The first one has a simple workaround in Hugo. Define the import order in its own script and make sure it gets passed early to ESBuild, e.g. by putting it in a script group with a name that comes early in the alphabet.
```
[build options]: #build-options
-[`Resource`]: https://gohugo.io/methods/resource/
+[`Resource`]: /methods/resource/
[`Resources`]: /methods/page/resources/
[`Resources.Mount`]: /methods/page/resources/#mount
[`templates.Defer`]: /functions/templates/defer/
[instance]: #instance
[JavaScript import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
[js.Batch Demo Repo]: https://github.com/bep/hugojsbatchdemo/
-[js.Build]: https://gohugo.io/hugo-pipes/js/#options
-[map]: https://gohugo.io/functions/collections/dictionary/
+[map]: /functions/collections/dictionary/
[OptionsSetter]: #optionssetter
-[page bundles]: https://gohugo.io/content-management/page-bundles/
+[page bundles]: /content-management/page-bundles/
[params options]: #params-options
[runner]: #runner
[script options]: #script-options
[script]: #script
[SetOptions]: #optionssetter
-[with]: https://gohugo.io/functions/go-template/with/
+[with]: /functions/go-template/with/
{{% include "./_common/options.md" %}}
-### Import JS code from /assets
+### Import JS code from the assets directory
`js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this:
import * as data from 'my/module/data.json';
```
-Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
+Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
Also note the new `params` option that can be passed from template to your JS files, e.g.:
Use the `js.Build` function to include Node.js dependencies.
-Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
+Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`.
-The start directory for resolving npm packages (aka. packages that live inside a `node_modules` folder) is always the main project folder.
+The start directory for resolving npm packages (aka. packages that live inside a `node_modules` directory) is always the main project directory.
{{% note %}}
If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project.
import * as params from '@params';
```
-Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `/assets` and import them directly.
+Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `assets` and import them directly.
minify
: (`bool`)Let `js.Build` handle the minification.
sourcesContent {{< new-in 0.140.0 >}}
: (`bool`) Whether to include the content of the source files in the source map. By default, this is `true`.
-
JSX {{< new-in 0.124.0 >}}
: (`string`) How to handle/transform JSX syntax. One of: `transform`, `preserve`, `automatic`. Default is `transform`. Notably, the `automatic` transform was introduced in React 17+ and will cause the necessary JSX helper functions to be imported automatically. See https://esbuild.github.io/api/#jsx
const container = document.getElementById('app');
if (container) render(<App />, container);
-```
\ No newline at end of file
+```
## Translation tables
-Create translation tables in the i18n directory, naming each file according to [RFC 5646]. Translation tables may be JSON, TOML, or YAML. For example:
+Create translation tables in the `i18n` directory, naming each file according to [RFC 5646]. Translation tables may be JSON, TOML, or YAML. For example:
```text
i18n/en.toml
signatures: [math.Abs VALUE]
---
-{{< new-in 0.112.0 >}}
-
```go-html-template
{{ math.Abs -2.1 }} → 2.1
```
signatures: [math.Add VALUE VALUE...]
---
-If one of the numbers is a [`float`], the result is a `float`.
+If one of the numbers is a [`float`](g), the result is a `float`.
```go-html-template
{{ add 12 3 2 }} → 17
```
-[`float`]: /getting-started/glossary/#float
-
You can also use the `add` function to concatenate strings.
```go-html-template
signatures: [math.Div VALUE VALUE...]
---
-If one of the numbers is a [`float`], the result is a `float`.
+If one of the numbers is a [`float`](g), the result is a `float`.
```go-html-template
{{ div 12 3 2 }} → 2
```
-
-[`float`]: /getting-started/glossary/#float
signatures: [math.Mul VALUE VALUE...]
---
-If one of the numbers is a [`float`], the result is a `float`.
+If one of the numbers is a [`float`](g), the result is a `float`.
```go-html-template
{{ mul 12 3 2 }} → 72
```
-
-[`float`]: /getting-started/glossary/#float
{{< new-in 0.121.2 >}}
-The `math.Rand` function returns a pseudo-random number in the [half-open interval] [0.0, 1.0).
+The `math.Rand` function returns a pseudo-random number in the half-open [interval](g) [0.0, 1.0).
```go-html-template
{{ math.Rand }} → 0.6312770459590062
```
-To generate a random integer in the [closed interval] [0, 5]:
+To generate a random integer in the closed interval [0, 5]:
```go-html-template
{{ math.Rand | mul 6 | math.Floor }}
```go-html-template
{{ div (math.Rand | mul 50 | math.Ceil) 10 }}
```
-
-[closed interval]: /getting-started/glossary/#interval
-[half-open interval]: /getting-started/glossary/#interval
signatures: [math.Sub VALUE VALUE...]
---
-If one of the numbers is a [`float`], the result is a `float`.
+If one of the numbers is a [`float`](g), the result is a `float`.
```go-html-template
{{ sub 12 3 2 }} → 7
```
-
-[`float`]: /getting-started/glossary/#float
signatures: ['openapi3.Unmarshal RESOURCE']
---
-Use the `openapi3.Unmarshal` function with [global], [page], or [remote] resources.
+Use the `openapi3.Unmarshal` function with [global resources](g), [page resources](g), or [remote resources](g).
-[global]: /getting-started/glossary/#global-resource
-[page]: /getting-started/glossary/#page-resource
-[remote]: /getting-started/glossary/#remote-resource
[OpenAPI]: https://www.openapis.org/
For example, to work with a remote [OpenAPI] definition:
```go-html-template
{{ $url := "https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.json" }}
{{ $api := "" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $api = . | openapi3.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
Hugo renders this to:
-
```html
<p>/pets</p>
<dl>
[`path.Clean`]: https://pkg.go.dev/path#Clean
[`path.Join`]: https://pkg.go.dev/path#Join
-
```go-html-template
{{ path.Join "partial" "news.html" }} → partial/news.html
{{ path.Join "partial/" "news.html" }} → partial/news.html
```
{{% note %}}
-This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
For page resources, use the [`Resources.ByType`] method on a `Page` object.
The `resources.Concat` function returns a concatenated slice of resources, caching the result using the target path as its cache key. Each resource must have the same [media type].
-Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods.
+Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] method.
[media type]: https://en.wikipedia.org/wiki/Media_type
[`publish`]: /methods/resource/publish/
The example above:
1. Captures the template as a resource
-2. Executes the resource as a template, passing the current page in context
-3. Publishes the resource to css/main.css
+1. Executes the resource as a template, passing the current page in context
+1. Publishes the resource to css/main.css
The result is:
After cryptographically hashing the resource content:
1. The values returned by the `.Permalink` and `.RelPermalink` methods include the hash sum
-2. The resource's `.Data.Integrity` method returns a [Subresource Integrity] (SRI) value consisting of the name of the hash algorithm, one hyphen, and the base64-encoded hash sum
+1. The resource's `.Data.Integrity` method returns a [Subresource Integrity] (SRI) value consisting of the name of the hash algorithm, one hyphen, and the base64-encoded hash sum
[Subresource Integrity]: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
[`permalink`]: /methods/resource/permalink/
[`relpermalink`]: /methods/resource/relpermalink/
-Let's say you need to publish a file named "site.json" in the root of your public directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example:
+Let's say you need to publish a file named "site.json" in the root of your `public` directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example:
```json
{
- "build_date": "2024-02-19T12:27:05-08:00",
- "hugo_version": "0.137.1",
- "last_modified": "2024-02-19T12:01:42-08:00"
+ "build_date": "2025-01-16T19:14:41-08:00",
+ "hugo_version": "0.141.0",
+ "last_modified": "2025-01-16T19:14:46-08:00"
}
```
The example above:
1. Creates a map with the relevant key-value pairs using the [`dict`] function
-2. Encodes the map as a JSON string using the [`jsonify`] function
-3. Creates a resource from the JSON string using the `resources.FromString` function
-4. Publishes the file to the root of the public directory using the resource's `.Publish` method
+1. Encodes the map as a JSON string using the [`jsonify`] function
+1. Creates a resource from the JSON string using the `resources.FromString` function
+1. Publishes the file to the root of the `public` directory using the resource's `.Publish` method
Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your string contains template actions. Rewriting the example above:
```
{{% note %}}
-This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
For page resources, use the [`Resources.Get`] method on a `Page` object.
```
{{% note %}}
-This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
For page resources, use the [`Resources.GetMatch`] method on a `Page` object.
```go-html-template
{{ $url := "https://example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
## Remote data
-When retrieving remote data, use the [`transform.Unmarshal`] function to [unmarshal] the response.
+When retrieving remote data, use the [`transform.Unmarshal`] function to [unmarshal](g) the response.
[`transform.Unmarshal`]: /functions/transform/unmarshal/
-[unmarshal]: /getting-started/glossary/#unmarshal
```go-html-template
{{ $data := dict }}
{{ $url := "https://example.org/books.json" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
## Error handling
-The [`Err`] method on a resource returned by the `resources.GetRemote` function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build.
+Use the [`try`] statement to capture HTTP request errors. If you do not handle the error yourself, Hugo will fail the build.
-[`Err`]: /methods/resource/err/
+[`try`]: /functions/go-template/try
{{% note %}}
-Hugo does not classify an HTTP response with status code 404 as an error. In this case the function returns nil.
+Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil.
{{% /note %}}
```go-html-template
{{ $url := "https://broken-example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
```go-html-template
{{ $url := "https://broken-example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ warnf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ else }}
+ {{ warnf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
```go-html-template
{{ $url := "https://example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ with .Data }}
{{ .ContentLength }} → 42764
{{ .ContentType }} → image/jpeg
{{ .StatusCode }} → 200
{{ .TransferEncoding }} → []
{{ end }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
```
{{% note %}}
-This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
For page resources, use the [`Resources.Match`] method on a `Page` object.
{{% /note %}}
Step 4
-: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [config/production].
+: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`].
{{< code-toggle file=hugo >}}
[build.buildStats]
Default is `production` for `hugo` and `development` for `hugo server`.
HUGO_PUBLISHDIR
-: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this folder from PostCSS when running the server, you could run the server with one of these flags:
+: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this directory from PostCSS when running the server, you could run the server with one of these flags:
```sh
hugo server --renderToDisk
[node.js]: https://nodejs.org/en/download
[supported file name]: https://github.com/postcss/postcss-load-config#usage
-[config/production]: /getting-started/configuration/#configuration-directory
+[`config/production`]: /getting-started/configuration/#configuration-directory
[configure build]: /getting-started/configuration/#configure-build
[purgecss]: https://github.com/FullHuman/purgecss#readme
For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
-[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository.
+[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository.
#### GitHub Pages
```yaml
variables:
- HUGO_VERSION: 0.137.1
- DART_SASS_VERSION: 1.80.6
+ HUGO_VERSION: 0.141.0
+ DART_SASS_VERSION: 1.83.4
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
```toml
[build.environment]
-HUGO_VERSION = "0.137.1"
-DART_SASS_VERSION = "1.80.6"
+HUGO_VERSION = "0.141.0"
+DART_SASS_VERSION = "1.83.4"
+NODE_VERSION = "22"
TZ = "America/Los_Angeles"
[build]
Use the `safe.CSS` function to encapsulate known safe content that matches any of:
1. The CSS3 stylesheet production, such as `p { color: purple }`.
-2. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
-3. CSS3 declaration productions, such as `color: red; margin: 2px`.
-4. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
+1. The CSS3 rule production, such as `a[href=~"https:"].foo#bar`.
+1. CSS3 declaration productions, such as `color: red; margin: 2px`.
+1. The CSS3 value production, such as `rgba(0, 0, 255, 127)`.
Use of this type presents a security risk: the encapsulated content should come from a trusted source, as it will be included verbatim in the template output.
aliases: [/functions/strings.containsnonspace]
---
-{{< new-in 0.111.0 >}}
-
Whitespace characters include `\t`, `\n`, `\v`, `\f`, `\r`, and characters in the [Unicode Space Separator] category.
[Unicode Space Separator]: https://www.compart.com/en/unicode/category/Zs
{{ slicestr "BatMan" 0 3 }} → Bat
```
-The START and END arguments represent the endpoints of a [half-open interval], a concept that may be difficult to grasp when first encountered. You may find that the [`strings.Substr`] function is easier to understand.
+The START and END arguments represent the endpoints of a half-open [interval](g), a concept that may be difficult to grasp when first encountered. You may find that the [`strings.Substr`] function is easier to understand.
-[half-open interval]: /getting-started/glossary/#interval
[`strings.Substr`]: /functions/strings/substr/
This function only works in combination with the `with` keyword.
{{% /note %}}
-
{{% note %}}
Variables defined on the outside are not visible on the inside and vice versa. To pass in data, use the `data` [option](#options).
{{% /note %}}
data (`map`)
: Optional map to pass as data to the deferred template. This will be available in the deferred template as `.` or `$`.
-
```go-html-template
Language Outside: {{ site.Language.Lang }}
Page Outside: {{ .RelPermalink }}
The order of precedence for determining the time zone is:
1. The time zone offset in the date/time string
-2. The time zone provided as the second argument to the `time.AsTime` function
-3. The time zone specified in your site configuration
-4. The `Etc/UTC` time zone
-
+1. The time zone provided as the second argument to the `time.AsTime` function
+1. The time zone specified in your site configuration
+1. The `Etc/UTC` time zone
[IANA Time Zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
[`time.Time`]: https://pkg.go.dev/time#Time
-[`timeZone`]: https://gohugo.io/getting-started/configuration/#timezone
+[`timeZone`]: /getting-started/configuration/#timezone
[functions]: /functions/time/
[methods]: /methods/time/
The time unit must be one of the following:
-
Duration|Valid time units
:--|:--
hours|`hour`, `h`
To override the default time zone, set the [`timeZone`] in your site configuration. The order of precedence for determining the time zone is:
1. The time zone offset in the date/time string
-2. The time zone specified in your site configuration
-3. The `Etc/UTC` time zone
+1. The time zone specified in your site configuration
+1. The `Etc/UTC` time zone
-[`timeZone`]: https://gohugo.io/getting-started/configuration/#timezone
+[`timeZone`]: /getting-started/configuration/#timezone
## Layout string
2023-10-15 12:59:28.337140706 -0700 PDT m=+0.041752605
```
-To format and [localize] the value, pass it through the [`time.Format`] function:
+To format and [localize](g) the value, pass it through the [`time.Format`] function:
```go-html-template
{{ time.Now | time.Format "Jan 2006" }} → Oct 2023
The `time.Now` function returns a `time.Time` value, so you can chain any of the [time methods] to the resulting value. For example:
-
```go-html-template
{{ time.Now.Year }} → 2023 (int)
{{ time.Now.Weekday.String }} → Sunday
```
[`time.Format`]: /functions/time/format/
-[localize]: /getting-started/glossary/#localization
[time methods]: /methods/time/
The `time.ParseDuration` function returns a time.Duration value that you can use with any of the `Duration` [methods].
-
A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
This template:
The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration]. Then you can write emoji shorthand directly into your content files;
-
```text
I :heart: Hugo!
```
- functions/transform/CanHighlight
- functions/transform/HighlightCodeBlock
returnType: template.HTML
- signatures: ['transform.Highlight INPUT LANG [OPTIONS]']
+ signatures: ['transform.Highlight CODE LANG [OPTIONS]']
aliases: [/functions/highlight]
toc: true
---
-The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles.
+The `highlight` function 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/
## Arguments
-INPUT
-: The code to highlight.
+The `transform.Highlight` shortcode takes three arguments.
+
+CODE
+: (`string`) The code to highlight.
LANG
-: The language of the code to highlight. Choose from one of the [supported languages]. Case-insensitive.
+: (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
OPTIONS
-: A map or comma-separated list of zero or more options. Set default values in [site configuration].
-
-## Options
-
-anchorLineNos
-: (`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
-
-codeFences
-: (`bool`) Whether to highlight fenced code blocks. Default is `true`.
-
-guessSyntax
-: (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer]. Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
-
-[lexer]: /getting-started/glossary/#lexer
-
-{{% note %}}
-The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
-{{% /note %}}
-
-hl_Lines
-: (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
-
-hl_inline
-: (`bool`) Whether to render the highlighted code without a wrapping container.Default is `false`.
-
-lineAnchors
-: (`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
-
-lineNoStart
-: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
-
-lineNos
-: (`bool`) Whether to display a number at the beginning of each line. Default is `false`.
+: (`map or string`) A map or space-separate key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive.
-lineNumbersInTable
-: (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
-
-noClasses
-: (`bool`) Whether to use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and generate the CSS file using the `hugo gen chromastyles` command. Default is `true`.
-
-style
-: (`string`) The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive. Default is `monokai`.
-
-tabWidth
-: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
-
-wrapperClass
-{{< new-in 0.140.2 >}}
-: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
-
-{{% note %}}
-Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
-
-lineNos=inline
-: equivalent to `lineNos=true` and `lineNumbersInTable=false`
-
-lineNos=table
-: equivalent to `lineNos=true` and `lineNumbersInTable=true`
-{{% /note %}}
+[site configuration]: /getting-started/configuration-markup#highlight
+[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages
## Examples
{{ transform.Highlight $input $lang $opts }}
```
-[Chroma]: https://github.com/alecthomas/chroma
-[site configuration]: /getting-started/configuration-markup#highlight
-[style gallery]: https://xyproto.github.io/splash/docs/
-[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages
+## Options
+
+{{% include "functions/_common/highlighting-options" %}}
---
title: transform.ToMath
-description: Renders a math expression using KaTeX.
+description: Renders mathematical equations and expressions written in the LaTeX markup language.
categories: []
-keywords: [math,katex]
+keywords: [katex,latex,math,typesetting]
action:
aliases: []
related:
- content-management/mathematics
returnType: types.Result[template.HTML]
- signatures: ['transform.ToMath EXPRESSION [OPTIONS]']
+ signatures: ['transform.ToMath INPUT [OPTIONS]']
aliases: [/functions/tomath]
toc: true
---
{{< new-in "0.132.0" >}}
-{{% note %}}
-This feature was introduced in Hugo 0.132.0 and is marked as experimental.
+Hugo uses an embedded instance of the [KaTeX] display engine to render mathematical markup to HTML. You do not need to install the KaTeX display engine.
-This does not mean that it's going to be removed, but this is our first use of WASI/Wasm in Hugo, and we need to see how it [works in the wild](https://github.com/gohugoio/hugo/issues/12736) before we can set it in stone.
-{{% /note %}}
+[KaTeX]: https://katex.org/
-## Arguments
+```go-html-template
+{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
+```
-EXPRESSION
-: The math expression to render using KaTeX.
+{{% note %}}
+By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result.
-OPTIONS
-: A map of zero or more options.
+[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
-## Options
+To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet.
-These are a subset of the [KaTeX options].
+{{% /note %}}
-output
-: (`string`). Determines the markup language of the output. One of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
+```go-html-template
+{{ $opts := dict "output" "htmlAndMathml" }}
+{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" $opts }}
+```
- {{% comment %}}Indent to prevent splitting the description list.{{% / comment %}}
+## Options
- With `html` and `htmlAndMathml` you must include KaTeX CSS within the `head` element of your base template. For example:
+Pass a map of options as the second argument to the `transform.ToMath` function. The options below are a subset of the KaTeX [rendering options].
- ```html
- <head>
- ...
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
- ...
- </head>
- ```
+[rendering options]: https://katex.org/docs/options.html
displayMode
: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`.
-leqno
-: (`bool`) If `true` render with the equation numbers on the left. Default is `false`.
+errorColor
+: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
+
+[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
fleqn
: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`.
+macros
+: (`map`) A map of macros to be used in the math expression. Default is `{}`.
+
+ ```go-html-template
+ {{ $macros := dict
+ "\\addBar" "\\bar{#1}"
+ "\\bold" "\\mathbf{#1}"
+ }}
+ {{ $opts := dict "macros" $macros }}
+ {{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
+ ```
+
minRuleThickness
: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
-macros
-: (`map`) A map of macros to be used in the math expression. Default is `{}`.
+output
+: (`string`). Determines the markup language of the output, one of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
+
+ With `html` and `htmlAndMathml` you must include the KaTeX style sheet within the `head` element of your base template.
+
+ ```html
+ <link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
throwOnError
-: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTex. See [error handling]. Default is `true`.
+: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`.
-errorColor
-: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
+## Error handling
-## Examples
+There are three ways to handle errors:
-### Basic
+1. Let KaTeX throw an error and fail the build. This is the default behavior.
+1. Set the `throwOnError` option to `false` to make KaTeX render the expression as an error instead of throwing an error. See [options](#options).
+1. Handle the error in your template.
-```go-html-template
-{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
-```
+The example below demonstrates error handing within a template.
-### Macros
+## Example
-```go-html-template
-{{ $macros := dict
- "\\addBar" "\\bar{#1}"
- "\\bold" "\\mathbf{#1}"
-}}
-{{ $opts := dict "macros" $macros }}
-{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
-```
+Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function.
-## Error handling
+###### Step 1
-There are 3 ways to handle errors from KaTeX:
+Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
-1. Let KaTeX throw an error and make the build fail. This is the default behavior.
-1. Handle the error in your template. See the render hook example below.
-1. Set the `throwOnError` option to `false` to make KaTeX render the expression as an error instead of throwing an error. See [options](#options).
+[passthrough extension]: /getting-started/configuration-markup/#passthrough
+
+{{< code-toggle file=hugo copy=true >}}
+[markup.goldmark.extensions.passthrough]
+enable = true
+
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['\[', '\]'], ['$$', '$$']]
+inline = [['\(', '\)']]
+{{< /code-toggle >}}
+
+{{% note %}}
+The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
+{{% /note %}}
-{{< code file=layouts/_default/_markup/render-passthrough-inline.html copy=true >}}
-{{ with transform.ToMath .Inner }}
- {{ with .Err }}
- {{ errorf "Failed to render KaTeX: %q. See %s" . $.Position }}
- {{ else }}
- {{ . }}
+###### Step 2
+
+Create a [passthrough render hook] to capture and render the LaTeX markup.
+
+[passthrough render hook]: /render-hooks/passthrough/
+
+{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}}
+{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
+{{- with try (transform.ToMath .Inner $opts) }}
+ {{- with .Err }}
+ {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
+ {{- else }}
+ {{- .Value }}
+ {{- $.Page.Store.Set "hasMath" true }}
+ {{- end }}
+{{- end -}}
+{{< /code >}}
+
+###### Step 3
+
+In your base template, conditionally include the KaTeX CSS within the head element.
+
+{{< code file=layouts/_default/baseof.html copy=true >}}
+<head>
+ {{ $noop := .WordCount }}
+ {{ if .Page.Store.Get "hasMath" }}
+ <link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
{{ end }}
-{{ end }}
-{{- /* chomp trailing newline */ -}}
+</head>
{{< /code >}}
-[error handling]: #error-handling
-[KaTeX options]: https://katex.org/docs/options.html
-[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
+In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
+
+#### Step 4
+
+Add some mathematical markup to your content, then test.
+
+{{< code file=content/example.md >}}
+This is an inline \(a^*=x-b^*\) equation.
+
+These are block equations:
+
+\[a^*=x-b^*\]
+
+$$a^*=x-b^*$$
+{{< /code >}}
aliases: [/functions/transform.unmarshal]
---
-The input can be a string or a [resource].
+The input can be a string or a [resource](g).
## Unmarshal a string
### Global resource
-A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
+A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
```text
assets/
```go-html-template
{{ $data := dict }}
{{ $url := "https://example.org/books.json" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ range where $data "author" "Victor Hugo" }}
```go-html-template
{{ $data := dict }}
{{ $url := "https://example.org/books/index.xml" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
}
```
-The title keys do not begin with an underscore or a letter---they are not valid [identifiers]. Use the [`index`] function to access the values:
+The title keys do not begin with an underscore or a letter---they are not valid [identifiers](g). Use the [`index`] function to access the values:
```go-html-template
{{ with $data.channel.item }}
```
[`index`]: /functions/collections/indexfunction/
-[identifiers]: https://go.dev/ref/spec#Identifiers
-[resource]: /getting-started/glossary/#resource
[page bundle]: /content-management/page-bundles/
aliases: [/functions/urls.joinpath]
---
-{{< new-in 0.112.0 >}}
-
```go-html-template
{{ urls.JoinPath }} → "" (empty string)
{{ urls.JoinPath "" }} → /
Instead of specifying a path, you can also provide an options map:
path
-: (`string`) The path to the page, relative to the content directory. Required.
+: (`string`) The path to the page, relative to the `content` directory. Required.
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
Instead of specifying a path, you can also provide an options map:
path
-: (`string`) The path to the page, relative to the content directory. Required.
+: (`string`) The path to the page, relative to the `content` directory. Required.
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
## Example
-Use the `urlize` function to create a link to a [term] page.
+Use the `urlize` function to create a link to a [term page](g).
Consider this site configuration:
To generate a list of term pages associated with a given content page, use the [`GetTerms`] method on a `Page` object.
[`GetTerms`]: /methods/page/getterms/
-[term]: /getting-started/glossary/#term
menu:
docs:
parent: getting-started
- weight: 60
-weight: 60
+ weight: 70
+weight: 70
slug: configuration-build
toc: true
---
#### noJSConfigInAssets
-(`bool`) If `true`, turns off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
+(`bool`) If `true`, turns off writing a `jsconfig.json` into your `assets` directory with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written.
#### useResourceCacheWhen
(`string`) When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available.
-
## Configure cache busters
-{{< new-in 0.112.0 >}}
-
The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this:
{{< code-toggle file=hugo >}}
Exclude `class` attributes, `id` attributes, or tags from `hugo_stats.json` with the `disableClasses`, `disableIDs`, and `disableTags` keys.
{{% note %}}
-Given that CSS purging is typically limited to production builds, place the `buildStats` object below [config/production].
+Given that CSS purging is typically limited to production builds, place the `buildStats` object below [`config/production`].
-[config/production]: /getting-started/configuration/#configuration-directory
+[`config/production`]: /getting-started/configuration/#configuration-directory
Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential.
{{% /note %}}
-Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build.
\ No newline at end of file
+Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build.
menu:
docs:
parent: getting-started
- weight: 50
-weight: 50
+ weight: 60
+weight: 60
slug: configuration-markup
toc: true
---
To avoid a conflict when enabling the Hugo Goldmark Extras subscript extension, if you want to render subscript and strikethrough text concurrently you must:
1. Disable the Goldmark strikethrough extension
-2. Enable the Hugo Goldmark Extras delete extension
+1. Enable the Hugo Goldmark Extras delete extension
For example:
{{< new-in 0.122.0 >}}
-Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. See [mathematics in Markdown] for details.
+Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details.
[mathematics in Markdown]: content-management/mathematics/
menu:
docs:
parent: getting-started
- weight: 40
-weight: 40
+ weight: 50
+weight: 50
toc: true
aliases: [/overview/source-directory/,/overview/configuration/]
---
## Configuration directory
-Instead of a single site configuration file, split your configuration by [environment], root configuration key, and language. For example:
-
-[environment]: /getting-started/glossary/#environment
+Instead of a single site configuration file, split your configuration by [environment](g), root configuration key, and language. For example:
```text
my-project/
Now consider the following scenario:
1. You don't want to load the analytics code when running `hugo server`.
-2. You want to use different Google tag IDs for your production and staging environments. For example:
+1. You want to use different Google tag IDs for your production and staging environments. For example:
- `G-PPPPPPPPP` for production
- `G-SSSSSSSSS` for staging
By default, Hugo sets its `environment` to `development` when running `hugo server`. In the absence of a `config/development` directory, Hugo uses the `config/_default` directory.
-2. `config/production/hugo.toml`
+1. `config/production/hugo.toml`
Include this section only:
By default, Hugo sets its `environment` to `production` when running `hugo`. The analytics code will use the `G-PPPPPPPPP` tag ID.
-3. `config/staging/hugo.toml`
+1. `config/staging/hugo.toml`
Include this section only:
(`string`) The directory from where Hugo reads data files. Default is `data`. {{% module-mounts-note %}}
+###### defaultOutputFormat
+(`string`) The default output format for the site. If unspecified, the first available format in the defined order (by weight, then alphabetically) will be used.
+
###### defaultContentLanguage
(`string`) Content without language indicator will default to this language. Default is `en`.
###### disableKinds
-(`string slice`) Disable rendering of the specified page [kinds], any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
-
-[kinds]: /getting-started/glossary/#page-kind
+(`string slice`) Disable rendering of the specified page [kinds](g), any of `404`, `home`, `page`, `robotstxt`, `rss`, `section`, `sitemap`, `taxonomy`, or `term`.
###### disableLanguages
See [Configure Build](/getting-started/configuration-build/).
-
## Configure server
This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slightly more powerful [Glob matching](https://github.com/gobwas/glob):
status = 404
{{< /code-toggle >}}
-
## Configure title case
By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook] when creating automatic section titles, and when transforming strings with the [`strings.Title`] function.
: (`string`) The absolute path to the Dart Sass executable. By default, Hugo searches for the executable in each of the paths in the `PATH` environment variable.
HUGO_ENVIRONMENT
-: (`string`) Overrides the default [environment], typically one of `development`, `staging`, or `production`.
-
-[environment]: /getting-started/glossary/#environment
+: (`string`) Overrides the default [environment](g), typically one of `development`, `staging`, or `production`.
HUGO_FILE_LOG_FORMAT
: (`string`) A format string for the file path, line number, and column number displayed when reporting errors, or when calling the `Position` method from a shortcode or Markdown render hook. Valid tokens are `:file`, `:line`, and `:col`. Default is `:file::line::col`.
[templates]: /templates/
[static-files]: /content-management/static-files/
-
## Configure HTTP cache
{{< new-in 0.127.0 >}}
: The [page language].
kind
-: The [kind] of the page.
+: The [kind](g) of the page.
output
-: The [output format] of the page.
+: The [output format](g) of the page.
It is recommended to put coarse grained filters (e.g. for language and output format) in the excludes section, e.g.:
[path]: /methods/page/path/
[page language]: /methods/page/language/
-[kind]: /getting-started/glossary/#page-kind
-[output format]: /getting-started/glossary/#output-format
-[type]: /getting-started/glossary/#content-type
menu:
docs:
parent: getting-started
- weight: 30
-weight: 30
+ weight: 40
+weight: 40
toc: true
aliases: [/overview/source-directory/]
---
###### layouts
-The layouts directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/).
+The `layouts` directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/).
###### public
###### static
-The `static` directory contains files that will be copied to the public directory when you build your site. For example: `favicon.ico`, `robots.txt`, and files that verify site ownership. Before the introduction of [page bundles](/getting-started/glossary/#page-bundle) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript.
+The `static` directory contains files that will be copied to the `public` directory when you build your site. For example: `favicon.ico`, `robots.txt`, and files that verify site ownership. Before the introduction of [page bundles](g) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript.
###### themes
-The `themes` directory contains one or more [themes](/getting-started/glossary/#theme), each in its own subdirectory.
+The `themes` directory contains one or more [themes](g), each in its own subdirectory.
## Union file system
```
{{% note %}}
-When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's content directory was mounted first.
+When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's `content` directory was mounted first.
{{% /note %}}
You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/hugo-modules/configuration/#module-configuration-mounts).
menu:
docs:
parent: getting-started
- weight: 70
-weight: 70
+ weight: 90
+weight: 90
toc: true
---
Length: 488 pages\
ISBN: 9781617297007
-
### Build Websites with Hugo
In this book, you'll use Hugo to build a personal portfolio site that you can use to showcase your skills and thoughts to the world. You'll build the basic skeleton, develop a custom theme, and use content templates to generate new pages quickly. You'll use internal and external data sources to embed content into your site, and render some of your content in JSON and RSS. You'll add a blog section with posts and integrate Disqus with your site, and then make your site searchable.
[{{< img src="build-websites-with-hugo.png" alt="Book cover: Build Websites with Hugo" filter="process" filterArgs="resize x350 webp">}}](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)
-
Author: Brian P. Hogan\
Publisher: [Pragmatic Bookshelf](https://pragprog.com/titles/bhhugo/build-websites-with-hugo/)\
Publication date: May 2020\
This course covers the basics of using the Hugo static site generator. Work your way through the articles and we'll teach you everything you need to know to create a professional and scalable website or blog!
-
1. [Introduction](https://www.giraffeacademy.com/static-site-generators/hugo/)
1. [Windows Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-windows/)
1. [Mac Installation](https://www.giraffeacademy.com/static-site-generators/hugo/installing-hugo-on-mac/)
+++ /dev/null
----
-title: Glossary of terms
-description: Terms commonly used throughout the documentation.
-categories: [getting started]
-keywords: [glossary]
-menu:
- docs:
- parent: getting-started
- weight: 60
-weight: 60
-# Use level 6 headings for each term in the glossary.
----
-
-[A](#action)
-[B](#bool)
-[C](#cache)
-[D](#default-sort-order)
-[E](#environment)
-[F](#field)
-[G](#global-resource)
-[H](#headless-bundle)
-[I](#identifier)
-[K](#kind)
-[L](#layout)
-[M](#map)
-[N](#node)
-[O](#object)
-[P](#page-bundle)
-[R](#regular-page)
-[S](#scalar)
-[T](#taxonomic-weight)
-[U](#unmarshal)
-[V](#variable)
-[W](#walk)
-[Z](#zero-time)
-
-###### action
-
-See [template action](#template-action).
-
-###### archetype
-
-A template for new content. See [details](/content-management/archetypes/).
-
-###### argument
-
-A [scalar](#scalar), [array](#array), [slice](#slice), [map](#map), or [object](#object) passed to a [function](#function), [method](#method), or [shortcode](#shortcode).
-
-###### array
-
-A numbered sequence of elements. Unlike Go's [slice](#slice) data type, an array has a fixed length. [Elements](#element) within an array can be [scalars](#scalar), slices, [maps](#map), pages, or other arrays. See the [Go documentation](https://go.dev/ref/spec#Array_types) for details.
-
-###### bool
-
-See [boolean](#boolean).
-
-###### boolean
-
-A data type with two possible values, either `true` or `false`.
-
-###### branch bundle
-
-A directory that contains an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page. See [details](/content-management/page-bundles/).
-
-###### build
-
-To generate a static site that includes HTML files and assets such as images, CSS, and JavaScript. The build process includes rendering and resource transformations.
-
-###### bundle
-
-See [page bundle](#page-bundle).
-
-###### cache
-
-A software component that stores data so that future requests for the same data are faster.
-
-###### chain
-
-Within a template, to connect one or more [identifiers](#identifier) with a dot. An identifier can represent a method, object, or field. For example, `.Site.Params.author.name` or `.Date.UTC.Hour`.
-
-###### CJK
-
-A collective term for the Chinese, Japanese, and Korean languages. See [details](https://en.wikipedia.org/wiki/CJK_characters).
-
-###### CLI
-
-Command line interface.
-
-###### collection
-
-An [array](#array), [slice](#slice), or [map](#map).
-
-###### content adapter
-
-A template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. See [details](/content-management/content-adapters/).
-
-###### content format
-
-A markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/).
-
-###### content type
-
-A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the content directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/).
-
-###### content view
-
-A template called with the `.Page.Render` method. See [details](/templates/content-view/).
-
-###### context
-
-Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#context).
-
-###### default sort order
-
-The default sort order for page collections. Hugo sorts by [weight](#weight), then by date (descending), then by link title, and then by file path.
-
-###### element
-
-A member of a slice or array.
-
-###### environment
-
-Typically one of `development`, `staging`, or `production`, each environment may exhibit different behavior depending on configuration and template logic. For example, in a production environment you might minify and fingerprint CSS, but that probably doesn't make sense in a development environment.
-
-When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your site with the `hugo` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag or the `HUGO_ENVIRONMENT` environment variable.
-
-To determine the current environment within a template, use the [`hugo.Environment`] function.
-
-[`hugo.Environment`]: /functions/hugo/environment/
-
-###### field
-
-A predefined key-value pair in front matter such as `date` or `title`. See also [parameter](#parameter).
-
-###### flag
-
-An option passed to a command-line program, beginning with one or two hyphens. See [details](/commands/hugo/).
-
-###### float
-
-See [floating point](#floating-point).
-
-###### floating point
-
-A numeric data type with a fractional component. For example, `3.14159`.
-
-###### fragment
-
-The final segment of a URL, beginning with a hash (`#`) mark, that references an `id` attribute of an HTML element on the page.
-
-###### front matter
-
-Metadata at the beginning of each content page, separated from the content by format-specific delimiters. See [details](/content-management/front-matter/).
-
-###### function
-
-Used within a [template action](#template-action), a function takes one or more [arguments](#argument) and returns a value. Unlike [methods](#method), functions are not associated with an [object](#object). See [details](/functions/).
-
-###### global resource
-
-A file within the assets directory, or within any directory [mounted](/hugo-modules/configuration/#module-configuration-mounts) to the assets directory. Capture one or more global resources using the [`resources.Get`], [`resources.GetMatch`], [`resources.Match`], or [`resources.ByType`] functions.
-
-[`resources.Get`]: /functions/resources/get/
-[`resources.GetMatch`]: /functions/resources/getmatch/
-[`resources.Match`]: /functions/resources/match/
-[`resources.ByType`]: /functions/resources/byType/
-
-###### headless bundle
-
-An unpublished leaf or branch bundle whose content and resources you can include in other pages. See [build options](/content-management/build-options/).
-
-###### identifier
-
-A string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores.
-
-###### int
-
-See [integer](#integer).
-
-###### integer
-
-A numeric data type without a fractional component. For example, `42`.
-
-###### internationalization
-
-Software design and development efforts that enable [localization](#localization). See the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated i18n.
-
-###### interval
-
-An [interval](https://en.wikipedia.org/wiki/Interval_(mathematics)) is a range of numbers between two endpoints: closed, open, or half-open.
-
-- A _closed_ interval, denoted by brackets, includes its endpoints. For example, [0, 1] is the interval where `0 <= x <= 1`.
-
-- An _open_ interval, denoted by parentheses, excludes its endpoints. For example, (0, 1) is the interval where `0 < x < 1`.
-
-- A _half-open_ interval includes only one of its endpoints. For example, (0, 1] is the _left-open_ interval where `0 < x <= 1`, while [0, 1) is the _right-open_ interval where `0 <= x < 1`.
-
-###### kind
-
-See [page kind](#page-kind).
-
-###### layout
-
-See [template](#template).
-
-###### leaf bundle
-
-A directory that contains an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. See [details](/content-management/page-bundles/).
-
-###### lexer
-
-A software component that identifies keywords, identifiers, operators, numbers, and other basic building blocks of a programming language within the input text.
-
-###### list page
-
-Any [page kind](#page-kind) that receives a page [collection](#collection) in [context](#context). This includes the home page, [section pages](#section-page), [taxonomy pages](#taxonomy-page), and [term pages](#term-page).
-
-###### list template
-
-Any template that renders a [list page](#list-page). This includes [home](/templates/types/#home), [section](/templates/types/#section), [taxonomy](/templates/types/#taxonomy), and [term](/templates/types/#term) templates.
-
-###### localization
-
-Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n.
-
-###### logical path
-
-{{< new-in 0.123.0 >}}
-
-A page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. Starting with a file path relative to the content directory, Hugo determines the logical path by stripping the file extension and language identifier, converting to lower case, then replacing spaces with hyphens. {{% comment %}}<!-- You may also set this value using the `path` front matter field. -->{{% /comment %}} See [examples](/methods/page/path/#examples).
-
-###### map
-
-An unordered group of elements, each indexed by a unique key. See the [Go documentation](https://go.dev/ref/spec#Map_types) for details.
-
-###### Markdown attribute
-
-A list of attributes, containing one or more key-value pairs, separated by spaces or commas, and wrapped by braces. Apply Markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark).
-
-###### marshal
-
-To transform a data structure into a serialized object. For example, transforming a [map](#map) into a JSON string. See [unmarshal](#unmarshal).
-
-###### method
-
-Used within a [template action](#template-action) and associated with an [object](#object), a method takes zero or more [arguments](#argument) and either returns a value or performs an action. For example, `.IsHome` is a method on the `.Page` object which returns `true` if the current page is the home page. See also [function](#function).
-
-###### module
-
-Like a [theme](#theme), a module is a packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. See [details](/hugo-modules/).
-
-###### node
-
-A class of [page kinds](#page-kind) including `home`, `section`, `taxonomy`, and `term`.
-
-###### noop
-
-An abbreviated form of "no operation", a _noop_ is a statement that does nothing.
-
-###### object
-
-A data structure with or without associated [methods](#method).
-
-###### ordered taxonomy
-
-Created by invoking the [`Alphabetical`] or [`ByCount`] method on a [`Taxonomy`](#taxonomy-object) object, which is a [map](#map), an ordered taxonomy is a [slice](#slice), where each element is an object that contains the [term](#term) and a slice of its [weighted pages](#weighted-page).
-
-[`Alphabetical`]: /methods/taxonomy/alphabetical/
-[`ByCount`]: /methods/taxonomy/bycount/
-
-###### output format
-
-{{% include "methods/page/_common/output-format-definition.md" %}}
-
-###### page bundle
-
-A directory that encapsulates both content and associated [resources](#resource). There are two types of page bundles: [leaf bundles](#leaf-bundle) and [branch bundles](#branch-bundle). See [details](/content-management/page-bundles/).
-
-###### page collection
-
-A slice of `Page` objects.
-
-###### page kind
-
-A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [details](/methods/page/kind/).
-
-Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` page kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
-
-###### page resource
-
-A file within a [page bundle](#page-bundle). Capture one or more page resources using any of the [`Resources`] methods on a `Page` object.
-
-[`Resources`]: /methods/page/resources/#methods
-
-###### pager
-
-Created during [pagination](#pagination), a pager contains a subset of a list page and navigation links to other pagers.
-
-###### paginate
-
-To split a list page into two or more subsets.
-
-###### pagination
-
-The process of [paginating](#paginate) a list page. See [details](/templates/pagination/).
-
-###### paginator
-
-A collection of [pagers](#pager).
-
-###### parameter
-
-Typically, a user-defined key-value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). See also [field](#field).
-
-###### partial
-
-A [template](#template) called from any other template including [shortcodes](#shortcode), [render hooks](#render-hook), and other partials. A partial either renders something or returns something. A partial can also call itself, for example, to [walk](#walk) a data structure.
-
-###### permalink
-
-The absolute URL of a published resource or a rendered page, including scheme and host.
-
-###### pipe
-
-See [pipeline](#pipeline).
-
-###### pipeline
-
-Within a [template action](#template-action), a pipeline is a possibly chained sequence of values, [function](#function) calls, or [method](#method) calls. Functions and methods in the pipeline may take multiple [arguments](#argument).
-
-A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. See the [Go documentation](https://pkg.go.dev/text/template#hdr-Pipelines) for details.
-
-###### publish
-
-See [build](#build).
-
-###### regular page
-
-Content with the "page" [page kind](#page-kind). See also [section page](#section-page).
-
-###### relative permalink
-
-The host-relative URL of a published resource or a rendered page.
-
-###### render hook
-
-A [template](#template) that overrides standard Markdown rendering. See [details](/render-hooks).
-
-###### remote resource
-
-A file on a remote server, accessible via HTTP or HTTPS with the [`resources.GetRemote`](/functions/resources/getremote) function.
-
-###### resource
-
-Any file consumed by the build process to augment or generate content, structure, behavior, or presentation. For example: images, videos, content snippets, CSS, Sass, JavaScript, and data.
-
-Hugo supports three types of resources: [global](#global-resource), [page](#page-resource), and [remote](#remote-resource)
-
-###### resource type
-
-The main type of a resource's [media type]. Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `video`, etc. Retrieve the resource type using the [`ResourceType`] method on a `Resource` object.
-
-[media type]: /methods/resource/mediatype/
-[`ResourceType`]: /methods/resource/resourcetype/
-
-###### scalar
-
-A single value, one of [string](#string), [integer](#integer), [floating point](#floating-point), or [boolean](#boolean).
-
-###### scratch pad
-
-Conceptually, a [map](#map) with [methods](#method) to set, get, update, and delete values. Attach the data structure to a `Page` object using the [`Scratch`] or [`Store`] methods, or create a locally scoped scratch pad using the [`newScratch`] function.
-
-[`Scratch`]: /methods/page/scratch/
-[`Store`]: /methods/page/store/
-[`newScratch`]: /functions/collections/newscratch/
-
-###### section
-
-A top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/content-management/sections/).
-
-###### section page
-
-Content with the "section" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and/or [section pages](#section-page) within the current [section](#section). See also [regular page](#regular-page).
-
-###### shortcode
-
-A [template](#template) called from within Markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/).
-
-###### slice
-
-A numbered sequence of elements. Unlike Go's [array](#array) data type, slices are dynamically sized. [Elements](#element) within a slice can be [scalars](#scalar), [arrays](#array), [maps](#map), pages, or other slices. See the [Go documentation](https://go.dev/ref/spec#Slice_types) for details.
-
-###### string
-
-A sequence of bytes. For example, `"What is 6 times 7?"` .
-
-###### string literal (interpreted)
-
-Interpreted string literals are character sequences between double quotes, as in "foo". Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted. See [details](https://go.dev/ref/spec#String_literals).
-
-###### string literal (raw)
-
-Raw string literals are character sequences between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters ('\r') inside raw string literals are discarded from the raw string value. See [details](https://go.dev/ref/spec#String_literals).
-
-###### taxonomic weight
-
-Defined in front matter and unique to each taxonomy, this [weight](#weight) determines the sort order of page collections contained within a [`Taxonomy`](#taxonomy-object) object. See [details](/content-management/taxonomies/#order-taxonomies).
-
-###### taxonomy
-
-A group of related [terms](#term) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue". See [details](/content-management/taxonomies/).
-
-###### taxonomy object
-
-A [map](#map) of [terms](#term) and the [weighted pages](#weighted-page) associated with each term.
-
-###### taxonomy page
-
-Content with the "taxonomy" [page kind](#page-kind). Typically a listing of [terms](#term) within a given [taxonomy](#taxonomy).
-
-###### template
-
-A file with [template actions](#template-action), located within the layouts directory of a project, theme, or module. See [details](/templates/).
-
-###### template action
-
-A data evaluation or control structure within a [template](#template), delimited by "{{" and "}}". See the [Go documentation](https://pkg.go.dev/text/template#hdr-Actions) for details.
-
-###### term
-
-A member of a [taxonomy](#taxonomy), used to classify content. See [details](/content-management/taxonomies/).
-
-###### term page
-
-Content with the "term" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and [section pages](#section-page) with a given [term](#term).
-
-###### theme
-
-A packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A theme may serve as the basis for a new site, or to augment an existing site. See also [module](#module).
-
-###### token
-
-An identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/time/format/#localization).
-
-###### type
-
-See [content type](#content-type).
-
-###### unmarshal
-
-To transform a serialized object into a data structure. For example, transforming a JSON file into a [map](#map) that you can access within a template. See [marshal](#marshal).
-
-###### variable
-
-A user-defined [identifier](#identifier) prepended with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo` and `$bar` are variables.
-
-###### walk
-
-To recursively traverse a nested data structure. For example, rendering a multilevel menu.
-
-###### weight
-
-Used to position an element within a collection sorted by weight. Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, and output formats.
-
-###### weighted page
-
-Contained within a [`Taxonomy`](#taxonomy-object) object, a weighted page is a [map](#map) with two elements: a `Page` object, and its [taxonomic weight](#taxonomic-weight) as defined in front matter. Access the elements using the `Page` and `Weight` keys.
-
-###### zero time
-
-The _zero time_ is January 1, 0001, 00:00:00 UTC. Formatted per [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) the _zero time_ is 0001-01-01T00:00:00-00:00.
--- /dev/null
+---
+title: Glossary of terms
+description: Terms commonly used throughout the documentation.
+categories: [getting started]
+keywords: [glossary]
+menu:
+ docs:
+ parent: getting-started
+ weight: 80
+weight: 80
+layout: single
+build:
+ render: always
+ list: always
+cascade:
+ build:
+ render: never
+ list: local
+---
+
+{{% glossary %}}
--- /dev/null
+---
+title: action
+---
+
+See [template action](g).
--- /dev/null
+---
+title: archetype
+---
+
+An archetype is a template for new content. See [details](/content-management/archetypes/).
--- /dev/null
+---
+title: argument
+---
+
+A [scalar](g), [array](g), [slice](g), [map](g), or [object](g) passed to a [function](g), [method](g), or [shortcode](g).
--- /dev/null
+---
+title: array
+---
+
+A numbered sequence of [elements](g). Unlike Go's [slice](g) data type, an array has a fixed length. Elements within an array can be [scalars](g), slices, [maps](g), pages, or other arrays. See the [Go documentation](https://go.dev/ref/spec#Array_types) for details.
--- /dev/null
+---
+title: bool
+---
+
+See [boolean](g).
--- /dev/null
+---
+title: boolean
+---
+
+A data type with two possible values, either `true` or `false`.
--- /dev/null
+---
+title: branch bundle
+---
+
+A directory that contains an `_index.md` file and zero or more [resources](g). Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page. See [details](/content-management/page-bundles/).
--- /dev/null
+---
+title: build
+---
+
+To generate a static site that includes HTML files and assets such as images, CSS, and JavaScript. The build process includes rendering and resource transformations.
--- /dev/null
+---
+title: bundle
+---
+
+See [page bundle](g).
--- /dev/null
+---
+title: cache
+---
+
+A software component that stores data so that future requests for the same data are faster.
--- /dev/null
+---
+title: chain
+---
+
+Within a template, to connect one or more [identifiers](g) with a dot. An identifier can represent a method, object, or field. For example, `.Site.Params.author.name` or `.Date.UTC.Hour`.
--- /dev/null
+---
+title: CJK
+---
+
+A collective term for the Chinese, Japanese, and Korean languages. See [details](https://en.wikipedia.org/wiki/CJK_characters).
--- /dev/null
+---
+title: CLI
+---
+
+Command line interface.
--- /dev/null
+---
+title: collection
+---
+
+An [array](g), [slice](g), or [map](g).
--- /dev/null
+---
+title: content adapter
+---
+
+A template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. See [details](/content-management/content-adapters/).
--- /dev/null
+---
+title: content format
+---
+
+A markup language for creating content. Typically Markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/).
--- /dev/null
+---
+title: content type
+---
+
+A classification of content inferred from the top-level directory name or the `type` set in [front matter](g). Pages in the root of the `content` directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](g). See [details](/content-management/types/)
--- /dev/null
+---
+title: content view
+---
+
+A template called with the `.Page.Render` method. See [details](/templates/content-view/).
--- /dev/null
+---
+title: context
+---
+
+Represented by a dot "." within a [template action](g), context is the current location in a data structure. For example, while iterating over a [collection](g) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#context).
--- /dev/null
+---
+title: default sort order
+---
+
+The default sort order for page collections. Hugo sorts by [weight](g), then by date (descending), then by link title, and then by file path.
--- /dev/null
+---
+title: element
+---
+
+A member of a slice or array.
--- /dev/null
+---
+title: environment
+---
+
+Typically one of `development`, `staging`, or `production`, each environment may exhibit different behavior depending on configuration and template logic. For example, in a production environment you might minify and fingerprint CSS, but that probably doesn't make sense in a development environment.
+
+When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your site with the `hugo` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag or the `HUGO_ENVIRONMENT` environment variable.
+
+To determine the current environment within a template, use the [`hugo.Environment`] function.
+
+[`hugo.Environment`]: /functions/hugo/environment/
--- /dev/null
+---
+title: field
+---
+
+A predefined key-value pair in front matter such as `date` or `title`. See also [parameter](g).
--- /dev/null
+---
+title: flag
+---
+
+An option passed to a command-line program, beginning with one or two hyphens. See [details](/commands/hugo/).
--- /dev/null
+---
+title: float
+alias: true
+---
+
+See [floating point](g).
--- /dev/null
+---
+title: floating point
+---
+
+A numeric data type with a fractional component. For example, `3.14159`.
--- /dev/null
+---
+title: fragment
+---
+
+The final segment of a URL, beginning with a hash (`#`) mark, that references an `id` attribute of an HTML element on the page.
--- /dev/null
+---
+title: front matter
+---
+
+Metadata at the beginning of each content page, separated from the content by format-specific delimiters. See [details](/content-management/front-matter/).
--- /dev/null
+---
+title: function
+---
+
+Used within a [template action](g), a function takes one or more [arguments](g) and returns a value. Unlike [methods](g), functions are not associated with an [object](g). See [details](/functions/).
--- /dev/null
+---
+title: global resource
+---
+
+A file within the `assets` directory, or within any directory [mounted](/hugo-modules/configuration/#module-configuration-mounts) to the `assets` directory. Capture one or more global resources using the [`resources.Get`], [`resources.GetMatch`], [`resources.Match`], or [`resources.ByType`] functions.
+
+[`resources.Get`]: /functions/resources/get/
+[`resources.GetMatch`]: /functions/resources/getmatch/
+[`resources.Match`]: /functions/resources/match/
+[`resources.ByType`]: /functions/resources/byType/
--- /dev/null
+---
+title: headless bundle
+---
+
+An unpublished leaf or branch bundle whose content and resources you can include in other pages. See [build options](/content-management/build-options/).
--- /dev/null
+---
+title: identifier
+---
+
+A string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores.
--- /dev/null
+---
+title: int
+---
+
+See [integer](g).
--- /dev/null
+---
+title: integer
+---
+
+A numeric data type without a fractional component. For example, `42`.
--- /dev/null
+---
+title: internationalization
+---
+
+Software design and development efforts that enable [localization](g). See the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated i18n.
--- /dev/null
+---
+title: interpreted string literal
+---
+
+Interpreted string literals are character sequences between double quotes, as in "foo". Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted. See [details](https://go.dev/ref/spec#String_literals).
--- /dev/null
+---
+title: interval
+---
+
+An [interval](https://en.wikipedia.org/wiki/Interval_(mathematics)) is a range of numbers between two endpoints: closed, open, or half-open.
+
+- A _closed_ interval, denoted by brackets, includes its endpoints. For example, [0, 1] is the interval where `0 <= x <= 1`.
+
+- An _open_ interval, denoted by parentheses, excludes its endpoints. For example, (0, 1) is the interval where `0 < x < 1`.
+
+- A _half-open_ interval includes only one of its endpoints. For example, (0, 1] is the _left-open_ interval where `0 < x <= 1`, while [0, 1) is the _right-open_ interval where `0 <= x < 1`.
--- /dev/null
+---
+title: kind
+---
+
+See [page kind](g).
--- /dev/null
+---
+title: layout
+---
+
+See [template](g).
--- /dev/null
+---
+title: leaf bundle
+---
+
+A directory that contains an index.md file and zero or more [resources](g). Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. See [details](/content-management/page-bundles/).
--- /dev/null
+---
+title: lexer
+---
+
+A software component that identifies keywords, identifiers, operators, numbers, and other basic building blocks of a programming language within the input text.
--- /dev/null
+---
+title: list page
+---
+
+Any [page kind](g) that receives a page [collection](g) in [context](g). This includes the home page, [section pages](g), [taxonomy pages](g), and [term pages](g).
--- /dev/null
+---
+title: list template
+---
+
+Any template that renders a [list page](g). This includes [home](/templates/types/#home), [section](/templates/types/#section), [taxonomy](/templates/types/#taxonomy), and [term](/templates/types/#term) templates.
--- /dev/null
+---
+title: localization
+---
+
+Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n.
--- /dev/null
+---
+title: logical path
+---
+
+{{< new-in 0.123.0 >}}
+
+A page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. Starting with a file path relative to the `content` directory, Hugo determines the logical path by stripping the file extension and language identifier, converting to lower case, then replacing spaces with hyphens. See [examples](/methods/page/path/#examples).
--- /dev/null
+---
+title: map
+---
+
+An unordered group of elements, each indexed by a unique key. See the [Go documentation](https://go.dev/ref/spec#Map_types) for details.
--- /dev/null
+---
+title: Markdown attribute
+---
+
+A list of attributes, containing one or more key-value pairs, separated by spaces or commas, and wrapped by braces. Apply Markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark).
--- /dev/null
+---
+title: marshal
+---
+
+To transform a data structure into a serialized object. For example, transforming a [map](g) into a JSON string. See [unmarshal](g).
--- /dev/null
+---
+title: method
+---
+
+Used within a [template action](g) and associated with an [object](g), a method takes zero or more [arguments](g) and either returns a value or performs an action. For example, `.IsHome` is a method on the `.Page` object which returns `true` if the current page is the home page. See also [function](g).
--- /dev/null
+---
+title: module
+---
+
+Like a [theme](g), a module is a packaged combination of [archetypes](g), assets, content, data, [templates](g), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. See [details](/hugo-modules/).
--- /dev/null
+---
+title: node
+---
+
+A class of [page kinds](g) including `home`, `section`, `taxonomy`, and `term`.
--- /dev/null
+---
+title: noop
+---
+
+An abbreviated form of "no operation", a _noop_ is a statement that does nothing.
--- /dev/null
+---
+title: object
+---
+
+A data structure with or without associated [methods](g).
--- /dev/null
+---
+title: ordered taxonomy
+---
+
+Created by invoking the [`Alphabetical`] or [`ByCount`] method on a [`Taxonomy`](g) object, which is a [map](g), an _ordered taxonomy_ is a [slice](g), where each element is an object that contains the [term](g) and a slice of its [weighted pages](g).
+
+[`Alphabetical`]: /methods/taxonomy/alphabetical/
+[`ByCount`]: /methods/taxonomy/bycount/
--- /dev/null
+---
+title: output format
+---
+
+Hugo generates one or more files per page when building a site. For example, when rendering home, [section](g), [taxonomy](g), and [term](g) pages, Hugo generates an HTML file and an RSS file. Both HTML and RSS are built-in _output formats_. Create multiple output formats, and control generation based on [page kind](g), or by enabling one or more output formats for one or more pages. See [details].
+
+[details]: /templates/output-formats/
--- /dev/null
+---
+title: page bundle
+---
+
+A directory that encapsulates both content and associated [resources](g). There are two types of page bundles: [leaf bundles](g) and [branch bundles](g). See [details](/content-management/page-bundles/).
--- /dev/null
+---
+title: page collection
+---
+
+A slice of `Page` objects.
--- /dev/null
+---
+title: page kind
+---
+
+A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [details](/methods/page/kind/).
+
+Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` page kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
--- /dev/null
+---
+title: page resource
+---
+
+A file within a [page bundle](g). Capture one or more page resources using any of the [`Resources`] methods on a `Page` object.
+
+[`Resources`]: /methods/page/resources/#methods
--- /dev/null
+---
+title: pager
+---
+
+Created during [pagination](g), a pager contains a subset of a list page and navigation links to other pagers.
--- /dev/null
+---
+title: paginate
+---
+
+To split a list page into two or more subsets.
--- /dev/null
+---
+title: pagination
+---
+
+The process of [paginating](g) a list page. See [details](/templates/pagination/).
--- /dev/null
+---
+title: paginator
+---
+
+A collection of [pagers](g).
--- /dev/null
+---
+title: parameter
+---
+
+Typically, a user-defined key-value pair at the site or page level, but may also refer to a configuration setting or an [argument](g). See also [field](g).
--- /dev/null
+---
+title: partial
+---
+
+A [template](g) called from any other template including [shortcodes](g), [render hooks](g), and other partials. A partial either renders something or returns something. A partial can also call itself, for example, to [walk](g) a data structure.
--- /dev/null
+---
+title: permalink
+---
+
+The absolute URL of a published resource or a rendered page, including scheme and host.
--- /dev/null
+---
+title: pipe
+---
+
+See [pipeline](g).
--- /dev/null
+---
+title: pipeline
+---
+
+Within a [template action](g), a pipeline is a possibly chained sequence of values, [function](g) calls, or [method](g) calls. Functions and methods in the pipeline may take multiple [arguments](g).
+
+A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. See the [Go documentation](https://pkg.go.dev/text/template#hdr-Pipelines) for details.
--- /dev/null
+---
+title: publish
+---
+
+See [build](g).
--- /dev/null
+---
+title: raw string literal
+---
+
+Raw string literals are character sequences between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters (`\r`) inside raw string literals are discarded from the raw string value. See [details](https://go.dev/ref/spec#String_literals).
--- /dev/null
+---
+title: regular page
+---
+
+Content with the "page" [page kind](g). See also [section page](g).
--- /dev/null
+---
+title: relative permalink
+---
+
+The host-relative URL of a published resource or a rendered page.
--- /dev/null
+---
+title: remote resource
+---
+
+A file on a remote server, accessible via HTTP or HTTPS with the [`resources.GetRemote`](/functions/resources/getremote) function.
--- /dev/null
+---
+title: render hook
+---
+
+A [template](g) that overrides standard Markdown rendering. See [details](/render-hooks).
--- /dev/null
+---
+title: resource type
+---
+
+The main type of a resource's [media type]. Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `video`, etc. Retrieve the resource type using the [`ResourceType`] method on a `Resource` object.
+
+[media type]: /methods/resource/mediatype/
+[`ResourceType`]: /methods/resource/resourcetype/
--- /dev/null
+---
+title: resource
+---
+
+Any file consumed by the build process to augment or generate content, structure, behavior, or presentation. For example: images, videos, content snippets, CSS, Sass, JavaScript, and data.
+
+Hugo supports three types of resources: [global resources](g), [page resources](g), and [remote resources](g).
--- /dev/null
+---
+title: scalar
+---
+
+A _scalar_ is a single value, one of [string](g), [integer](g), [floating point](g), or [boolean](g).
--- /dev/null
+---
+title: scratch pad
+---
+
+Conceptually, a [map](g) with [methods](g) to set, get, update, and delete values. Attach the data structure to a `Page` or `Site` object using the [`Store`] method, or create a locally scoped scratch pad using the [`newScratch`] function.
+
+[`Store`]: /methods/page/store/
+[`newScratch`]: /functions/collections/newscratch/
--- /dev/null
+---
+title: section page
+---
+
+Content with the "section" [page kind](g). Typically a listing of [regular pages](g) and/or other section pages within the current [section](g).
--- /dev/null
+---
+title: section
+---
+
+A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](g). Section templates receive one or more page [collections](g) in [context](g). See [details](/content-management/sections/).
--- /dev/null
+---
+title: shortcode
+---
+
+A [template](g) called from within Markdown, taking zero or more [arguments](g). See [details](/content-management/shortcodes/).
--- /dev/null
+---
+title: slice
+---
+
+A numbered sequence of elements. Unlike Go's [array](g) data type, slices are dynamically sized. [Elements](g) within a slice can be [scalars](g), [arrays](g), [maps](g), pages, or other slices. See the [Go documentation](https://go.dev/ref/spec#Slice_types) for details.
--- /dev/null
+---
+title: string
+---
+
+A sequence of bytes. For example, `"What is 6 times 7?"`.
--- /dev/null
+---
+title: taxonomic weight
+---
+
+Defined in front matter and unique to each taxonomy, this [weight](g) determines the sort order of page collections contained within a [`Taxonomy`](g) object. See [details](/content-management/taxonomies/#order-taxonomies).
--- /dev/null
+---
+title: taxonomy object
+---
+
+A [map](g) of [terms](g) and the [weighted pages](g) associated with each term.
--- /dev/null
+---
+title: taxonomy page
+---
+
+Content with the "taxonomy" [page kind](g). Typically a listing of [terms](g) within a given [taxonomy](g).
--- /dev/null
+---
+title: taxonomy
+---
+
+A group of related [terms](g) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue". See [details](/content-management/taxonomies/).
--- /dev/null
+---
+title: template action
+---
+
+A data evaluation or control structure within a [template](g), delimited by "{{" and "}}". See the [Go documentation](https://pkg.go.dev/text/template#hdr-Actions) for details.
--- /dev/null
+---
+title: template
+---
+
+A file with [template actions](g), located within the `layouts` directory of a project, theme, or module. See [details](/templates/).
--- /dev/null
+---
+title: term page
+---
+
+Content with the "term" [page kind](g). Typically a listing of [regular pages](g) and [section pages](g) with a given [term](g).
--- /dev/null
+---
+title: term
+---
+
+A member of a [taxonomy](g), used to classify content. See [details](/content-management/taxonomies/).
--- /dev/null
+---
+title: theme
+---
+
+A packaged combination of [archetypes](g), assets, content, data, [templates](g), translation tables, static files, or configuration settings. A theme may serve as the basis for a new site, or to augment an existing site. See also [module](g).
--- /dev/null
+---
+title: token
+---
+
+An identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/time/format/#localization).
--- /dev/null
+---
+title: type
+---
+
+See [content type](g).
--- /dev/null
+---
+title: unmarshal
+---
+
+To transform a serialized object into a data structure. For example, transforming a JSON file into a [map](g) that you can access within a template. See [marshal](g).
--- /dev/null
+---
+title: variable
+---
+
+A user-defined [identifier](g) prepended with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](g). For example, `$foo` and `$bar` are variables.
--- /dev/null
+---
+title: walk
+---
+
+To recursively traverse a nested data structure. For example, rendering a multilevel menu.
--- /dev/null
+---
+title: weight
+---
+
+Used to position an element within a collection sorted by weight. Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, and output formats.
--- /dev/null
+---
+title: weighted page
+---
+
+Contained within a [`Taxonomy`](g) object, a weighted page is a [map](g) with two elements: a `Page` object, and its [taxonomic weight](g) as defined in front matter. Access the elements using the `Page` and `Weight` keys.
--- /dev/null
+---
+title: zero time
+---
+
+The _zero time_ is January 1, 0001, 00:00:00 UTC. Formatted per [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) the _zero time_ is 0001-01-01T00:00:00-00:00.
In this tutorial you will:
1. Create a site
-2. Add content
-3. Configure the site
-4. Publish the site
+1. Add content
+1. Configure the site
+1. Publish the site
## Prerequisites
Make the following changes:
1. Set the `baseURL` for your production site. This value must begin with the protocol and end with a slash, as shown above.
-
-2. Set the `languageCode` to your language and region.
-
-3. Set the `title` for your production site.
+1. Set the `languageCode` to your language and region.
+1. Set the `title` for your production site.
Start Hugo's development server to see your changes, remembering to include draft content.
{{% note %}}
Hugo does not clear the `public` directory before building your site. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build.
-Depending on your needs, you may wish to manually clear the contents of the public directory before every build.
+Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build.
{{% /note %}}
## Draft, future, and expired content
{{< new-in 0.123.0 >}}
{{% note %}}
-Hugo publishes descendants of draft, future, and expired [node] pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
+Hugo publishes descendants of draft, future, and expired [node](g) pages. To prevent publication of these descendants, use the [`cascade`] front matter field to cascade [build options] to the descendant pages.
[build options]: /content-management/build-options/
[`cascade`]: /content-management/front-matter/#cascade-field
-[node]: /getting-started/glossary/#node
{{% /note %}}
You can override the default behavior when running `hugo` or `hugo server` with command line flags:
## Deploy your site
{{% note %}}
-As noted above, Hugo does not clear the public directory before building your site. Manually clear the contents of the public directory before each build to remove draft, expired, and future content.
+As noted above, Hugo does not clear the `public` directory before building your site. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content.
{{% /note %}}
When you are ready to deploy your site, run:
hugo
```
-This builds your site, publishing the files to the public directory. The directory structure will look something like this:
+This builds your site, publishing the files to the `public` directory. The directory structure will look something like this:
```text
public/
Learn more in the [hosting and deployment] section.
-[^1]: The Git repository contains the entire project directory, typically excluding the public directory because the site is built _after_ the push.
+[^1]: The Git repository contains the entire project directory, typically excluding the `public` directory because the site is built _after_ the push.
[`--destination`]: /commands/hugo/#options
[`hugo server`]: /commands/hugo_server/
HOST=my-server.com
DIR=my/directory/to/topologix.fr/ # the directory where your website files should go
-hugo && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} # this will delete everything on the server that's not in the local public folder
+hugo && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} # this will delete everything on the server that's not in the local public directory
exit 0
```
You can set up a Hugo site on 21YunBox in two quick steps:
1. Create a new web service on 21YunBox, and give 21YunBox permission to access your GitHub or Gitee repo.
-2. Use the following values during creation:
+1. Use the following values during creation:
| Field | Value |
| --------------------- | ------------------------------------------------ |
Please complete the following tasks before continuing:
1. [Create an AWS account]
-2. [Install Git]
-3. [Create a Hugo site] and test it locally with `hugo server`
-4. Commit the changes to your local repository
-5. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account
+1. [Install Git]
+1. [Create a Hugo site] and test it locally with `hugo server`
+1. Commit the changes to your local repository
+1. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account
[Bitbucket]: https://bitbucket.org/product
[Create a Hugo site]: /getting-started/quick-start/
Please complete the following tasks before continuing:
1. [Create a GitHub account]
-2. [Install Git]
-3. [Create a Hugo site] and test it locally with `hugo server`.
+1. [Install Git]
+1. [Create a Hugo site] and test it locally with `hugo server`.
[Create a GitHub account]: https://github.com/signup
[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
build:
runs-on: ubuntu-latest
env:
- HUGO_VERSION: 0.137.1
+ HUGO_VERSION: 0.141.0
steps:
- name: Install Hugo CLI
run: |
Please complete the following tasks before continuing:
1. [Create a Netlify account]
-2. [Install Git]
-3. [Create a Hugo site] and test it locally with `hugo server`
-4. Commit the changes to your local repository
-5. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account
+1. [Install Git]
+1. [Create a Hugo site] and test it locally with `hugo server`
+1. Commit the changes to your local repository
+1. Push the local repository to your [GitHub], [GitLab], or [Bitbucket] account
[Bitbucket]: https://bitbucket.org/product
[Create a Hugo site]: /getting-started/quick-start/
{{< code file=netlify.toml >}}
[build.environment]
-HUGO_VERSION = "0.137.1"
+HUGO_VERSION = "0.141.0"
+NODE_VERSION = "22"
TZ = "America/Los_Angeles"
[build]
{{< code file=netlify.toml >}}
[build.environment]
-HUGO_VERSION = "0.137.1"
-DART_SASS_VERSION = "1.80.6"
+HUGO_VERSION = "0.141.0"
+DART_SASS_VERSION = "1.83.4"
+NODE_VERSION = "22"
TZ = "America/Los_Angeles"
[build]
* Amazon S3: [create a bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) and [host a static website](https://docs.aws.amazon.com/AmazonS3/latest/userguide/WebsiteHosting.html)
* Microsoft Azure: [create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal) and [host a static website](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website)
-
## Configuring your first deployment
In the configuration file for your site, add a `[deployment]` section
See `hugo help deploy` or [the deploy command-line documentation][commandline] for more command-line options.
-
### How the file list works
The first thing `hugo deploy` does is create file lists for local and remote by
* If the configuration specifies an `exclude` pattern, files matching the
pattern are skipped.
-
{{% note %}}
When creating the local file list, a few additional skips apply: first, Hugo always
skips files named `.DS_Store`.
traversed if it exists.
{{% /note %}}
-
-
### How the local and remote file lists are compared
In the second step, Hugo compares the two file lists to figure out what changes
# Azure Blob Storage; see https://gocloud.dev/howto/blob/#azure
#URL = "azblob://$web"
-# You can use a "prefix=" query parameter to target a subfolder of the bucket:
-#URL = "gs://<Bucket Name>?prefix=a/subfolder/"
+# You can use a "prefix=" query parameter to target a subdirectory of the bucket:
+#URL = "gs://<Bucket Name>?prefix=a/subdirectory/"
# If you are using a CloudFront CDN, deploy will invalidate the cache as needed.
#cloudFrontDistributionID = "<FILL ME IN>"
Some example projects:
-- [https://github.com/bep/docuapi](https://github.com/bep/docuapi) is a theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo’s folder structure. It even shows a JS Bundler implementation in regular Go templates.
+- [https://github.com/bep/docuapi](https://github.com/bep/docuapi) is a theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo's directory structure. It even shows a JS Bundler implementation in regular Go templates.
- [https://github.com/bep/my-modular-site](https://github.com/bep/my-modular-site) is a very simple site used for testing.
{{< /code-toggle >}}
path
-: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your themes folder.
+: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your `themes` directory.
ignoreConfig
: If enabled, any module configuration file, e.g. `hugo.toml`, will not be loaded. Note that this will also stop the loading of any transitive module dependencies.
: Set to `true` to disable the module while keeping any version info in the `go.*` files.
noMounts
-: Do not mount any folder in this import.
+: Do not mount any directory in this import.
noVendor
: Never vendor this import (only allowed in main project).
: (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative.
target
-: (`string`) Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`.
+: (`string`) Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component directories: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`.
disableWatch
{{< new-in 0.128.0 >}}
* For `i18n` and `data` files, Hugo merges deeply using the translation ID and data key inside the files.
* For `static`, `layouts` (templates), and `archetypes` files, these are merged on file level. So the left-most file will be chosen.
-The name used in the `theme` definition above must match a folder in `/your-site/themes`, e.g. `/your-site/themes/my-shortcodes`. There are plans to improve on this and get a URL scheme so this can be resolved automatically.
+The name used in the `theme` definition above must match a directory in `/your-site/themes`, e.g. `/your-site/themes/my-shortcodes`. There are plans to improve on this and get a URL scheme so this can be resolved automatically.
Also note that a component that is part of a theme can have its own configuration file, e.g. `hugo.toml`. There are currently some restrictions to what a theme component can configure:
The easiest way to use a Module for a theme is to import it in the configuration.
1. Initialize the hugo module system: `hugo mod init github.com/<your_user>/<your_project>`
-2. Import the theme:
+1. Import the theme:
{{< code-toggle file=hugo >}}
[module]
## Vendor your modules
-`hugo mod vendor` will write all the module dependencies to a `_vendor` folder, which will then be used for all subsequent builds.
+`hugo mod vendor` will write all the module dependencies to a `_vendor` directory, which will then be used for all subsequent builds.
Note that:
* You can run `hugo mod vendor` on any level in the module tree.
-* Vendoring will not store modules stored in your `themes` folder.
+* Vendoring will not store modules stored in your `themes` directory.
* Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the [Glob](https://github.com/gobwas/glob) pattern given.
Also see the [CLI Doc](/commands/hugo_mod_vendor/).
This is about global and remote resources.
global resource
-: A file within the assets directory, or within any directory [mounted] to the assets directory.
+: A file within the `assets` directory, or within any directory [mounted] to the `assets` directory.
remote resource
: A file on a remote server, accessible via HTTP or HTTPS.
## Asset directory
-Asset files must be stored in the asset directory. This is `/assets` by default, but can be configured via the configuration file's `assetDir` key.
+Asset files must be stored in the asset directory. This is `assets` by default, but can be configured via the configuration file's `assetDir` key.
## Asset publishing
weight: 60
---
-
See [JS functions](/functions/js/).
There are currently two limitations to this:
1. This only works in `*.html` templates (i.e. templates that produces HTML files).
-2. You cannot manipulate the values returned from the resource's methods. E.g. the `upper` in this example will not work as expected:
+1. You cannot manipulate the values returned from the resource's methods. E.g. the `upper` in this example will not work as expected:
```go-html-template
{{ $css := resources.Get "css/main.css" }}
There are several ways to set up CSS purging with PostCSS in Hugo. If you have a simple project, you should consider going the simpler route and drop the use of `resources.PostProcess` and just extract keywords from the templates. See the [Tailwind documentation](https://tailwindcss.com/docs/controlling-file-size/#app) for some examples.
{{% /note %}}
-The below configuration will write a `hugo_stats.json` file to the project root as part of the build. If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory).
+The below configuration will write a `hugo_stats.json` file to the project root as part of the build. If you're only using this for the production build, you should consider placing it below [`config/production`](/getting-started/configuration/#configuration-directory).
{{< code-toggle file=hugo >}}
[build.buildStats]
: The value e.g. set with `hugo -e production` (defaults to `production` for `hugo` and `development` for `hugo server`).
HUGO_PUBLISHDIR
-: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this folder from PostCSS when running the server, you could run the server with one of these flags:
+: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this directory from PostCSS when running the server, you could run the server with one of these flags:
```sh
hugo server --renderToDisk
For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries.
-[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository.
+[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository.
#### GitHub Pages
```yaml
variables:
- HUGO_VERSION: 0.137.1
- DART_SASS_VERSION: 1.80.6
+ HUGO_VERSION: 0.141.0
+ DART_SASS_VERSION: 1.83.4
GIT_DEPTH: 0
GIT_STRATEGY: clone
GIT_SUBMODULE_STRATEGY: recursive
```toml
[build.environment]
-HUGO_VERSION = "0.137.1"
-DART_SASS_VERSION = "1.80.6"
+HUGO_VERSION = "0.141.0"
+DART_SASS_VERSION = "1.83.4"
+NODE_VERSION = "22"
TZ = "America/Los_Angeles"
[build]
www-apps/hugo extended
```
-2. Install using the Paludis package manager:
-
+1. Install using the Paludis package manager:
```sh
cave resolve -x repository/heirecka
www-apps/hugo extended
```
-2. Build using the Portage package manager:
+1. Build using the Portage package manager:
```sh
sudo emerge www-apps/hugo
[`URL`]: /methods/menu-entry/url/
{{% /note %}}
-
Consider this content structure:
```text
With this template code:
-
{{< code file=layouts/partials/menu.html >}}
<ul>
{{ range .Site.Menus.main }}
With this template:
-
```go-html-template
<ul>
{{ range .Site.Menus.main }}
For menu entries associated with a page, the `URL` method returns the page's [`RelPermalink`], otherwise it returns the entry's `url` property.
-
```go-html-template
<ul>
{{ range .Site.Menus.main }}
signatures: [MENU.ByWeight]
---
-The `ByWeight` method returns the given menu with its entries sorted by [`weight`], then by `name`, then by `identifier`. This is the default sort order.
-
-[`weight`]: /getting-started/glossary/#weight
+The `ByWeight` method returns the given menu with its entries sorted by [`weight`](g), then by `name`, then by `identifier`. This is the default sort order.
Consider this menu definition:
signatures: [PAGE.AlternativeOutputFormats]
---
-{{% include "methods/page/_common/output-format-definition.md" %}}
+{{% glossary-term "output format" %}}
The `AlternativeOutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, excluding the current output format, each representing one of the output formats enabled for the given page.. See [details](/templates/output-formats/).
signatures: [PAGE.BundleType]
---
-A page bundle is a directory that encapsulates both content and associated [resources]. There are two types of page bundles: [leaf bundles] and [branch bundles]. See [details](/content-management/page-bundles/).
+A page bundle is a directory that encapsulates both content and associated [resources](g). There are two types of page bundles: [leaf bundles](g) and [branch bundles](g). See [details](/content-management/page-bundles/).
The `BundleType` method on a `Page` object returns `branch` for branch bundles, `leaf` for leaf bundles, and an empty string if the page is not a page bundle.
```go-html-template
{{ .BundleType }}
```
-
-[resources]: /getting-started/glossary/#resource
-[leaf bundles]: /getting-started/glossary/#leaf-bundle
-[branch bundles]: /getting-started/glossary/#branch-bundle
{{% include "methods/page/_common/definition-of-section.md" %}}
{{% note %}}
-The current section of a [section] page, [taxonomy] page, [term] page, or the home page, is itself.
-
-[section]: /getting-started/glossary/#section
-[taxonomy]: /getting-started/glossary/#taxonomy
-[term]: /getting-started/glossary/#term
+The current section of a [section page](g), [taxonomy page](g), [term page](g), or the home page, is itself.
{{% /note %}}
Consider this content structure:
toc: true
---
-The `Data` method on a `Page` object returns a unique data object for each [page kind].
-
-[page kind]: /getting-started/glossary/#page-kind
+The `Data` method on a `Page` object returns a unique data object for each [page kind](g).
{{% note %}}
-The `Data` method is only useful within [taxonomy] and [term] templates.
+The `Data` method is only useful within [taxonomy](g) and [term](g) templates.
Themes that are not actively maintained may still use `.Data.Pages` in list templates. Although that syntax remains functional, use one of these methods instead: [`Pages`], [`RegularPages`], or [`RegularPagesRecursive`]
[`Pages`]: /methods/page/pages/
[`RegularPages`]: /methods/page/regularpages/
[`RegularPagesRecursive`]: /methods/page/regularpagesrecursive/
-[term]: /getting-started/glossary/#term
-[taxonomy]: /getting-started/glossary/#taxonomy
{{% /note %}}
The examples that follow are based on this site configuration:
```
Terms
-: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages] associated with each term.
+: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages](g) associated with each term.
```go-html-template
{{ $taxonomyObject := .Data.Terms }}
[taxonomy templates]: /templates/types/#taxonomy
[term templates]: /templates/types/#term
-[weighted pages]: /getting-started/glossary/#weighted-page
toc: true
---
-By default, not all pages are backed by a file, including top level [section] pages, [taxonomy] pages, and [term] pages. By definition, you cannot retrieve file information when the file does not exist.
+By default, not all pages are backed by a file, including top level [section pages](g), [taxonomy pages](g), and [term pages](g). By definition, you cannot retrieve file information when the file does not exist.
-To back one of the pages above with a file, create an _index.md file in the corresponding directory. For example:
+To back one of the pages above with a file, create an `_index.md` file in the corresponding directory. For example:
```text
content/
{{ .ContentBaseName }}
{{ end }}
```
-
-[section]: /getting-started/glossary/#section
-[taxonomy]: /getting-started/glossary/#taxonomy
-[term]: /getting-started/glossary/#term
toc: true
---
-{{< new-in 0.111.0 >}}
-
-In a URL, whether absolute or relative, the [fragment] links to an `id` attribute of an HTML element on the page.
+In a URL, whether absolute or relative, the [fragment](g) links to an `id` attribute of an HTML element on the page.
```text
/articles/article-1#section-2
path fragment
```
-Hugo assigns an `id` attribute to each Markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [Markdown attribute] as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
+Hugo assigns an `id` attribute to each Markdown [ATX] and [setext] heading within the page content. You can override the `id` with a [Markdown attribute](g) as needed. This creates the relationship between an entry in the [table of contents] (TOC) and a heading on the page.
-Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking] the `Fragments.Map` data structure.
+Use the `Fragments` method on a `Page` object to create a table of contents with the `Fragments.ToHTML` method, or by [walking](g) the `Fragments.Map` data structure.
## Methods
<pre>{{ debug.Dump .Fragments.Headings }}</pre>
```
-
HeadingsMap
: (`map`) A nested map of all headings on the page. Each map contains the following keys: `ID`, `Level`, `Title` and `Headings`. To inspect the data structure:
```
Identifiers.Contains ID
-: (`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook].
+: (`bool`) Reports whether one or more headings on the page has the given `id` attribute, useful for validating fragments within a link [render hook](g).
```go-html-template
{{ .Fragments.Identifiers.Contains "section-2" }} → true
{{% /note %}}
[atx]: https://spec.commonmark.org/0.30/#atx-headings
-[fragment]: /getting-started/glossary/#fragment
-[markdown attribute]: /getting-started/glossary/#markdown-attribute
[setext]: https://spec.commonmark.org/0.30/#setext-headings
[table of contents]: /methods/page/tableofcontents/
-[walking]: /getting-started/glossary/#walk
[`tableofcontents`]: /methods/page/tableofcontents/
-[render hook]: /getting-started/glossary/#render-hook
[details]: /methods/site/getpage/
-When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the content directory.
+When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the `content` directory.
If Hugo cannot resolve the path to a page, the method returns nil. If the path is ambiguous, Hugo throws an error and fails the build.
## Understanding context
-Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
+Inside of the `with` block, the [context](g) (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
```go-html-template
{{ with .Site.GetPage "/auctions" }}
Gaining a thorough understanding of context is critical for anyone writing template code.
{{% /note %}}
-[context]: /getting-started/glossary/#context
[`with`]: /functions/go-template/with/
[`else`]: /functions/go-template/else/
## Understanding context
-Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
+Inside of the `with` block, the [context](g) (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
```go-html-template
{{ with .Site.GetPage "/auctions" }}
Gaining a thorough understanding of context is critical for anyone writing template code.
{{% /note %}}
-[context]: /getting-started/glossary/#context
[`with`]: /functions/go-template/with/
[`else`]: /functions/go-template/else/
## Understanding context
-Inside of the `with` block, the [context] (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
+Inside of the `with` block, the [context](g) (the dot) is the section `Page` object, not the `Page` object passed into the template. If we were to use this syntax:
```go-html-template
{{ with .Site.GetPage "/auctions" }}
Gaining a thorough understanding of context is critical for anyone writing template code.
{{% /note %}}
-[context]: /getting-started/glossary/#context
[`with`]: /functions/go-template/with/
[`else`]: /functions/go-template/else/
signatures: [PAGE.IsHome]
---
-The `IsHome` method on a `Page` object returns `true` if the [page kind] is `home`.
+The `IsHome` method on a `Page` object returns `true` if the [page kind](g) is `home`.
```text
content/
```go-html-template
{{ .IsHome }}
```
-
-[page kind]: /getting-started/glossary/#page-kind
signatures: [PAGE.IsNode]
---
-The `IsNode` method on a `Page` object returns `true` if the [page kind] is `home`, `section`, `taxonomy`, or `term`.
+The `IsNode` method on a `Page` object returns `true` if the [page kind](g) is `home`, `section`, `taxonomy`, or `term`.
It returns `false` is the page kind is `page`.
```go-html-template
{{ .IsNode }}
```
-[page kind]: /getting-started/glossary/#page-kind
signatures: [PAGE.IsPage]
---
-The `IsPage` method on a `Page` object returns `true` if the [page kind] is `page`.
+The `IsPage` method on a `Page` object returns `true` if the [page kind](g) is `page`.
```text
content/
```go-html-template
{{ .IsPage }}
```
-
-[page kind]: /getting-started/glossary/#page-kind
signatures: [PAGE.IsSection]
---
-The `IsSection` method on a `Page` object returns `true` if the [page kind] is `section`.
+The `IsSection` method on a `Page` object returns `true` if the [page kind](g) is `section`.
```text
content/
```go-html-template
{{ .IsSection }}
```
-
-[page kind]: /getting-started/glossary/#page-kind
└── _index.md
```
-When rendering content/en/books/book-1.md:
+When rendering `content/en/books/book-1.md`:
```go-html-template
{{ .IsTranslated }} → true
```
-When rendering content/en/books/book-2.md:
+When rendering `content/en/books/book-2.md`:
```go-html-template
{{ .IsTranslated }} → false
signatures: [PAGE.Kind]
---
-The [page kind] is one of `home`, `page`, `section`, `taxonomy`, or `term`.
+The [page kind](g) is one of `home`, `page`, `section`, `taxonomy`, or `term`.
```text
content/
```go-html-template
{{ .Kind }}
```
-
-[page kind]: /getting-started/glossary/#page-kind
toc: true
---
-{{% include "methods/page/_common/output-format-definition.md" %}}
+{{% glossary-term "output format" %}}
The `OutputFormats` method on a `Page` object returns a slice of `OutputFormat` objects, each representing one of the output formats enabled for the given page. See [details](/templates/output-formats/).
signatures: [PAGE.Page]
---
-This is a convenience method, useful within partial templates that are called from both [shortcodes] and page templates.
+This is a convenience method, useful within partial templates that are called from both [shortcodes](g) and page templates.
{{< code file=layouts/shortcodes/foo.html >}}
{{ partial "my-partial.html" . }}
{{< /code >}}
-When the shortcode calls the partial, it passes the current [context] (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`.
+When the shortcode calls the partial, it passes the current [context](g) (the dot). The context includes identifiers such as `Page`, `Params`, `Inner`, and `Name`.
{{< code file=layouts/_default/single.html >}}
{{ partial "my-partial.html" . }}
But don't.
{{% /note %}}
-
-
-[context]: getting-started/glossary/#context
-[shortcodes]: /getting-started/glossary/#shortcode
signatures: [PAGE.Pages]
---
-The `Pages` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context].
+The `Pages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g).
Range through the page collection in your template:
lessons/lesson-2/resources/task-list.md
lessons/lesson-2/resources/worksheet.md
-In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an _index.md file. Its contents are part of the lesson-2 section.
+In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section.
{{% note %}}
When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details].
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
```
-
-[collection]: /getting-started/glossary/#collection
-[context]: /getting-started/glossary/#context
-[page kinds]: /getting-started/glossary/#page-kind
-[section]: /getting-started/glossary/#section
In the example above, we:
1. Build a page collection
-2. Sort the collection by title
-3. Paginate the collection, with 7 elements per pager
-4. Range over the paginated page collection, rendering a link to each page
-5. Call the embedded pagination template to create navigation links between pagers
+1. Sort the collection by title
+1. Paginate the collection, with 7 elements per pager
+1. Range over the paginated page collection, rendering a link to each page
+1. Call the embedded pagination template to create navigation links between pagers
{{% note %}}
Please note that the results of pagination are cached. Once you have invoked either the `Paginator` or `Paginate` method, the paginated collection is immutable. Additional invocations of these methods will have no effect.
[site configuration]: /getting-started/configuration/#pagination
-You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates]. Each of these receives a collection of regular pages in [context]. When you invoke the `Paginator` method, it paginates the page collection received in context.
+You can invoke pagination on the [home template], [section templates], [taxonomy templates], and [term templates]. Each of these receives a collection of regular pages in [context](g). When you invoke the `Paginator` method, it paginates the page collection received in context.
[home template]: /templates/types/#home
[section templates]: /templates/types/#section
[taxonomy templates]: /templates/types/#taxonomy
[term templates]: /templates/types/#term
-[context]: /getting-started/glossary/#context
{{< code file=layouts/_default/list.html >}}
{{ range .Paginator.Pages }}
The `title` and `date` fields are standard parameters---the other fields are user-defined.
-Access the custom parameters by [chaining] the [identifiers]:
+Access the custom parameters by [chaining](g) the [identifiers](g):
```go-html-template
{{ .Params.display_related }} → true
```
[`index`]: /functions/collections/indexfunction/
-[chaining]: /getting-started/glossary/#chain
-[identifiers]: /getting-started/glossary/#identifier
{{< new-in 0.123.0 >}}
-The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file.
-
-[logical path]: /getting-started/glossary#logical-path
+The `Path` method on a `Page` object returns the [logical path](g) of the given page, regardless of whether the page is backed by a file.
```go-html-template
{{ .Path }} → /posts/post-1
[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
{{% /note %}}
-To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the content directory, and then:
+To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the `content` directory, and then:
1. Strips the file extension
-2. Strips the language identifier
-3. Converts the result to lower case
-4. Replaces spaces with hyphens
+1. Strips the language identifier
+1. Converts the result to lower case
+1. Replaces spaces with hyphens
The value returned by the `Path` method on a `Page` object is independent of content format, language, and URL modifiers such as the `slug` and `url` front matter fields.
[`urls.RelRef`]: /functions/urls/relref/
[`Page.GetPage`]: /methods/page/getpage/
[`Site.GetPage`]: /methods/site/getpage/
-[`ref`]: /content-management/shortcodes/#ref
-[`relref`]: /content-management/shortcodes/#relref
+[`ref`]: /shortcodes/ref/
+[`relref`]: /shortcodes/relref/
[`Page.Ref`]: /methods/page/ref/
[`Page.RelRef`]: /methods/page/relref/
[`Shortcode.Ref`]: /methods/shortcode/ref
Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
{{% /note %}}
-
## Logical tree
Just as file paths form a file tree, logical paths form a logical tree.
signatures: [PAGE.Plain]
---
-The `Plain` method on a `Page` object renders Markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities].
+The `Plain` method on a `Page` object renders Markdown and [shortcodes](g) to HTML, then strips the HTML [tags]. It does not strip HTML [entities].
To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function.
{{ .Plain | htmlUnescape }}
```
-[shortcodes]: /getting-started/glossary/#shortcode
[html/template]: https://pkg.go.dev/html/template
[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag
This is useful when rendering a page in a plain text [output format].
{{% note %}}
-[Shortcodes] within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object.
+[Shortcodes](g) within the content are not rendered. To get the raw content with shortcodes rendered, use the [`RenderShortcodes`] method on a `Page` object.
-[shortcodes]: /getting-started/glossary/#shortcode
[`RenderShortcodes`]: /methods/page/rendershortcodes/
{{% /note %}}
The map of option contains:
path
-: (`string`) The path to the page, relative to the content directory. Required.
+: (`string`) The path to the page, relative to the `content` directory. Required.
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
signatures: [PAGE.RegularPages]
---
-The `RegularPages` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context].
+The `RegularPages` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g).
Range through the page collection in your template:
lessons/lesson-2/resources/task-list.md
lessons/lesson-2/resources/worksheet.md
-In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an _index.md file. Its contents are part of the lesson-2 section.
+In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section](g)---it does not contain an _index.md file. Its contents are part of the lesson-2 section.
{{% note %}}
When used with the `Site` object, the `RegularPages` method recursively returns all regular pages within the site. See [details].
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
```
-
-[collection]: /getting-started/glossary/#collection
-[context]: /getting-started/glossary/#context
-[page kinds]: /getting-started/glossary/#page-kind
-[section]: /getting-started/glossary/#section
signatures: [PAGE.RegularPagesRecursive]
---
-The `RegularPagesRecursive` method on a `Page` object is available to these [page kinds]: `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection] in [context].
+The `RegularPagesRecursive` method on a `Page` object is available to these [page kinds](g): `home`, `section`, `taxonomy`, and `term`. The templates for these page kinds receive a page [collection](g) in [context](g).
Range through the page collection in your template:
{{% note %}}
The `RegularPagesRecursive` method in not available on a `Site` object.
{{% /note %}}
-
-[collection]: /getting-started/glossary/#collection
-[context]: /getting-started/glossary/#context
-[page kinds]: /getting-started/glossary/#page-kind
The map of option contains:
path
-: (`string`) The path to the page, relative to the content directory. Required.
+: (`string`) The path to the page, relative to the `content` directory. Required.
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
`Render` method|`partial` function|
:--|:--
The `Page` object is automatically passed to the given template. You cannot pass additional context.| You must specify the context, allowing you to pass a combination of objects, slices, maps, and scalars.
-The path to the template is determined by the [content type].|You must specify the path to the template, relative to the layouts/partials directory.
+The path to the template is determined by the [content type](g).|You must specify the path to the template, relative to the `layouts/partials` directory.
Consider this layout structure:
[content views]: /templates/content-view/
[`partial`]: /functions/partials/include/
-[content type]: /getting-started/glossary/#content-type
Note that the shortcode within the content file was rendered, but the surrounding Markdown was preserved.
-
## Limitations
The primary use case for `.RenderShortcodes` is inclusion of Markdown content. If you try to use `.RenderShortcodes` inside `HTML` blocks when inside Markdown, you will get a warning similar to this:
toc: true
---
-The `Resources` method on a `Page` object returns a collection of page resources. A page resource is a file within a [page bundle].
+The `Resources` method on a `Page` object returns a collection of page resources. A page resource is a file within a [page bundle](g).
To work with global or remote resources, see the [`resources`] functions.
This method is currently only useful in [js.Batch](/functions/js/batch/#import-context).
-
## Pattern matching
With the `GetMatch` and `Match` methods, Hugo determines a match using a case-insensitive [glob pattern].
[`resources`]: /functions/resources/
[glob pattern]: https://github.com/gobwas/glob#example
[media type]: https://en.wikipedia.org/wiki/Media_type
-[page bundle]: /getting-started/glossary/#page-bundle
signatures: [PAGE.Scratch]
toc: true
aliases: [/extras/scratch/,/doc/scratch/,/functions/scratch]
+expiryDate: 2025-11-18 # deprecated 2024-11-18
---
{{% deprecated-in 0.138.0 %}}
[`PAGE.Store`]: /methods/page/store/
{{% /deprecated-in %}}
-The `Scratch` method on a `Page` object creates a [scratch pad] to store and manipulate data. To create a scratch pad that is not reset on server rebuilds, use the [`Store`] method instead.
+The `Scratch` method on a `Page` object creates a [scratch pad](g) to store and manipulate data. To create a scratch pad that is not reset on server rebuilds, use the [`Store`] method instead.
To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function.
[`Store`]: /methods/page/store/
[`newScratch`]: /functions/collections/newscratch/
-[scratch pad]: /getting-started/glossary/#scratch-pad
{{% include "methods/page/_common/scratch-methods.md" %}}
The `Scratch` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
-If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable:
-
-[noop]: /getting-started/glossary/#noop
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
```go-html-template
{{ $noop := .Content }}
However, if the `type` field in front matter has been defined on one or more pages, the page collection based on `Type` will be different than the page collection based on `Section`.
-
[`where`]: /functions/collections/where/
[`Type`]: /methods/page/type/
aliases: [/functions/store]
---
-The `Store` method on a `Page` object creates a persistent [scratch pad] to store and manipulate data. To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function.
+The `Store` method on a `Page` object creates a persistent [scratch pad](g) to store and manipulate data. To create a locally scoped scratch pad that is not attached to a `Page` object, use the [`newScratch`] function.
[`Scratch`]: /methods/page/scratch/
[`newScratch`]: /functions/collections/newscratch/
-[scratch pad]: /getting-started/glossary/#scratch-pad
## Methods
The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
-If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable:
-
-[noop]: /getting-started/glossary/#noop
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
```go-html-template
{{ $noop := .Content }}
signatures: [PAGE.Summary]
---
-{{% comment %}}
-Do not remove the manual summary divider below.
-If you do, you will break its first literal usage on this page.
-{{% /comment %}}
+<!-- Do not remove the manual summary divider below. -->
+<!-- If you do, you will break its first literal usage on this page. -->
+
<!--more-->
You can define a [summary] manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
signatures: [PAGE.Type]
---
-The `Type` method on a `Page` object returns the [content type] of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined.
+The `Type` method on a `Page` object returns the [content type](g) of the given page. The content type is defined by the `type` field in front matter, or inferred from the top-level directory name if the `type` field in front matter is not defined.
With this content structure:
└── _index.md
```
-To list the books, regardless of [section]:
+To list the books, regardless of [section](g):
```go-html-template
{{ range where .Site.RegularPages.ByTitle "Type" "books" }}
The `type` field in front matter is also useful for targeting a template. See [details].
-[content type]: /getting-started/glossary/#content-type
[details]: /templates/lookup-order/#target-a-template
-[section]: /getting-started/glossary/#section
signatures: [PAGE.Weight]
---
-The `Weight` method on a `Page` object returns the [weight] of the given page as defined in front matter.
-
-[weight]: /getting-started/glossary/#weight
+The `Weight` method on a `Page` object returns the [weight](g) of the given page as defined in front matter.
{{< code-toggle file=content/recipes/sushi.md fm=true >}}
title = 'How to make spicy tuna hand rolls'
_comment: Do not remove front matter.
---
-A _section_ is a top-level content directory, or any content directory with an _index.md file.
+A _section_ is a top-level content directory, or any content directory with an `_index.md` file.
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
-[site configuration]: getting-started/configuration/#configure-page
+[site configuration]: /getting-started/configuration/#configure-page
[`Next`]: /methods/pages/prev
[`Prev`]: /methods/pages/prev
To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility.
-[site configuration]: getting-started/configuration/#configure-page
+[site configuration]: /getting-started/configuration/#configure-page
[`Next`]: /methods/pages/prev
[`Prev`]: /methods/pages/prev
+++ /dev/null
----
-_comment: Do not remove front matter.
----
-Hugo generates one or more files per page when building a site. For example, when rendering home, [section], [taxonomy], and [term] pages, Hugo generates an HTML file and an RSS file. Both HTML and RSS are built-in _output formats_. Create multiple output formats, and control generation based on [page kind], or by enabling one or more output formats for one or more pages. See [details].
-
-[section]: /getting-started/glossary/#section
-[taxonomy]: /getting-started/glossary/#taxonomy
-[term]: /getting-started/glossary/#term
-[page kind]: /getting-started/glossary/#page-kind
-[details]: /templates/output-formats/
signatures: [PAGES.ByWeight]
---
-Assign a [weight] to a page using the `weight` field in front matter. The weight must be a non-zero integer. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted pages are placed at the end of the collection.
-
-[weight]: /getting-started/glossary/#weight
+Assign a [weight](g) to a page using the `weight` field in front matter. The weight must be a non-zero integer. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted pages are placed at the end of the collection.
```go-html-template
{{ range .Pages.ByWeight }}
When grouping by date, the value is determined by your [site configuration], defaulting to the `date` field in front matter.
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region.
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
[`time.Format`]: /functions/time/format/
[layout string]: #layout-string
-[localized]: /getting-started/glossary/#localization
[site configuration]: /getting-started/configuration/#configure-dates
{{% include "methods/pages/_common/group-sort-order.md" %}}
When grouping by expiration date, the value is determined by your [site configuration], defaulting to the `expiryDate` field in front matter.
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region.
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
[`time.Format`]: /functions/time/format/
[layout string]: #layout-string
-[localized]: /getting-started/glossary/#localization
[site configuration]: /getting-started/configuration/#configure-dates
{{% include "methods/pages/_common/group-sort-order.md" %}}
When grouping by last modification date, the value is determined by your [site configuration], defaulting to the `lastmod` field in front matter.
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region.
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
[`time.Format`]: /functions/time/format/
[layout string]: #layout-string
-[localized]: /getting-started/glossary/#localization
[site configuration]: /getting-started/configuration/#configure-dates
{{% include "methods/pages/_common/group-sort-order.md" %}}
signatures: ['PAGES.GroupByParamDate PARAM LAYOUT [SORT]']
---
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region.
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
[`time.Format`]: /functions/time/format/
[layout string]: #layout-string
-[localized]: /getting-started/glossary/#localization
{{% include "methods/pages/_common/group-sort-order.md" %}}
When grouping by publish date, the value is determined by your [site configuration], defaulting to the `publishDate` field in front matter.
-The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized] for language and region.
+The [layout string] has the same format as the layout string for the [`time.Format`] function. The resulting group key is [localized](g) for language and region.
[`time.Format`]: /functions/time/format/
[layout string]: #layout-string
-[localized]: /getting-started/glossary/#localization
[site configuration]: /getting-started/configuration/#configure-dates
{{% include "methods/pages/_common/group-sort-order.md" %}}
{{ end }}
{{< /code >}}
-
## Options
indices
[`keyVals`]: /functions/collections/keyvals/
fragments
-: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment] identifiers of the documents.
+: (`slice`) A list of special keywords that is used for indices configured as type "fragments". This will match the [fragment](g) identifiers of the documents.
A contrived example using all of the above:
```
[details]: /content-management/related/
-[fragment]: /getting-started/glossary/#fragment
[related content configuration]: /content-management/related/
{{ end }}
```
-
[WCAG]: https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines
[contrast ratio]: https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio
[enhanced]: https://www.w3.org/WAI/WCAG22/quickref/?showtechniques=145#contrast-enhanced
```go-html-template
{{ $url := "https://example.org/images/a.jpg" }}
-{{ with resources.GetRemote $url }}
+{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
- {{ else }}
+ {{ else with .Value }}
{{ with .Data }}
{{ .ContentLength }} → 42764
{{ .ContentType }} → image/jpeg
{{ .StatusCode }} → 200
{{ .TransferEncoding }} → []
{{ end }}
+ {{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
-{{ else }}
- {{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
TransferEncoding
: (`string`) The transfer encoding.
-
[`resources.GetRemote`]: /functions/resources/getremote/
- methods/resource/Data
returnType: resource.resourceError
signatures: [RESOURCE.Err]
+expiryDate: 2026-01-16 # deprecated 2025-01-16
---
+{{% deprecated-in 0.141.0 %}}
+Use the `try` statement instead. See [example].
+
+[example]: /functions/go-template/try/#example
+{{% /deprecated-in %}}
+
The `Err` method on a resource returned by the [`resources.GetRemote`] function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build.
[`resources.GetRemote`]: /functions/resources/getremote/
The `Key` method is useful if you need to get the resource's publishing path without publishing the resource. Unlike the `Permalink`, `RelPermalink`, or `Publish` methods, calling `Key` will not publish the resource.
-
{{% include "methods/resource/_common/global-page-remote-resources.md" %}}
[`Permalink`]: /methods/resource/permalink/
## Global resource
-With a [global resource], the `Name` method returns the path to the resource, relative to the assets directory.
+With a [global resource](g), the `Name` method returns the path to the resource, relative to the `assets` directory.
```text
assets/
## Page resource
-With a [page resource], if you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter.
+With a [page resource](g), if you create an element in the `resources` array in front matter, the `Name` method returns the value of the `name` parameter.
```text
content/
```
## Remote resource
-With a [remote resource], the `Name` method returns a hashed file name.
+With a [remote resource](g), the `Name` method returns a hashed file name.
```go-html-template
{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
{{ .Name }} → /a_18432433023265451104.jpg
{{ end }}
```
-
-[global resource]: /getting-started/glossary/#global-resource
-[logical path]: /getting-started/glossary/#logical-path
-[page resource]: /getting-started/glossary/#page-resource
-[remote resource]: /getting-started/glossary/#remote-resource
signatures: [RESOURCE.Params]
---
-Use the `Params` method with [page resources]. It is not applicable to either [global] or [remote] resources.
-
-[global]: /getting-started/glossary/#global-resource
-[page resources]: /getting-started/glossary/#page-resource
-[remote]: /getting-started/glossary/#remote-resource
+Use the `Params` method with [page resources](g). It is not applicable to either [global resources](g) or [remote resources](g).
With this content structure:
signatures: [RESOURCE.Permalink]
---
-The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [permalink].
-
-[permalink]: /getting-started/glossary/#permalink
+The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [permalink](g).
```go-html-template
{{ with resources.Get "images/a.jpg" }}
signatures: [RESOURCE.RelPermalink]
---
-The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [relative permalink].
-
-[relative permalink]: /getting-started/glossary/#relative-permalink
+The `Permalink` method on a `Resource` object writes the resource to the publish directory, typically `public`, and returns its [relative permalink](g).
```go-html-template
{{ with resources.Get "images/a.jpg" }}
## Global resource
-With a [global resource], the `Title` method returns the path to the resource, relative to the assets directory.
+With a [global resource](g), the `Title` method returns the path to the resource, relative to the `assets` directory.
```text
assets/
## Page resource
-With a [page resource], if you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter.
+With a [page resource](g), if you create an element in the `resources` array in front matter, the `Title` method returns the value of the `title` parameter.
```text
content/
## Remote resource
-With a [remote resource], the `Title` method returns a hashed file name.
+With a [remote resource](g), the `Title` method returns a hashed file name.
```go-html-template
{{ with resources.GetRemote "https://example.org/images/a.jpg" }}
{{ .Title }} → /a_18432433023265451104.jpg
{{ end }}
```
-
-[global resource]: /getting-started/glossary/#global-resource
-[page resource]: /getting-started/glossary/#page-resource
-[remote resource]: /getting-started/glossary/#remote-resource
---
{{% note %}}
-
-Use this method with [global], [page], or [remote] resources.
-
-[global]: /getting-started/glossary/#global-resource
-[page]: /getting-started/glossary/#page-resource
-[remote]: /getting-started/glossary/#remote-resource
-
+Use this method with [global resources](g), [page resources](g), or [remote resources](g).
{{% /note %}}
In the example above, the value returned by `Inner` is Markdown, but it was rendered as plain text. Use either of the following approaches to render Markdown to HTML.
{{% /note %}}
-
## Use RenderString
Let's modify the example above to pass the value returned by `Inner` through the [`RenderString`] method on the `Page` object:
The "now" shortcode formats the current time using:
1. The `dateFormat` argument passed to the "now" shortcode, if present
-2. The `dateFormat` argument passed to the "greeting" shortcode, if present
-3. The default layout string defined at the top of the shortcode
+1. The `dateFormat` argument passed to the "greeting" shortcode, if present
+1. The default layout string defined at the top of the shortcode
The map of option contains:
path
-: (`string`) The path to the page, relative to the content directory. Required.
+: (`string`) The path to the page, relative to the `content` directory. Required.
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
The map of option contains:
path
-: (`string`) The path to the page, relative to the content directory. Required.
+: (`string`) The path to the page, relative to the `content` directory. Required.
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.
- functions/collections/NewScratch
returnType: maps.Scratch
signatures: [SHORTCODE.Scratch]
+expiryDate: 2025-11-18 # deprecated 2024-11-18
---
{{% deprecated-in 0.139.0 %}}
[`SHORTCODE.Store`]: /methods/shortcode/store/
{{% /deprecated-in %}}
-The `Scratch` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode.
+The `Scratch` method within a shortcode creates a [scratch pad](g) to store and manipulate data. The scratch pad is scoped to the shortcode.
{{% note %}}
With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Scratch` method within a shortcode is obsolete.
[`newScratch`]: /functions/collections/newscratch/
{{% /note %}}
-[scratch pad]: /getting-started/glossary/#scratch-pad
-
{{% include "methods/page/_common/scratch-methods.md" %}}
{{< new-in 0.139.0 >}}
-The `Store` method within a shortcode creates a [scratch pad] to store and manipulate data. The scratch pad is scoped to the shortcode.
+The `Store` method within a shortcode creates a [scratch pad](g) to store and manipulate data. The scratch pad is scoped to the shortcode.
{{% note %}}
With the introduction of the [`newScratch`] function, and the ability to [assign values to template variables] after initialization, the `Store` method within a shortcode is mostly obsolete.
[`newScratch`]: /functions/collections/newScratch/
{{% /note %}}
-[Store pad]: /getting-started/glossary/#scratch-pad
-
{{% include "methods/page/_common/scratch-methods.md" %}}
signatures: [SITE.AllPages]
---
-This method returns all page [kinds] in all languages. That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
+This method returns all page [kinds](g) in all languages. That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
In most cases you should use the [`RegularPages`] method instead.
[`RegularPages`]: /methods/site/regularpages/
-[kinds]: /getting-started/glossary/#page-kind
```go-html-template
{{ range .Site.AllPages }}
signatures: [SITE.Data]
---
-Use the `Data` method on a `Site` object to access data within the data directory, or within any directory [mounted] to the data directory. Supported data formats include JSON, TOML, YAML, and XML.
+Use the `Data` method on a `Site` object to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML.
[mounted]: /hugo-modules/configuration/#module-configuration-mounts
{{% note %}}
-Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the data directory. You cannot access data within CSV files using this method.
+Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method.
[`transform.Unmarshal`]: /functions/transform/unmarshal/
{{% /note %}}
-Consider this data directory:
+Consider this `data` directory:
```text
data/
isbn: 978-0521280495
{{< /code >}}
-Access the data by [chaining] the [identifiers]:
+Access the data by [chaining](g) the [identifiers](g):
```go-html-template
{{ range $category, $books := .Site.Data.books }}
{{ end }}
```
-In the template examples above, each of the keys is a valid [identifier]. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function. For example:
-
-[identifier]: /getting-started/glossary/#identifier
+In the template examples above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function. For example:
```go-html-template
{{ index .Site.Data.books "historical-fiction" }}
```
[`index`]: /functions/collections/indexfunction/
-[chaining]: /getting-started/glossary/#chain
-[identifiers]: /getting-started/glossary/#identifier
[details]: /methods/page/getpage/
-When using the `GetPage` method on a `Site` object, specify a path relative to the content directory.
+When using the `GetPage` method on a `Site` object, specify a path relative to the `content` directory.
If Hugo cannot resolve the path to a page, the method returns nil.
└── _index.md
```
-In the home template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle]:
+In the home template, use the `GetPage` method on a `Site` object to render all the images in the headless [page bundle](g):
```go-html-template
{{ with .Site.GetPage "/headless" }}
{{ end }}
{{ end }}
```
-
-[page bundle]: /getting-started/glossary/#page-bundle
signatures: [SITE.Pages]
---
-This method returns all page [kinds] in the current language. That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
+This method returns all page [kinds](g) in the current language. That includes the home page, section pages, taxonomy pages, term pages, and regular pages.
In most cases you should use the [`RegularPages`] method instead.
[`RegularPages`]: /methods/site/regularpages/
-[kinds]: /getting-started/glossary/#page-kind
```go-html-template
{{ range .Site.Pages }}
display_toc = true
{{< /code-toggle >}}
-
```go-html-template
{{ .Site.Param "display_toc" }} → true
```
rfc_3339 = '2006-01-02T15:04:05-07:00'
{{< /code-toggle >}}
-Access the custom parameters by [chaining] the [identifiers]:
+Access the custom parameters by [chaining](g) the [identifiers](g):
```go-html-template
{{ .Site.Params.subtitle }} → The Best Widgets on Earth
```
[`index`]: /functions/collections/indexfunction/
-[chaining]: /getting-started/glossary/#chain
-[identifiers]: /getting-started/glossary/#identifier
signatures: [SITE.RegularPages]
---
-The `RegularPages` method on a `Site` object returns a collection of all [regular pages].
-
-[regular pages]: /getting-started/glossary/#regular-page
+The `RegularPages` method on a `Site` object returns a collection of all [regular pages](g).
```go-html-template
{{ range .Site.RegularPages }}
{{< new-in 0.139.0 >}}
-The `Store` method on a `Site` object creates a persistent [scratch pad] to store and manipulate data. To create a locally scoped scratch pad that is not attached to a `Site` object, use the [`newScratch`] function.
+The `Store` method on a `Site` object creates a persistent [scratch pad](g) to store and manipulate data. To create a locally scoped scratch pad that is not attached to a `Site` object, use the [`newScratch`] function.
[`Scratch`]: /methods/site/scratch/
[`newScratch`]: /functions/collections/newscratch/
-[scratch pad]: /getting-started/glossary/#scratch-pad
## Methods
The `Store` method is often used to set scratch pad values within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are indeterminate until Hugo renders the page content.
-If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable:
-
-[noop]: /getting-started/glossary/#noop
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
```go-html-template
{{ $noop := .Content }}
signatures: [SITE.Taxonomies]
---
-{{% comment %}}
-Show template example: GetTerms
-{{% /comment %}}
-
Conceptually, the `Taxonomies` method on a `Site` object returns a data structure such as:
{{< code-toggle >}}
- Pride and Prejudice
{{< /code-toggle >}}
-
To list the "suspense" books:
```go-html-template
toc: true
---
-The `Alphabetical` method on a `Taxonomy` object returns an [ordered taxonomy], sorted alphabetically by [term].
+The `Alphabetical` method on a `Taxonomy` object returns an [ordered taxonomy](g), sorted alphabetically by [term](g).
-While a `Taxonomy` object is a [map], an ordered taxonomy is a [slice], where each element is an object that contains the term and a slice of its [weighted pages].
+While a `Taxonomy` object is a [map](g), an ordered taxonomy is a [slice](g), where each element is an object that contains the term and a slice of its [weighted pages](g).
{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}}
<li><a href="/books/jamaica-inn/">Jamaica inn</a></li>
</ul>
```
-
-[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy
-[term]: /getting-started/glossary/#term
-[map]: /getting-started/glossary/#map
-[slice]: /getting-started/glossary/#slice
-[term]: /getting-started/glossary/#term
-[weighted pages]: /getting-started/glossary/#weighted-page
toc: true
---
-The `ByCount` method on a `Taxonomy` object returns an [ordered taxonomy], sorted by the number of pages associated with each [term].
+The `ByCount` method on a `Taxonomy` object returns an [ordered taxonomy](g), sorted by the number of pages associated with each [term](g).
-While a `Taxonomy` object is a [map], an ordered taxonomy is a [slice], where each element is an object that contains the term and a slice of its [weighted pages].
+While a `Taxonomy` object is a [map](g), an ordered taxonomy is a [slice](g), where each element is an object that contains the term and a slice of its [weighted pages](g).
{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}}
<li><a href="/books/pride-and-prejudice/">Pride and prejudice</a></li>
</ul>
```
-
-[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy
-[term]: /getting-started/glossary/#term
-[map]: /getting-started/glossary/#map
-[slice]: /getting-started/glossary/#slice
-[term]: /getting-started/glossary/#term
-[weighted pages]: /getting-started/glossary/#weighted-page
toc: true
---
-The `Count` method on a `Taxonomy` object returns the number of number of [weighted pages] to which the given [term] has been assigned.
+The `Count` method on a `Taxonomy` object returns the number of number of [weighted pages](g) to which the given [term](g) has been assigned.
{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}}
```go-html-template
{{ $taxonomyObject.Count "suspense" }} → 3
```
-
-[weighted pages]: /getting-started/glossary/#weighted-page
-[term]: /getting-started/glossary/#term
toc: true
---
-The `Get` method on a `Taxonomy` object returns a slice of [weighted pages] to which the given [term] has been assigned.
+The `Get` method on a `Taxonomy` object returns a slice of [weighted pages](g) to which the given [term](g) has been assigned.
{{% include "methods/taxonomy/_common/get-a-taxonomy-object.md" %}}
{{ $weightedPages := $taxonomyObject.suspense }}
```
-But, if the term is not a valid [identifier], you cannot use the [chaining] syntax. For example, this will throw an error because the identifier contains a hyphen:
+But, if the term is not a valid [identifier](g), you cannot use the [chaining](g) syntax. For example, this will throw an error because the identifier contains a hyphen:
```go-html-template
{{ $weightedPages := $taxonomyObject.my-genre }}
<h2><a href="/books/and-then-there-were-none/">And then there were none</a></h2>
```
-[chaining]: /getting-started/glossary/#chain
[`index`]: /functions/collections/indexfunction/
-[identifier]: /getting-started/glossary/#identifier
-[term]: /getting-started/glossary/#term
-[weighted pages]: /getting-started/glossary/#weighted-page
In the example above, the first anchor element is a link to the term page.
-
[`Alphabetical`]: /methods/taxonomy/alphabetical/
[`ByCount`]: /methods/taxonomy/bycount/
: (`page.Page`) Returns the term's `Page` object, useful for linking to the term page.
Pages
-: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight]. To sort or group, use any of the [methods] available to the `Pages` object. For example, sort by the last modification date.
+: (`page.Pages`) Returns a `Pages` object containing the `Page` objects to which the term is assigned, sorted by [taxonomic weight](g). To sort or group, use any of the [methods] available to the `Pages` object. For example, sort by the last modification date.
Term
: (`string`) Returns the term name.
WeightedPages
-: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by [taxonomic weight]. The `Pages` method above is more flexible, allowing you to sort and group.
+: (`page.WeightedPages`) Returns a slice of weighted pages to which the term is assigned, sorted by taxonomic weight. The `Pages` method above is more flexible, allowing you to sort and group.
[methods]: /methods/pages/
-[taxonomic weight]: /getting-started/glossary/#taxonomic-weight
```
{{% note %}}
-To [localize] the return value, use the [`time.Format`] function instead.
+To [localize](g) the return value, use the [`time.Format`] function instead.
-[localize]: /getting-started/glossary/#localization
[`time.Format`]: /functions/time/format/
{{% /note %}}
The rounding behavior for halfway values is to round up.
-The `Round` method operates on TIME as an absolute duration since the [zero time]; it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Round` may return a time with a non-zero minute, depending on the time zone.
+The `Round` method operates on TIME as an absolute duration since the [zero time](g); it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Round` may return a time with a non-zero minute, depending on the time zone.
```go-html-template
{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
{{ ($t.Round $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-28T00:00:00-00:00
```
-
-[zero time]: /getting-started/glossary/#zero-time
signatures: [TIME.Truncate DURATION]
---
-The `Truncate` method operates on TIME as an absolute duration since the [zero time]; it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Truncate` may return a time with a non-zero minute, depending on the time zone.
+The `Truncate` method operates on TIME as an absolute duration since the [zero time](g); it does not operate on the presentation form of the time. If DURATION is a multiple of one hour, `Truncate` may return a time with a non-zero minute, depending on the time zone.
```go-html-template
{{ $t := time.AsTime "2023-01-27T23:44:58-08:00" }}
{{ ($t.Truncate $d).Format "2006-01-02T15:04:05-00:00" }} → 2023-01-27T23:00:00-00:00
```
-
-[zero time]: /getting-started/glossary/#zero-time
To complete this showcase:
1. Write the story about your site in this file.
-2. Add a summary to the `bio.md` file in this folder.
-3. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`.
-4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls
+1. Add a summary to the `bio.md` file in this directory.
+1. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`.
+1. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls
The content of this bundle explained:
featured.png
: A reasonably sized screenshot of your website. It can be named anything, but the name must start with "featured". The sample image is `1500x750` (2:1 aspect ratio).
-
[`emojify`]: /functions/transform/emojify/
[`RenderString`]: /methods/page/renderstring/
-{{% comment %}}
+<!--
To generate the sections below:
git clone https://github.com/ikatyang/emoji-cheat-sheet
2. Search/replace (regex) "^###\s" with "## "
3. Search/replace "^####\s " with "### "
4. Search/replace (regex) "<br />" ""
-{{% /comment %}}
+-->
## Table of Contents
## Page
-Use these `Page` methods when rendering lists on [section] pages, [taxonomy] pages, [term] pages, and the home page.
-
-[section]: /getting-started/glossary/#section
-[taxonomy]: /getting-started/glossary/#taxonomy
-[term]: /getting-started/glossary/#term
+assets/
+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 omitElementIDs=true titlePrefix=PAGE. >}}
By default, Hugo sorts page collections by:
1. [Weight]
-2. [Date] in descending order
-3. [LinkTitle] falling back to [Title]
-4. [Filename] if the page is backed by a file
+1. [Date] in descending order
+1. [LinkTitle] falling back to [Title]
+1. [Filename] if the page is backed by a file
[Date]: /methods/page/date/
[Weight]: /methods/page/weight/
{{< new-in 0.125.0 >}}
-The primary use case for `PageInner` is to resolve links and [page resources] relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
+The primary use case for `PageInner` is to resolve links and [page resources](g) relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
{{< code file=layouts/shortcodes/include.html >}}
{{ with .Get 0 }}
- [Embedded image render hook]({{% eturl render-image %}})
[`RenderShortcodes`]: /methods/page/rendershortcodes/
-[page resources]: /getting-started/glossary/#page-resource
## Context
-Blockquote render hook templates receive the following [context]:
-
-[context]: /getting-started/glossary/#context
+Blockquote render hook templates receive the following [context](g):
###### AlertType
## Context
-Code block render hook templates receive the following [context]:
-
-[context]: /getting-started/glossary/#context
+Code block render hook templates receive the following [context](g):
###### Attributes
## Context
-Heading render hook templates receive the following [context]:
-
-[context]: /getting-started/glossary/#context
+Heading render hook templates receive the following [context](g):
###### Anchor
description destination title
```
-These components are passed into the render hook [context] as shown below.
-
-[context]: /getting-started/glossary/#context
+These components are passed into the render hook [context](g) as shown below.
## Context
[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
{{% /note %}}
-The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource], falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
-
-[page resource]: /getting-started/glossary/#page-resource
-[global resource]: /getting-started/glossary/#global-resource
+The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
-You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration:
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration:
{{< code-toggle file=hugo >}}
[[module.mounts]]
└── render-table.html
```
-The template lookup order allows you to create different render hooks for each page [type], [kind], language, and [output format]. For example:
+The template lookup order allows you to create different render hooks for each page [type](g), [kind](g), language, and [output format](g). For example:
```text
layouts/
└── render-link.rss.xml
```
-[kind]: /getting-started/glossary/#page-kind
-[output format]: /getting-started/glossary/#output-format
-[type]: /getting-started/glossary/#content-type
-
The remaining pages in this section describe each type of render hook, including examples and the context received by each template.
text destination title
```
-These components are passed into the render hook [context] as shown below.
-
-[context]: /getting-started/glossary/#context
+These components are passed into the render hook [context](g) as shown below.
## Context
Link render hook templates receive the following context:
-[context]: /getting-started/glossary/#context
-
###### Destination
(`string`) The link destination.
[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
{{% /note %}}
-The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource], then falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
-
-[page resource]: /getting-started/glossary/#page-resource
-[global resource]: /getting-started/glossary/#global-resource
+The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource](g), then falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
-You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration:
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration:
{{< code-toggle file=hugo >}}
[[module.mounts]]
In the example above there are two sets of `block` delimiters. You may use either one in your Markdown.
-The Goldmark passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in [LaTeX] or [Tex].
+The Goldmark passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in the LaTeX markup language.
[mathematical expressions]: /content-management/mathematics/
-[LaTeX]: https://www.latex-project.org/
-[Tex]: https://en.wikipedia.org/wiki/TeX
-To enable custom rendering of passthrough elements, create a render hook.
+To enable custom rendering of passthrough elements, create a passthrough render hook.
## Context
-Passthrough render hook templates receive the following [context]:
-
-[context]: /getting-started/glossary/#context
+Passthrough render hook templates receive the following [context](g):
###### Attributes
## Example
-As an alternative to rendering mathematical expressions with the MathJax or KaTeX display engine, create a passthrough render hook which calls the [`transform.ToMath`] function:
+Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the [`transform.ToMath`] function.
[`transform.ToMath`]: /functions/transform/tomath/
{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}}
-{{ if eq .Type "block" }}
- {{ $opts := dict "displayMode" true }}
- {{ transform.ToMath .Inner $opts }}
-{{ else }}
- {{ transform.ToMath .Inner }}
-{{ end }}
+{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
+{{- with try (transform.ToMath .Inner $opts) }}
+ {{- with .Err }}
+ {{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
+ {{- else }}
+ {{- .Value }}
+ {{- $.Page.Store.Set "hasMath" true }}
+ {{- end }}
+{{- end -}}
{{< /code >}}
+Then, in your base template, conditionally include the KaTeX CSS within the head element:
+
+{{< code file=layouts/_default/baseof.html copy=true >}}
+<head>
+ {{ $noop := .WordCount }}
+ {{ if .Page.Store.Get "hasMath" }}
+ <link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
+ {{ end }}
+</head>
+{{< /code >}}
+
+In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
+
Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of passthrough element:
```text
## Context
-Table render hook templates receive the following [context]:
-
-[context]: /getting-started/glossary/#context
+Table render hook templates receive the following [context](g):
###### Attributes
--- /dev/null
+---
+title: Shortcodes
+linkTitle: In this section
+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.
--- /dev/null
+---
+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 # with v0.142.0 and later use HTML comments instead
+---
+
+{{% 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.
--- /dev/null
+---
+title: Details
+description: Insert an HTML details element into your content using the details shortcode.
+categories: [shortcodes]
+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 %}}
+
+## Example
+
+With this markup:
+
+```text
+{{</* details summary="See the details" */>}}
+This is a **bold** word.
+{{</* /details */>}}
+```
+
+Hugo renders this HTML:
+
+```html
+<details>
+ <summary>See the details</summary>
+ <p>This is a <strong>bold</strong> word.</p>
+</details>
+```
+
+Which looks like this in your browser:
+
+{{< details summary="See the details" >}}
+This is a **bold** word.
+{{< /details >}}
+
+## Parameters
+
+summary
+: (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`.
+
+open
+: (`bool`) Whether to initially display the content of the `details` element. Default is `false`.
+
+class
+: (`string`) The `class` attribute of the `details` element.
+
+name
+: (`string`) The `name` attribute of the `details` element.
+
+title
+: (`string`) The `title` attribute of the `details` element.
+
+## Styling
+
+Use CSS to style the `details` element, the `summary` element, and the content itself.
+
+```css
+/* target the details element */
+details { }
+
+/* target the summary element */
+details > summary { }
+
+/* target the children of the summary element */
+details > summary > * { }
+
+/* target the content */
+details > :not(summary) { }
+```
--- /dev/null
+---
+title: Figure
+description: Insert an HTML figure element into your content using the figure shortcode.
+categories: [shortcodes]
+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 %}}
+
+## Example
+
+With this markup:
+
+```text
+{{</* figure
+ src="/images/examples/zion-national-park.jpg"
+ alt="A photograph of Zion National Park"
+ link="https://www.nps.gov/zion/index.htm"
+ caption="Zion National Park"
+ class="ma0 w-75"
+*/>}}
+```
+
+Hugo renders this HTML:
+
+```html
+<figure class="ma0 w-75">
+ <a href="https://www.nps.gov/zion/index.htm">
+ <img
+ src="/images/examples/zion-national-park.jpg"
+ alt="A photograph of Zion National Park"
+ >
+ </a>
+ <figcaption>
+ <p>Zion National Park</p>
+ </figcaption>
+</figure>
+```
+
+Which looks like this in your browser:
+
+{{< figure
+ src="/images/examples/zion-national-park.jpg"
+ alt="A photograph of Zion National Park"
+ link="https://www.nps.gov/zion/index.htm"
+ caption="Zion National Park"
+ class="ma0 w-75"
+>}}
+
+## Parameters
+
+src
+: (`string`) The `src` attribute of the `img` element. Typically this is a [page resource](g) or a [global resource](g).
+
+alt
+: (`string`) The `alt` attribute of the `img` element.
+
+width
+: (`int`) The `width` attribute of the `img` element.
+
+height
+: (`int`) The `height` attribute of the `img` element.
+
+loading
+: (`string`) The `loading` attribute of the `img` element.
+
+class
+: (`string`) The `class` attribute of the `figure` element.
+
+link
+: (`string`) The `href` attribute of the anchor element that wraps the `img` element.
+
+target
+: (`string`) The `target` attribute of the anchor element that wraps the `img` element.
+
+rel
+: (`rel`) The `rel` attribute of the anchor element that wraps the `img` element.
+
+title
+: (`string`) Within the `figurecaption` element, the title is at the top, wrapped within an `h4` element.
+
+caption
+: (`string`) Within the `figurecaption` element, the caption is at the bottom and may contain plain text or markdown.
+
+attr
+: (`string`) Within the `figurecaption` element, the attribution appears next to the caption and may contain plain text or markdown.
+
+attrlink
+: (`string`) The `href` attribute of the anchor element that wraps the attribution.
+
+## Image location
+
+The `figure` shortcode resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
+
+You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration:
+
+{{< code-toggle file=hugo >}}
+[[module.mounts]]
+source = 'assets'
+target = 'assets'
+
+[[module.mounts]]
+source = 'static'
+target = 'assets'
+{{< /code-toggle >}}
--- /dev/null
+---
+title: Gist
+description: Embed a GitHub Gist in your content using the gist shortcode.
+categories: [shortcodes]
+keywords: []
+menu:
+ docs:
+ parent: shortcodes
+ weight:
+weight:
+---
+
+{{% note %}}
+To override Hugo's embedded `gist` shortcode, copy the [source code] to a file with the same name in the `layouts/shortcodes` directory.
+
+[source code]: {{% eturl gist %}}
+{{% /note %}}
+
+To display a GitHub gist with this URL:
+
+```text
+https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b
+```
+
+Include this in your Markdown:
+
+```text
+{{</* gist user 23932424365401ffa5e9d9810102a477 */>}}
+```
+
+This will display all files in the gist alphabetically by file name.
+
+{{< gist jmooring 23932424365401ffa5e9d9810102a477 >}}
+
+To display a specific file within the gist:
+
+```text
+{{</* gist user 23932424365401ffa5e9d9810102a477 list.html */>}}
+```
+
+{{< gist jmooring 23932424365401ffa5e9d9810102a477 list.html >}}
--- /dev/null
+---
+title: Highlight
+description: Insert syntax-highlighted code into your content using the highlight shortcode.
+categories: [shortcodes]
+keywords: []
+menu:
+ docs:
+ parent: shortcodes
+ weight:
+weight:
+toc: true
+---
+
+{{% 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.
+
+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/
+
+## Arguments
+
+The `highlight` shortcode takes three arguments.
+
+```text
+{{</* highlight LANG OPTIONS */>}}
+CODE
+{{</* /highlight */>}}
+```
+
+CODE
+: (`string`) The code to highlight.
+
+LANG
+: (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
+
+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" */>}}
+package main
+
+import "fmt"
+
+func main() {
+ for i := 0; i < 3; i++ {
+ fmt.Println("Value of i:", i)
+ }
+}
+{{</* /highlight */>}}
+```
+
+Hugo renders this to:
+
+{{< highlight go "linenos=inline, hl_Lines=3 6-8, noClasses=true" >}}
+package main
+
+import "fmt"
+
+func main() {
+ for i := 0; i < 3; i++ {
+ fmt.Println("Value of i:", i)
+ }
+}
+{{< /highlight >}}
+
+You can also use the `highlight` shortcode for inline code snippets:
+
+```text
+This is some {{</* highlight go "hl_inline=true" */>}}fmt.Println("inline"){{</* /highlight */>}} code.
+```
+
+Hugo renders this to:
+
+This is some {{< highlight go "hl_inline=true, noClasses=true" >}}fmt.Println("inline"){{< /highlight >}} code.
+
+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 >}}
+{{ $code := .Inner | strings.TrimSpace }}
+{{ $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.
+```
+
+Hugo renders this to:
+
+This is some {{< hl >}}fmt.Println("inline"){{< /hl >}} code.
+
+## Options
+
+Pass the options when calling the shortcode. You can set their default values in your [site configuration].
+
+{{% include "functions/_common/highlighting-options" %}}
--- /dev/null
+---
+title: Instagram
+description: Embed an Instagram post in your content using the instagram shortcode.
+categories: [shortcodes]
+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 %}}
+
+## Example
+
+To display an Instagram post with this URL:
+
+```text
+https://www.instagram.com/p/CxOWiQNP2MO/
+```
+
+Include this in your Markdown:
+
+```text
+{{</* instagram CxOWiQNP2MO */>}}
+```
+
+Huge renders this to:
+
+{{< instagram CxOWiQNP2MO >}}
+
+## Privacy
+
+Adjust the relevant privacy settings in your site configuration.
+
+{{< code-toggle config=privacy.instagram />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+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`.
--- /dev/null
+---
+title: Param
+description: Insert a parameter from front matter or site configuration into your content using the param shortcode.
+categories: [shortcodes]
+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 %}}
+
+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 >}}
+---
+title: Example
+date: 2025-01-15T23:29:46-08:00
+params:
+ color: red
+ size: medium
+---
+
+We found a {{</* param "color" */>}} shirt.
+{{< /code >}}
+
+Hugo renders this to:
+
+```html
+<p>We found a red shirt.</p>
+```
+
+Access nested values by [chaining](g) the [identifiers](g):
+
+```text
+{{</* param my.nested.param */>}}
+```
--- /dev/null
+---
+title: QR
+description: Insert a QR code into your content using the qr shortcode.
+categories: [shortcodes]
+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 %}}
+
+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:
+
+```text
+{{</* qr text="https://gohugo.io" /*/>}}
+```
+
+Or insert the text between the opening and closing tags:
+
+```text
+{{</* qr */>}}
+https://gohugo.io
+{{</* /qr */>}}
+```
+
+Both of the above produce this image:
+
+{{< qr text="https://gohugo.io" class="qrcode" />}}
+
+To create a QR code for a phone number:
+
+```text
+{{</* qr text="tel:+12065550101" /*/>}}
+```
+
+{{< qr text="tel:+12065550101" class="qrcode" />}}
+
+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
+VERSION:2.1
+N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD
+FN;CHARSET=UTF-8:Dr. John R. Smith, PhD.
+ORG;CHARSET=UTF-8:ABC Widgets
+TITLE;CHARSET=UTF-8:Vice President Engineering
+TEL;TYPE=WORK:+12065550101
+EMAIL;TYPE=WORK:jsmith@example.org
+END:VCARD
+{{</* /qr */>}}
+```
+
+{{< qr level="low" scale=2 alt="QR code of vCard for John Smith" class="qrcode" >}}
+BEGIN:VCARD
+VERSION:2.1
+N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD
+FN;CHARSET=UTF-8:Dr. John R. Smith, PhD.
+ORG;CHARSET=UTF-8:ABC Widgets
+TITLE;CHARSET=UTF-8:Vice President Engineering
+TEL;TYPE=WORK:+12065550101
+EMAIL;TYPE=WORK:jsmith@example.org
+END:VCARD
+{{< /qr >}}
+
+## Parameters
+
+text
+: (`string`) The text to encode, falling back to the text between the opening and closing shortcode tags.
+
+level
+: (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`.
+
+scale
+: (`int`) The number of image pixels per QR code module. Must be greater than or equal to 2. Default is `4`.
+
+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.
+
+class
+: (`string`) The `class` attribute of the `img` element.
+
+id
+: (`string`) The `id` attribute of the `img` element.
+
+title
+: (`string`) The `title` attribute of the `img` element.
--- /dev/null
+---
+title: Ref
+description: Insert a permalink to the given page reference using the ref shortcode.
+categories: [shortcodes]
+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.
+
+[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.
+
+[content format]: /content-management/formats/
+[link render hooks]: /render-hooks/images/#default
+{{% /note %}}
+
+The `ref` shortcode returns the permalink of the given page reference.
+
+Example usage:
+
+```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" */%}})
+```
+
+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>
+```
+
+{{% note %}}
+Always use the `{{%/* */%}}` notation when calling this shortcode.
+{{% /note %}}
--- /dev/null
+---
+title: Relref
+description: Insert a relative permalink to the given page reference using the relref shortcode.
+categories: [shortcodes]
+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.
+
+[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.
+
+[content format]: /content-management/formats/
+[link render hooks]: /render-hooks/links/
+{{% /note %}}
+
+The `relref` shortcode returns the relative permalink of the given page reference.
+
+Example usage:
+
+```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" */%}})
+```
+
+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>
+```
+
+{{% note %}}
+Always use the `{{%/* */%}}` notation when calling this shortcode.
+{{% /note %}}
--- /dev/null
+---
+title: Vimeo
+description: Embed a Vimeo video in your content using the vimeo shortcode.
+categories: [shortcodes]
+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 %}}
+
+## Example
+
+To display a Vimeo video with this URL:
+
+```text
+https://vimeo.com/channels/staffpicks/55073825
+```
+
+Include this in your Markdown:
+
+```text
+{{</* vimeo 55073825 */>}}
+```
+
+Hugo renders this to:
+
+{{< vimeo 55073825 >}}
+
+## Parameters
+
+class
+: (`string`) The `class` attribute of the wrapping `div` element. Adding one or more CSS classes disables inline styling.
+
+id
+: (`string`) The `id` of the Vimeo video
+
+title
+: (`string`) The `title` attribute of the `iframe` element.
+
+If you proivde a `class` or `title` you must use a named parameter for the `id`.
+
+```text
+{{</* vimeo id=55073825 class="foo bar" title="My Video" */>}}
+```
+
+## Privacy
+
+Adjust the relevant privacy settings in your site configuration.
+
+{{< code-toggle config=privacy.vimeo />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+enableDNT
+: (`bool`) Whether to block the Vimeo player from tracking session data and analytics. Default is `false`.
+
+simple
+: (`bool`) Whether to enable simple mode. If `true`, the video thumbnail is fetched from Vimeo and overlaid with a play button. Clicking the thumbnail opens the video in a new Vimeo tab. Default is `false`.
+
+The source code for the simple version of the shortcode is available [here].
+
+[here]: {{% eturl vimeo_simple %}}
--- /dev/null
+---
+title: X
+description: Embed an X post in your content using the x shortcode.
+categories: [shortcodes]
+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 %}}
+
+## Example
+
+To display an X post with this URL:
+
+```txt
+https://x.com/SanDiegoZoo/status/1453110110599868418
+```
+
+Include this in your Markdown:
+
+```text
+{{</* x user="SanDiegoZoo" id="1453110110599868418" */>}}
+```
+
+Rendered:
+
+{{< x user="SanDiegoZoo" id="1453110110599868418" >}}
+
+## Privacy
+
+Adjust the relevant privacy settings in your site configuration.
+
+{{< code-toggle config=privacy.x />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+enableDNT
+: (`bool`) Whether to prevent X from using post and embedded page data for personalized suggestions and ads. Default is `false`.
+
+simple
+: (`bool`) Whether to enable simple mode. If `true`, Hugo builds a static version of the of the post without JavaScript. Default is `false`.
+
+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 />}}
--- /dev/null
+---
+title: YouTube
+description: Embed a YouTube video in your content using the youtube shortcode.
+categories: [shortcodes]
+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 %}}
+
+## Example
+
+To display a YouTube video with this URL:
+
+```text
+https://www.youtube.com/watch?v=0RKpf3rK57I
+```
+
+Include this in your Markdown:
+
+```text
+{{</* youtube 0RKpf3rK57I */>}}
+```
+
+Hugo renders this to:
+
+{{< youtube 0RKpf3rK57I >}}
+
+## Parameters
+
+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 >}}
+: (`bool`) Whether the `iframe` element can activate full screen mode. Default is `true`.
+
+autoplay
+ {{< 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 >}}
+: (`bool`) Whether to display the video controls. Default is `true`.
+
+end
+{{< 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 >}}
+: (`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`.
+
+mute
+{{< 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 >}}
+: (`int`) The time, measured in seconds from the start of the video, when the player should start playing the video.
+
+title
+: (`string`) The `title` attribute of the `iframe` element. Defaults to "YouTube video".
+
+Example using some of the above:
+
+```text
+{{</* youtube id=0RKpf3rK57I start=30 end=60 loading=lazy */>}}
+```
+
+## Privacy
+
+Adjust the relevant privacy settings in your site configuration.
+
+{{< code-toggle config=privacy.youTube />}}
+
+disable
+: (`bool`) Whether to disable the shortcode. Default is `false`.
+
+privacyEnhanced
+: (`bool`) Whether to block YouTube from storing information about visitors on your website unless the user plays the embedded video. Default is `false`.
**Hugo is FAST**. Our previous static site generator took nearly a minute to compile our (then much smaller) site. Developers might be used to this, but it wasn't cutting it for writers who wanted to see live previews of their work. Hugo did the same job in milliseconds, and to this day compiles 400 pages in five languages in the blink of an eye.
-**Hugo is flexible**. Thanks to Hugo's content and layout system, we were able to preserve our existing file and folder structure and port our entire production site in a few days. We could then create new content types that weren't possible before, like these snazzy [showcases](https://support.1password.com/explore/extension/).
+**Hugo is flexible**. Thanks to Hugo's content and layout system, we were able to preserve our existing file and directory structure and port our entire production site in a few days. We could then create new content types that weren't possible before, like these snazzy [showcases](https://support.1password.com/explore/extension/).
**Hugo is great for writers**. Our documentation team was already comfortable with Markdown and Git and could start creating content for Hugo with zero downtime. Once we added shortcodes, our writers were able to dress up articles with features like [platform boxes](https://support.1password.com/get-the-apps/) with just a bit of new syntax.
---
title: Showcases
draft: true
----
\ No newline at end of file
+---
---
-This project was such a blast to develop, it’s a real pleasure to put new technologies to good use in production, and to see real performance and usability benefits from them. Even using classic web methods of serving folders with files is fun when you’ve been using dynamic systems for a while – there’s something really pure about it.
+This project was such a blast to develop, it’s a real pleasure to put new technologies to good use in production, and to see real performance and usability benefits from them. Even using classic web methods of serving directories with files is fun when you’ve been using dynamic systems for a while – there’s something really pure about it.
---
The **Let’s Encrypt website** has a common set of elements: A landing page and some other static info-pages, a document section, a blog, and a documentation section. Having it moved to Hugo was mostly motivated by a _simpler administration and Hugo's [multilingual support](/content-management/multilingual/)_. They already serve HTTPS to more than 60 million domains, and having the documentation available in more languages will increase that reach.[^1]
-{{< tweet user="letsencrypt" id="971755920639307777" >}}
+{{< x user="letsencrypt" id="971755920639307777" >}}
I helped them port the site from Jekyll to Hugo. There are usually very few surprises doing this. I know Hugo very well, but working on sites with a history usually comes up with something new.
The site is built by:
* [Tobias Kummer](https://www.overmind-studios.de/about/)
-
Please:
1. Fork https://github.com/gohugoio/hugoDocs.
-2. Run `hugo new content showcase/your-site`. This will use the archetype bundle in the [docs repo](https://github.com/gohugoio/hugoDocs/tree/master/archetypes).
-3. Follow the instructions in the newly created page bundle.
-4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls.
+1. Run `hugo new content showcase/your-site`. This will use the archetype bundle in the [docs repo](https://github.com/gohugoio/hugoDocs/tree/master/archetypes).
+1. Follow the instructions in the newly created page bundle.
+1. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls.
[^1]: We want this to show Hugo in its best light, so this is not for the average Hugo blog. In most cases the answer to "Is my site [notable](https://www.dictionary.com/browse/notable)?" will be obvious, but if in doubt, create an [issue](https://github.com/gohugoio/hugoDocs/issues) with a link and some words, and we can discuss it. But if you have a site with an interesting Hugo story or a company site where the company itself is notable, you are most welcome.
weight: 160
---
-To render a 404 error page in the root of your site, create a 404 template in the root of the layouts directory. For example:
+To render a 404 error page in the root of your site, create a 404 template in the root of the `layouts` directory. For example:
{{< code file=layouts/404.html >}}
{{ define "main" }}
aliases: [/templates/overview/,/templates/content]
---
-A template is an HTML file with [template actions](/getting-started/glossary/#template-action), located within the layouts directory of a project, theme, or module. Visit the topics below, in the order presented, to understand template selection and creation.
+A template is an HTML file with [template actions](g), located within the `layouts` directory of a project, theme, or module. Visit the topics below, in the order presented, to understand template selection and creation.
To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single template], `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view.
```txt
- ▾ layouts/
- ▾ posts/
- li.html
- single.html
- summary.html
- ▾ project/
- li.html
- single.html
- summary.html
+layouts/
+├── posts/
+│ ├── li.html
+│ ├── single.html
+│ └── summary.html
+├── project/
+│ ├── li.html
+│ └── single.html
+└── summary.html
```
## Which template will be rendered?
## Disqus
{{% note %}}
-To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
`{{ partial "disqus.html" . }}`
## Google Analytics
{{% note %}}
-To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
`{{ partial "google_analytics.html" . }}`
## Open Graph
{{% note %}}
-To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
`{{ partial "opengraph.html" . }}`
## Schema
{{% note %}}
-To override Hugo's embedded Schema template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+To override Hugo's embedded Schema template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
`{{ partial "schema.html" . }}`
## X (Twitter) Cards
{{% note %}}
-To override Hugo's embedded Twitter Cards template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+To override Hugo's embedded Twitter Cards template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
`{{ partial "twitter_cards.html" . }}`
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.
-
{{< youtube ut1xtRZ1QOA >}}
## Home template lookup order
## Add content and front matter to the home page
-The home page accepts content and front matter from an `_index.md` file. This file should live at the root of your `content` folder (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.
+The home page accepts content and front matter from an `_index.md` 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.
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.
toc: true
---
-A template is a file in the layouts directory of a project, theme, or module. Templates use [variables] , [functions], and [methods] to transform your content, resources, and data into a published page.
+A template is a file in the `layouts` directory of a project, theme, or module. Templates use [variables] , [functions], and [methods] to transform your content, resources, and data into a published page.
[functions]: /functions/
[methods]: /methods/
## Context
-The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects] and associated [methods].
-
-[objects]: /getting-started/glossary/#object
-[methods]: /getting-started/glossary/#method
+The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects](g) and associated [methods](g).
For example, a template for a single page receives a `Page` object, and the `Page` object provides methods to return values or perform actions.
{{ end }}
{{< /code >}}
-In the example above, the context changes as we `range` through the [slice] of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to:
-
-[slice]: /getting-started/glossary/#slice
+In the example above, the context changes as we `range` through the [slice](g) of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to:
```html
<h2>My Page Title</h2>
In the examples above the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template.
-A template action may contain literal values ([boolean], [string], [integer], and [float]), variables, functions, and methods.
-
-[boolean]: /getting-started/glossary/#boolean
-[string]: /getting-started/glossary/#string
-[integer]: /getting-started/glossary/#integer
-[float]: /getting-started/glossary/#float
+A template action may contain literal values ([boolean](g), [string](g), [integer](g), and [float](g)), variables, functions, and methods.
{{< code file=layouts/_default/single.html >}}
{{ $convertToLower := true }}
### Pipes
-Within a template action you may [pipe] a value to a function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent:
-
-[pipe]: /getting-started/glossary/#pipeline
+Within a template action you may [pipe](g) a value to a function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent:
```go-html-template
{{ strings.ToLower "Hugo" }} → hugo
}}
```
-You can also split [raw string literals] over two or more lines. For example, these are equivalent:
-
-[raw string literals]: /getting-started/glossary/#string-literal-raw
+You can also split [raw string literals](g) over two or more lines. For example, these are equivalent:
```go-html-template
{{ $msg := "This is line one.\nThis is line two." }}
## Variables
-A variable is a user-defined [identifier] prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
-
-[identifier]: /getting-started/glossary/#identifier
+A variable is a user-defined [identifier](g) prepended with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables.
-Variables may contain [scalars], [slices], [maps], or [objects].
-
-[scalars]: /getting-started/glossary/#scalar
-[slices]: /getting-started/glossary/#slice
-[maps]: /getting-started/glossary/#map
-[objects]: /getting-started/glossary/#object
+Variables may contain [scalars](g), [slices](g), [maps](g), or [objects](g).
Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. For example:
Slices and arrays are zero-based; element 0 is the first element.
{{% /note %}}
-With variables that represent a map or object, [chain] identifiers to return the desired value or to access the desired method.
-
-[chain]: /getting-started/glossary/#chain
+With variables that represent a map or object, [chain](g) identifiers to return the desired value or to access the desired method.
```go-html-template
{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }}
`Page`|[`Date`](methods/page/date/)|Returns the date of the given page.
`Page`|[`Params`](methods/page/params/)|Returns a map of custom parameters as defined in the front matter of the given page.
`Page`|[`Title`](methods/page/title/)|Returns the title of the given page.
-`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the data directory.
+`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the `data` directory.
`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in the site configuration.
`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the site configuration.
[`partial`]: /functions/partials/include/
[`partialCached`]: /functions/partials/includecached/
-[`template`]: functions/go-template/template/
+[`template`]: /functions/go-template/template/
Use the [`partial`] or [`partialCached`] function to include one or more [partial templates]:
: Is relevant for `section`, `taxonomy` and `term` types.
{{% note %}}
-Templates can live in either the project's or the themes' layout folders, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
+Templates can live in either the project's or the themes' `layout` directories, and the most specific templates will be chosen. Hugo will interleave the lookups listed below, finding the most specific one either in the project or themes.
{{% /note %}}
## Target a template
└── contact.md
```
-Files in the root of the content directory have a [content type] of `page`. To render these pages with a unique template, create a matching subdirectory:
-
-[content type]: /getting-started/glossary/#content-type
+Files in the root of the `content` directory have a [content type](g) of `page`. To render these pages with a unique template, create a matching subdirectory:
```text
layouts/
## Terminology
paginate
-: To split a [list page] into two or more subsets.
+: To split a [list page](g) into two or more subsets.
pagination
: The process of paginating a list page.
paginator
: A collection of pagers.
-[list page]: /getting-started/glossary/#list-page
-
## Configuration
Control pagination behavior in your site configuration. These are the default settings:
In the example above, we:
1. Build a page collection
-2. Sort the page collection by title
-3. Paginate the page collection, with 7 pages per pager
-4. Range over the paginated page collection, rendering a link to each page
-5. Call the embedded pagination template to create navigation links between pagers
-
+1. Sort the page collection by title
+1. Paginate the page collection, with 7 pages per pager
+1. Range over the paginated page collection, rendering a link to each page
+1. Call the embedded pagination template to create navigation links between pagers
To paginate a list page using the `Paginator` method:
In the example above, we:
1. Paginate the page collection passed into the template, with the default number of pages per pager
-2. Range over the paginated page collection, rendering a link to each page
-3. Call the embedded pagination template to create navigation links between pagers
+1. Range over the paginated page collection, rendering a link to each page
+1. Call the embedded pagination template to create navigation links between pagers
## Caching
```
{{% note %}}
-To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function:
+To override Hugo's embedded pagination template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function:
`{{ partial "pagination.html" . }}`
├── head/
│ ├── favicons.html
│ ├── metadata.html
- │ ├── prerender.html
- │ └── twitter.html
+ │ └── prerender.html
└── header/
├── site-header.html
└── site-nav.html
You may overwrite the internal template with a custom template. Hugo selects the template using this lookup order:
1. `/layouts/robots.txt`
-2. `/themes/<THEME>/layouts/robots.txt`
+1. `/themes/<THEME>/layouts/robots.txt`
## robots.txt template example
To create a robots.txt file without using a template:
1. Set `enableRobotsTXT` to `false` in the site configuration.
-2. Create a robots.txt file in the `static` directory.
+1. Create a robots.txt file in the `static` directory.
-Remember that Hugo copies everything in the [static directory][static] to the root of `publishDir` (typically `public`) when you build your site.
+Remember that Hugo copies everything in the [`static` directory][static] to the root of `publishDir` (typically `public`) when you build your site.
[static]: /getting-started/directory-structure/
{{% /note %}}
term = ['html']
{{< /code-toggle >}}
-To disable feed generation for all [page kinds]:
-
-[page kinds]: /getting-started/glossary/#page-kind
+To disable feed generation for all [page kinds](g):
{{< code-toggle file=hugo >}}
disableKinds = ['rss']
Shortcode name|Output format|Language|Template path
:--|:--|:--|:--
-foo|html|en|layouts/shortcodes/foo.en.html
-foo|html|en|layouts/shortcodes/foo.html.html
-foo|html|en|layouts/shortcodes/foo.html
-foo|html|en|layouts/shortcodes/foo.html.en.html
+foo|html|en|`layouts/shortcodes/foo.en.html`
+foo|html|en|`layouts/shortcodes/foo.html.html`
+foo|html|en|`layouts/shortcodes/foo.html`
+foo|html|en|`layouts/shortcodes/foo.html.en.html`
Shortcode name|Output format|Language|Template path
:--|:--|:--|:--
-foo|rss|en|layouts/shortcodes/foo.en.xml
-foo|rss|en|layouts/shortcodes/foo.rss.xml
-foo|rss|en|layouts/shortcodes/foo.en.html
-foo|rss|en|layouts/shortcodes/foo.rss.en.xml
-foo|rss|en|layouts/shortcodes/foo.xml
-foo|rss|en|layouts/shortcodes/foo.html.en.html
-foo|rss|en|layouts/shortcodes/foo.html.html
-foo|rss|en|layouts/shortcodes/foo.html
+foo|rss|en|`layouts/shortcodes/foo.en.xml`
+foo|rss|en|`layouts/shortcodes/foo.rss.xml`
+foo|rss|en|`layouts/shortcodes/foo.en.html`
+foo|rss|en|`layouts/shortcodes/foo.rss.en.xml`
+foo|rss|en|`layouts/shortcodes/foo.xml`
+foo|rss|en|`layouts/shortcodes/foo.html.en.html`
+foo|rss|en|`layouts/shortcodes/foo.html.html`
+foo|rss|en|`layouts/shortcodes/foo.html`
Note that templates provided by a theme or module always take precedence.
[`Name`]: /methods/shortcode/name/
[`Position`]: /methods/shortcode/position/
[built-in shortcode]: /content-management/shortcodes/
-[figure]: /content-management/shortcodes/#figure
+[figure]: /shortcodes/figure/
[lookup order]: /templates/lookup-order/
[source organization]: /getting-started/directory-structure/
[vimeoexample]: #single-flexible-example-vimeo
-[youtubeshortcode]: /content-management/shortcodes/#youtube
+[youtubeshortcode]: /shortcodes/youtube/
To override the built-in sitemap.xml template, create a new file in either of these locations:
-- layouts/sitemap.xml
-- layouts/_default/sitemap.xml
+- `layouts/sitemap.xml`
+- `layouts/_default/sitemap.xml`
When ranging through the page collection, access the _change frequency_ and _priority_ with `.Sitemap.ChangeFreq` and `.Sitemap.Priority` respectively.
To override the built-in sitemapindex.xml template, create a new file in either of these locations:
-- layouts/sitemapindex.xml
-- layouts/_default/sitemapindex.xml
+- `layouts/sitemapindex.xml`
+- `layouts/_default/sitemapindex.xml`
## Disable sitemap generation
{{</ code-toggle >}}
[`publishDir`]: /getting-started/configuration#publishdir
-[sitemap protocol]: <https://www.sitemaps.org/protocol.html>
+[sitemap protocol]: https://www.sitemaps.org/protocol.html
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy-templates/]
---
-The [taxonomy] template below inherits the site's shell from the [base template], and renders a list of [terms] in the current taxonomy.
+The [taxonomy](g) template below inherits the site's shell from the [base template], and renders a list of [terms](g) in the current taxonomy.
-[taxonomy]: /getting-started/glossary/#taxonomy
-[terms]: /getting-started/glossary/#term
[base template]: /templates/types/
{{< code file=layouts/_default/taxonomy.html >}}
```
Terms
-: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages] associated with each term.
-
-[weighted pages]: /getting-started/glossary/#weighted-page
+: (`page.Taxonomy`) Returns the `Taxonomy` object, consisting of a map of terms and the [weighted pages](g) associated with each term.
```go-html-template
{{ $taxonomyObject := .Data.Terms }}
## Include content links
-The [`Alphabetical`] and [`ByCount`] methods used in the previous examples return an [ordered taxonomy], so we can also list the content to which each term is assigned.
+The [`Alphabetical`] and [`ByCount`] methods used in the previous examples return an [ordered taxonomy](g), so we can also list the content to which each term is assigned.
-[ordered taxonomy]: /getting-started/glossary/#ordered-taxonomy
[`Alphabetical`]: /methods/taxonomy/alphabetical/
[`ByCount`]: /methods/taxonomy/bycount/
## Display metadata
-Display metadata about each term by creating a corresponding branch bundle in the content directory.
+Display metadata about each term by creating a corresponding branch bundle in the `content` directory.
For example, create an "authors" taxonomy:
author = 'authors'
{{< /code-toggle >}}
-Then create content with one [branch bundle] for each term:
-
-[branch bundle]: /getting-started/glossary/#branch-bundle
+Then create content with one [branch bundle](g) for each term:
```text
content/
toc: true
---
-The [term] template below inherits the site's shell from the [base template], and renders a list of pages associated with the current term.
+The [term](g) template below inherits the site's shell from the [base template], and renders a list of pages associated with the current term.
-[term]: /getting-started/glossary/#term
[base template]: /templates/types/
{{< code file=layouts/_default/term.html >}}
## Display metadata
-Display metadata about each term by creating a corresponding branch bundle in the content directory.
+Display metadata about each term by creating a corresponding branch bundle in the `content` directory.
For example, create an "authors" taxonomy:
author = 'authors'
{{< /code-toggle >}}
-Then create content with one [branch bundle] for each term:
-
-[branch bundle]: /getting-started/glossary/#branch-bundle
+Then create content with one [branch bundle](g) for each term:
```text
content/
## Structure
-Create templates in the layouts directory in the root of your project.
+Create templates in the `layouts` directory in the root of your project.
Although your site may not require each of these templates, the example below is typical for a site of medium complexity.
## Taxonomy
-A taxonomy template renders a list of terms in a [taxonomy].
-
-[taxonomy]: /getting-started/glossary/#taxonomy
+A taxonomy template renders a list of terms in a [taxonomy](g).
For example, the taxonomy template below inherits the site's shell from the base template, and renders a list of terms in the current taxonomy.
## Term
-A term template renders a list of pages associated with a [term].
-
-[term]: /getting-started/glossary/#term
+A term template renders a list of pages associated with a [term](g).
For example, the term template below inherits the site's shell from the base template, and renders a list of pages associated with the current term.
A shortcode template is used to render a component of your site. Unlike partial templates, shortcode templates are called from content pages.
-For example, the shortcode template below renders an audio element from a [global resource].
-
-[global resource]: /getting-started/glossary/#global-resource
+For example, the shortcode template below renders an audio element from a [global resource](g).
{{< code file=layouts/shortcodes/audio.html >}}
{{ with resources.Get (.Get "src") }}
## DokuWiki
[dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo)
-: Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extras like the TODO plugin. Written with extensibility in mind using Python 3. Also generates a TOML header for each page. Designed to copy-paste the wiki directory into your /content directory.
+: Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extras like the TODO plugin. Written with extensibility in mind using Python 3. Also generates a TOML header for each page. Designed to copy-paste the wiki directory into your `content` directory.
## WordPress
[Hugo Lyra](https://github.com/paolomainardi/hugo-lyra)
: Hugo-Lyra is a JavaScript module to integrate [Lyra](https://github.com/LyraSearch/lyra) into a Hugo website. It contains the server-side part to generate the index and the client-side library (optional) to bootstrap the search engine easily.
-[INFINI Pizza for WebAssembly](https://github.com/infinilabs/pizza-docsearch)
+[INFINI Pizza for WebAssembly](https://github.com/infinilabs/pizza-docsearch)
: Pizza is a super-lightweight yet fully featured search engine written in Rust. You can quickly add offline search functionality to your Hugo website in just five minutes with only three lines of code. For a step-by-step guide on integrating it with Hugo, check out [this blog tutorial](https://dev.to/medcl/adding-search-functionality-to-a-hugo-static-site-based-on-infini-pizza-for-webassembly-4h5e).
-
## Commercial
[Algolia](https://www.algolia.com/)
When a project _deprecates_ something, they are telling its users:
1. Don't use Thing One anymore.
-2. Use Thing Two instead.
-3. We're going to remove Thing One at some point in the future.
+1. Use Thing Two instead.
+1. We're going to remove Thing One at some point in the future.
[reasons for deprecation]: https://en.wikipedia.org/wiki/Deprecation
After the project team deprecates something in code, Hugo will:
1. Log an INFO message for 6 minor releases[^1]
-2. Log a WARN message for another 6 minor releases
-3. Log an ERROR message and fail the build thereafter
+1. Log a WARN message for another 6 minor releases
+1. Log an ERROR message and fail the build thereafter
To see the INFO messages, you must use the `--logLevel` command line flag:
parent: troubleshooting
weight: 70
weight: 70
-# Use level 6 headings for each question.
---
Hugo’s [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question.
###### Why do I see "Page Not Found" when visiting the home page?
-In the content/_index.md file:
+In the `content/_index.md` file:
- Is `draft` set to `true`?
- Is the `date` in the future?
###### Why is a given page not published?
-In the content/section/page.md file, or in the content/section/page/index.md file:
+In the `content/section/page.md` file, or in the `content/section/page/index.md` file:
- - Is `draft` set to `true`?
- - Is the `date` in the future?
- - Is the `publishDate` in the future?
- - Is the `expiryDate` in the past?
+- Is `draft` set to `true`?
+- Is the `date` in the future?
+- Is the `publishDate` in the future?
+- Is the `expiryDate` in the past?
If the answer to any of these questions is yes, either change the field values, or use one of these command line flags: `--buildDrafts`, `--buildFuture`, or `--buildExpired`.
###### Why can't I see any of a page's descendants?
-You may have an index.md file instead of an _index.md file. See [details](/content-management/page-bundles/).
+You may have an `index.md` file instead of an `_index.md` file. See [details](/content-management/page-bundles/).
###### What is the difference between an index.md file and an _index.md file?
-A directory with an index.md file is a [leaf bundle]. A directory with an _index.md file is a [branch bundle]. See [details](/content-management/page-bundles/).
-
-[branch bundle]: /getting-started/glossary/#branch-bundle
-[leaf bundle]: /getting-started/glossary/#leaf-bundle
+A directory with an `index.md file` is a [leaf bundle](g). A directory with an `_index.md` file is a [branch bundle](g). See [details](/content-management/page-bundles/).
###### Why is my partial template not rendered as expected?
-You may have neglected to pass the required [context] when calling the partial. For example:
+You may have neglected to pass the required [context](g) when calling the partial. For example:
```go-html-template
{{/* incorrect */}}
###### Why is my page Scratch or Store missing a value?
-The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a [scratch pad] on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
-
-[scratch pad]: /getting-started/glossary/#scratch-pad
-
-If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop] variable:
+The [`Scratch`] and [`Store`] methods on a `Page` object allow you to create a [scratch pad](g) on the given page to store and manipulate data. Values are often set within a shortcode, a partial template called by a shortcode, or by a Markdown render hook. In all three cases, the scratch pad values are not determinate until Hugo renders the page content.
-[noop]: /getting-started/glossary/#noop
+If you need to access a scratch pad value from a parent template, and the parent template has not yet rendered the page content, you can trigger content rendering by assigning the returned value to a [noop](g) variable:
```go-html-template
{{ $noop := .Content }}
[`Paginate`]: /methods/page/paginate/
[`Paginator`]: /methods/page/paginator/
-[context]: /getting-started/glossary/#context
[forum]: https://discourse.gohugo.io
[installation]: /installation/
[requesting help]: https://discourse.gohugo.io/t/requesting-help/9132
: The number of times the template was executed.
template
-: The path to the template, relative to the layouts directory.
+: The path to the template, relative to the `layouts` directory.
[`partial`]: /functions/partials/include/
[`partialCached`]: /functions/partials/includecached/
## Timers
-Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates. See [details](/functions/debug/timer/).
+Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottlenecks in templates. See [details](/functions/debug/timer/).
- Aliases:
- armasm
Name: ArmAsm
+ - Aliases:
+ - atl
+ Name: ATL
- Aliases:
- autohotkey
- ahk
- dosbatch
- winbatch
Name: Batchfile
+ - Aliases:
+ - beef
+ Name: Beef
- Aliases:
- bib
- bibtex
- Aliases:
- css
Name: CSS
+ - Aliases:
+ - csv
+ Name: CSV
- Aliases:
- cue
Name: CUE
- Gherkin
Name: Gherkin
- Aliases:
- - gleam>
+ - gleam
Name: Gleam
- Aliases:
- glsl
- Aliases:
- json
Name: JSON
+ - Aliases:
+ - jsonata
+ Name: JSONata
+ - Aliases:
+ - jsonnet
+ Name: Jsonnet
- Aliases:
- julia
- jl
Name: Matlab
- Aliases:
- mcfunction
- Name: mcfunction
+ - mcf
+ Name: MCFunction
- Aliases:
- meson
- meson.build
- nixos
- nix
Name: Nix
+ - Aliases:
+ - nsis
+ - nsi
+ - nsh
+ Name: NSIS
- Aliases:
- objective-c
- objectivec
- Aliases:
- smarty
Name: Smarty
+ - Aliases:
+ - snbt
+ Name: SNBT
- Aliases:
- snobol
Name: Snobol
- Aliases:
- typoscripthtmldata
Name: TypoScriptHtmlData
+ - Aliases:
+ - typst
+ Name: Typst
- Aliases: null
Name: ucode
- Aliases:
- Aliases:
- wgsl
Name: WebGPU Shading Language
+ - Aliases:
+ - vtt
+ Name: WebVTT
- Aliases:
- whiley
Name: Whiley
dataDir: data
defaultContentLanguage: en
defaultContentLanguageInSubdir: false
+ defaultOutputFormat: html
deployment:
confirm: false
dryRun: false
lineNos: false
lineNumbersInTable: true
noClasses: true
- noHl: false
style: monokai
tabWidth: 4
wrapperClass: highlight
disable: false
enableDNT: false
simple: false
+ x:
+ disable: false
+ enableDNT: false
+ simple: false
youTube:
disable: false
privacyEnhanced: false
limit: -1
twitter:
disableInlineCSS: false
+ x:
+ disableInlineCSS: false
sitemap:
changeFreq: ""
disable: false
Args: null
Description: ""
Examples: null
+ Mask:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
Opacity:
Aliases: null
Args: null
Args: null
Description: ""
Examples: null
+ QR:
+ Aliases: null
+ Args: null
+ Description: ""
+ Examples: null
Saturation:
Aliases: null
Args: null
'google_analytics' = 'google_analytics.html'
'opengraph' = 'opengraph.html'
'pagination' = 'pagination.html'
-'schema' = 'schema.html'
-'twitter_cards' = 'twitter_cards.html'
-
'robots' = '_default/robots.txt'
'rss' = '_default/rss.xml'
+'schema' = 'schema.html'
'sitemap' = '_default/sitemap.xml'
'sitemapindex' = '_default/sitemapindex.xml'
+'twitter_cards' = 'twitter_cards.html'
# Render hooks
+'render-codeblock-goat' = '_default/_markup/render-codeblock-goat.html'
'render-image' = '_default/_markup/render-image.html'
'render-link' = '_default/_markup/render-link.html'
-'render-codeblock-goat' = '_default/_markup/render-codeblock-goat.html'
+'render-table' = '_default/_markup/render-table.html'
# Shortcodes
-'comment' = 'shortcodes/comment.html'
'details' = 'shortcodes/details.html'
'figure' = 'shortcodes/figure.html'
'gist' = 'shortcodes/gist.html'
'highlight' = 'shortcodes/highlight.html'
'instagram' = 'shortcodes/instagram.html'
'param' = 'shortcodes/param.html'
+'qr' = 'shortcodes/qr.html'
'ref' = 'shortcodes/ref.html'
'relref' = 'shortcodes/relref.html'
'twitter' = 'shortcodes/twitter.html'
+'twitter_simple' = 'shortcodes/twitter_simple.html'
'vimeo' = 'shortcodes/vimeo.html'
+'vimeo_simple' = 'shortcodes/vimeo_simple.html'
+'x' = 'shortcodes/x.html'
+'x_simple' = 'shortcodes/x_simple.html'
'youtube' = 'shortcodes/youtube.html'
go 1.22.0
-require github.com/gohugoio/gohugoioTheme v0.0.0-20250106044328-feb60697e056 // indirect
+require github.com/gohugoio/gohugoioTheme v0.0.0-20250116152525-2d382cae7743 // indirect
-github.com/gohugoio/gohugoioTheme v0.0.0-20250106044328-feb60697e056 h1:nPfHricsQXtVewK865bX2LDLhUImhIZEuajlYPM2Bho=
-github.com/gohugoio/gohugoioTheme v0.0.0-20250106044328-feb60697e056/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
+github.com/gohugoio/gohugoioTheme v0.0.0-20250116152525-2d382cae7743 h1:gjoqq8+RnGwpuU/LQVYGGR/LsDplrfUjOabWwoROYsM=
+github.com/gohugoio/gohugoioTheme v0.0.0-20250116152525-2d382cae7743/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
+++ /dev/null
-{
- "htmlElements": {
- "tags": [
- "",
- "a",
- "article",
- "aside",
- "blockquote",
- "body",
- "br",
- "button",
- "circle",
- "code",
- "date",
- "dd",
- "div",
- "dl",
- "dt",
- "em",
- "figcaption",
- "figure",
- "footer",
- "form",
- "g",
- "h1",
- "h2",
- "h3",
- "h4",
- "h5",
- "h6",
- "head",
- "header",
- "hr",
- "html",
- "i",
- "iframe",
- "img",
- "li",
- "link",
- "main",
- "meta",
- "nav",
- "noscript",
- "ol",
- "p",
- "path",
- "pre",
- "script",
- "section",
- "small",
- "span",
- "strong",
- "style",
- "sup",
- "svg",
- "table",
- "tbody",
- "td",
- "thead",
- "time",
- "title",
- "tr",
- "ul"
- ],
- "classes": [
- "!('about'",
- "!('content-management'",
- "!('contribute'",
- "!('functions'",
- "!('getting-started'",
- "!('hosting-and-deployment'",
- "!('modules'",
- "!('pipes'",
- "!('templates'",
- "!('tools'",
- "!('troubleshooting'",
- "!('variables'",
- "\u0026\u0026",
- "(false",
- "(true",
- "-ml-px",
- "-mr-12",
- "-mr-3",
- "-translate-x-3",
- "-translate-y-2",
- "absolute",
- "absolute-l",
- "active",
- "admonition",
- "admonition-content",
- "admonition-icon",
- "anchor",
- "b--moon-gray",
- "benchstat",
- "better",
- "bg-accent-color-dark",
- "bg-animate",
- "bg-black",
- "bg-carrot-500",
- "bg-cover",
- "bg-gradient-to-b",
- "bg-gray-100",
- "bg-gray-200",
- "bg-gray-300",
- "bg-gray-50",
- "bg-gray-600",
- "bg-gray-900",
- "bg-green-100",
- "bg-mango-300",
- "bg-mango-50",
- "bg-near-white",
- "bg-opacity-20",
- "bg-opacity-75",
- "bg-orange-500",
- "bg-steel-200",
- "bg-steel-500",
- "bg-steel-600",
- "bg-steel-800",
- "bg-steel-900",
- "bg-white",
- "blTK",
- "black",
- "block",
- "bmt1",
- "border",
- "border-0",
- "border-2",
- "border-b",
- "border-gray-100",
- "border-gray-200",
- "border-gray-300",
- "border-l",
- "border-none",
- "border-r",
- "border-solid",
- "border-t",
- "border-transparent",
- "bottom-0",
- "break-inside-avoid-l",
- "btn-primary",
- "c",
- "c1",
- "chroma",
- "clearfix",
- "cm",
- "code-copy-content",
- "code-toggle",
- "column-count-3-l",
- "column-gap-1-l",
- "configs",
- "copy",
- "cp",
- "cursor-pointer",
- "dark:bg-red-800",
- "dark:border-gray-800",
- "delta",
- "details",
- "dim",
- "disabled",
- "divide-gray-200",
- "divide-x",
- "err",
- "f2-fluid",
- "f6",
- "filename",
- "fill-current",
- "fixed",
- "fixed-lTK",
- "flex",
- "flex-1",
- "flex-auto",
- "flex-auto-ns",
- "flex-col",
- "flex-column",
- "flex-none",
- "flex-shrink-0",
- "flex-wrap",
- "fn",
- "focus:border-steel-500",
- "focus:outline-none",
- "focus:ring-1",
- "focus:ring-2",
- "focus:ring-inset",
- "focus:ring-offset-2",
- "focus:ring-steel-500",
- "focus:ring-white",
- "focus:z-10",
- "font-black",
- "font-bold",
- "font-extrabold",
- "font-extralight",
- "font-medium",
- "font-mono",
- "font-normal",
- "font-sans",
- "font-semibold",
- "footnote-backref",
- "footnote-ref",
- "footnotes",
- "from-primarydark",
- "gap-4",
- "ge",
- "grid",
- "grid-cols-1",
- "group",
- "grow",
- "gs",
- "gu",
- "h-0",
- "h-0.5",
- "h-10",
- "h-12",
- "h-16",
- "h-2",
- "h-32",
- "h-5",
- "h-6",
- "h-64",
- "h-8",
- "h-full",
- "h-screen",
- "h6",
- "hidden",
- "highlight",
- "hl",
- "hover",
- "hover-bg-green",
- "hover-bg-near-white",
- "hover-bg-primary-color",
- "hover-bg-primary-color-dark",
- "hover-blue",
- "hover:bg-gray-300",
- "hover:bg-gray-50",
- "hover:bg-steel-500",
- "hover:bg-steel-700",
- "hover:border",
- "hover:text-gray-200",
- "hover:text-gray-900",
- "hover:text-hotpink-400",
- "hover:text-hotpink-600",
- "hover:text-limegreen-900",
- "hover:text-royalblue-700",
- "hover:text-steel-500",
- "hover:text-white",
- "img",
- "in",
- "inline-block",
- "inline-flex",
- "inset-0",
- "inset-x-0",
- "instagram-media",
- "items-center",
- "items-start",
- "justify-between",
- "justify-center",
- "justify-end",
- "k",
- "kc",
- "kd",
- "kr",
- "kt",
- "l",
- "language-asciidoc",
- "language-bash",
- "language-go",
- "language-go-html-template",
- "language-go-text-template",
- "language-html",
- "language-js",
- "language-json",
- "language-markdown",
- "language-md",
- "language-ps1",
- "language-sh",
- "language-svg",
- "language-text",
- "language-toml",
- "language-txt",
- "language-xml",
- "language-yaml",
- "language-yml",
- "lazyload",
- "ld",
- "lead",
- "leading-none",
- "leading-normal",
- "leading-relaxed",
- "leading-snug",
- "leading-tight",
- "left-0",
- "lg:bg-steel-700",
- "lg:block",
- "lg:flex",
- "lg:flex-grow",
- "lg:flex-shrink-0",
- "lg:hidden",
- "lg:inline-block",
- "lg:items-center",
- "lg:max-w-lg",
- "lg:mb-0",
- "lg:mr-auto",
- "lg:mt-0",
- "lg:p-4",
- "lg:pb-5",
- "lg:prose-lg",
- "lg:pt-0",
- "lg:px-4",
- "lg:px-5",
- "lg:px-8",
- "lg:py-5",
- "lg:py-8",
- "lg:rounded-md",
- "lg:shadow-lg",
- "lg:space-x-4",
- "lg:text-5xl",
- "lg:w-1/2",
- "lg:w-1/4",
- "lg:w-1/5",
- "lg:w-11/12",
- "lg:w-3/5",
- "lg:w-4/5",
- "lg:w-auto",
- "light-gray",
- "link",
- "list-reset",
- "lnt",
- "lntable",
- "lntd",
- "m",
- "m-0",
- "m-1",
- "max-w-6xl",
- "max-w-lg",
- "max-w-xs",
- "mb-0",
- "mb-1",
- "mb-2",
- "mb-3",
- "mb-4",
- "mb-8",
- "mb5",
- "mb7",
- "md:flex",
- "md:flex-col",
- "md:flex-grow",
- "md:grid-cols-2",
- "md:mt-8",
- "md:pb-12",
- "menu))",
- "menu['about']",
- "menu['content-management']",
- "menu['contribute']",
- "menu['functions']",
- "menu['getting-started']",
- "menu['hosting-and-deployment']",
- "menu['modules']",
- "menu['pipes']",
- "menu['templates']",
- "menu['tools']",
- "menu['troubleshooting']",
- "menu['variables']",
- "mf",
- "mi",
- "min-h-screen",
- "min-w-0",
- "minor",
- "ml-1",
- "ml-10",
- "ml-4",
- "ml-6",
- "ml1",
- "mr-1.5",
- "mr-10",
- "mr-3",
- "mr-4",
- "mt-0",
- "mt-1",
- "mt-2",
- "mt-4",
- "mt-5",
- "mt-6",
- "mt-8",
- "mt3",
- "mt4",
- "mv2",
- "mv3",
- "mv4",
- "mv6",
- "mw-100",
- "mw5-l",
- "mx-auto",
- "my-0",
- "n",
- "na",
- "navbar-menu",
- "nb",
- "needs-js",
- "nested-blockquote",
- "nested-copy-seperator",
- "nested-img",
- "nested-links",
- "nested-linksTK",
- "nested-list-reset",
- "nf",
- "ni",
- "nightwind",
- "nightwind-prevent",
- "nightwind-prevent-block",
- "nn",
- "no-js",
- "no-underline",
- "nodelta",
- "note",
- "note-icon",
- "nt",
- "nt3",
- "nv",
- "nx",
- "o",
- "o-0",
- "o-80",
- "oldnew",
- "opacity-60",
- "open",
- "order-0",
- "order-0-l",
- "order-1",
- "order-1-l",
- "order-2",
- "output-content",
- "overflow-hidden",
- "overflow-x-scroll",
- "overflow-y-auto",
- "p",
- "p-0",
- "p-2",
- "p-3",
- "p-4",
- "p-5",
- "p-8",
- "pa4-m",
- "page-item",
- "page-link",
- "pagination",
- "pb-1",
- "pb-2",
- "pb-3",
- "pb-4",
- "pb-5",
- "pb-7",
- "pb-8",
- "pb2",
- "ph1",
- "ph2",
- "ph4",
- "pl-0",
- "pl-1",
- "pl-2",
- "pl-3",
- "pl-6",
- "pl5-l",
- "pr-2",
- "pr1",
- "primary-color",
- "prose",
- "pt-0",
- "pt-1",
- "pt-2",
- "pt-3",
- "pt-4",
- "pt-5",
- "pv1",
- "px-0",
- "px-2",
- "px-3",
- "px-4",
- "py-0",
- "py-0.5",
- "py-1.5",
- "py-2",
- "py-3",
- "py-4",
- "py-6",
- "relative",
- "right-0",
- "rounded",
- "rounded-full",
- "rounded-l-lg",
- "rounded-l-md",
- "rounded-lg",
- "rounded-md",
- "rounded-r-md",
- "row",
- "s",
- "s1",
- "s2",
- "san-serif",
- "se",
- "shadow",
- "shadow-lg",
- "shadow-md",
- "shadow-sm",
- "show",
- "sm:flex",
- "sm:grid-cols-2",
- "sm:mb-0",
- "sm:mt-0",
- "sm:mt-8",
- "sm:p-4",
- "sm:pb-0",
- "sm:pb-6",
- "sm:pt-3",
- "sm:pt-5",
- "sm:px-4",
- "sm:px-5",
- "sm:px-6",
- "sm:py-0",
- "sm:py-4",
- "sm:py-5",
- "sm:py-6",
- "sm:text-2xl",
- "sm:text-4xl",
- "sm:text-base",
- "sm:text-center",
- "sm:text-left",
- "sm:w-1/2",
- "sm:w-1/5",
- "sm:w-11/12",
- "sm:w-4/5",
- "space-x-4",
- "space-x-8",
- "space-y-1",
- "sr-only",
- "table",
- "table-bordered",
- "tc",
- "text-2xl",
- "text-3xl",
- "text-4xl",
- "text-5xl",
- "text-base",
- "text-black",
- "text-center",
- "text-gray-200",
- "text-gray-300",
- "text-gray-400",
- "text-gray-500",
- "text-gray-600",
- "text-gray-900",
- "text-lg",
- "text-limegreen-600",
- "text-limegreen-700",
- "text-mango-100",
- "text-mango-300",
- "text-md",
- "text-royalblue-500",
- "text-royalblue-600",
- "text-sm",
- "text-steel-100",
- "text-steel-500",
- "text-steel-900",
- "text-white",
- "text-xl",
- "text-xs",
- "tile",
- "tip",
- "tip-icon",
- "to-steel-800",
- "top-0",
- "top-2",
- "tracked",
- "tracking-normal",
- "tracking-tight",
- "transform",
- "twitter-tweet",
- "unchanged",
- "uppercase",
- "v-base",
- "v-mid",
- "v-top",
- "w",
- "w-1/5",
- "w-10",
- "w-11/12",
- "w-12",
- "w-14",
- "w-2",
- "w-2/3",
- "w-30-l",
- "w-32",
- "w-5",
- "w-50-m",
- "w-6",
- "w-64",
- "w-8",
- "w-80-nsTK",
- "w-96",
- "w-auto",
- "w-full",
- "w-two-third-l",
- "warning",
- "whitespace-no-wrap",
- "worse",
- "x",
- "xl:flex",
- "xl:flex-col",
- "z-0",
- "z-40",
- "z-999",
- "||"
- ],
- "ids": [
- ".gitlab-ci.yml",
- "/blog/greatest-city/index.html",
- "/content/actors/bruce-willis/_index.md",
- "/layouts/shortcodes/img.html",
- "/layouts/shortcodes/vimeo.html",
- "/layouts/shortcodes/year.html",
- "/layouts/shortcodes/youtube.html",
- "/themes/yourtheme/layouts/review/single.html",
- "404.html",
- "TableOfContents",
- "addrobotstxt.sh",
- "all-taxonomies-keys-and-pages.html",
- "all-taxonomies.html",
- "archetype-example.sh",
- "archetypes/functions.md",
- "archetypes/newsletter.md",
- "articles.html",
- "asciicast-3mf1JGaN0AX0Z7j5kLGl3hSh8",
- "asciicast-7naKerRYUGVPj8kiDmdh5k5h9",
- "asciicast-BvJBsF6egk9c163bMsObhuNXj",
- "asciicast-ItACREbFgvJ0HjnSNeTknxWy9",
- "asciicast-Lc5iwTVny2kuUC8lqvNnL6oDU",
- "asciicast-eUojYCfRTZvkEiqc52fUsJRBR",
- "bad-url-sidebar-menu-output.html",
- "base-64-output.html",
- "base64-input.html",
- "baseof.html",
- "bf-config.toml",
- "bf-config.yml",
- "boxfile.yml",
- "breadcrumb.html",
- "check-title-length.html",
- "clone-herring-cove-theme.sh",
- "config.toml",
- "content-header.html",
- "content-image.md",
- "content/blog/greatest-city.md",
- "content/posts/_index.md",
- "content/posts/default-function-example.md",
- "content/posts/my-awesome-post.md",
- "content/posts/my-post.md",
- "content/posts/old-post.md",
- "content/posts/old-url.md",
- "content/tutorials/learn-html.md",
- "correct-url-sidebar-menu-output.html",
- "delimit-example-front-matter.toml",
- "delimit-page-tags-final-and-input.html",
- "delimit-page-tags-final-and-output.html",
- "delimit-page-tags-input.html",
- "delimit-page-tags-output.html",
- "disqus.html",
- "dot-notation-default-return-value.html",
- "dot-notation-default-value.html",
- "example-tweet-input.md",
- "example-tweet-output.html",
- "example-vimeo-input.md",
- "example-vimeo-output.html",
- "example-youtube-input-with-autoplay.md",
- "example-youtube-input-with-title.md",
- "example-youtube-input.md",
- "example-youtube-output.html",
- "example.com/posts/index.html",
- "example.com/quote/index.html",
- "external-links.svg",
- "figure-input-example.md",
- "figure-output-example.html",
- "first-and-where-together.html",
- "fn:1",
- "fn:2",
- "fnref:1",
- "fnref:2",
- "footer.html",
- "from-gh.sh",
- "gist-input.md",
- "gist-output.html",
- "gitignore.sh",
- "gohugoio",
- "grab-top-two-tags.html",
- "header.html",
- "highlight-example.md",
- "how-many-posts.html",
- "hugo-new-site.sh",
- "if-instead-of-default.html",
- "img-output.html",
- "index.html",
- "instagram-hide-caption-output.html",
- "instagram-input-hide-caption.md",
- "instagram-input.md",
- "install-brew.sh",
- "install-extended-with-chocolatey.ps1",
- "install-go.sh",
- "install-openssh.sh",
- "install-with-chocolatey.ps1",
- "install-with-homebrew.sh",
- "install-with-linuxbrew.sh",
- "install-with-macports.sh",
- "install.sh",
- "layout/_default/section.html",
- "layout/_default/single.html",
- "layouts/404.html",
- "layouts/_default/_markup/render-heading.html",
- "layouts/_default/_markup/render-image.html",
- "layouts/_default/_markup/render-link.html",
- "layouts/_default/baseof.html",
- "layouts/_default/li.html",
- "layouts/_default/list.html",
- "layouts/_default/section.html",
- "layouts/_default/single.html",
- "layouts/_default/summary.html",
- "layouts/_default/taxonomy.html",
- "layouts/index.html",
- "layouts/partials/all-taxonomies.html",
- "layouts/partials/alllanguages.html",
- "layouts/partials/bad-url-sidebar-menu.html",
- "layouts/partials/breadcrumb.html",
- "layouts/partials/by-date-reverse.html",
- "layouts/partials/by-date.html",
- "layouts/partials/by-expiry-date.html",
- "layouts/partials/by-group-by-page.html",
- "layouts/partials/by-last-mod.html",
- "layouts/partials/by-length.html",
- "layouts/partials/by-link-title.html",
- "layouts/partials/by-nested-param.html",
- "layouts/partials/by-page-date.html",
- "layouts/partials/by-page-expiry-date.html",
- "layouts/partials/by-page-field.html",
- "layouts/partials/by-page-lastmod.html",
- "layouts/partials/by-page-param-as-date.html",
- "layouts/partials/by-page-param.html",
- "layouts/partials/by-page-publish-date.html",
- "layouts/partials/by-publish-date.html",
- "layouts/partials/by-rating.html",
- "layouts/partials/by-title.html",
- "layouts/partials/by-weight.html",
- "layouts/partials/content-header.html",
- "layouts/partials/correct-url-sidebar-menu.html",
- "layouts/partials/default-order.html",
- "layouts/partials/disqus.html",
- "layouts/partials/footer.html",
- "layouts/partials/get-csv.html",
- "layouts/partials/groups.html",
- "layouts/partials/head.html",
- "layouts/partials/header.html",
- "layouts/partials/i18nlist.html",
- "layouts/partials/post-tag-link.html",
- "layouts/partials/post-tag-list.html",
- "layouts/partials/related.html",
- "layouts/partials/schemaorg-metadata.html",
- "layouts/partials/sidebar.html",
- "layouts/partials/svgs/external-links.svg",
- "layouts/partials/toc.html",
- "layouts/partials/twitter.html",
- "layouts/partials/upcoming-events.html",
- "layouts/posts/single.html",
- "layouts/robots.txt",
- "layouts/section/articles.html",
- "layouts/section/posts.html",
- "layouts/shortcodes/gallery.html",
- "layouts/shortcodes/img.html",
- "layouts/shortcodes/imgproc.html",
- "li.html",
- "links-to-all-tags.html",
- "list.html",
- "netlify.toml",
- "note-with-heading.html",
- "note-with-heading.md",
- "page-list-with-summaries.html",
- "partial-cached-example.html",
- "partials/templates/random-tweets.html",
- "post-tag-list.html",
- "prose",
- "push-wecker-to-gh.sh",
- "range-through-tags-w-global.html",
- "remove-herring-cove-git.sh",
- "robots.txt",
- "schemaorg-metadata.html",
- "section.html",
- "setup-gh-repo.sh",
- "shuffle-input.html",
- "shuffle-output.html",
- "sidebar.html",
- "single.html",
- "slice.html",
- "summary.html",
- "syntax-highlighted.html",
- "tags-range-with-page-variable.html",
- "taxonomy.html",
- "time-passed.html",
- "tip-output.html",
- "toc.html",
- "tutorials/learn-html/index.html",
- "tweets.html",
- "unix-to-month-integer.html",
- "upcoming-events.html",
- "using-tip.md",
- "variable-as-default-value.html",
- "vimeo-iframes.html",
- "warning-admonition-input.md",
- "warning-admonition-output.html",
- "wercker-build-step.yml",
- "wercker.yml",
- "where-intersect-variables.html",
- "with-instead-of-default.html",
- "yourbaseurl/review/book01/index.html",
- "youtube-embed.html"
- ]
- }
-}
\ No newline at end of file
+++ /dev/null
-project = "hugoDocs"
-
-[release_settings]
- name = "${HUGORELEASER_TAG}"
- type = "github"
- repository = "hugoDocs"
- repository_owner = "gohugoio"
-
- draft = true
- prerelease = false
-
- [release_settings.release_notes_settings]
- generate = true
- generate_on_host = false
- short_threshold = 10
- short_title = "What's Changed"
-
- groups = [
- { regexp = "snapcraft:|Merge commit|Merge branch|netlify:|release:|Squashed", ignore = true },
- { title = "Typo fixes", regexp = "typo", ordinal = 20 },
- { title = "Dependency Updates", regexp = "deps", ordinal = 30 },
- { title = "Improvements", regexp = ".*", ordinal = 10 },
- ]
-
-[[releases]]
- paths = ["archives/**"]
- # In this file we have only one release, but path can be used to partition the release step, e.g.:
- # hugoreleaser release -paths "releases/myrelease"
- path = "myrelease"
--- /dev/null
+project: hugoDocs
+release_settings:
+ name: ${HUGORELEASER_TAG}
+ type: github
+ repository: hugoDocs
+ repository_owner: gohugoio
+ draft: true
+ prerelease: false
+ release_notes_settings:
+ generate: true
+ generate_on_host: false
+ short_threshold: 10
+ short_title: What's Changed
+ groups:
+ - regexp: snapcraft:|Merge commit|Merge branch|netlify:|release:|Squashed
+ ignore: true
+ - title: Typo fixes
+ regexp: typo
+ ordinal: 20
+ - title: Dependency Updates
+ regexp: deps
+ ordinal: 30
+ - title: Improvements
+ regexp: .*
+ ordinal: 10
+releases:
+ - paths:
+ - archives/**
+ path: myrelease
--- /dev/null
+{{- /* Last modified: 2025-01-19T14:44:56-08:00 */}}
+
+{{- /*
+Copyright 2025 Veriphor LLC
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License. You may obtain a copy of
+the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations under
+the License.
+*/}}
+
+{{- /*
+This render hook resolves internal destinations by looking for a matching:
+
+ 1. Content page
+ 2. Page resource (a file in the current page bundle)
+ 3. Section resource (a file in the current section)
+ 4. Global resource (a file in the assets directory)
+
+It skips the section resource lookup if the current page is a leaf bundle.
+
+External destinations are not modified.
+
+You must place global resources in the assets directory. If you have placed
+your resources in the static directory, and you are unable or unwilling to move
+them, you must mount the static directory to the assets directory by including
+both of these entries in your site configuration:
+
+ [[module.mounts]]
+ source = 'assets'
+ target = 'assets'
+
+ [[module.mounts]]
+ source = 'static'
+ target = 'assets'
+
+By default, if this render hook is unable to resolve a destination, including a
+fragment if present, it passes the destination through without modification. To
+emit a warning or error, set the error level in your site configuration:
+
+ [params.render_hooks.link]
+ errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+
+When you set the error level to warning, and you are in a development
+environment, you can visually highlight broken internal links:
+
+ [params.render_hooks.link]
+ errorLevel = 'warning' # ignore (default), warning, or error (fails the build)
+ highlightBroken = true # true or false (default)
+
+This will add a "broken" class to anchor elements with invalid src attributes.
+Add a rule to your CSS targeting the broken links:
+
+ a.broken {
+ background: #ff0;
+ border: 2px solid #f00;
+ padding: 0.1em 0.2em;
+ }
+
+This render hook may be unable to resolve destinations created with the ref and
+relref shortcodes. Unless you set the error level to ignore you should not use
+either of these shortcodes in conjunction with this render hook.
+
+@context {string} Destination The link destination.
+@context {page} Page A reference to the page containing the link.
+@context {string} PlainText The link description as plain text.
+@context {string} Text The link description.
+@context {string} Title The link title.
+
+@returns {template.html}
+*/}}
+
+{{- /* Initialize. */}}
+{{- $renderHookName := "link" }}
+
+{{- /* Verify minimum required version. */}}
+{{- $minHugoVersion := "0.141.0" }}
+{{- if lt hugo.Version $minHugoVersion }}
+ {{- errorf "The %q render hook requires Hugo v%s or later." $renderHookName $minHugoVersion }}
+{{- end }}
+
+{{- /* Error level when unable to resolve destination: ignore, warning, or error. */}}
+{{- $errorLevel := or site.Params.render_hooks.link.errorLevel "ignore" | lower }}
+
+{{- /* If true, adds "broken" class to broken links. Applicable in development environment when errorLevel is warning. */}}
+{{- $highlightBrokenLinks := or site.Params.render_hooks.link.highlightBroken false }}
+
+{{- /* Validate error level. */}}
+{{- if not (in (slice "ignore" "warning" "error") $errorLevel) }}
+ {{- errorf "The %q render hook is misconfigured. The errorLevel %q is invalid. Please check your site configuration." $renderHookName $errorLevel }}
+{{- end }}
+
+{{- /* Determine content path for warning and error messages. */}}
+{{- $contentPath := .Page.String }}
+
+{{- /* Parse destination. */}}
+{{- $u := urls.Parse .Destination }}
+
+{{- /* Set common message. */}}
+{{- $msg := printf "The %q render hook was unable to resolve the destination %q in %s" $renderHookName $u.String $contentPath }}
+
+{{- /* Set attributes for anchor element. */}}
+{{- $attrs := dict "href" $u.String }}
+{{- if eq $u.String "g" }}
+ {{- /* Destination is a glossary term. */}}
+ {{- $ctx := dict
+ "contentPath" $contentPath
+ "errorLevel" $errorLevel
+ "renderHookName" $renderHookName
+ "text" .Text
+ }}
+ {{- $attrs = partial "inline/h-rh-l/get-glossary-link-attributes.html" $ctx }}
+{{- else if $u.IsAbs }}
+ {{- /* Destination is a remote resource. */}}
+ {{- $attrs = merge $attrs (dict "rel" "external") }}
+{{- else }}
+ {{- with $u.Path }}
+ {{- with $p := or ($.PageInner.GetPage .) ($.PageInner.GetPage (strings.TrimRight "/" .)) }}
+ {{- /* Destination is a page. */}}
+ {{- $href := .RelPermalink }}
+ {{- with $u.RawQuery }}
+ {{- $href = printf "%s?%s" $href . }}
+ {{- end }}
+ {{- with $u.Fragment }}
+ {{- $ctx := dict
+ "contentPath" $contentPath
+ "errorLevel" $errorLevel
+ "page" $p
+ "parsedURL" $u
+ "renderHookName" $renderHookName
+ }}
+ {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
+ {{- $href = printf "%s#%s" $href . }}
+ {{- end }}
+ {{- $attrs = dict "href" $href }}
+ {{- else with $.PageInner.Resources.Get $u.Path }}
+ {{- /* Destination is a page resource; drop query and fragment. */}}
+ {{- $attrs = dict "href" .RelPermalink }}
+ {{- else with (and (ne $.Page.BundleType "leaf") ($.Page.CurrentSection.Resources.Get $u.Path)) }}
+ {{- /* Destination is a section resource, and current page is not a leaf bundle. */}}
+ {{- $attrs = dict "href" .RelPermalink }}
+ {{- else with resources.Get $u.Path }}
+ {{- /* Destination is a global resource; drop query and fragment. */}}
+ {{- $attrs = dict "href" .RelPermalink }}
+ {{- else }}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- if and $highlightBrokenLinks hugo.IsDevelopment }}
+ {{- $attrs = merge $attrs (dict "class" "broken") }}
+ {{- end }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- else }}
+ {{- with $u.Fragment }}
+ {{- /* Destination is on the same page; prepend relative permalink. */}}
+ {{- $ctx := dict
+ "contentPath" $contentPath
+ "errorLevel" $errorLevel
+ "page" $.Page
+ "parsedURL" $u
+ "renderHookName" $renderHookName
+ }}
+ {{- partial "inline/h-rh-l/validate-fragment.html" $ctx }}
+ {{- $attrs = dict "href" (printf "%s#%s" $.Page.RelPermalink .) }}
+ {{- else }}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- if and $highlightBrokenLinks hugo.IsDevelopment }}
+ {{- $attrs = merge $attrs (dict "class" "broken") }}
+ {{- end }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+{{- end }}
+
+{{- /* Render anchor element. */ -}}
+<a
+ {{- with .Title }} title="{{ . }}" {{- end }}
+ {{- range $k, $v := $attrs }}
+ {{- if $v }}
+ {{- printf " %s=%q" $k ($v | transform.HTMLEscape) | safeHTMLAttr }}
+ {{- end }}
+ {{- end -}}
+>{{ .Text }}</a>
+
+{{- define "partials/inline/h-rh-l/validate-fragment.html" }}
+ {{- /*
+ Validates the fragment portion of a link destination.
+
+ @context {string} contentPath The page containing the link.
+ @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error.
+ @context {page} page The page corresponding to the link destination
+ @context {struct} parsedURL The link destination parsed by urls.Parse.
+ @context {string} renderHookName The name of the render hook.
+ */}}
+
+ {{- /* Initialize. */}}
+ {{- $contentPath := .contentPath }}
+ {{- $errorLevel := .errorLevel }}
+ {{- $p := .page }}
+ {{- $u := .parsedURL }}
+ {{- $renderHookName := .renderHookName }}
+
+ {{- /* Validate. */}}
+ {{- with $u.Fragment }}
+ {{- if $p.Fragments.Identifiers.Contains . }}
+ {{- if gt ($p.Fragments.Identifiers.Count .) 1 }}
+ {{- $msg := printf "The %q render hook detected duplicate heading IDs %q in %s" $renderHookName . $contentPath }}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- else }}
+ {{- /* Determine target path for warning and error message. */}}
+ {{- $targetPath := "" }}
+ {{- with $p.File }}
+ {{- $targetPath = .Path }}
+ {{- else }}
+ {{- $targetPath = .Path }}
+ {{- end }}
+ {{- /* Set common message. */}}
+ {{- $msg := printf "The %q render hook was unable to find heading ID %q in %s. See %s" $renderHookName . $targetPath $contentPath }}
+ {{- if eq $targetPath $contentPath }}
+ {{- $msg = printf "The %q render hook was unable to find heading ID %q in %s" $renderHookName . $targetPath }}
+ {{- end }}
+ {{- /* Throw warning or error. */}}
+ {{- if eq $errorLevel "warning" }}
+ {{- warnf $msg }}
+ {{- else if eq $errorLevel "error" }}
+ {{- errorf $msg }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+{{- end }}
+
+{{- define "partials/inline/h-rh-l/get-glossary-link-attributes.html" }}
+ {{- /*
+ Returns the anchor element attributes for a link to the given glossary term.
+
+ It first checks for the existence of a glossary page for the given term. If
+ no page is found, it then checks for a glossary page for the singular form of
+ the term. If neither page exists it throws a warning or error dependent on
+ the errorLevel setting
+
+ The returned href attribute does not point to the glossary term page.
+ Instead, via its fragment, it points to an entry on the glossary page.
+
+ @context {string} contentPath The page containing the link.
+ @context {string} errorLevel The error level when unable to resolve destination; ignore (default), warning, or error.
+ @context {string} renderHookName The name of the render hook.
+ @context {string} text The link text.
+ */}}
+
+ {{- /* Get context.. */}}
+ {{- $contentPath := .contentPath }}
+ {{- $errorLevel := .errorLevel }}
+ {{- $renderHookName := .renderHookName }}
+ {{- $text := .text | transform.Plainify | strings.ToLower }}
+
+ {{- /* Initialize. */}}
+ {{- $glossaryPath := "/getting-started/glossary" }}
+ {{- $termGiven := $text }}
+ {{- $termActual := "" }}
+ {{- $termSingular := inflect.Singularize $termGiven }}
+
+ {{- /* Verify that the glossary page exists. */}}
+ {{- $glossaryPage := site.GetPage $glossaryPath }}
+ {{- if not $glossaryPage }}
+ {{- errorf "The %q render hook was unable to find %s: see %s" $renderHookName $glossaryPath $contentPath }}
+ {{- end }}
+
+ {{- /* Theres a better way to handle this, but it works for now. */}}
+ {{- $cheating := dict
+ "chaining" "chain"
+ "localize" "localization"
+ "localized" "localization"
+ "paginating" "paginate"
+ "walking" "walk"
+ }}
+
+ {{- /* Verify that a glossary term page exists for the given term. */}}
+ {{- if site.GetPage (urls.JoinPath $glossaryPath ($termGiven | urlize)) }}
+ {{- $termActual = $termGiven }}
+ {{- else if site.GetPage (urls.JoinPath $glossaryPath ($termSingular | urlize)) }}
+ {{- $termActual = $termSingular }}
+ {{- else }}
+ {{- $termToTest := index $cheating $termGiven }}
+ {{- if site.GetPage (urls.JoinPath $glossaryPath ($termToTest | urlize)) }}
+ {{- $termActual = $termToTest }}
+ {{- end }}
+ {{- end }}
+
+ {{- if not $termActual }}
+ {{- errorf "The %q render hook was unable to find a glossary page for either the singular or plural form of the term %q: see %s" $renderHookName $termGiven $contentPath }}
+ {{- end }}
+
+ {{- /* Create the href attribute. */}}
+ {{- $href := ""}}
+ {{- if $termActual }}
+ {{- $href = fmt.Printf "%s#%s" $glossaryPage.RelPermalink (anchorize $termActual) }}
+ {{- end }}
+
+ {{- return (dict "href" $href) }}
+{{- end -}}
--- /dev/null
+{{- /*
+Renders the definition of the given glossary term.
+
+@param {string} (.Get 0) The glossary term.
+@returns {template.HTML}
+
+@example {{% glossary-term float %}}
+@example {{% glossary-term "floating point" %}}
+*/}}
+
+{{- with .Get 0 }}
+ {{- $path := printf "/getting-started/glossary/%s" (urlize .) }}
+ {{- with site.GetPage $path }}
+{{ .RenderShortcodes }}{{/* Do not indent. */}}
+ {{- else }}
+ {{- errorf "The glossary term (%s) shortcode was unable to find %s: see %s" $.Name $path $.Position }}
+ {{- end }}
+{{- else }}
+ {{- errorf "The glossary term (%s) shortcode requires one positional parameter: see %s" $.Name $.Position }}
+{{- end }}
--- /dev/null
+{{- /*
+Renders the glossary of terms.
+
+When you call this shortcode using the {{% %}} notation, the glossary terms are
+Markdown headings (level 6) which means they are members of .Page.Fragments.
+This allows the link render hook to verify links to glossary terms.
+
+Yes, the terms themselves are pages, but we don't want to link to the pages, at
+least not right now. Instead, we want to link to the fragments rendered by this
+shortcode.
+
+@returns {template.HTML}
+
+@example {{% glossary %}}
+*/}}
+{{- $path := "/getting-started/glossary" }}
+{{- with site.GetPage $path }}
+ {{- with $p := .Pages.ByTitle }}
+
+ {{- /* Build and render alphabetical index. */}}
+ {{- $m := dict }}
+ {{- range $p }}
+ {{- $k := substr .Title 0 1 | strings.ToUpper }}
+ {{- if index $m $k }}
+ {{- continue }}
+ {{- end }}
+ {{- $anchor := path.BaseName .Path | anchorize }}
+ {{- $m = merge $m (dict $k $anchor) }}
+ {{- end }}
+ {{- range $k, $v := $m }}
+[{{ $k }}](#{{ $v }}) {{/* Do not indent. */}}
+ {{- end }}
+
+ {{- /* Render glossary terms. */}}
+ {{- range $p }}
+###### {{ .Title }}{{/* Do not indent. */}}
+{{ .RenderShortcodes }}{{/* Do not indent. */}}
+ {{- end }}
+
+ {{- end }}
+{{- else }}
+ {{- errorf "The %q shortcode was unable to get %s: see %s" .Name $path .Position}}
+{{- end }}
command = "hugo --gc --minify"
[build.environment]
- HUGO_VERSION = "0.140.2"
+ HUGO_VERSION = "0.142.0"
[context.production.environment]
HUGO_ENV = "production"
projects / brevno-suite / hugo / commitdiff
