Merge commit '346b60358dd8ec2ca228e6635bff9d7914b398b7'
This commit is contained in:
Bjørn Erik Pedersen
commit
43307b07f8
384 changed files with 3305 additions and 3271 deletions
|
|
@ -23,3 +23,4 @@ MD046: false
|
|||
MD049: false
|
||||
MD050: false
|
||||
MD053: false
|
||||
MD055: false
|
||||
|
|
|
|||
|
|
@ -10,9 +10,9 @@
|
|||
}
|
||||
|
||||
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;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4769,9 +4769,9 @@ h6:hover .header-link {
|
|||
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;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -4,14 +4,14 @@
|
|||
|
||||
{{ $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">
|
||||
|
|
|
|||
|
|
@ -4,14 +4,14 @@
|
|||
|
||||
{{ $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 }}
|
||||
|
|
|
|||
|
|
@ -11,13 +11,13 @@ Supports CSV, JSON, TOML, YAML, and XML.
|
|||
|
||||
{{ $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 }}
|
||||
|
|
|
|||
11
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/hl.html
generated
Normal file
11
docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/hl.html
generated
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
{{- /*
|
||||
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 }}
|
||||
|
|
@ -120,8 +120,8 @@ Renders the given image using the given filter, if any.
|
|||
|
||||
{{- $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"
|
||||
}}
|
||||
|
||||
|
|
@ -229,6 +229,12 @@ Renders the given image using the given filter, if any.
|
|||
{{- $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 }}
|
||||
|
|
@ -322,11 +328,15 @@ Renders the given image using the given filter, if any.
|
|||
{{- 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 }}
|
||||
|
|
@ -354,15 +364,15 @@ Renders the given image using the given filter, if any.
|
|||
{{- $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) }}
|
||||
|
|
|
|||
|
|
@ -1 +1 @@
|
|||
# github.com/gohugoio/gohugoioTheme v0.0.0-20250106044328-feb60697e056
|
||||
# github.com/gohugoio/gohugoioTheme v0.0.0-20250116152525-2d382cae7743
|
||||
|
|
|
|||
19
docs/archetypes/glossary.md
Normal file
19
docs/archetypes/glossary.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
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]'."
|
||||
-->
|
||||
|
|
@ -20,7 +20,7 @@ byline: "[bep](https://github.com/bep), Hugo Lead"
|
|||
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
|
||||
|
||||
|
|
|
|||
BIN
docs/assets/images/examples/mask.png
Normal file
BIN
docs/assets/images/examples/mask.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 134 KiB |
|
|
@ -55,20 +55,26 @@ identifier = 'render-hooks'
|
|||
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/'
|
||||
|
|
@ -77,25 +83,25 @@ 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/'
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ toc: true
|
|||
: 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.
|
||||
|
|
@ -123,7 +123,7 @@ toc: true
|
|||
[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/
|
||||
|
|
@ -134,6 +134,6 @@ toc: true
|
|||
[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/
|
||||
|
|
|
|||
|
|
@ -39,11 +39,11 @@ respectDoNotTrack = false
|
|||
[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
|
||||
|
|
@ -64,10 +64,10 @@ disable = true
|
|||
disable = true
|
||||
[privacy.instagram]
|
||||
disable = true
|
||||
[privacy.twitter]
|
||||
disable = true
|
||||
[privacy.vimeo]
|
||||
disable = true
|
||||
[privacy.x]
|
||||
disable = true
|
||||
[privacy.youtube]
|
||||
disable = true
|
||||
{{< /code-toggle >}}
|
||||
|
|
@ -92,19 +92,19 @@ simple
|
|||
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 >}}
|
||||
|
||||
|
|
|
|||
|
|
@ -72,7 +72,6 @@ hugo [flags]
|
|||
* [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
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ aliases: [/content/archetypes/]
|
|||
|
||||
## 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:
|
||||
|
||||
|
|
@ -25,7 +25,7 @@ date = '{{ .Date }}'
|
|||
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
|
||||
|
|
@ -39,7 +39,7 @@ date = '2023-08-24T11:49:46-07:00'
|
|||
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/
|
||||
|
|
@ -59,18 +59,18 @@ hugo new content posts/my-first-post.md
|
|||
|
||||
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.
|
||||
|
|
@ -79,9 +79,7 @@ File
|
|||
: (`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/).
|
||||
|
|
@ -130,11 +128,11 @@ One or more practical examples, each within a fenced code block.
|
|||
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.
|
||||
|
||||
|
|
@ -193,11 +191,3 @@ To create an article using the tutorials archetype:
|
|||
```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
|
||||
|
|
|
|||
|
|
@ -21,7 +21,6 @@ publishResources = true
|
|||
render = 'always'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
|
||||
list
|
||||
: When to include the page within page collections. Specify one of:
|
||||
|
||||
|
|
@ -115,7 +114,7 @@ public/
|
|||
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
|
||||
|
||||
|
|
@ -181,7 +180,7 @@ public/
|
|||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ toc: true
|
|||
|
||||
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/
|
||||
|
|
@ -33,7 +33,7 @@ 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
|
||||
|
||||
|
|
@ -137,9 +137,8 @@ Key|Description|Required
|
|||
`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 %}}
|
||||
|
|
@ -158,7 +157,7 @@ Key|Description|Required
|
|||
`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 %}}
|
||||
|
|
@ -193,14 +192,14 @@ Step 3
|
|||
{{/* 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. */}}
|
||||
|
|
@ -223,10 +222,10 @@ Step 3
|
|||
{{/* 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
|
||||
|
|
@ -235,9 +234,9 @@ Step 3
|
|||
"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 }}
|
||||
|
||||
|
|
@ -281,7 +280,7 @@ Step 4
|
|||
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
|
||||
|
||||
|
|
@ -352,8 +351,6 @@ To detect page collisions, use the `--printPathWarnings` flag when building your
|
|||
|
||||
[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/
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ The pages can be referenced as follows:
|
|||
{{</* 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
|
||||
|
|
|
|||
|
|
@ -12,21 +12,15 @@ toc: true
|
|||
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.
|
||||
|
|
@ -42,7 +36,7 @@ project/
|
|||
```
|
||||
|
||||
{{% 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.
|
||||
|
|
|
|||
|
|
@ -29,7 +29,10 @@ content/
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -37,7 +40,7 @@ Hugo selects the content renderer based on the `markup` identifier in front matt
|
|||
|
||||
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:
|
||||
|
||||
|
|
@ -48,24 +51,39 @@ 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:
|
||||
|
||||
|
|
@ -79,6 +97,10 @@ The CLI flags passed to the Asciidoctor executable depend on configuration. You
|
|||
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.
|
||||
|
|
@ -89,6 +111,8 @@ Hugo passes these CLI flags when calling the Pandoc executable:
|
|||
--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.
|
||||
|
|
@ -99,6 +123,9 @@ Hugo passes these CLI flags when calling the rst2html executable:
|
|||
--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
|
||||
|
|
@ -116,22 +143,3 @@ When converting content to HTML, Hugo uses:
|
|||
- 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
|
||||
|
|
|
|||
|
|
@ -39,15 +39,7 @@ weight = 10
|
|||
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
|
||||
|
||||
|
|
@ -82,7 +74,6 @@ The field names below are reserved. For example, you cannot create a custom fiel
|
|||
|
||||
(`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
|
||||
|
|
@ -113,22 +104,19 @@ If `true`, the page will not be rendered unless you pass the `--buildDrafts` fla
|
|||
|
||||
###### 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
|
||||
|
|
@ -140,7 +128,6 @@ kind
|
|||
lang
|
||||
: The language code for this page. This is usually derived from the module mount or filename.
|
||||
-->
|
||||
{{% /comment %}}
|
||||
|
||||
###### lastmod
|
||||
|
||||
|
|
@ -154,7 +141,7 @@ lang
|
|||
|
||||
[`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
|
||||
|
||||
|
|
@ -184,13 +171,11 @@ Alias to [lastmod](#lastmod).
|
|||
|
||||
[output formats]: /templates/output-formats/
|
||||
|
||||
{{% comment %}}
|
||||
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
|
||||
<!--
|
||||
path
|
||||
: The canonical page path.
|
||||
-->
|
||||
{{% /comment %}}
|
||||
|
||||
###### params
|
||||
|
||||
|
|
@ -254,9 +239,8 @@ Alias to [publishDate](#publishdate).
|
|||
|
||||
###### 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
|
||||
|
|
@ -268,10 +252,8 @@ Alias to [expirydate](#expirydate).
|
|||
(`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
|
||||
|
|
@ -302,7 +284,7 @@ Parameter|Data type|Used by these embedded templates
|
|||
`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 %}}
|
||||
|
|
@ -332,7 +314,7 @@ genres = ['mystery','romance']
|
|||
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`
|
||||
|
|
@ -340,8 +322,6 @@ You can add taxonomy terms to the front matter of any these [page kinds]:
|
|||
- `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 >}}
|
||||
|
|
@ -360,9 +340,7 @@ Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] metho
|
|||
|
||||
## 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
|
||||
|
||||
|
|
@ -459,5 +437,5 @@ When populating a date field, whether a [custom page parameter](#parameters) or
|
|||
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
|
||||
|
|
|
|||
|
|
@ -88,15 +88,15 @@ Example 3: A more concise way to skip image rendering if the resource is not fou
|
|||
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 }}
|
||||
```
|
||||
|
||||
|
|
@ -482,7 +482,7 @@ To control tag availability, change the `excludeFields` or `includeFields` setti
|
|||
|
||||
## 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:
|
||||
|
||||
|
|
@ -500,15 +500,14 @@ If you change image processing methods or options, or if you rename or remove im
|
|||
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
|
||||
|
|
|
|||
|
|
@ -45,7 +45,6 @@ title = true # default is true
|
|||
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].
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
---
|
||||
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
|
||||
|
|
@ -15,18 +15,11 @@ math: true
|
|||
|
||||
{{< new-in 0.122.0 >}}
|
||||
|
||||
\[
|
||||
\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].
|
||||
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, this is the mathematical markup for the equations displayed at the top of this page:
|
||||
For example, with this LaTeX markup:
|
||||
|
||||
```text
|
||||
\[
|
||||
|
|
@ -37,15 +30,30 @@ JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y
|
|||
\]
|
||||
```
|
||||
|
||||
The MathJax display engine renders this:
|
||||
|
||||
\[
|
||||
\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
|
||||
|
||||
|
|
@ -122,7 +130,7 @@ The example above loads the partial template if you have set the `math` paramete
|
|||
|
||||
###### 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.
|
||||
|
|
@ -173,7 +181,7 @@ If you use the `$...$` delimiter pair for inline equations, and occasionally use
|
|||
|
||||
## 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).
|
||||
|
|
@ -184,9 +192,9 @@ See the [inline delimiters](#inline-delimiters) section for details.
|
|||
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, {
|
||||
|
|
@ -218,11 +226,7 @@ As shown in [Step 2] above, MathJax supports chemical equations without addition
|
|||
[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
|
||||
|
|
|
|||
|
|
@ -17,8 +17,8 @@ aliases: [/extras/menus/]
|
|||
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.
|
||||
|
||||
|
|
@ -34,7 +34,7 @@ Although you can use these methods in combination when defining a menu, the menu
|
|||
|
||||
## 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"
|
||||
|
|
@ -229,5 +229,4 @@ See [menu templates].
|
|||
[localize]: /content-management/multilingual/#menus
|
||||
[menu templates]: /templates/menu/
|
||||
[multilingual]: /content-management/multilingual/#menus
|
||||
[section]: /getting-started/glossary/#section
|
||||
[template]: /templates/menu/
|
||||
|
|
|
|||
|
|
@ -21,7 +21,6 @@ This is the default language configuration:
|
|||
|
||||
In the above, `en` is the language key.
|
||||
|
||||
|
||||
Language keys must conform to the syntax described in [RFC 5646]. For example:
|
||||
|
||||
- `en`
|
||||
|
|
@ -80,7 +79,7 @@ defaultContentLanguageInSubdir
|
|||
: (`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`.
|
||||
|
|
@ -110,34 +109,42 @@ weight
|
|||
[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
|
||||
### Site parameters
|
||||
|
||||
{{< new-in 0.112.0 >}}
|
||||
|
||||
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.Title }}
|
||||
{{ site.Language.LanguageCode }}
|
||||
{{ site.Params.color }}
|
||||
{{ site.Params.color }} --> red
|
||||
{{ site.Params.subtitle }} --> Reference, Tutorials, and Explanations
|
||||
```
|
||||
|
||||
When building the English site:
|
||||
|
||||
```go-html-template
|
||||
{{ site.Params.color }} --> blue
|
||||
{{ site.Params.subtitle }} --> 'Referenz, Tutorials und Erklärungen'
|
||||
```
|
||||
|
||||
### Disable a language
|
||||
|
|
@ -165,7 +172,6 @@ Note that you cannot disable the default content language.
|
|||
|
||||
### Configure multilingual multihost
|
||||
|
||||
|
||||
Hugo supports multiple languages in a multihost configuration. This means you can configure a `baseURL` per `language`.
|
||||
|
||||
{{% note %}}
|
||||
|
|
@ -217,7 +223,7 @@ There are two ways to manage your content translations. Both ensure each page is
|
|||
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.
|
||||
|
|
@ -232,7 +238,7 @@ If a file has no language code, it will be assigned the default language.
|
|||
|
||||
### 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:
|
||||
|
|
@ -251,14 +257,14 @@ The value of `contentDir` can be any valid path -- even absolute path references
|
|||
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
|
||||
|
||||
|
|
@ -267,8 +273,8 @@ Any pages sharing the same `translationKey` set in front matter will be linked a
|
|||
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"
|
||||
|
|
|
|||
|
|
@ -30,15 +30,13 @@ The "about" page is a page bundle. It logically associates a resource with conte
|
|||
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
|
||||
|
|
@ -47,13 +45,13 @@ Page bundle characteristics vary by bundle type.
|
|||
|
||||
| | 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
|
||||
|
|
@ -61,11 +59,11 @@ Page bundle characteristics vary by bundle type.
|
|||
[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/
|
||||
|
|
@ -94,7 +92,7 @@ about
|
|||
: 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
|
||||
|
||||
|
|
@ -111,12 +109,12 @@ another-leaf-bundle
|
|||
: 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/
|
||||
|
|
@ -139,23 +137,19 @@ home page
|
|||
: 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
|
||||
|
|
|
|||
|
|
@ -42,9 +42,8 @@ namedSlices
|
|||
: (`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:
|
||||
|
|
@ -65,8 +64,6 @@ We improved and simplified this feature in Hugo 0.111.0. Before this we had 3 di
|
|||
|
||||
## 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 >}}
|
||||
|
|
@ -82,7 +79,7 @@ weight = 80
|
|||
{{< /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 }}
|
||||
|
|
@ -140,16 +137,16 @@ toLower
|
|||
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
|
||||
|
|
@ -157,22 +154,3 @@ 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 %}}
|
||||
|
|
|
|||
|
|
@ -15,10 +15,10 @@ aliases: [/content/sections/]
|
|||
|
||||
## 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:
|
||||
|
|
@ -92,15 +92,15 @@ With the file structure from the [example above](#overview):
|
|||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -72,557 +72,7 @@ You can call shortcodes within other shortcodes by creating your own templates t
|
|||
|
||||
## 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 */>}}
|
||||
```
|
||||
|
||||
### qr
|
||||
|
||||
{{% 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.
|
||||
|
||||
[QR code]: https://en.wikipedia.org/wiki/QR_code
|
||||
|
||||
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 >}}
|
||||
|
||||
Internally this shortcode calls the `images.QR` function. Please read the [related documentation] for implementation details and guidance.
|
||||
|
||||
[related documentation]: /functions/images/qr/
|
||||
|
||||
The `qr` shortcode accepts these named arguments:
|
||||
|
||||
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.
|
||||
|
||||
### 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
|
||||
|
||||
|
|
|
|||
|
|
@ -12,10 +12,10 @@ weight: 160
|
|||
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.
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/s
|
|||
|
||||
## 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:
|
||||
|
||||
|
|
|
|||
|
|
@ -128,7 +128,6 @@ title ="Bar"
|
|||
url = "/:sections[last]/:slug"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
|
||||
## Site configuration
|
||||
|
||||
### Permalinks
|
||||
|
|
@ -473,7 +472,7 @@ Hugo renders alias files before rendering pages. A new page with the previous fi
|
|||
|
||||
### 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.
|
||||
|
|
|
|||
|
|
@ -37,7 +37,7 @@ For a complete guide to contributing to Hugo, see the [Contribution Guide].
|
|||
[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/
|
||||
|
|
@ -172,7 +172,7 @@ CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest
|
|||
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:
|
||||
|
|
|
|||
|
|
@ -22,6 +22,12 @@ For documentation related to a new feature, please include the documentation cha
|
|||
|
||||
## 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:
|
||||
|
|
@ -29,19 +35,41 @@ 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:
|
||||
|
||||
#### Terminology
|
||||
```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
|
||||
|
||||
Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note:
|
||||
|
||||
|
|
@ -54,7 +82,9 @@ Please link to the [glossary of terms] when necessary, and use the terms consist
|
|||
- 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:
|
||||
|
||||
|
|
@ -62,23 +92,23 @@ 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.
|
||||
|
|
@ -87,13 +117,13 @@ 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".
|
||||
|
||||
|
|
@ -105,7 +135,16 @@ For example:
|
|||
[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:
|
||||
|
||||
|
|
@ -133,8 +172,6 @@ Always include the language code when using a fenced code block:
|
|||
```
|
||||
````
|
||||
|
||||
Rendered:
|
||||
|
||||
```go-html-template
|
||||
{{ if eq $foo "bar" }}
|
||||
{{ print "foo is bar" }}
|
||||
|
|
@ -150,8 +187,6 @@ Use this syntax to include shortcodes calls within your code examples:
|
|||
{{%/*/* foo */*/%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
```text
|
||||
{{</* foo */>}}
|
||||
{{%/* foo */%}}
|
||||
|
|
@ -169,8 +204,6 @@ title = 'My Site'
|
|||
{{</* /code-toggle */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
baseURL = 'https://example.org/'
|
||||
languageCode = 'en-US'
|
||||
|
|
@ -189,8 +222,6 @@ draft = false
|
|||
{{</* /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
|
||||
|
|
@ -209,8 +240,6 @@ Use the [code shortcode] for other code examples that require a file name:
|
|||
{{</* /code */>}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
{{ range .Site.RegularPages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
|
|
@ -223,7 +252,7 @@ These shortcodes are commonly used throughout the documentation. Other shortcode
|
|||
|
||||
### 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`.
|
||||
|
|
@ -234,23 +263,50 @@ file
|
|||
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 */%}}
|
||||
|
|
@ -260,8 +316,6 @@ Use [`hugo.IsServer`] instead.
|
|||
{{%/* /deprecated-in */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{% deprecated-in 0.127.0 %}}
|
||||
Use [`hugo.IsServer`] instead.
|
||||
|
||||
|
|
@ -270,7 +324,7 @@ 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].
|
||||
|
|
@ -278,27 +332,41 @@ 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 */%}}
|
||||
|
|
@ -308,8 +376,6 @@ Use the [`math.Mod`] function to control...
|
|||
{{%/* /note */%}}
|
||||
```
|
||||
|
||||
Rendered:
|
||||
|
||||
{{% note %}}
|
||||
Use the [`math.Mod`] function to control...
|
||||
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ Visit [themes.gohugo.io] to browse a collection of themes created by the Hugo co
|
|||
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:
|
||||
|
||||
|
|
|
|||
59
docs/content/en/functions/_common/highlighting-options.md
Normal file
59
docs/content/en/functions/_common/highlighting-options.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
_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 %}}
|
||||
|
|
@ -38,7 +38,7 @@ The template above is rendered to:
|
|||
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" }}
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ action:
|
|||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -33,7 +33,6 @@ To create an empty map:
|
|||
{{ $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
|
||||
|
|
|
|||
|
|
@ -16,11 +16,7 @@ action:
|
|||
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" }}
|
||||
|
|
|
|||
|
|
@ -13,11 +13,10 @@ action:
|
|||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -32,21 +32,15 @@ Hugo will test for equality if you do not provide an `OPERATOR` argument. For ex
|
|||
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).
|
||||
|
||||
|
|
@ -102,9 +96,7 @@ The examples below perform comparisons within a page collection, but the same co
|
|||
|
||||
## 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" }}
|
||||
|
|
@ -113,10 +105,7 @@ Compare the value of the given field to a [`string`]:
|
|||
|
||||
## 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" }}
|
||||
|
|
@ -131,9 +120,7 @@ Compare the value of the given field to an [`int`] or [`float`]:
|
|||
|
||||
## 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" }}
|
||||
|
|
@ -146,10 +133,7 @@ Compare the value of the given field to a [`bool`]:
|
|||
|
||||
## 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":
|
||||
|
||||
|
|
@ -219,7 +203,7 @@ For example, to return a collection of pages that were created before the curren
|
|||
|
||||
### 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.
|
||||
|
|
@ -400,8 +384,8 @@ Is rendered to:
|
|||
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/
|
||||
|
||||
|
|
|
|||
|
|
@ -125,7 +125,7 @@ Run `hugo env` to list the active transpilers.
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -144,8 +144,8 @@ To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file
|
|||
|
||||
```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
|
||||
|
|
@ -178,8 +178,9 @@ To install Dart Sass for your builds on Netlify, the `netlify.toml` file should
|
|||
|
||||
```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]
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ Process the resource:
|
|||
{{ 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -17,15 +17,12 @@ expiryDate: 2025-02-19 # deprecated 2024-02-19
|
|||
---
|
||||
|
||||
{{% 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:
|
||||
|
|
@ -46,7 +43,7 @@ Access the data with either of the following:
|
|||
{{% 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:
|
||||
|
|
@ -134,16 +131,16 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`]
|
|||
|
||||
```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 }}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -17,15 +17,12 @@ expiryDate: 2025-02-19 # deprecated 2024-02-19
|
|||
---
|
||||
|
||||
{{% 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:
|
||||
|
|
@ -137,15 +134,15 @@ Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`]
|
|||
|
||||
```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 }}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ action:
|
|||
|
||||
{{< 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -25,16 +25,16 @@ https://api.github.com/repos/gohugoio/hugo/readme
|
|||
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 }}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -26,7 +26,6 @@ Use the [`warnidf`] function to allow optional suppression of specific warnings.
|
|||
|
||||
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 }}
|
||||
|
|
|
|||
|
|
@ -13,8 +13,6 @@ toc: true
|
|||
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
|
||||
|
|
@ -37,7 +35,7 @@ Do not use the global `page` function in shortcodes, partials called by shortcod
|
|||
|
||||
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.
|
||||
|
||||
|
|
@ -103,7 +101,3 @@ If Hugo renders the section page before a content page, the cached rendered shor
|
|||
|
||||
[`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
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ Within a range block:
|
|||
|
||||
## 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:
|
||||
|
||||
|
|
@ -76,7 +76,6 @@ Gaining a thorough understanding of context is critical for anyone writing templ
|
|||
{{% /note %}}
|
||||
|
||||
[`seq`]: /functions/collections/seq/
|
||||
[context]: /getting-started/glossary/#context
|
||||
|
||||
## Array or slice of scalars
|
||||
|
||||
|
|
|
|||
|
|
@ -13,21 +13,12 @@ action:
|
|||
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 %}}
|
||||
|
|
|
|||
113
docs/content/en/functions/go-template/try.md
Normal file
113
docs/content/en/functions/go-template/try.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
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 %}}
|
||||
|
|
@ -62,7 +62,7 @@ Initialize a variable, scoped to the current block:
|
|||
|
||||
## 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:
|
||||
|
||||
|
|
@ -94,8 +94,6 @@ This template will render the page title as desired:
|
|||
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/
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ action:
|
|||
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
|
||||
|
|
@ -26,5 +26,3 @@ Command|Environment
|
|||
`hugo --environment staging`|`staging`
|
||||
`hugo server`|`development`
|
||||
`hugo server --environment staging`|`staging`
|
||||
|
||||
[environment]: /getting-started/glossary/#environment
|
||||
|
|
|
|||
|
|
@ -11,5 +11,5 @@ action:
|
|||
---
|
||||
|
||||
```go-html-template
|
||||
{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.137.1">
|
||||
{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.141.0">
|
||||
```
|
||||
|
|
|
|||
|
|
@ -15,11 +15,10 @@ toc: true
|
|||
|
||||
{{< 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
|
||||
|
||||
|
|
@ -108,9 +107,7 @@ Removes the given key.
|
|||
|
||||
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 }}
|
||||
|
|
|
|||
|
|
@ -11,5 +11,5 @@ action:
|
|||
---
|
||||
|
||||
```go-html-template
|
||||
{{ hugo.Version }} → 0.137.1
|
||||
{{ hugo.Version }} → 0.141.0
|
||||
```
|
||||
|
|
|
|||
|
|
@ -13,5 +13,3 @@ action:
|
|||
```go-html-template
|
||||
{{ hugo.WorkingDir }} → /home/user/projects/my-hugo-site
|
||||
```
|
||||
|
||||
{{< new-in 0.112.0 >}}
|
||||
|
|
|
|||
|
|
@ -25,12 +25,9 @@ See [image processing] for an overview of Hugo's image pipeline.
|
|||
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 %}}
|
||||
|
|
|
|||
|
|
@ -117,11 +117,10 @@ This example uses the default dithering options.
|
|||
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
|
||||
|
|
@ -157,6 +156,6 @@ For best results, if the dithering palette is grayscale, convert the image to gr
|
|||
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
|
||||
|
|
|
|||
80
docs/content/en/functions/images/Mask.md
Normal file
80
docs/content/en/functions/images/Mask.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
---
|
||||
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
|
||||
>}}
|
||||
|
|
@ -27,11 +27,7 @@ Capture the overlay image as a resource:
|
|||
{{ 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:
|
||||
|
||||
|
|
|
|||
|
|
@ -72,7 +72,6 @@ hint
|
|||
|
||||
[`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" }}
|
||||
|
|
|
|||
|
|
@ -109,4 +109,4 @@ https://gohugo.io
|
|||
|
||||
The `qr` shortcode accepts several arguments including `level` and `scale`. See the [related documentation] for details.
|
||||
|
||||
[related documentation]: /content-management/shortcodes/#qr
|
||||
[related documentation]: /shortcodes/qr/
|
||||
|
|
|
|||
|
|
@ -17,11 +17,15 @@ toc: true
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -37,58 +41,74 @@ x
|
|||
y
|
||||
: (`int`) The vertical offset, in pixels, relative to the top of the image. Default is `10`.
|
||||
|
||||
alignx
|
||||
{{< new-in 0.141.0 >}}
|
||||
: (`string`) The horizontal alignment of the text relative to the `x` position. One of `left`, `center`, or `right`. Default is `left`.
|
||||
|
||||
[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
|
||||
|
||||
|
|
|
|||
|
|
@ -32,12 +32,10 @@ The Batch `ID` is used to create the base directory for this batch. Forward slas
|
|||
* [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.
|
||||
|
|
@ -70,7 +68,6 @@ The `Instance` method takes two `string` arguments `SCRIPT_ID` and `INSTANCE_ID`
|
|||
|
||||
`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.
|
||||
|
|
@ -129,7 +126,6 @@ The runner script's export must be a function that takes one argument, the group
|
|||
|
||||
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';
|
||||
|
|
@ -154,13 +150,11 @@ export default function Run(group) {
|
|||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
#### 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].
|
||||
|
|
@ -233,7 +227,7 @@ Hugo will, by default, first try to resolve any import in [assets](/hugo-pipes/i
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -283,7 +277,6 @@ See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global-
|
|||
{{ end }}
|
||||
```
|
||||
|
||||
|
||||
## Known Issues
|
||||
|
||||
In the official documentation for [ESBuild's code splitting], there's a warning note in the header. The two issues are:
|
||||
|
|
@ -294,7 +287,7 @@ In the official documentation for [ESBuild's code splitting], there's a warning
|
|||
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.
|
||||
|
||||
|
|
@ -307,7 +300,7 @@ console.log('entrypoints-workaround.js');
|
|||
```
|
||||
|
||||
[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/
|
||||
|
|
@ -319,13 +312,12 @@ console.log('entrypoints-workaround.js');
|
|||
[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/
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ format
|
|||
|
||||
{{% 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:
|
||||
|
||||
|
|
@ -79,7 +79,7 @@ For other files (e.g. `JSON`, `CSS`) you need to use the relative path including
|
|||
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.:
|
||||
|
||||
|
|
@ -98,9 +98,9 @@ Hugo will, by default, generate a `assets/jsconfig.json` file that maps the impo
|
|||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ And then in your JS file:
|
|||
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.
|
||||
|
|
@ -74,7 +74,6 @@ sourceMap
|
|||
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
|
||||
|
||||
|
|
@ -96,4 +95,4 @@ const App = () => <>Hello world!</>;
|
|||
|
||||
const container = document.getElementById('app');
|
||||
if (container) render(<App />, container);
|
||||
```
|
||||
```
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ To render placeholders for missing and fallback translations, set
|
|||
|
||||
## 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
|
||||
|
|
|
|||
|
|
@ -10,8 +10,6 @@ action:
|
|||
signatures: [math.Abs VALUE]
|
||||
---
|
||||
|
||||
{{< new-in 0.112.0 >}}
|
||||
|
||||
```go-html-template
|
||||
{{ math.Abs -2.1 }} → 2.1
|
||||
```
|
||||
|
|
|
|||
|
|
@ -15,14 +15,12 @@ action:
|
|||
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
|
||||
|
|
|
|||
|
|
@ -15,10 +15,8 @@ action:
|
|||
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
|
||||
|
|
|
|||
|
|
@ -15,10 +15,8 @@ action:
|
|||
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
|
||||
|
|
|
|||
|
|
@ -12,13 +12,13 @@ action:
|
|||
|
||||
{{< 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 }}
|
||||
|
|
@ -41,6 +41,3 @@ To generate a random float, with one digit after the decimal point, in the close
|
|||
```go-html-template
|
||||
{{ div (math.Rand | mul 50 | math.Ceil) 10 }}
|
||||
```
|
||||
|
||||
[closed interval]: /getting-started/glossary/#interval
|
||||
[half-open interval]: /getting-started/glossary/#interval
|
||||
|
|
|
|||
|
|
@ -15,10 +15,8 @@ action:
|
|||
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
|
||||
|
|
|
|||
|
|
@ -10,11 +10,8 @@ action:
|
|||
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:
|
||||
|
|
@ -22,14 +19,14 @@ 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 }}
|
||||
```
|
||||
|
||||
|
|
@ -59,7 +56,6 @@ To list the GET and POST operations for each of the API paths:
|
|||
|
||||
Hugo renders this to:
|
||||
|
||||
|
||||
```html
|
||||
<p>/pets</p>
|
||||
<dl>
|
||||
|
|
|
|||
|
|
@ -23,7 +23,6 @@ See Go's [`path.Join`] and [`path.Clean`] documentation for details.
|
|||
[`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
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ The [media type] is typically one of `image`, `text`, `audio`, `video`, or `appl
|
|||
```
|
||||
|
||||
{{% 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ action:
|
|||
|
||||
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/
|
||||
|
|
|
|||
|
|
@ -49,8 +49,8 @@ Place this in your baseof.html template:
|
|||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -36,6 +36,6 @@ The hash algorithm may be one of `md5`, `sha256` (default), `sha384`, or `sha512
|
|||
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
|
||||
|
|
|
|||
|
|
@ -19,13 +19,13 @@ Hugo publishes the resource to the target path when you call its [`Publish`], [`
|
|||
[`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"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -48,9 +48,9 @@ Place this in your baseof.html template:
|
|||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ action:
|
|||
```
|
||||
|
||||
{{% 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ action:
|
|||
```
|
||||
|
||||
{{% 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -20,14 +20,14 @@ toc: true
|
|||
|
||||
```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 }}
|
||||
```
|
||||
|
||||
|
|
@ -67,22 +67,21 @@ You can also change the request method and set the request body:
|
|||
|
||||
## 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 }}
|
||||
```
|
||||
|
||||
|
|
@ -98,24 +97,24 @@ In these cases, pass the resource `Content` through the `transform.Unmarshal` fu
|
|||
|
||||
## 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 }}
|
||||
```
|
||||
|
||||
|
|
@ -123,14 +122,14 @@ To log an error as a warning instead of an error:
|
|||
|
||||
```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 }}
|
||||
```
|
||||
|
||||
|
|
@ -142,10 +141,10 @@ The [`Data`] method on a resource returned by the `resources.GetRemote` function
|
|||
|
||||
```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
|
||||
|
|
@ -153,9 +152,9 @@ The [`Data`] method on a resource returned by the `resources.GetRemote` function
|
|||
{{ .StatusCode }} → 200
|
||||
{{ .TransferEncoding }} → []
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $url }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $url }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ action:
|
|||
```
|
||||
|
||||
{{% 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -79,7 +79,7 @@ module.exports = {
|
|||
{{% /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]
|
||||
|
|
@ -122,7 +122,7 @@ HUGO_ENVIRONMENT
|
|||
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
|
||||
|
|
@ -153,6 +153,6 @@ You cannot manipulate the values returned from the resource’s methods. For exa
|
|||
|
||||
[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
|
||||
|
|
|
|||
|
|
@ -126,7 +126,7 @@ Run `hugo env` to list the active transpilers.
|
|||
|
||||
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
|
||||
|
||||
|
|
@ -145,8 +145,8 @@ To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file
|
|||
|
||||
```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
|
||||
|
|
@ -179,8 +179,9 @@ To install Dart Sass for your builds on Netlify, the `netlify.toml` file should
|
|||
|
||||
```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]
|
||||
|
|
|
|||
|
|
@ -26,9 +26,9 @@ aliases: [/functions/safecss]
|
|||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -16,8 +16,6 @@ action:
|
|||
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
|
||||
|
|
|
|||
|
|
@ -20,7 +20,6 @@ The START and END positions are zero-based, where `0` represents the first chara
|
|||
{{ 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/
|
||||
|
|
|
|||
|
|
@ -46,7 +46,6 @@ In some rare use cases, you may need to defer the execution of a template until
|
|||
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 %}}
|
||||
|
|
@ -79,7 +78,6 @@ key (`string`)
|
|||
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 }}
|
||||
|
|
|
|||
|
|
@ -42,13 +42,12 @@ The list of valid time zones may be system dependent, but should include `UTC`,
|
|||
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/
|
||||
|
|
|
|||
|
|
@ -32,7 +32,6 @@ There are 86400 seconds in one day.
|
|||
|
||||
The time unit must be one of the following:
|
||||
|
||||
|
||||
Duration|Valid time units
|
||||
:--|:--
|
||||
hours|`hour`, `h`
|
||||
|
|
|
|||
|
|
@ -37,10 +37,10 @@ Examples of parsable string representations:
|
|||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ This produces a `time.Time` value, with a string representation such as:
|
|||
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
|
||||
|
|
@ -35,7 +35,6 @@ To format and [localize] the value, pass it through the [`time.Format`] function
|
|||
|
||||
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
|
||||
|
|
@ -44,5 +43,4 @@ The `time.Now` function returns a `time.Time` value, so you can chain any of the
|
|||
```
|
||||
|
||||
[`time.Format`]: /functions/time/format/
|
||||
[localize]: /getting-started/glossary/#localization
|
||||
[time methods]: /methods/time/
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Reference in a new issue