mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-18 21:11:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '346b60358dd8ec2ca228e6635bff9d7914b398b7'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-01-23 09:47:46 +01:00
parent 7f0f50b133 346b60358d
commit 43307b07f8
384 changed files with 3305 additions and 3271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/content/en/functions/_common/highlighting-options.md Normal file
View 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 %}}

2
docs/content/en/functions/collections/After.md
View File

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

2
docs/content/en/functions/collections/Append.md
View File

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

1
docs/content/en/functions/collections/Dictionary.md
View File

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

6
docs/content/en/functions/collections/In.md
View File

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

3
docs/content/en/functions/collections/NewScratch.md
View File

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

34
docs/content/en/functions/collections/Where.md
View File

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

11
docs/content/en/functions/css/Sass.md
View File

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

2
docs/content/en/functions/css/TailwindCSS.md
View File

@@ -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
docs/content/en/functions/data/GetCSV.md
View File

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

15
docs/content/en/functions/data/GetJSON.md
View File

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

2
docs/content/en/functions/debug/Timer.md
View File

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

10
docs/content/en/functions/encoding/Base64Decode.md
View File

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

1
docs/content/en/functions/fmt/Warnf.md
View File

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

8
docs/content/en/functions/global/page.md
View File

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

3
docs/content/en/functions/go-template/range.md
View File

@@ -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
docs/content/en/functions/go-template/return.md
View File

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

4
docs/content/en/functions/go-template/with.md
View File

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

4
docs/content/en/functions/hugo/Environment.md
View File

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

2
docs/content/en/functions/hugo/Generator.md
View File

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

7
docs/content/en/functions/hugo/Store.md
View File

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

2
docs/content/en/functions/hugo/Version.md
View File

@@ -11,5 +11,5 @@ action:
---
```go-html-template
{{ hugo.Version }} → 0.137.1
{{ hugo.Version }} → 0.141.0
```

2
docs/content/en/functions/hugo/WorkingDir.md
View File

@@ -13,5 +13,3 @@ action:
```go-html-template
{{ hugo.WorkingDir }} → /home/user/projects/my-hugo-site
```
{{< new-in 0.112.0 >}}

5
docs/content/en/functions/images/Config.md
View File

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

9
docs/content/en/functions/images/Dither.md
View File

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

6
docs/content/en/functions/images/Overlay.md
View File

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

1
docs/content/en/functions/images/Process.md
View File

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

2
docs/content/en/functions/images/QR.md
View File

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

76
docs/content/en/functions/images/Text.md
View File

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

22
docs/content/en/functions/js/Batch.md
View File

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

8
docs/content/en/functions/js/Build.md
View File

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

5
docs/content/en/functions/js/_common/options.md
View File

@@ -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);
```
```

2
docs/content/en/functions/lang/Translate.md
View File

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

2
docs/content/en/functions/math/Abs.md
View File

@@ -10,8 +10,6 @@ action:
signatures: [math.Abs VALUE]
---
{{< new-in 0.112.0 >}}
```go-html-template
{{ math.Abs -2.1 }} → 2.1
```

4
docs/content/en/functions/math/Add.md
View File

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

4
docs/content/en/functions/math/Div.md
View File

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

4
docs/content/en/functions/math/Mul.md
View File

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

7
docs/content/en/functions/math/Rand.md
View File

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

4
docs/content/en/functions/math/Sub.md
View File

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

14
docs/content/en/functions/openapi3/Unmarshal.md
View File

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

1
docs/content/en/functions/path/Join.md
View File

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

2
docs/content/en/functions/resources/ByType.md
View File

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

2
docs/content/en/functions/resources/Concat.md
View File

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

4
docs/content/en/functions/resources/ExecuteAsTemplate.md
View File

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

2
docs/content/en/functions/resources/Fingerprint.md
View File

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

14
docs/content/en/functions/resources/FromString.md
View File

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

2
docs/content/en/functions/resources/Get.md
View File

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

2
docs/content/en/functions/resources/GetMatch.md
View File

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

49
docs/content/en/functions/resources/GetRemote.md
View File

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

2
docs/content/en/functions/resources/Match.md
View File

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

6
docs/content/en/functions/resources/PostProcess.md
View File

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

11
docs/content/en/functions/resources/ToCSS.md
View File

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

6
docs/content/en/functions/safe/CSS.md
View File

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

2
docs/content/en/functions/strings/ContainsNonSpace.md
View File

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

3
docs/content/en/functions/strings/SliceString.md
View File

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

2
docs/content/en/functions/templates/Defer.md
View File

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

9
docs/content/en/functions/time/AsTime.md
View File

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

1
docs/content/en/functions/time/Duration.md
View File

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

6
docs/content/en/functions/time/Format.md
View File

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

4
docs/content/en/functions/time/Now.md
View File

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

1
docs/content/en/functions/time/ParseDuration.md
View File

@@ -17,7 +17,6 @@ aliases: [/functions/time.parseduration]
The `time.ParseDuration` function returns a time.Duration value that you can use with any of the `Duration` [methods].
A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
This template:

1
docs/content/en/functions/transform/Emojify.md
View File

@@ -17,7 +17,6 @@ See the list of [emoji shortcodes] for available emoticons.
The `emojify` function can be called in your templates but not directly in your content files by default. For emojis in content files, set `enableEmoji` to `true` in your site's [configuration]. Then you can write emoji shorthand directly into your content files;
```text
I :heart: Hugo!
```

83
docs/content/en/functions/transform/Highlight.md
View File

@@ -9,81 +9,31 @@ action:
- functions/transform/CanHighlight
- functions/transform/HighlightCodeBlock
returnType: template.HTML
signatures: ['transform.Highlight INPUT LANG [OPTIONS]']
signatures: ['transform.Highlight CODE LANG [OPTIONS]']
aliases: [/functions/highlight]
toc: true
---
The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles.
The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 [available styles].
[chroma]: https://github.com/alecthomas/chroma
[available styles]: https://xyproto.github.io/splash/docs/
## Arguments
INPUT
: The code to highlight.
The `transform.Highlight` shortcode takes three arguments.
CODE
: (`string`) The code to highlight.
LANG
: The language of the code to highlight. Choose from one of the [supported languages]. Case-insensitive.
: (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive.
OPTIONS
: A map or comma-separated list of zero or more options. Set default values in [site configuration].
: (`map or string`) A map or space-separate key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive.
## Options
anchorLineNos
: (`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
codeFences
: (`bool`) Whether to highlight fenced code blocks. Default is `true`.
guessSyntax
: (`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer]. Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
[lexer]: /getting-started/glossary/#lexer
{{% note %}}
The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
{{% /note %}}
hl_Lines
: (`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
hl_inline
: (`bool`) Whether to render the highlighted code without a wrapping container.Default is `false`.
lineAnchors
: (`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
lineNoStart
: (`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
lineNos
: (`bool`) Whether to display a number at the beginning of each line. Default is `false`.
lineNumbersInTable
: (`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
noClasses
: (`bool`) Whether to use inline CSS styles instead of an external CSS file. To use an external CSS file, set this value to `false` and generate the CSS file using the `hugo gen chromastyles` command. Default is `true`.
style
: (`string`) The CSS styles to apply to the highlighted code. See the [style gallery] for examples. Case-sensitive. Default is `monokai`.
tabWidth
: (`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
wrapperClass
{{< new-in 0.140.2 >}}
: (`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
{{% note %}}
Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
lineNos=inline
: equivalent to `lineNos=true` and `lineNumbersInTable=false`
lineNos=table
: equivalent to `lineNos=true` and `lineNumbersInTable=true`
{{% /note %}}
[site configuration]: /getting-started/configuration-markup#highlight
[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages
## Examples
@@ -101,7 +51,6 @@ lineNos=table
{{ transform.Highlight $input $lang $opts }}
```
[Chroma]: https://github.com/alecthomas/chroma
[site configuration]: /getting-started/configuration-markup#highlight
[style gallery]: https://xyproto.github.io/splash/docs/
[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages
## Options
{{% include "functions/_common/highlighting-options" %}}

211
docs/content/en/functions/transform/ToMath.md
View File

@@ -1,112 +1,161 @@
---
title: transform.ToMath
description: Renders a math expression using KaTeX.
description: Renders mathematical equations and expressions written in the LaTeX markup language.
categories: []
keywords: [math,katex]
keywords: [katex,latex,math,typesetting]
action:
aliases: []
related:
- content-management/mathematics
returnType: types.Result[template.HTML]
signatures: ['transform.ToMath EXPRESSION [OPTIONS]']
signatures: ['transform.ToMath INPUT [OPTIONS]']
aliases: [/functions/tomath]
toc: true
---
{{< new-in "0.132.0" >}}
{{% note %}}
This feature was introduced in Hugo 0.132.0 and is marked as experimental.
Hugo uses an embedded instance of the [KaTeX] display engine to render mathematical markup to HTML. You do not need to install the KaTeX display engine.
This does not mean that it's going to be removed, but this is our first use of WASI/Wasm in Hugo, and we need to see how it [works in the wild](https://github.com/gohugoio/hugo/issues/12736) before we can set it in stone.
{{% /note %}}
## Arguments
EXPRESSION
: The math expression to render using KaTeX.
OPTIONS
: A map of zero or more options.
## Options
These are a subset of the [KaTeX options].
output
: (`string`). Determines the markup language of the output. One of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
{{% comment %}}Indent to prevent splitting the description list.{{% / comment %}}
With `html` and `htmlAndMathml` you must include KaTeX CSS within the `head` element of your base template. For example:
```html
<head>
...
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">
...
</head>
```
displayMode
: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`.
leqno
: (`bool`) If `true` render with the equation numbers on the left. Default is `false`.
fleqn
: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`.
minRuleThickness
: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
macros
: (`map`) A map of macros to be used in the math expression. Default is `{}`.
throwOnError
: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTex. See [error handling]. Default is `true`.
errorColor
: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
## Examples
### Basic
[KaTeX]: https://katex.org/
```go-html-template
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }}
```
### Macros
{{% note %}}
By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result.
[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML
To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet.
{{% /note %}}
```go-html-template
{{ $macros := dict
"\\addBar" "\\bar{#1}"
"\\bold" "\\mathbf{#1}"
}}
{{ $opts := dict "macros" $macros }}
{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
{{ $opts := dict "output" "htmlAndMathml" }}
{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" $opts }}
```
## Options
Pass a map of options as the second argument to the `transform.ToMath` function. The options below are a subset of the KaTeX [rendering options].
[rendering options]: https://katex.org/docs/options.html
displayMode
: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`.
errorColor
: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`.
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
fleqn
: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`.
macros
: (`map`) A map of macros to be used in the math expression. Default is `{}`.
```go-html-template
{{ $macros := dict
"\\addBar" "\\bar{#1}"
"\\bold" "\\mathbf{#1}"
}}
{{ $opts := dict "macros" $macros }}
{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }}
```
minRuleThickness
: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`.
output
: (`string`). Determines the markup language of the output, one of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`.
With `html` and `htmlAndMathml` you must include the KaTeX style sheet within the `head` element of your base template.
```html
<link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
throwOnError
: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`.
## Error handling
There are 3 ways to handle errors from KaTeX:
There are three ways to handle errors:
1. Let KaTeX throw an error and make the build fail. This is the default behavior.
1. Handle the error in your template. See the render hook example below.
1. Let KaTeX throw an error and fail the build. This is the default behavior.
1. Set the `throwOnError` option to `false` to make KaTeX render the expression as an error instead of throwing an error. See [options](#options).
1. Handle the error in your template.
{{< code file=layouts/_default/_markup/render-passthrough-inline.html copy=true >}}
{{ with transform.ToMath .Inner }}
{{ with .Err }}
{{ errorf "Failed to render KaTeX: %q. See %s" . $.Position }}
{{ else }}
{{ . }}
{{ end }}
{{ end }}
{{- /* chomp trailing newline */ -}}
The example below demonstrates error handing within a template.
## Example
Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the `transform.ToMath` function.
###### Step 1
Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw Markdown within delimited snippets of text, including the delimiters themselves.
[passthrough extension]: /getting-started/configuration-markup/#passthrough
{{< code-toggle file=hugo copy=true >}}
[markup.goldmark.extensions.passthrough]
enable = true
[markup.goldmark.extensions.passthrough.delimiters]
block = [['\[', '\]'], ['$$', '$$']]
inline = [['\(', '\)']]
{{< /code-toggle >}}
{{% note %}}
The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
{{% /note %}}
###### Step 2
Create a [passthrough render hook] to capture and render the LaTeX markup.
[passthrough render hook]: /render-hooks/passthrough/
{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}}
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with try (transform.ToMath .Inner $opts) }}
{{- with .Err }}
{{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
{{- else }}
{{- .Value }}
{{- $.Page.Store.Set "hasMath" true }}
{{- end }}
{{- end -}}
{{< /code >}}
[error handling]: #error-handling
[KaTeX options]: https://katex.org/docs/options.html
[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
###### Step 3
In your base template, conditionally include the KaTeX CSS within the head element.
{{< code file=layouts/_default/baseof.html copy=true >}}
<head>
{{ $noop := .WordCount }}
{{ if .Page.Store.Get "hasMath" }}
<link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
{{ end }}
</head>
{{< /code >}}
In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
#### Step 4
Add some mathematical markup to your content, then test.
{{< code file=content/example.md >}}
This is an inline \(a^*=x-b^*\) equation.
These are block equations:
\[a^*=x-b^*\]
$$a^*=x-b^*$$
{{< /code >}}

24
docs/content/en/functions/transform/Unmarshal.md
View File

@@ -16,7 +16,7 @@ toc: true
aliases: [/functions/transform.unmarshal]
---
The input can be a string or a [resource].
The input can be a string or a [resource](g).
## Unmarshal a string
@@ -37,7 +37,7 @@ Use the `transform.Unmarshal` function with global, page, and remote resources.
### Global resource
A global resource is a file within the assets directory, or within any directory mounted to the assets directory.
A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory.
```text
assets/
@@ -97,14 +97,14 @@ A remote resource is a file on a remote server, accessible via HTTP or HTTPS.
```go-html-template
{{ $data := dict }}
{{ $url := "https://example.org/books.json" }}
{{ with resources.GetRemote $url }}
{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else }}
{{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ range where $data "author" "Victor Hugo" }}
@@ -175,14 +175,14 @@ Get the remote data:
```go-html-template
{{ $data := dict }}
{{ $url := "https://example.org/books/index.xml" }}
{{ with resources.GetRemote $url }}
{{ with try (resources.GetRemote $url) }}
{{ with .Err }}
{{ errorf "%s" . }}
{{ else }}
{{ else with .Value }}
{{ $data = . | transform.Unmarshal }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
{{ else }}
{{ errorf "Unable to get remote resource %q" $url }}
{{ end }}
```
@@ -271,7 +271,7 @@ Each item node looks like this:
}
```
The title keys do not begin with an underscore or a letter---they are not valid [identifiers]. Use the [`index`] function to access the values:
The title keys do not begin with an underscore or a letter---they are not valid [identifiers](g). Use the [`index`] function to access the values:
```go-html-template
{{ with $data.channel.item }}
@@ -296,6 +296,4 @@ Hugo renders this to:
```
[`index`]: /functions/collections/indexfunction/
[identifiers]: https://go.dev/ref/spec#Identifiers
[resource]: /getting-started/glossary/#resource
[page bundle]: /content-management/page-bundles/

2
docs/content/en/functions/urls/JoinPath.md
View File

@@ -12,8 +12,6 @@ action:
aliases: [/functions/urls.joinpath]
---
{{< new-in 0.112.0 >}}
```go-html-template
{{ urls.JoinPath }} → "" (empty string)
{{ urls.JoinPath "" }} → /

2
docs/content/en/functions/urls/Ref.md
View File

@@ -35,7 +35,7 @@ The second argument is a path to a page, with or without a file extension, with
Instead of specifying a path, you can also provide an options map:
path
: (`string`) The path to the page, relative to the content directory. Required.
: (`string`) The path to the page, relative to the `content` directory. Required.
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.

2
docs/content/en/functions/urls/RelRef.md
View File

@@ -42,7 +42,7 @@ Code|baseURL|Permalink
Instead of specifying a path, you can also provide an options map:
path
: (`string`) The path to the page, relative to the content directory. Required.
: (`string`) The path to the page, relative to the `content` directory. Required.
lang
: (`string`) The language (site) to search for the page. Default is the current language. Optional.

3
docs/content/en/functions/urls/URLize.md
View File

@@ -16,7 +16,7 @@ aliases: [/functions/urlize]
## Example
Use the `urlize` function to create a link to a [term] page.
Use the `urlize` function to create a link to a [term page](g).
Consider this site configuration:
@@ -60,4 +60,3 @@ To create a link to the term page:
To generate a list of term pages associated with a given content page, use the [`GetTerms`] method on a `Page` object.
[`GetTerms`]: /methods/page/getterms/
[term]: /getting-started/glossary/#term