diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2025-04-10 13:04:51 +0200 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2025-04-10 13:04:51 +0200 |
commit | 653f1c1d462332bccf303a5040e5cd99c89a4378 (patch) | |
tree | c993984f169a240567526e9993261241c0cda771 /docs/content/en/functions | |
parent | 208a0de6c31354df6f9463d49e90db9dec935169 (diff) | |
parent | 5be51ac3db225d5df501ed1fa1499c41d97dbf65 (diff) | |
download | hugo-653f1c1d462332bccf303a5040e5cd99c89a4378.tar.gz hugo-653f1c1d462332bccf303a5040e5cd99c89a4378.zip |
Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'
Diffstat (limited to 'docs/content/en/functions')
315 files changed, 2302 insertions, 3614 deletions
diff --git a/docs/content/en/functions/_common/_index.md b/docs/content/en/functions/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/functions/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/functions/_common/glob-patterns.md b/docs/content/en/functions/_common/glob-patterns.md deleted file mode 100644 index d3092dece..000000000 --- a/docs/content/en/functions/_common/glob-patterns.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Path|Pattern|Match -:--|:--|:-- -`images/foo/a.jpg`|`images/foo/*.jpg`|`true` -`images/foo/a.jpg`|`images/foo/*.*`|`true` -`images/foo/a.jpg`|`images/foo/*`|`true` -`images/foo/a.jpg`|`images/*/*.jpg`|`true` -`images/foo/a.jpg`|`images/*/*.*`|`true` -`images/foo/a.jpg`|`images/*/*`|`true` -`images/foo/a.jpg`|`*/*/*.jpg`|`true` -`images/foo/a.jpg`|`*/*/*.*`|`true` -`images/foo/a.jpg`|`*/*/*`|`true` -`images/foo/a.jpg`|`**/*.jpg`|`true` -`images/foo/a.jpg`|`**/*.*`|`true` -`images/foo/a.jpg`|`**/*`|`true` -`images/foo/a.jpg`|`**`|`true` -`images/foo/a.jpg`|`*/*.jpg`|`false` -`images/foo/a.jpg`|`*.jpg`|`false` -`images/foo/a.jpg`|`*.*`|`false` -`images/foo/a.jpg`|`*`|`false` diff --git a/docs/content/en/functions/_common/go-html-template-package.md b/docs/content/en/functions/_common/go-html-template-package.md deleted file mode 100644 index 57992ea66..000000000 --- a/docs/content/en/functions/_common/go-html-template-package.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Hugo uses Go's [text/template] and [html/template] packages. - -The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection. - -By default, Hugo uses the html/template package when rendering HTML files. - -To generate HTML output that is safe against code injection, the html/template package escapes strings in certain contexts. - -[text/template]: https://pkg.go.dev/text/template -[html/template]: https://pkg.go.dev/html/template diff --git a/docs/content/en/functions/_common/highlighting-options.md b/docs/content/en/functions/_common/highlighting-options.md deleted file mode 100644 index 2d07ccccc..000000000 --- a/docs/content/en/functions/_common/highlighting-options.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -_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 %}} diff --git a/docs/content/en/functions/_common/locales.md b/docs/content/en/functions/_common/locales.md deleted file mode 100644 index 42d008776..000000000 --- a/docs/content/en/functions/_common/locales.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -{{% note %}} - -Localization of dates, currencies, numbers, and percentages is performed by the [gohugoio/locales] package. The language tag of the current site must match one of the listed locales. - -[gohugoio/locales]: https://github.com/gohugoio/locales -{{% /note %}} diff --git a/docs/content/en/functions/_common/regular-expressions.md b/docs/content/en/functions/_common/regular-expressions.md deleted file mode 100644 index 58f81a2ee..000000000 --- a/docs/content/en/functions/_common/regular-expressions.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -When specifying the regular expression, use a raw [string literal] (backticks) instead of an interpreted string literal (double quotes) to simplify the syntax. With an interpreted string literal you must escape backslashes. - -Go's regular expression package implements the [RE2 syntax]. The RE2 syntax is a subset of that accepted by [PCRE], roughly speaking, and with various [caveats]. Note that the RE2 `\C` escape sequence is not supported. - -[caveats]: https://swtch.com/~rsc/regexp/regexp3.html#caveats -[PCRE]: https://www.pcre.org/ -[RE2 syntax]: https://github.com/google/re2/wiki/Syntax/ -[string literal]: https://go.dev/ref/spec#String_literals diff --git a/docs/content/en/functions/_common/time-layout-string.md b/docs/content/en/functions/_common/time-layout-string.md deleted file mode 100644 index 3664eaef2..000000000 --- a/docs/content/en/functions/_common/time-layout-string.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Format a `time.Time` value based on [Go's reference time]: - -[Go's reference time]: https://pkg.go.dev/time#pkg-constants - -```text -Mon Jan 2 15:04:05 MST 2006 -``` - -Create a layout string using these components: - -Description|Valid components -:--|:-- -Year|`"2006" "06"` -Month|`"Jan" "January" "01" "1"` -Day of the week|`"Mon" "Monday"` -Day of the month|`"2" "_2" "02"` -Day of the year|`"__2" "002"` -Hour|`"15" "3" "03"` -Minute|`"4" "04"` -Second|`"5" "05"` -AM/PM mark|`"PM"` -Time zone offsets|`"-0700" "-07:00" "-07" "-070000" "-07:00:00"` - -Replace the sign in the layout string with a Z to print Z instead of an offset for the UTC zone. - -Description|Valid components -:--|:-- -Time zone offsets|`"Z0700" "Z07:00" "Z07" "Z070000" "Z07:00:00"` - -```go-html-template -{{ $t := "2023-01-27T23:44:58-08:00" }} -{{ $t = time.AsTime $t }} -{{ $t = $t.Format "Jan 02, 2006 3:04 PM Z07:00" }} - -{{ $t }} → Jan 27, 2023 11:44 PM -08:00 -``` - -Strings such as `PST` and `CET` are not time zones. They are time zone _abbreviations_. - -Strings such as `-07:00` and `+01:00` are not time zones. They are time zone _offsets_. - -A time zone is a geographic area with the same local time. For example, the time zone abbreviated by `PST` and `PDT` (depending on Daylight Savings Time) is `America/Los_Angeles`. diff --git a/docs/content/en/functions/_index.md b/docs/content/en/functions/_index.md index 95d766b13..d3081210b 100644 --- a/docs/content/en/functions/_index.md +++ b/docs/content/en/functions/_index.md @@ -1,17 +1,8 @@ --- title: Functions - description: Use these functions within your templates and archetypes. categories: [] keywords: [] -menu: - docs: - identifier: functions-in-this-section - parent: functions - weight: 10 weight: 10 -showSectionMenu: true aliases: [/layout/functions/,/templates/functions] --- - -Use these functions within your templates and archetypes. diff --git a/docs/content/en/functions/cast/ToFloat.md b/docs/content/en/functions/cast/ToFloat.md index 51bc908b6..572042937 100644 --- a/docs/content/en/functions/cast/ToFloat.md +++ b/docs/content/en/functions/cast/ToFloat.md @@ -3,13 +3,11 @@ title: cast.ToFloat description: Converts a value to a decimal floating-point number (base 10). categories: [] keywords: [] -action: - aliases: [float] - related: - - functions/cast/ToInt - - functions/cast/ToString - returnType: float64 - signatures: [cast.ToFloat INPUT] +params: + functions_and_methods: + aliases: [float] + returnType: float64 + signatures: [cast.ToFloat INPUT] aliases: [/functions/float] --- diff --git a/docs/content/en/functions/cast/ToInt.md b/docs/content/en/functions/cast/ToInt.md index c4bb10268..4ede69229 100644 --- a/docs/content/en/functions/cast/ToInt.md +++ b/docs/content/en/functions/cast/ToInt.md @@ -2,13 +2,11 @@ title: cast.ToInt description: Converts a value to a decimal integer (base 10). keywords: [] -action: - aliases: [int] - related: - - functions/cast/ToFloat - - functions/cast/ToString - returnType: int - signatures: [cast.ToInt INPUT] +params: + functions_and_methods: + aliases: [int] + returnType: int + signatures: [cast.ToInt INPUT] aliases: [/functions/int] --- @@ -46,8 +44,7 @@ With a hexadecimal (base 16) input: {{ int "0x11" }} → 17 (int) ``` -{{% note %}} -Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros: +> [!note] +> Values with a leading zero are octal (base 8). When casting a string representation of a decimal (base 10) number, remove leading zeros: `{{ strings.TrimLeft "0" "0011" | int }} → 11` -{{% /note %}} diff --git a/docs/content/en/functions/cast/ToString.md b/docs/content/en/functions/cast/ToString.md index a701c9421..1bba001c9 100644 --- a/docs/content/en/functions/cast/ToString.md +++ b/docs/content/en/functions/cast/ToString.md @@ -3,13 +3,11 @@ title: cast.ToString description: Converts a value to a string. categories: [] keywords: [] -action: - aliases: [string] - related: - - functions/cast/ToFloat - - functions/cast/ToInt - returnType: string - signatures: [cast.ToString INPUT] +params: + functions_and_methods: + aliases: [string] + returnType: string + signatures: [cast.ToString INPUT] aliases: [/functions/string] --- diff --git a/docs/content/en/functions/cast/_index.md b/docs/content/en/functions/cast/_index.md index 82389237a..1584ab159 100644 --- a/docs/content/en/functions/cast/_index.md +++ b/docs/content/en/functions/cast/_index.md @@ -1,12 +1,7 @@ --- title: Cast functions linkTitle: cast -description: Template functions to cast a value from one data type to another. +description: Use these functions to cast a value from one data type to another. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to cast a value from one data type to another. diff --git a/docs/content/en/functions/collections/After.md b/docs/content/en/functions/collections/After.md index 1f2759da6..c8a822846 100644 --- a/docs/content/en/functions/collections/After.md +++ b/docs/content/en/functions/collections/After.md @@ -3,13 +3,11 @@ title: collections.After description: Slices an array to the items after the Nth item. categories: [] keywords: [] -action: - aliases: [after] - related: - - functions/collections/First - - functions/collections/Last - returnType: any - signatures: [collections.After INDEX COLLECTION] +params: + functions_and_methods: + aliases: [after] + returnType: any + signatures: [collections.After INDEX COLLECTION] aliases: [/functions/after] --- @@ -40,7 +38,7 @@ You can use `after` in combination with the [`first`] function and Hugo's [power 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). 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 >}} +```go-html-template {file="layouts/section/articles.html"} {{ define "main" }} <section class="row featured-article"> <h2>Featured Article</h2> @@ -63,7 +61,7 @@ You can use `after` in combination with the [`first`] function and Hugo's [power {{ end }} </div> {{ end }} -{{< /code >}} +``` [`first`]: /functions/collections/first/ [`slice`]: /functions/collections/slice/ diff --git a/docs/content/en/functions/collections/Append.md b/docs/content/en/functions/collections/Append.md index 7189c9068..cf1d1a3f5 100644 --- a/docs/content/en/functions/collections/Append.md +++ b/docs/content/en/functions/collections/Append.md @@ -3,14 +3,13 @@ title: collections.Append description: Appends one or more elements to a slice and returns the resulting slice. categories: [] keywords: [] -action: - aliases: [append] - related: - - functions/collections/Merge - returnType: any - signatures: - - collections.Append ELEMENT [ELEMENT...] COLLECTION - - collections.Append COLLECTION1 COLLECTION2 +params: + functions_and_methods: + aliases: [append] + returnType: any + signatures: + - collections.Append ELEMENT [ELEMENT...] COLLECTION + - collections.Append COLLECTION1 COLLECTION2 aliases: [/functions/append] --- diff --git a/docs/content/en/functions/collections/Apply.md b/docs/content/en/functions/collections/Apply.md index 9153e546a..7ffe49053 100644 --- a/docs/content/en/functions/collections/Apply.md +++ b/docs/content/en/functions/collections/Apply.md @@ -3,11 +3,11 @@ title: collections.Apply description: Returns a new collection with each element transformed by the given function. categories: [] keywords: [] -action: - aliases: [apply] - related: [] - returnType: '[]any' - signatures: [collections.Apply COLLECTION FUNCTION PARAM...] +params: + functions_and_methods: + aliases: [apply] + returnType: '[]any' + signatures: [collections.Apply COLLECTION FUNCTION PARAM...] aliases: [/functions/apply] --- diff --git a/docs/content/en/functions/collections/Complement.md b/docs/content/en/functions/collections/Complement.md index 1c785de0b..ce810dc00 100644 --- a/docs/content/en/functions/collections/Complement.md +++ b/docs/content/en/functions/collections/Complement.md @@ -3,14 +3,11 @@ title: collections.Complement description: Returns the elements of the last collection that are not in any of the others. categories: [] keywords: [] -action: - aliases: [complement] - related: - - functions/collections/Intersect - - functions/collections/SymDiff - - functions/collections/Union - returnType: any - signatures: ['collections.Complement COLLECTION [COLLECTION...]'] +params: + functions_and_methods: + aliases: [complement] + returnType: any + signatures: ['collections.Complement COLLECTION [COLLECTION...]'] aliases: [/functions/complement] --- @@ -24,11 +21,8 @@ To find the elements within `$c3` that do not exist in `$c1` or `$c2`: {{ complement $c1 $c2 $c3 }} → [1 2] ``` -{{% note %}} -Make your code simpler to understand by using a [chained pipeline]: - -[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines -{{% /note %}} +> [!note] +> Make your code simpler to understand by using a [chained pipeline]: ```go-html-template {{ $c3 | complement $c1 $c2 }} → [1 2] @@ -55,11 +49,8 @@ To list everything except blog articles (`blog`) and frequently asked questions {{ end }} ``` -{{% note %}} -Although the example above demonstrates the `complement` function, you could use the [`where`] function as well: - -[`where`]: /functions/collections/where/ -{{% /note %}} +> [!note] +> Although the example above demonstrates the `complement` function, you could use the [`where`] function as well: ```go-html-template {{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }} @@ -77,4 +68,6 @@ In this example we use the `complement` function to remove [stop words] from a s {{ delimit $filtered " " }} → The quick brown fox jumps lazy dog ``` +[`where`]: /functions/collections/where/ +[chained pipeline]: https://pkg.go.dev/text/template#hdr-Pipelines [stop words]: https://en.wikipedia.org/wiki/Stop_word diff --git a/docs/content/en/functions/collections/Delimit.md b/docs/content/en/functions/collections/Delimit.md index b85059d4b..9d09620aa 100644 --- a/docs/content/en/functions/collections/Delimit.md +++ b/docs/content/en/functions/collections/Delimit.md @@ -3,12 +3,11 @@ title: collections.Delimit description: Loops through any array, slice, or map and returns a string of all the values separated by a delimiter. categories: [] keywords: [] -action: - aliases: [delimit] - related: - - functions/strings/Split - returnType: string - signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]'] +params: + functions_and_methods: + aliases: [delimit] + returnType: string + signatures: ['collections.Delimit COLLECTION DELIMITER [LAST]'] aliases: [/functions/delimit] --- @@ -22,9 +21,8 @@ Delimit a slice: Delimit a map: -{{% note %}} -The `delimit` function sorts maps by key, returning the values. -{{% /note %}} +> [!note] +> The `delimit` function sorts maps by key, returning the values. ```go-html-template {{ $m := dict "b" 2 "a" 1 "c" 3 }} diff --git a/docs/content/en/functions/collections/Dictionary.md b/docs/content/en/functions/collections/Dictionary.md index a55838e27..8aa428106 100644 --- a/docs/content/en/functions/collections/Dictionary.md +++ b/docs/content/en/functions/collections/Dictionary.md @@ -3,12 +3,11 @@ title: collections.Dictionary description: Returns a map composed of the given key-value pairs. categories: [] keywords: [] -action: - aliases: [dict] - related: - - functions/collections/Slice - returnType: map[string]any - signatures: ['collections.Dictionary [VALUE...]'] +params: + functions_and_methods: + aliases: [dict] + returnType: map[string]any + signatures: ['collections.Dictionary [VALUE...]'] aliases: [/functions/dict] --- diff --git a/docs/content/en/functions/collections/First.md b/docs/content/en/functions/collections/First.md index 07634d6b8..9a672278d 100644 --- a/docs/content/en/functions/collections/First.md +++ b/docs/content/en/functions/collections/First.md @@ -3,14 +3,11 @@ title: collections.First description: Returns the given collection, limited to the first N elements. categories: [] keywords: [] -action: - aliases: [first] - related: - - functions/collections/After - - functions/collections/Last - - methods/pages/Limit - returnType: any - signatures: [collections.First N COLLECTION] +params: + functions_and_methods: + aliases: [first] + returnType: any + signatures: [collections.First N COLLECTION] aliases: [/functions/first] --- @@ -23,7 +20,7 @@ aliases: [/functions/first] Set `N` to zero to return an empty collection. ```go-html-template -{{ $emptyPageCollection := first 0 .Pages}} +{{ $emptyPageCollection := first 0 .Pages }} ``` Use `first` and [`where`] together. diff --git a/docs/content/en/functions/collections/Group.md b/docs/content/en/functions/collections/Group.md index 0ec45516c..4b269b92a 100644 --- a/docs/content/en/functions/collections/Group.md +++ b/docs/content/en/functions/collections/Group.md @@ -3,11 +3,11 @@ title: collections.Group description: Groups the given page collection by the given key. categories: [] keywords: [] -action: - aliases: [group] - related: [] - returnType: any - signatures: [collections.Group KEY PAGES] +params: + functions_and_methods: + aliases: [group] + returnType: any + signatures: [collections.Group KEY PAGES] aliases: [/functions/group] --- diff --git a/docs/content/en/functions/collections/In.md b/docs/content/en/functions/collections/In.md index 754c65f83..e94b4b0ed 100644 --- a/docs/content/en/functions/collections/In.md +++ b/docs/content/en/functions/collections/In.md @@ -3,16 +3,11 @@ title: collections.In description: Reports whether the given value is a member of the given set. categories: [] keywords: [] -action: - aliases: [in] - related: - - functions/strings/Contains - - functions/strings/ContainsAny - - functions/strings/ContainsNonSpace - - functions/strings/HasPrefix - - functions/strings/HasSuffix - returnType: bool - signatures: [collections.In SET VALUE] +params: + functions_and_methods: + aliases: [in] + returnType: bool + signatures: [collections.In SET VALUE] aliases: [/functions/in] --- diff --git a/docs/content/en/functions/collections/IndexFunction.md b/docs/content/en/functions/collections/IndexFunction.md index 977e14d1e..248595961 100644 --- a/docs/content/en/functions/collections/IndexFunction.md +++ b/docs/content/en/functions/collections/IndexFunction.md @@ -3,12 +3,11 @@ title: collections.Index description: Returns the object, element, or value associated with the given key or keys. categories: [] keywords: [] -action: - aliases: [index] - related: [] - returnType: any - signatures: - - collections.Index COLLECTION KEY... +params: + functions_and_methods: + aliases: [index] + returnType: any + signatures: [collections.Index COLLECTION KEY...] aliases: [/functions/index,/functions/index-function] --- diff --git a/docs/content/en/functions/collections/Intersect.md b/docs/content/en/functions/collections/Intersect.md index 9e9cc0c76..ffa9c8196 100644 --- a/docs/content/en/functions/collections/Intersect.md +++ b/docs/content/en/functions/collections/Intersect.md @@ -3,14 +3,11 @@ title: collections.Intersect description: Returns the common elements of two arrays or slices, in the same order as the first array. categories: [] keywords: [] -action: - aliases: [intersect] - related: - - functions/collections/Complement - - functions/collections/SymDiff - - functions/collections/Union - returnType: any - signatures: [collections.Intersect SET1 SET2] +params: + functions_and_methods: + aliases: [intersect] + returnType: any + signatures: [collections.Intersect SET1 SET2] aliases: [/functions/intersect] --- diff --git a/docs/content/en/functions/collections/IsSet.md b/docs/content/en/functions/collections/IsSet.md index 62b81b712..5457df5d4 100644 --- a/docs/content/en/functions/collections/IsSet.md +++ b/docs/content/en/functions/collections/IsSet.md @@ -3,13 +3,11 @@ title: collections.IsSet description: Reports whether the key exists within the collection. categories: [] keywords: [] -action: - aliases: [isset] - related: - - functions/go-template/if - - functions/go-template/with - returnType: bool - signatures: [collections.IsSet COLLECTION KEY] +params: + functions_and_methods: + aliases: [isset] + returnType: bool + signatures: [collections.IsSet COLLECTION KEY] aliases: [/functions/isset] --- @@ -40,6 +38,5 @@ But if the value of `showHeroImage` is `false`, we can't use either `if` or `wit {{ end }} ``` -{{% note %}} -When using the `isset` function you must reference the key using lower case. See the previous example. -{{% /note %}} +> [!note] +> When using the `isset` function you must reference the key using lower case. See the previous example. diff --git a/docs/content/en/functions/collections/KeyVals.md b/docs/content/en/functions/collections/KeyVals.md index 6a2109e78..bd58caea0 100644 --- a/docs/content/en/functions/collections/KeyVals.md +++ b/docs/content/en/functions/collections/KeyVals.md @@ -3,12 +3,11 @@ title: collections.KeyVals description: Returns a KeyVals struct. categories: [] keywords: [] -action: - aliases: [keyVals] - related: - - methods/pages/Related - returnType: types.KeyValues - signatures: [collections.KeyVals KEY VALUE...] +params: + functions_and_methods: + aliases: [keyVals] + returnType: types.KeyValues + signatures: [collections.KeyVals KEY VALUE...] aliases: [/functions/keyvals] --- @@ -16,7 +15,7 @@ The primary application for this function is the definition of the `namedSlices` [`Related`]: /methods/pages/related/ -See [related content](/content-management/related). +See [related content](/content-management/related-content/). ```go-html-template {{ $kv := keyVals "foo" "a" "b" "c" }} diff --git a/docs/content/en/functions/collections/Last.md b/docs/content/en/functions/collections/Last.md index 7739b8726..f0cfff219 100644 --- a/docs/content/en/functions/collections/Last.md +++ b/docs/content/en/functions/collections/Last.md @@ -3,13 +3,11 @@ title: collections.Last description: Returns the given collection, limited to the last N elements. categories: [] keywords: [] -action: - aliases: [last] - related: - - functions/collections/After - - functions/collections/First - returnType: any - signatures: [collections.Last N COLLECTION] +params: + functions_and_methods: + aliases: [last] + returnType: any + signatures: [collections.Last N COLLECTION] aliases: [/functions/last] --- @@ -22,7 +20,7 @@ aliases: [/functions/last] Set `N` to zero to return an empty collection. ```go-html-template -{{ $emptyPageCollection := last 0 .Pages}} +{{ $emptyPageCollection := last 0 .Pages }} ``` Use `last` and [`where`] together. diff --git a/docs/content/en/functions/collections/Merge.md b/docs/content/en/functions/collections/Merge.md index 3f5208cfc..c9998be39 100644 --- a/docs/content/en/functions/collections/Merge.md +++ b/docs/content/en/functions/collections/Merge.md @@ -3,12 +3,11 @@ title: collections.Merge description: Returns the result of merging two or more maps. categories: [] keywords: [] -action: - aliases: [merge] - related: - - functions/collections/Append - returnType: any - signatures: [collections.Merge MAP MAP...] +params: + functions_and_methods: + aliases: [merge] + returnType: any + signatures: [collections.Merge MAP MAP...] aliases: [/functions/merge] --- @@ -64,6 +63,5 @@ Example 4 {{ $merged.z.a }} → huey ``` -{{% note %}} -Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append). -{{% /note %}} +> [!note] +> Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append). diff --git a/docs/content/en/functions/collections/NewScratch.md b/docs/content/en/functions/collections/NewScratch.md index a76168961..34fc7f5d6 100644 --- a/docs/content/en/functions/collections/NewScratch.md +++ b/docs/content/en/functions/collections/NewScratch.md @@ -3,23 +3,18 @@ title: collections.NewScratch description: Returns a locally scoped "scratch pad" to store and manipulate data. categories: [] keywords: [] -action: - aliases: [newScratch] - related: - - methods/page/Store - - methods/site/Store - - methods/shortcode/Store - - functions/hugo/Store - returnType: maps.Scratch - signatures: [collections.NewScratch ] -toc: true +params: + functions_and_methods: + aliases: [newScratch] + returnType: maps.Scratch + signatures: [collections.NewScratch ] --- Use the `collections.NewScratch` function to create a locally scoped [scratch pad](g) to store and manipulate data. To create a scratch pad with a different [scope](g), refer to the [scope](#scope) section below. ## Methods -###### Set +### Set Sets the value of the given key. @@ -28,7 +23,7 @@ Sets the value of the given key. {{ $s.Set "greeting" "Hello" }} ``` -###### Get +### Get Gets the value of the given key. @@ -38,7 +33,7 @@ Gets the value of the given key. {{ $s.Get "greeting" }} → Hello ``` -###### Add +### Add Adds the given value to existing value(s) of the given key. @@ -65,7 +60,7 @@ For single values, `Add` accepts values that support Go's `+` operator. If the f {{ $s.Get "greetings" }} → [Hello Welcome Cheers] ``` -###### SetInMap +### SetInMap Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. @@ -76,7 +71,7 @@ Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to th {{ $s.Get "greetings" }} → map[english:Hello french:Bonjour] ``` -###### DeleteInMap +### DeleteInMap Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. @@ -88,7 +83,7 @@ Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. {{ $s.Get "greetings" }} → map[french:Bonjour] ``` -###### GetSortedMapValues +### GetSortedMapValues Returns an array of values from `key` sorted by `mapKey`. @@ -99,7 +94,7 @@ Returns an array of values from `key` sorted by `mapKey`. {{ $s.GetSortedMapValues "greetings" }} → [Hello Bonjour] ``` -###### Delete +### Delete Removes the given key. @@ -109,9 +104,9 @@ Removes the given key. {{ $s.Delete "greeting" }} ``` -###### Values +### Values -Returns the raw backing map. Do not use with `Scratch` or `Store` methods on a `Page` object due to concurrency issues. +Returns the raw backing map. Do not use with `Store` methods on a `Page` object due to concurrency issues. ```go-html-template {{ $s := newScratch }} diff --git a/docs/content/en/functions/collections/Querify.md b/docs/content/en/functions/collections/Querify.md index 0eb409421..fd74935b7 100644 --- a/docs/content/en/functions/collections/Querify.md +++ b/docs/content/en/functions/collections/Querify.md @@ -3,13 +3,11 @@ title: collections.Querify description: Returns a URL query string composed of the given key-value pairs, encoded and sorted by key. categories: [] keywords: [] -action: - aliases: [querify] - related: - - functions/go-template/urlquery.md - returnType: string - signatures: - - collections.Querify [VALUE...] +params: + functions_and_methods: + aliases: [querify] + returnType: string + signatures: ['collections.Querify [VALUE...]'] aliases: [/functions/querify] --- diff --git a/docs/content/en/functions/collections/Reverse.md b/docs/content/en/functions/collections/Reverse.md index d0a449763..ee455939c 100644 --- a/docs/content/en/functions/collections/Reverse.md +++ b/docs/content/en/functions/collections/Reverse.md @@ -3,14 +3,11 @@ title: collections.Reverse description: Reverses the order of a collection. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/collections/Sort - - functions/collections/Shuffle - - functions/collections/Uniq - returnType: any - signatures: [collections.Reverse COLLECTION] +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: [collections.Reverse COLLECTION] aliases: [/functions/collections.reverse] --- diff --git a/docs/content/en/functions/collections/Seq.md b/docs/content/en/functions/collections/Seq.md index b572bd7c0..e396f07e3 100644 --- a/docs/content/en/functions/collections/Seq.md +++ b/docs/content/en/functions/collections/Seq.md @@ -3,14 +3,14 @@ title: collections.Seq description: Returns a slice of integers. categories: [] keywords: [] -action: - aliases: [seq] - related: [] - returnType: '[]int' - signatures: - - collections.Seq LAST - - collections.Seq FIRST LAST - - collections.Seq FIRST INCREMENT LAST +params: + functions_and_methods: + aliases: [seq] + returnType: '[]int' + signatures: + - collections.Seq LAST + - collections.Seq FIRST LAST + - collections.Seq FIRST INCREMENT LAST aliases: [/functions/seq] --- @@ -31,6 +31,5 @@ A contrived example of iterating over a sequence of integers: {{ $product }} → 24 ``` -{{% note %}} -The slice created by the `seq` function is limited to 2000 elements. -{{% /note %}} +> [!note] +> The slice created by the `seq` function is limited to 2000 elements. diff --git a/docs/content/en/functions/collections/Shuffle.md b/docs/content/en/functions/collections/Shuffle.md index 0f28eb4d8..3a27c099a 100644 --- a/docs/content/en/functions/collections/Shuffle.md +++ b/docs/content/en/functions/collections/Shuffle.md @@ -3,14 +3,11 @@ title: collections.Shuffle description: Returns a random permutation of a given array or slice. categories: [] keywords: [] -action: - aliases: [shuffle] - related: - - functions/collections/Reverse - - functions/collections/Sort - - functions/collections/Uniq - returnType: any - signatures: [collections.Shuffle COLLECTION] +params: + functions_and_methods: + aliases: [shuffle] + returnType: any + signatures: [collections.Shuffle COLLECTION] aliases: [/functions/shuffle] --- diff --git a/docs/content/en/functions/collections/Slice.md b/docs/content/en/functions/collections/Slice.md index 385f9b658..76180fabe 100644 --- a/docs/content/en/functions/collections/Slice.md +++ b/docs/content/en/functions/collections/Slice.md @@ -3,12 +3,11 @@ title: collections.Slice description: Returns a slice composed of the given values. categories: [] keywords: [] -action: - aliases: [slice] - related: - - functions/collections/Dictionary - returnType: any - signatures: ['collections.Slice [VALUE...]'] +params: + functions_and_methods: + aliases: [slice] + returnType: any + signatures: ['collections.Slice [VALUE...]'] aliases: [/functions/slice] --- diff --git a/docs/content/en/functions/collections/Sort.md b/docs/content/en/functions/collections/Sort.md index 815260f20..67e5de5cb 100644 --- a/docs/content/en/functions/collections/Sort.md +++ b/docs/content/en/functions/collections/Sort.md @@ -3,15 +3,11 @@ title: collections.Sort description: Sorts slices, maps, and page collections. categories: [] keywords: [] -action: - aliases: [sort] - related: - - functions/collections/Reverse - - functions/collections/Shuffle - - functions/collections/Uniq - returnType: any - signatures: ['collections.Sort COLLECTION [KEY] [ORDER]'] -toc: true +params: + functions_and_methods: + aliases: [sort] + returnType: any + signatures: ['collections.Sort COLLECTION [KEY] [ORDER]'] aliases: [/functions/sort] --- @@ -65,9 +61,8 @@ firstName = "Jean" lastName = "Valjean" {{< /code-toggle >}} -{{% note %}} -When sorting maps, the `KEY` argument must be lowercase. -{{% /note %}} +> [!note] +> When sorting maps, the `KEY` argument must be lowercase. ### Ascending order {#map-ascending-order} @@ -141,11 +136,8 @@ After sorting: ## Sort a page collection -{{% note %}} -Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well. - -[sorting and grouping methods]: /methods/pages/ -{{% /note %}} +> [!note] +> Although you can use the `sort` function to sort a page collection, Hugo provides [sorting and grouping methods] as well. In this contrived example, sort the site's regular pages by `.Type` in descending order: @@ -154,3 +146,5 @@ In this contrived example, sort the site's regular pages by `.Type` in descendin <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} ``` + +[sorting and grouping methods]: /methods/pages/ diff --git a/docs/content/en/functions/collections/SymDiff.md b/docs/content/en/functions/collections/SymDiff.md index 7eba3ef42..8974d2d3e 100644 --- a/docs/content/en/functions/collections/SymDiff.md +++ b/docs/content/en/functions/collections/SymDiff.md @@ -3,15 +3,11 @@ title: collections.SymDiff description: Returns the symmetric difference of two collections. categories: [] keywords: [] -action: - aliases: [symdiff] - related: - - functions/collections/Complement - - functions/collections/Intersect - - functions/collections/SymDiff - - functions/collections/Union - returnType: any - signatures: [COLLECTION | collections.SymDiff COLLECTION] +params: + functions_and_methods: + aliases: [symdiff] + returnType: any + signatures: [COLLECTION | collections.SymDiff COLLECTION] aliases: [/functions/symdiff] --- diff --git a/docs/content/en/functions/collections/Union.md b/docs/content/en/functions/collections/Union.md index 7fed49a10..ce6d6d010 100644 --- a/docs/content/en/functions/collections/Union.md +++ b/docs/content/en/functions/collections/Union.md @@ -3,32 +3,24 @@ title: collections.Union description: Given two arrays or slices, returns a new array that contains the elements that belong to either or both arrays/slices. categories: [] keywords: [] -action: - aliases: [union] - related: - - functions/collections/Complement - - functions/collections/Intersect - - functions/collections/SymDiff - - functions/collections/Union - returnType: any - signatures: [collections.Union SET1 SET2] +params: + functions_and_methods: + aliases: [union] + returnType: any + signatures: [collections.Union SET1 SET2] aliases: [/functions/union] --- Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. ```go-html-template -{{ union (slice 1 2 3) (slice 3 4 5) }} -<!-- returns [1 2 3 4 5] --> +{{ union (slice 1 2 3) (slice 3 4 5) }} → [1 2 3 4 5] -{{ union (slice 1 2 3) nil }} -<!-- returns [1 2 3] --> +{{ union (slice 1 2 3) nil }} → [1 2 3] -{{ union nil (slice 1 2 3) }} -<!-- returns [1 2 3] --> +{{ union nil (slice 1 2 3) }} → [1 2 3] -{{ union nil nil }} -<!-- returns an error because both arrays/slices have to be of the same type --> +{{ union nil nil }} → [] ``` ## OR filter in where query diff --git a/docs/content/en/functions/collections/Uniq.md b/docs/content/en/functions/collections/Uniq.md index 02b590c18..d19298b21 100644 --- a/docs/content/en/functions/collections/Uniq.md +++ b/docs/content/en/functions/collections/Uniq.md @@ -3,15 +3,11 @@ title: collections.Uniq description: Returns the given collection, removing duplicate elements. categories: [] keywords: [] -action: - aliases: [uniq] - related: - - functions/collections/Reverse - - functions/collections/Shuffle - - functions/collections/Sort - - functions/collections/Uniq - returnType: any - signatures: [collections.Uniq COLLECTION] +params: + functions_and_methods: + aliases: [uniq] + returnType: any + signatures: [collections.Uniq COLLECTION] aliases: [/functions/uniq] --- diff --git a/docs/content/en/functions/collections/Where.md b/docs/content/en/functions/collections/Where.md index 014a063a1..1df84afc4 100644 --- a/docs/content/en/functions/collections/Where.md +++ b/docs/content/en/functions/collections/Where.md @@ -3,12 +3,11 @@ title: collections.Where description: Returns the given collection, removing elements that do not satisfy the comparison condition. categories: [] keywords: [] -action: - aliases: [where] - related: [] - returnType: any - signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE'] -toc: true +params: + functions_and_methods: + aliases: [where] + returnType: any + signatures: ['collections.Where COLLECTION KEY [OPERATOR] VALUE'] aliases: [/functions/where] --- @@ -87,12 +86,12 @@ Use any of the following logical operators: `intersect` : (`bool`) Reports whether the given field value (a slice) contains one or more elements in common with `VALUE`. See [details](/functions/collections/intersect). -`like` {{< new-in 0.116.0 />}} -: (`bool`) Reports whether the given field value matches the regular expression specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression. +`like` +: {{< new-in 0.116.0 />}} +: (`bool`) Reports whether the given field value matches the [regular expression](g) specified in `VALUE`. Use the `like` operator to compare `string` values. The `like` operator returns `false` when comparing other data types to the regular expression. -{{% note %}} -The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps. -{{% /note %}} +> [!note] +> The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps. ## String comparison @@ -155,7 +154,7 @@ To return a collection of pages where the "color" page parameter is neither "red ## Intersection comparison -Compare a [`slice`] to a [`slice`], returning collection elements with common values. This is frequently used when comparing taxonomy terms. +Compare a `slice` to a `slice`, returning collection elements with common values. This is frequently used when comparing taxonomy terms. For example, to return a collection of pages where any of the terms in the "genres" taxonomy are "suspense" or "romance": @@ -176,11 +175,10 @@ To return a collection of pages where the "author" page parameter begins with ei {{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }} ``` -{{% include "functions/_common/regular-expressions.md" %}} +{{% include "/_common/functions/regular-expressions.md" %}} -{{% note %}} -Use the `like` operator to compare string values. Comparing other data types will result in an empty collection. -{{% /note %}} +> [!note] +> Use the `like` operator to compare string values. Comparing other data types will result in an empty collection. ## Date comparison @@ -188,12 +186,6 @@ Use the `like` operator to compare string values. Comparing other data types wil There are four predefined front matter dates: [`date`], [`publishDate`], [`lastmod`], and [`expiryDate`]. Regardless of the front matter data format (TOML, YAML, or JSON) these are [`time.Time`] values, allowing precise comparisons. -[`date`]: /methods/page/date/ -[`publishdate`]: /methods/page/publishdate/ -[`lastmod`]: /methods/page/lastmod/ -[`expirydate`]: /methods/page/expirydate/ -[`time.Time`]: https://pkg.go.dev/time#Time - For example, to return a collection of pages that were created before the current year: ```go-html-template @@ -205,20 +197,19 @@ For example, to return a collection of pages that were created before the curren 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. -{{% /note %}} +> [!note] +> Using TOML for pages with custom front matter dates enables precise date comparisons. With TOML, date values are first-class citizens. TOML has a date data type while JSON and YAML do not. If you quote a TOML date, it is a string. If you do not quote a TOML date value, it is [`time.Time`] value, enabling precise comparisons. In the TOML example below, note that the event date is not quoted. -{{< code file="content/events/2024-user-conference.md" >}} +```text {file="content/events/2024-user-conference.md"} +++ title = '2024 User Conference" eventDate = 2024-04-01 +++ -{{< /code >}} +``` To return a collection of future events: @@ -272,8 +263,6 @@ These are equivalent: Useful for theme authors, avoid hardcoding section names by using the `where` function with the [`MainSections`] method on a `Site` object. -[`MainSections`]: /methods/site/mainsections/ - ```go-html-template {{ $pages := where .Site.RegularPages "Section" "in" .Site.MainSections }} ``` @@ -281,11 +270,10 @@ Useful for theme authors, avoid hardcoding section names by using the `where` fu With this construct, a theme author can instruct users to specify their main sections in the site configuration: {{< code-toggle file=hugo >}} -[params] mainSections = ['blog','galleries'] {{< /code-toggle >}} -If `params.mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top level section with the most pages. +If `mainSections` is not defined in the site configuration, the `MainSections` method returns a slice with one element---the top-level section with the most pages. ## Boolean/undefined comparison @@ -387,13 +375,11 @@ To exclude a page with an undefined field from a boolean _inequality_ test: 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/ - This template: ```go-html-template {{ $p1 := where .Site.RegularPages "Params.exclude" "ne" true }} -{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} <ul> {{ range $p1 | complement $p2 }} <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> @@ -413,7 +399,7 @@ This template: ```go-html-template {{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }} -{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} +{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }} <ul> {{ range $p1 | complement $p2 }} <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> @@ -428,3 +414,9 @@ Is rendered to: <li><a href="/posts/post-1/">Post 2</a></li> </ul> ``` + +[`collections.Complement`]: /functions/collections/complement/ +[`date`]: /methods/page/date/ +[`lastmod`]: /methods/page/lastmod/ +[`MainSections`]: /methods/site/mainsections/ +[`time.Time`]: https://pkg.go.dev/time#Time diff --git a/docs/content/en/functions/collections/_index.md b/docs/content/en/functions/collections/_index.md index 51981f79b..c7b856f4f 100644 --- a/docs/content/en/functions/collections/_index.md +++ b/docs/content/en/functions/collections/_index.md @@ -1,12 +1,7 @@ --- title: Collections functions linkTitle: collections -description: Template functions to work with arrays, slices, maps, and page collections. +description: Use these functions to work with arrays, slices, maps, and page collections. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with arrays, slices, maps, and page collections. diff --git a/docs/content/en/functions/compare/Conditional.md b/docs/content/en/functions/compare/Conditional.md index 997b71e94..c004bf4e6 100644 --- a/docs/content/en/functions/compare/Conditional.md +++ b/docs/content/en/functions/compare/Conditional.md @@ -3,12 +3,11 @@ title: compare.Conditional description: Returns one of two arguments depending on the value of the control argument. categories: [] keywords: [] -action: - aliases: [cond] - related: - - functions/compare/Default - returnType: any - signatures: [compare.Conditional CONTROL ARG1 ARG2] +params: + functions_and_methods: + aliases: [cond] + returnType: any + signatures: [compare.Conditional CONTROL ARG1 ARG2] aliases: [/functions/cond] --- diff --git a/docs/content/en/functions/compare/Default.md b/docs/content/en/functions/compare/Default.md index bf859d51c..f8bd06f06 100644 --- a/docs/content/en/functions/compare/Default.md +++ b/docs/content/en/functions/compare/Default.md @@ -2,27 +2,24 @@ title: compare.Default description: Returns the second argument if set, else the first argument. keywords: [] -action: - aliases: [default] - related: - - functions/compare/Conditional - - functions/go-template/Or - returnType: any - signatures: [compare.Default DEFAULT INPUT] +params: + functions_and_methods: + aliases: [default] + returnType: any + signatures: [compare.Default DEFAULT INPUT] aliases: [/functions/default] --- The `default` function returns the second argument if set, else the first argument. -{{% note %}} -When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset. - -{{% include "functions/go-template/_common/truthy-falsy.md" %}} - -To set a default value based on truthiness, use the [`or`] operator instead. - -[`or`]: /functions/go-template/or/ -{{% /note %}} +> [!note] +> When the second argument is the boolean `false` value, the `default` function returns `false`. All _other_ falsy values are considered unset. +> +> The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values. +> +> Everything else is truthy. +> +> To set a default value based on truthiness, use the [`or`] operator instead. The `default` function returns the second argument if set: @@ -46,3 +43,5 @@ The `default` function returns the first argument if the second argument is not {{ default 42 slice }} → 42 {{ default 42 <nil> }} → 42 ``` + +[`or`]: /functions/go-template/or/ diff --git a/docs/content/en/functions/compare/Eq.md b/docs/content/en/functions/compare/Eq.md index a877aeddf..583e2e495 100644 --- a/docs/content/en/functions/compare/Eq.md +++ b/docs/content/en/functions/compare/Eq.md @@ -3,16 +3,11 @@ title: compare.Eq description: Returns the boolean truth of arg1 == arg2 || arg1 == arg3. categories: [] keywords: [] -action: - aliases: [eq] - related: - - functions/compare/Ge - - functions/compare/Gt - - functions/compare/Le - - functions/compare/Lt - - functions/compare/Ne - returnType: bool - signatures: ['compare.Eq ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [eq] + returnType: bool + signatures: ['compare.Eq ARG1 ARG2 [ARG...]'] aliases: [/functions/eq] --- diff --git a/docs/content/en/functions/compare/Ge.md b/docs/content/en/functions/compare/Ge.md index ce1fd2302..fd793f0c9 100644 --- a/docs/content/en/functions/compare/Ge.md +++ b/docs/content/en/functions/compare/Ge.md @@ -3,16 +3,11 @@ title: compare.Ge description: Returns the boolean truth of arg1 >= arg2 && arg1 >= arg3. categories: [] keywords: [] -action: - aliases: [ge] - related: - - functions/compare/Eq - - functions/compare/Gt - - functions/compare/Le - - functions/compare/Lt - - functions/compare/Ne - returnType: bool - signatures: ['compare.Ge ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [ge] + returnType: bool + signatures: ['compare.Ge ARG1 ARG2 [ARG...]'] aliases: [/functions/ge] --- diff --git a/docs/content/en/functions/compare/Gt.md b/docs/content/en/functions/compare/Gt.md index 9ff3b0c89..f48312cf7 100644 --- a/docs/content/en/functions/compare/Gt.md +++ b/docs/content/en/functions/compare/Gt.md @@ -3,16 +3,11 @@ title: compare.Gt description: Returns the boolean truth of arg1 > arg2 && arg1 > arg3. categories: [] keywords: [] -action: - aliases: [gt] - related: - - functions/compare/Eq - - functions/compare/Ge - - functions/compare/Le - - functions/compare/Lt - - functions/compare/Ne - returnType: bool - signatures: ['compare.Gt ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [gt] + returnType: bool + signatures: ['compare.Gt ARG1 ARG2 [ARG...]'] aliases: [/functions/gt] --- diff --git a/docs/content/en/functions/compare/Le.md b/docs/content/en/functions/compare/Le.md index a0fbed29d..b490d6807 100644 --- a/docs/content/en/functions/compare/Le.md +++ b/docs/content/en/functions/compare/Le.md @@ -3,16 +3,11 @@ title: compare.Le description: Returns the boolean truth of arg1 <= arg2 && arg1 <= arg3. categories: [] keywords: [] -action: - aliases: [le] - related: - - functions/compare/Eq - - functions/compare/Ge - - functions/compare/Gt - - functions/compare/Lt - - functions/compare/Ne - returnType: bool - signatures: ['compare.Le ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [le] + returnType: bool + signatures: ['compare.Le ARG1 ARG2 [ARG...]'] aliases: [/functions/le] --- diff --git a/docs/content/en/functions/compare/Lt.md b/docs/content/en/functions/compare/Lt.md index b306a97b5..a5578cc84 100644 --- a/docs/content/en/functions/compare/Lt.md +++ b/docs/content/en/functions/compare/Lt.md @@ -3,16 +3,11 @@ title: compare.Lt description: Returns the boolean truth of arg1 < arg2 && arg1 < arg3. categories: [] keywords: [] -action: - aliases: [lt] - related: - - functions/compare/Eq - - functions/compare/Ge - - functions/compare/Gt - - functions/compare/Le - - functions/compare/Ne - returnType: bool - signatures: ['compare.Lt ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [lt] + returnType: bool + signatures: ['compare.Lt ARG1 ARG2 [ARG...]'] aliases: [/functions/lt] --- diff --git a/docs/content/en/functions/compare/Ne.md b/docs/content/en/functions/compare/Ne.md index dbe0a3898..8839983f8 100644 --- a/docs/content/en/functions/compare/Ne.md +++ b/docs/content/en/functions/compare/Ne.md @@ -3,16 +3,11 @@ title: compare.Ne description: Returns the boolean truth of arg1 != arg2 && arg1 != arg3. categories: [] keywords: [] -action: - aliases: [ne] - related: - - functions/compare/Eq - - functions/compare/Ge - - functions/compare/Gt - - functions/compare/Le - - functions/compare/Lt - returnType: bool - signatures: ['compare.Ne ARG1 ARG2 [ARG...]'] +params: + functions_and_methods: + aliases: [ne] + returnType: bool + signatures: ['compare.Ne ARG1 ARG2 [ARG...]'] aliases: [/functions/ne] --- diff --git a/docs/content/en/functions/compare/_index.md b/docs/content/en/functions/compare/_index.md index a9b3a7b27..59673a2c8 100644 --- a/docs/content/en/functions/compare/_index.md +++ b/docs/content/en/functions/compare/_index.md @@ -1,12 +1,7 @@ --- title: Compare functions linkTitle: compare -description: Template functions to compare two or more values. +description: Use these functions to compare two or more values. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to compare two or more values. diff --git a/docs/content/en/functions/crypto/FNV32a.md b/docs/content/en/functions/crypto/FNV32a.md index 0255349a3..03bcc57e7 100644 --- a/docs/content/en/functions/crypto/FNV32a.md +++ b/docs/content/en/functions/crypto/FNV32a.md @@ -1,18 +1,18 @@ --- title: crypto.FNV32a -description: Returns the 32-bit FNV (Fowler–Noll–Vo) non-cryptographic hash of the given string. +description: Returns the 32-bit FNV (Fowler-Noll-Vo) non-cryptographic hash of the given string. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: int - signatures: [crypto.FNV32a STRING] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [crypto.FNV32a STRING] expiryDate: 2026-07-31 # deprecated 2024-07-31 in v0.129.0 --- -{{% deprecated-in 0.129.0 %}} +{{< deprecated-in 0.129.0 >}} Use [`hash.FNV32a`] instead. [`hash.FNV32a`]: /functions/hash/FNV32a/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/docs/content/en/functions/crypto/HMAC.md b/docs/content/en/functions/crypto/HMAC.md index 1906689a2..5929826dd 100644 --- a/docs/content/en/functions/crypto/HMAC.md +++ b/docs/content/en/functions/crypto/HMAC.md @@ -3,15 +3,11 @@ title: crypto.HMAC description: Returns a cryptographic hash that uses a key to sign a message. categories: [] keywords: [] -action: - aliases: [hmac] - related: - - functions/crypto/FNV32a - - functions/crypto/MD5 - - functions/crypto/SHA1 - - functions/crypto/SHA256 - returnType: string - signatures: ['crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING]'] +params: + functions_and_methods: + aliases: [hmac] + returnType: string + signatures: ['crypto.HMAC HASH_TYPE KEY MESSAGE [ENCODING]'] aliases: [/functions/hmac] --- diff --git a/docs/content/en/functions/crypto/MD5.md b/docs/content/en/functions/crypto/MD5.md index ba44660df..89bb8cc1b 100644 --- a/docs/content/en/functions/crypto/MD5.md +++ b/docs/content/en/functions/crypto/MD5.md @@ -3,15 +3,11 @@ title: crypto.MD5 description: Hashes the given input and returns its MD5 checksum encoded to a hexadecimal string. categories: [] keywords: [] -action: - aliases: [md5] - related: - - functions/crypto/FNV32a - - functions/crypto/HMAC - - functions/crypto/SHA1 - - functions/crypto/SHA256 - returnType: string - signatures: [crypto.MD5 INPUT] +params: + functions_and_methods: + aliases: [md5] + returnType: string + signatures: [crypto.MD5 INPUT] aliases: [/functions/md5] --- diff --git a/docs/content/en/functions/crypto/SHA1.md b/docs/content/en/functions/crypto/SHA1.md index 204ff0384..c80dac0a4 100644 --- a/docs/content/en/functions/crypto/SHA1.md +++ b/docs/content/en/functions/crypto/SHA1.md @@ -3,15 +3,11 @@ title: crypto.SHA1 description: Hashes the given input and returns its SHA1 checksum encoded to a hexadecimal string. categories: [] keywords: [] -action: - aliases: [sha1] - related: - - functions/crypto/FNV32a - - functions/crypto/HMAC - - functions/crypto/MD5 - - functions/crypto/SHA256 - returnType: string - signatures: [crypto.SHA1 INPUT] +params: + functions_and_methods: + aliases: [sha1] + returnType: string + signatures: [crypto.SHA1 INPUT] aliases: [/functions/sha,/functions/sha1] --- diff --git a/docs/content/en/functions/crypto/SHA256.md b/docs/content/en/functions/crypto/SHA256.md index 6fb657767..d0a66c069 100644 --- a/docs/content/en/functions/crypto/SHA256.md +++ b/docs/content/en/functions/crypto/SHA256.md @@ -3,15 +3,11 @@ title: crypto.SHA256 description: Hashes the given input and returns its SHA256 checksum encoded to a hexadecimal string. categories: [] keywords: [] -action: - aliases: [sha256] - related: - - functions/crypto/FNV32a - - functions/crypto/HMAC - - functions/crypto/MD5 - - functions/crypto/SHA1 - returnType: string - signatures: [crypto.SHA256 INPUT] +params: + functions_and_methods: + aliases: [sha256] + returnType: string + signatures: [crypto.SHA256 INPUT] aliases: [/functions/sha256] --- diff --git a/docs/content/en/functions/crypto/_index.md b/docs/content/en/functions/crypto/_index.md index 5c95aab6e..5771630d4 100644 --- a/docs/content/en/functions/crypto/_index.md +++ b/docs/content/en/functions/crypto/_index.md @@ -1,12 +1,7 @@ --- title: Crypto functions linkTitle: crypto -description: Template functions to create cryptographic hashes. +description: Use these functions to create cryptographic hashes. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to create cryptographic hashes. diff --git a/docs/content/en/functions/css/PostCSS.md b/docs/content/en/functions/css/PostCSS.md index 1a1a792ec..9cc698248 100644 --- a/docs/content/en/functions/css/PostCSS.md +++ b/docs/content/en/functions/css/PostCSS.md @@ -3,14 +3,11 @@ title: css.PostCSS description: Processes the given resource with PostCSS using any PostCSS plugin. categories: [] keywords: [] -action: - aliases: [postCSS] - related: - - functions/css/Sass - - functions/css/TailwindCSS - returnType: resource.Resource - signatures: ['css.PostCSS [OPTIONS] RESOURCE'] -toc: true +params: + functions_and_methods: + aliases: [postCSS] + returnType: resource.Resource + signatures: ['css.PostCSS [OPTIONS] RESOURCE'] --- {{< new-in 0.128.0 />}} @@ -25,40 +22,40 @@ toc: true Follow the steps below to transform CSS using any of the available [PostCSS plugins]. -[postcss plugins]: https://postcss.org/docs/postcss-plugins +### Step 1 -Step 1 -: Install [Node.js]. +Install [Node.js]. -[node.js]: https://nodejs.org/en/download +### Step 2 -Step 2 -: Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules: +Install the required Node.js packages in the root of your project. For example, to add vendor prefixes to your CSS rules: ```sh npm i -D postcss postcss-cli autoprefixer ``` -Step 3 -: Create a PostCSS configuration file in the root of your project. +### Step 3 -{{< code file=postcss.config.js >}} +Create a PostCSS configuration file in the root of your project. + +```js {file="postcss.config.js"} module.exports = { plugins: [ require('autoprefixer') ] }; -{{< /code >}} +``` + +> [!note] +> If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. -{{% note %}} -{{% include "functions/resources/_common/postcss-windows-warning.md" %}} -{{% /note %}} +### Step 4 -Step 4 -: Place your CSS file within the `assets/css` directory. +Place your CSS file within the `assets/css` directory. -Step 5 -: Process the resource with PostCSS: +### Step 5 + +Process the resource with PostCSS: ```go-html-template {{ with resources.Get "css/main.css" | postCSS }} @@ -74,13 +71,13 @@ config : (`string`) The directory that contains the PostCSS configuration file. Default is the root of the project directory. noMap -: (`bool`) Default is `false`. If `true`, disables inline sourcemaps. +: (`bool`) Whether to disable inline source maps. Default is `false`. inlineImports -: (`bool`) Default is `false`. Enable inlining of @import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. +: (`bool`) Whether to enable inlining of import statements. It does so recursively, but will only import a file once. URL imports (e.g. `@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');`) and imports with media queries will be ignored. Note that this import routine does not care about the CSS spec, so you can have @import anywhere in the file. Hugo will look for imports relative to the module mount and will respect theme overrides. Default is `false`. skipInlineImportsNotFound -: (`bool`) Default is `false`. Before Hugo 0.99.0 when `inlineImports` was enabled and we failed to resolve an import, we logged it as a warning. We now fail the build. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set `skipInlineImportsNotFound` to true. +: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. If you have regular CSS imports in your CSS that you want to preserve, you can either use imports with URL or media queries (Hugo does not try to resolve those) or set this option to `true`. Default is `false`." ```go-html-template {{ $opts := dict "config" "config-directory" "noMap" true }} @@ -124,3 +121,8 @@ module.exports = { ] } ``` + +[#7333]: https://github.com/gohugoio/hugo/issues/7333 +[Node.js]: https://nodejs.org/en +[PostCSS plugins]: https://postcss.org/docs/postcss-plugins +[this example]: https://github.com/postcss/postcss-load-config#packagejson diff --git a/docs/content/en/functions/css/Sass.md b/docs/content/en/functions/css/Sass.md index 73f7af1ea..1d5487130 100644 --- a/docs/content/en/functions/css/Sass.md +++ b/docs/content/en/functions/css/Sass.md @@ -3,16 +3,11 @@ title: css.Sass description: Transpiles Sass to CSS. categories: [] keywords: [] -action: - aliases: [toCSS] - related: - - functions/resources/Fingerprint - - functions/resources/Minify - - functions/css/PostCSS - - functions/resources/PostProcess - returnType: resource.Resource - signatures: ['css.Sass [OPTIONS] RESOURCE'] -toc: true +params: + functions_and_methods: + aliases: [toCSS] + returnType: resource.Resource + signatures: ['css.Sass [OPTIONS] RESOURCE'] --- {{< new-in 0.128.0 />}} @@ -70,10 +65,10 @@ precision : (`int`) Precision of floating point math. Not applicable to Dart Sass. enableSourceMap -: (`bool`) If `true`, generates a source map. +: (`bool`) Whether to generate a source map. Default is `false`. sourceMapIncludeSources -: (`bool`) If `true`, embeds sources in the generated source map. Not applicable to LibSass. +: (`bool`) Whether to embed sources in the generated source map. Not applicable to LibSass. Default is `false`. includePaths : (`slice`) A slice of paths, relative to the project root, that the transpiler will use when resolving `@use` and `@import` statements. @@ -128,7 +123,7 @@ Run `hugo env` to list the active transpilers. ### Installing in a production environment -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. +For [CI/CD](g) 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. @@ -149,8 +144,8 @@ To install Dart Sass for your builds on GitLab Pages, the `.gitlab-ci.yml` file ```yaml variables: - HUGO_VERSION: 0.141.0 - DART_SASS_VERSION: 1.83.4 + HUGO_VERSION: 0.144.2 + DART_SASS_VERSION: 1.85.0 GIT_DEPTH: 0 GIT_STRATEGY: clone GIT_SUBMODULE_STRATEGY: recursive @@ -183,8 +178,8 @@ To install Dart Sass for your builds on Netlify, the `netlify.toml` file should ```toml [build.environment] -HUGO_VERSION = "0.141.0" -DART_SASS_VERSION = "1.83.4" +HUGO_VERSION = "0.144.2" +DART_SASS_VERSION = "1.85.0" NODE_VERSION = "22" TZ = "America/Los_Angeles" @@ -229,12 +224,11 @@ If you build Hugo from source and run `mage test -v`, the test will fail if you [brew.sh]: https://brew.sh/ [chocolatey.org]: https://community.chocolatey.org/packages/sass -[ci/cd]: https://en.wikipedia.org/wiki/CI/CD [dart sass]: https://sass-lang.com/dart-sass [libsass]: https://sass-lang.com/libsass [prebuilt binaries]: https://github.com/sass/dart-sass/releases/latest [scoop.sh]: https://scoop.sh/#/apps?q=sass -[site configuration]: /getting-started/configuration/#configure-build +[site configuration]: /configuration/build/ [snap package]: /installation/linux/#snap [snapcraft.io]: https://snapcraft.io/dart-sass [starter workflow]: https://github.com/actions/starter-workflows/blob/main/pages/hugo.yml diff --git a/docs/content/en/functions/css/TailwindCSS.md b/docs/content/en/functions/css/TailwindCSS.md index 44c549196..6add7373a 100644 --- a/docs/content/en/functions/css/TailwindCSS.md +++ b/docs/content/en/functions/css/TailwindCSS.md @@ -3,28 +3,27 @@ title: css.TailwindCSS description: Processes the given resource with the Tailwind CSS CLI. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/Fingerprint - - functions/resources/Minify - - functions/css/PostCSS - returnType: resource.Resource - signatures: ['css.TailwindCSS [OPTIONS] RESOURCE'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['css.TailwindCSS [OPTIONS] RESOURCE'] --- {{< new-in 0.128.0 />}} -Use the `css.TailwindCSS` function to process your Tailwind CSS files. This function uses the Tailwind CSS CLI to: +Use the `css.TailwindCSS` function to process your Tailwind CSS files. This function uses the Tailwind CSS CLI to: 1. Scan your templates for Tailwind CSS utility class usage. 1. Compile those utility classes into standard CSS. 1. Generate an optimized CSS output file. +> [!caution] +> Tailwind CSS v4.0 and later requires a relatively [modern browser](https://tailwindcss.com/docs/compatibility#browser-support) to render correctly. + ## Setup -###### Step 1 +### Step 1 Install the Tailwind CSS CLI v4.0 or later: @@ -36,7 +35,7 @@ The TailwindCSS CLI is also available as a [standalone executable] if you want t [standalone executable]: https://github.com/tailwindlabs/tailwindcss/releases/latest -###### Step 2 +### Step 2 Add this to your site configuration: @@ -58,23 +57,22 @@ source = "(postcss|tailwind)\\.config\\.js" target = "css" {{< /code-toggle >}} - -###### Step 3 +### Step 3 Create a CSS entry file: -{{< code file=assets/css/main.css copy=true >}} +```css {file="assets/css/main.css" copy=true} @import "tailwindcss"; @source "hugo_stats.json"; -{{< /code >}} +``` Tailwind CSS respects `.gitignore` files. This means that if `hugo_stats.json` is listed in your `.gitignore` file, Tailwind CSS will ignore it. To make `hugo_stats.json` available to Tailwind CSS you must explicitly source it as shown in the example above. -###### Step 4 +### Step 4 Create a partial template to process the CSS with the Tailwind CSS CLI: -{{< code file=layouts/partials/css.html copy=true >}} +```go-html-template {file="layouts/partials/css.html" copy=true} {{ with (templates.Defer (dict "key" "global")) }} {{ with resources.Get "css/main.css" }} {{ $opts := dict @@ -92,21 +90,21 @@ Create a partial template to process the CSS with the Tailwind CSS CLI: {{ end }} {{ end }} {{ end }} -{{< /code >}} +``` -###### Step 5 +### Step 5 Call the partial template from your base template: -{{< code file=layouts/default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} <head> ... {{ partialCached "css.html" . }} ... <head> -{{< /code >}} +``` -###### Step 6 +### Step 6 Optionally create a `tailwind.config.js` file in the root of your project as shown below. This is necessary if you use the [Tailwind CSS IntelliSense extension] for Visual Studio Code. @@ -114,7 +112,7 @@ extension] for Visual Studio Code. [Tailwind CSS IntelliSense extension]: https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss -{{< code file=tailwind.config.js copy=true >}} +```js {file="tailwind.config.js" copy=true} /* This file is present to satisfy a requirement of the Tailwind CSS IntelliSense extension for Visual Studio Code. @@ -123,7 +121,7 @@ https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss The rest of this file is intentionally empty. */ -{{< /code >}} +``` ## Options @@ -137,4 +135,4 @@ inlineImports : (`bool`) Whether to enable inlining of `@import` statements. Inlining is performed recursively, but currently once only per file. It is not possible to import the same file in different scopes (root, media query, etc.). Note that this import routine does not care about the CSS specification, so you can have `@import` statements anywhere in the file. Default is `false`. skipInlineImportsNotFound -: (`bool`) When `inlineImports` is enabled, we fail the build if an import cannot be resolved. Enable this option to allow the build to continue and leave the import statement in place. Note that the inline importer does not process URL location or imports with media queries, so those will be left as-is even without enabling this option. Default is `false`. +: (`bool`) Whether to allow the build process to continue despite unresolved import statements, preserving the original import declarations. It is important to note that the inline importer does not process URL-based imports or those with media queries, and these will remain unaltered even when this option is disabled. Default is `false`. diff --git a/docs/content/en/functions/css/_index.md b/docs/content/en/functions/css/_index.md index a83a23819..9faabbbe9 100644 --- a/docs/content/en/functions/css/_index.md +++ b/docs/content/en/functions/css/_index.md @@ -1,12 +1,7 @@ --- title: CSS functions linkTitle: css -description: Template functions to work with CSS and Sass files. +description: Use these functions to work with CSS and Sass files. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with CSS and Sass files. diff --git a/docs/content/en/functions/data/GetCSV.md b/docs/content/en/functions/data/GetCSV.md index be848bce5..39c71b06c 100644 --- a/docs/content/en/functions/data/GetCSV.md +++ b/docs/content/en/functions/data/GetCSV.md @@ -3,23 +3,22 @@ title: data.GetCSV description: Returns an array of arrays from a local or remote CSV file, or an error if the file does not exist. categories: [] keywords: [] -action: - aliases: [getCSV] - related: [] - returnType: '[][]string' - signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [getCSV] + returnType: '[][]string' + signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]'] expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 --- -{{% deprecated-in 0.123.0 %}} +{{< deprecated-in 0.123.0 >}} 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/ [remote data example]: /functions/resources/getremote/#remote-data -{{% /deprecated-in %}} +{{< /deprecated-in >}} Given the following directory structure: @@ -36,11 +35,10 @@ Access the data with either of the following: {{ $data := getCSV "," "other-files/" "pets.csv" }} ``` -{{% 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. -{{% /note %}} +> [!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. Access remote data with either of the following: diff --git a/docs/content/en/functions/data/GetJSON.md b/docs/content/en/functions/data/GetJSON.md index 1b42cbf16..9cdea9287 100644 --- a/docs/content/en/functions/data/GetJSON.md +++ b/docs/content/en/functions/data/GetJSON.md @@ -3,23 +3,22 @@ title: data.GetJSON description: Returns a JSON object from a local or remote JSON file, or an error if the file does not exist. categories: [] keywords: [] -action: - aliases: [getJSON] - related: [] - returnType: any - signatures: ['data.GetJSON INPUT... [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [getJSON] + returnType: any + signatures: ['data.GetJSON INPUT... [OPTIONS]'] expiryDate: 2026-02-19 # deprecated 2024-02-19 in v0.123.0 --- -{{% deprecated-in 0.123.0 %}} +{{< deprecated-in 0.123.0 >}} 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/ [remote data example]: /functions/resources/getremote/#remote-data -{{% /deprecated-in %}} +{{< /deprecated-in >}} Given the following directory structure: @@ -36,9 +35,8 @@ Access the data with either of the following: {{ $data := getJSON "other-files/" "books.json" }} ``` -{{% note %}} -When working with local data, the file path is relative to the working directory. -{{% /note %}} +> [!note] +> When working with local data, the file path is relative to the working directory. Access remote data with either of the following: diff --git a/docs/content/en/functions/data/_index.md b/docs/content/en/functions/data/_index.md index 142d6b528..2177bc528 100644 --- a/docs/content/en/functions/data/_index.md +++ b/docs/content/en/functions/data/_index.md @@ -1,12 +1,7 @@ --- title: Data functions linkTitle: data -description: Template functions to read local or remote data files. +description: Use these functions to read local or remote data files. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to read local or remote data files. diff --git a/docs/content/en/functions/debug/Dump.md b/docs/content/en/functions/debug/Dump.md index 67b264bed..df846ac3d 100644 --- a/docs/content/en/functions/debug/Dump.md +++ b/docs/content/en/functions/debug/Dump.md @@ -3,11 +3,11 @@ title: debug.Dump description: Returns an object dump as a string. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [debug.Dump VALUE] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [debug.Dump VALUE] --- ```go-html-template @@ -29,6 +29,5 @@ action: ] ``` -{{% note %}} -Output from this function may change from one release to the next. Use for debugging only. -{{% /note %}} +> [!note] +> Output from this function may change from one release to the next. Use for debugging only. diff --git a/docs/content/en/functions/debug/Timer.md b/docs/content/en/functions/debug/Timer.md index 519c195c1..c2cd59211 100644 --- a/docs/content/en/functions/debug/Timer.md +++ b/docs/content/en/functions/debug/Timer.md @@ -3,11 +3,11 @@ title: debug.Timer description: Creates a named timer that reports elapsed time to the console. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: debug.Timer - signatures: [debug.Timer NAME] +params: + functions_and_methods: + aliases: [] + returnType: debug.Timer + signatures: [debug.Timer NAME] --- {{< new-in 0.120.0 />}} diff --git a/docs/content/en/functions/debug/_index.md b/docs/content/en/functions/debug/_index.md index 418828515..49fe416ed 100644 --- a/docs/content/en/functions/debug/_index.md +++ b/docs/content/en/functions/debug/_index.md @@ -1,12 +1,7 @@ --- title: Debug functions linkTitle: debug -description: Template functions to debug your templates. +description: Use these functions to debug your templates. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to debug your templates. diff --git a/docs/content/en/functions/diagrams/Goat.md b/docs/content/en/functions/diagrams/Goat.md index 69a099bb7..e2f55eee0 100644 --- a/docs/content/en/functions/diagrams/Goat.md +++ b/docs/content/en/functions/diagrams/Goat.md @@ -1,20 +1,20 @@ --- title: diagrams.Goat -description: Converts ASCII art to an SVG diagram, returning a GoAT diagram object. +description: Returns an SVGDiagram object created from the given GoAT markup and options. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: diagrams.goatDiagram - signatures: ['diagrams.Goat INPUT'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: diagrams.SVGDiagram + signatures: [diagrams.Goat MARKUP] --- -Useful in a [code block render hook], the `diagram.Goat` function converts ASCII art to an SVG diagram, returning a [GoAT] diagram object with the following methods: +Useful in a [code block render hook], the `diagrams.Goat` function returns an SVGDiagram object created from the given [GoAT] markup. -[GoAT]: https://github.com/blampe/goat#readme -[code block render hook]: /render-hooks/code-blocks/ +## Methods + +The SVGDiagram object has the following methods: Inner : (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper. @@ -30,13 +30,11 @@ Height ## GoAT Diagrams -Hugo natively supports [GoAT](https://github.com/bep/goat) diagrams with an [embedded code block render hook]. - -[embedded code block render hook]: {{% eturl render-codeblock-goat %}} +Hugo natively supports GoAT diagrams with an [embedded code block render hook]. This Markdown: -```` +````text ```goat .---. .-. .-. .-. .---. | A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | @@ -68,7 +66,7 @@ To customize rendering, override Hugo's [embedded code block render hook] for Go By way of example, let's create a code block render hook to render GoAT diagrams as `figure` elements with an optional caption. -{{< code file=layouts/_default/_markup/render-codeblock-goat.html >}} +```go-html-template {file="layouts/_default/_markup/render-codeblock-goat.html"} {{ $caption := or .Attributes.caption "" }} {{ $class := or .Attributes.class "diagram" }} {{ $id := or .Attributes.id (printf "diagram-%d" (add 1 .Ordinal)) }} @@ -81,17 +79,17 @@ By way of example, let's create a code block render hook to render GoAT diagrams {{ end }} <figcaption>{{ $caption }}</figcaption> </figure> -{{< /code >}} +``` This Markdown: -{{< code file=content/example.md lang=text >}} +````text {file="content/example.md" } ```goat {class="foo" caption="Diagram 1: Example"} .---. .-. .-. .-. .---. | A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B | '---' '-' '+' '+' '---' ``` -{{< /code >}} +```` Is rendered to: @@ -111,3 +109,7 @@ svg.foo { font-family: "Segoe UI","Noto Sans",Helvetica,Arial,sans-serif } ``` + +[code block render hook]: /render-hooks/code-blocks/ +[embedded code block render hook]: {{% eturl render-codeblock-goat %}} +[GoAT]: https://github.com/bep/goat diff --git a/docs/content/en/functions/diagrams/_index.md b/docs/content/en/functions/diagrams/_index.md index e136b4f33..6aa407071 100644 --- a/docs/content/en/functions/diagrams/_index.md +++ b/docs/content/en/functions/diagrams/_index.md @@ -1,12 +1,7 @@ --- title: Diagram functions linkTitle: diagrams -description: Template functions to render diagrams. +description: Use these functions to render diagrams. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to render diagrams. diff --git a/docs/content/en/functions/encoding/Base64Decode.md b/docs/content/en/functions/encoding/Base64Decode.md index 0745718bb..5237e904f 100644 --- a/docs/content/en/functions/encoding/Base64Decode.md +++ b/docs/content/en/functions/encoding/Base64Decode.md @@ -3,12 +3,11 @@ title: encoding.Base64Decode description: Returns the base64 decoding of the given content. categories: [] keywords: [] -action: - aliases: [base64Decode] - related: - - functions/encoding/Base64Encode - returnType: string - signatures: [encoding.Base64Decode INPUT] +params: + functions_and_methods: + aliases: [base64Decode] + returnType: string + signatures: [encoding.Base64Decode INPUT] aliases: [/functions/base64Decode] --- @@ -29,7 +28,7 @@ To retrieve and render the content: {{ with try (resources.GetRemote $url) }} {{ with .Err }} {{ errorf "%s" . }} - {{ else with .Value}} + {{ else with .Value }} {{ with . | transform.Unmarshal }} {{ .content | base64Decode | markdownify }} {{ end }} diff --git a/docs/content/en/functions/encoding/Base64Encode.md b/docs/content/en/functions/encoding/Base64Encode.md index 14f67a132..e19d6773c 100644 --- a/docs/content/en/functions/encoding/Base64Encode.md +++ b/docs/content/en/functions/encoding/Base64Encode.md @@ -3,12 +3,11 @@ title: encoding.Base64Encode description: Returns the base64 decoding of the given content. categories: [] keywords: [] -action: - aliases: [base64Encode] - related: - - functions/encoding/Base64Decode - returnType: string - signatures: [encoding.Base64Encode INPUT] +params: + functions_and_methods: + aliases: [base64Encode] + returnType: string + signatures: [encoding.Base64Encode INPUT] aliases: [/functions/base64, /functions/base64Encode] --- diff --git a/docs/content/en/functions/encoding/Jsonify.md b/docs/content/en/functions/encoding/Jsonify.md index 475f8a76a..1d60dd68d 100644 --- a/docs/content/en/functions/encoding/Jsonify.md +++ b/docs/content/en/functions/encoding/Jsonify.md @@ -3,14 +3,11 @@ title: encoding.Jsonify description: Encodes the given object to JSON. categories: [] keywords: [] -action: - aliases: [jsonify] - returnType: template.HTML - related: - - functions/transform/Remarshal - - functions/transform/Unmarshal - signatures: - - encoding.Jsonify [OPTIONS] INPUT +params: + functions_and_methods: + aliases: [jsonify] + returnType: template.HTML + signatures: ['encoding.Jsonify [OPTIONS] INPUT'] aliases: [/functions/jsonify] --- @@ -34,4 +31,4 @@ prefix : (`string`) Indentation prefix. Default is "". noHTMLEscape -: (`bool`) Disable escaping of problematic HTML characters inside JSON quoted strings. The default behavior is to escape `&`, `<`, and `>` to `\u0026`, `\u003c`, and `\u003e` to avoid certain safety problems that can arise when embedding JSON in HTML. Default is `false`. +: (`bool`) Whether to disable escaping of problematic HTML characters inside JSON quoted strings. The default behavior is to escape `&`, `<`, and `>` to `\u0026`, `\u003c`, and `\u003e` to avoid certain safety problems that can arise when embedding JSON in HTML. Default is `false`. diff --git a/docs/content/en/functions/encoding/_index.md b/docs/content/en/functions/encoding/_index.md index 3c4c4519e..f2819f0a7 100644 --- a/docs/content/en/functions/encoding/_index.md +++ b/docs/content/en/functions/encoding/_index.md @@ -1,12 +1,7 @@ --- title: Encoding functions linkTitle: encoding -description: Template functions to encode and decode data. +description: Use these functions to encode and decode data. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to encode and decode data. diff --git a/docs/content/en/functions/fmt/Errorf.md b/docs/content/en/functions/fmt/Errorf.md index 93f546351..799622f0e 100644 --- a/docs/content/en/functions/fmt/Errorf.md +++ b/docs/content/en/functions/fmt/Errorf.md @@ -3,18 +3,15 @@ title: fmt.Errorf description: Log an ERROR from a template. categories: [] keywords: [] -action: - aliases: [errorf] - related: - - functions/fmt/Erroridf - - functions/fmt/Warnf - - functions/fmt/Warnidf - returnType: string - signatures: ['fmt.Errorf FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [errorf] + returnType: string + signatures: ['fmt.Errorf FORMAT [INPUT]'] aliases: [/functions/errorf] --- -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% include "/_common/functions/fmt/format-string.md" %}} The `errorf` function evaluates the format string, then prints the result to the ERROR log and fails the build. diff --git a/docs/content/en/functions/fmt/Erroridf.md b/docs/content/en/functions/fmt/Erroridf.md index f442f09bf..97d628bac 100644 --- a/docs/content/en/functions/fmt/Erroridf.md +++ b/docs/content/en/functions/fmt/Erroridf.md @@ -3,18 +3,15 @@ title: fmt.Erroridf description: Log a suppressible ERROR from a template. categories: [] keywords: [] -action: - aliases: [erroridf] - related: - - functions/fmt/Errorf - - functions/fmt/Warnf - - functions/fmt/Warnidf - returnType: string - signatures: ['fmt.Erroridf ID FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [erroridf] + returnType: string + signatures: ['fmt.Erroridf ID FORMAT [INPUT]'] aliases: [/functions/erroridf] --- -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% include "/_common/functions/fmt/format-string.md" %}} The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreLogs` array in your site configuration. diff --git a/docs/content/en/functions/fmt/Print.md b/docs/content/en/functions/fmt/Print.md index 6f3128e5f..f1d169cfa 100644 --- a/docs/content/en/functions/fmt/Print.md +++ b/docs/content/en/functions/fmt/Print.md @@ -3,13 +3,11 @@ title: fmt.Print description: Prints the default representation of the given arguments using the standard `fmt.Print` function. categories: [] keywords: [] -action: - aliases: [print] - related: - - functions/fmt/Printf - - functions/fmt/Println - returnType: string - signatures: [fmt.Print INPUT] +params: + functions_and_methods: + aliases: [print] + returnType: string + signatures: [fmt.Print INPUT] aliases: [/functions/print] --- diff --git a/docs/content/en/functions/fmt/Printf.md b/docs/content/en/functions/fmt/Printf.md index 5d0127460..68df98609 100644 --- a/docs/content/en/functions/fmt/Printf.md +++ b/docs/content/en/functions/fmt/Printf.md @@ -3,17 +3,15 @@ title: fmt.Printf description: Formats a string using the standard `fmt.Sprintf` function. categories: [] keywords: [] -action: - aliases: [printf] - related: - - functions/fmt/Print - - functions/fmt/Println - returnType: string - signatures: ['fmt.Printf FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [printf] + returnType: string + signatures: ['fmt.Printf FORMAT [INPUT]'] aliases: [/functions/printf] --- -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% include "/_common/functions/fmt/format-string.md" %}} ```go-html-template {{ $var := "world" }} diff --git a/docs/content/en/functions/fmt/Println.md b/docs/content/en/functions/fmt/Println.md index a4db56ffb..b7fe608ff 100644 --- a/docs/content/en/functions/fmt/Println.md +++ b/docs/content/en/functions/fmt/Println.md @@ -3,13 +3,11 @@ title: fmt.Println description: Prints the default representation of the given argument using the standard `fmt.Print` function and enforces a line break. categories: [] keywords: [] -action: - aliases: [println] - related: - - functions/fmt/Print - - functions/fmt/Printf - returnType: string - signatures: [fmt.Println INPUT] +params: + functions_and_methods: + aliases: [println] + returnType: string + signatures: [fmt.Println INPUT] aliases: [/functions/println] --- diff --git a/docs/content/en/functions/fmt/Warnf.md b/docs/content/en/functions/fmt/Warnf.md index 643defd30..887a8d47f 100644 --- a/docs/content/en/functions/fmt/Warnf.md +++ b/docs/content/en/functions/fmt/Warnf.md @@ -3,18 +3,15 @@ title: fmt.Warnf description: Log a WARNING from a template. categories: [] keywords: [] -action: - aliases: [warnf] - related: - - functions/fmt/Errorf - - functions/fmt/Erroridf - - functions/fmt/Warnidf - returnType: string - signatures: ['fmt.Warnf FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [warnf] + returnType: string + signatures: ['fmt.Warnf FORMAT [INPUT]'] aliases: [/functions/warnf] --- -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% include "/_common/functions/fmt/format-string.md" %}} The `warnf` function evaluates the format string, then prints the result to the WARNING log. Hugo prints each unique message once to avoid flooding the log with duplicate warnings. diff --git a/docs/content/en/functions/fmt/Warnidf.md b/docs/content/en/functions/fmt/Warnidf.md index 70c109b5b..79ebf81e6 100644 --- a/docs/content/en/functions/fmt/Warnidf.md +++ b/docs/content/en/functions/fmt/Warnidf.md @@ -3,20 +3,17 @@ title: fmt.Warnidf description: Log a suppressible WARNING from a template. categories: [] keywords: [] -action: - aliases: [warnidf] - related: - - functions/fmt/Errorf - - functions/fmt/Erroridf - - functions/fmt/Warnf - returnType: string - signatures: ['fmt.Warnidf ID FORMAT [INPUT]'] +params: + functions_and_methods: + aliases: [warnidf] + returnType: string + signatures: ['fmt.Warnidf ID FORMAT [INPUT]'] aliases: [/functions/warnidf] --- {{< new-in 0.123.0 />}} -{{% include "functions/fmt/_common/fmt-layout.md" %}} +{{% include "/_common/functions/fmt/format-string.md" %}} The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your site configuration. diff --git a/docs/content/en/functions/fmt/_common/_index.md b/docs/content/en/functions/fmt/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/functions/fmt/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/functions/fmt/_common/fmt-layout.md b/docs/content/en/functions/fmt/_common/fmt-layout.md deleted file mode 100644 index 09a9ee867..000000000 --- a/docs/content/en/functions/fmt/_common/fmt-layout.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -The documentation for Go's [fmt] package describes the structure and content of the format string. - -[fmt]: https://pkg.go.dev/fmt diff --git a/docs/content/en/functions/fmt/_index.md b/docs/content/en/functions/fmt/_index.md index 51ef847ca..d388df112 100644 --- a/docs/content/en/functions/fmt/_index.md +++ b/docs/content/en/functions/fmt/_index.md @@ -1,12 +1,7 @@ --- title: Fmt functions linkTitle: fmt -description: Template functions to print strings within a template or to print messages to the terminal +description: Use these functions to print strings within a template or to print messages to the terminal. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to print strings within a template or to print messages to the terminal. diff --git a/docs/content/en/functions/global/_index.md b/docs/content/en/functions/global/_index.md index 1e609b56e..3d935176c 100644 --- a/docs/content/en/functions/global/_index.md +++ b/docs/content/en/functions/global/_index.md @@ -1,11 +1,6 @@ --- title: Global functions linkTitle: global -description: Global template functions to access page and site data. +description: Use these global functions to access page and site data. categories: [] -menu: - docs: - parent: functions --- - -Use these global functions to access page and site data. diff --git a/docs/content/en/functions/global/page.md b/docs/content/en/functions/global/page.md index 1dc8be515..0d4b8070f 100644 --- a/docs/content/en/functions/global/page.md +++ b/docs/content/en/functions/global/page.md @@ -3,13 +3,11 @@ title: page description: Provides global access to a Page object. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/global/site - returnType: - signatures: [page] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [page] aliases: [/functions/page] --- @@ -27,13 +25,12 @@ When a `Page` object is not in context, you can use the global `page` function: {{ page.Params.foo }} ``` -{{% note %}} -Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below. -{{% /note %}} +> [!note] +> Do not use the global `page` function in shortcodes, partials called by shortcodes, or cached partials. See [warnings](#warnings) below. ## Explanation -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. +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](g), [partial](g), or [render hook](g), it is not always practical or possible to access the `Page` object. @@ -99,5 +96,5 @@ When you call the [`Summary`] method, Hugo renders the page content including sh If Hugo renders the section page before a content page, the cached rendered shortcode will be incorrect. You cannot control the rendering sequence due to concurrency. -[`Summary`]: /methods/page/summary/ [`partialCached`]: /functions/partials/includecached/ +[`Summary`]: /methods/page/summary/ diff --git a/docs/content/en/functions/global/site.md b/docs/content/en/functions/global/site.md index a4879fee0..be0c6730e 100644 --- a/docs/content/en/functions/global/site.md +++ b/docs/content/en/functions/global/site.md @@ -3,12 +3,11 @@ title: site description: Provides global access to the current Site object. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/global/page - returnType: - signatures: [site] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [site] aliases: [/functions/site] --- @@ -27,6 +26,5 @@ When the `Site` object is in context you can use the `Site` property: {{ $.Site.Params.foo }} ``` -{{% note %}} -To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context. -{{% /note %}} +> [!note] +> To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context. diff --git a/docs/content/en/functions/go-template/_common/_index.md b/docs/content/en/functions/go-template/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/functions/go-template/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/functions/go-template/_common/text-template.md b/docs/content/en/functions/go-template/_common/text-template.md deleted file mode 100644 index 4b934c1e9..000000000 --- a/docs/content/en/functions/go-template/_common/text-template.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -See Go's [text/template] documentation for more information. - -[text/template]: https://pkg.go.dev/text/template diff --git a/docs/content/en/functions/go-template/_common/truthy-falsy.md b/docs/content/en/functions/go-template/_common/truthy-falsy.md deleted file mode 100644 index e15e58d61..000000000 --- a/docs/content/en/functions/go-template/_common/truthy-falsy.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values. - -Everything else is truthy. diff --git a/docs/content/en/functions/go-template/_index.md b/docs/content/en/functions/go-template/_index.md index 9075756aa..627dc2849 100644 --- a/docs/content/en/functions/go-template/_index.md +++ b/docs/content/en/functions/go-template/_index.md @@ -1,14 +1,7 @@ --- title: Go template functions, operators, and statements linkTitle: go template -description: Template functions, operators, and statements provided by Go's text/template package. +description: These are the functions, operators, and statements provided by Go's text/template package. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -These are the functions, operators, and statements provided by Go's [text/template] package. - -[text/template]: https://pkg.go.dev/text/template diff --git a/docs/content/en/functions/go-template/and.md b/docs/content/en/functions/go-template/and.md index 6bc8c60a5..77906df52 100644 --- a/docs/content/en/functions/go-template/and.md +++ b/docs/content/en/functions/go-template/and.md @@ -3,16 +3,14 @@ title: and description: Returns the first falsy argument. If all arguments are truthy, returns the last argument. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/not - - functions/go-template/or - returnType: any - signatures: [and VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: [and VALUE...] --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ and 1 0 "" }} → 0 (int) @@ -22,5 +20,3 @@ action: {{ and "a" "b" "c" }} → c (string) {{ and "a" 1 true }} → true (bool) ``` - -{{% include "functions/go-template/_common/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/block.md b/docs/content/en/functions/go-template/block.md index f8a082037..bffab1f8c 100644 --- a/docs/content/en/functions/go-template/block.md +++ b/docs/content/en/functions/go-template/block.md @@ -3,13 +3,11 @@ title: block description: Defines a template and executes it in place. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/define - - functions/go-template/end - returnType: - signatures: [block NAME CONTEXT] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [block NAME CONTEXT] --- A block is shorthand for defining a template: @@ -25,7 +23,7 @@ and then executing it in place: ``` The typical use is to define a set of root templates that are then customized by redefining the block templates within. -{{< code file=layouts/_default/baseof.html >}} +```go-html-template {file="layouts/_default/baseof.html"} <body> <main> {{ block "main" . }} @@ -33,16 +31,16 @@ The typical use is to define a set of root templates that are then customized by {{ end }} </main> </body> -{{< /code >}} +``` -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ define "main" }} <h1>{{ .Title }}</h1> {{ .Content }} {{ end }} -{{< /code >}} +``` -{{< code file=layouts/_default/list.html >}} +```go-html-template {file="layouts/_default/list.html"} {{ define "main" }} <h1>{{ .Title }}</h1> {{ .Content }} @@ -50,6 +48,6 @@ The typical use is to define a set of root templates that are then customized by <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2> {{ end }} {{ end }} -{{< /code >}} +``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/break.md b/docs/content/en/functions/go-template/break.md index 14074d7c0..9236ec91e 100644 --- a/docs/content/en/functions/go-template/break.md +++ b/docs/content/en/functions/go-template/break.md @@ -3,13 +3,11 @@ title: break description: Used with the range statement, stops the innermost iteration and bypasses all remaining iterations. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/continue - - functions/go-template/range - returnType: - signatures: [break] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [break] --- This template code: @@ -30,4 +28,4 @@ Is rendered to: <p>foo</p> ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/continue.md b/docs/content/en/functions/go-template/continue.md index c8030b8b7..0b9339bf4 100644 --- a/docs/content/en/functions/go-template/continue.md +++ b/docs/content/en/functions/go-template/continue.md @@ -3,13 +3,11 @@ title: continue description: Used with the range statement, stops the innermost iteration and continues to the next iteration. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/break - - functions/go-template/range - returnType: - signatures: [continue] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [continue] --- This template code: @@ -31,4 +29,4 @@ Is rendered to: <p>baz</p> ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/define.md b/docs/content/en/functions/go-template/define.md index f15dd6ff0..19762a3d6 100644 --- a/docs/content/en/functions/go-template/define.md +++ b/docs/content/en/functions/go-template/define.md @@ -3,16 +3,11 @@ title: define description: Defines a template. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/block - - functions/go-template/end - - functions/go-template/template - - functions/partials/Include - - functions/partials/IncludeCached - returnType: - signatures: [define NAME] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [define NAME] --- Use with the [`block`] statement: @@ -52,4 +47,4 @@ Use with the [`template`] function: [`template`]: /functions/go-template/block/ [`partial`]: /functions/partials/include/ -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/else.md b/docs/content/en/functions/go-template/else.md index 698998bd8..db3980070 100644 --- a/docs/content/en/functions/go-template/else.md +++ b/docs/content/en/functions/go-template/else.md @@ -3,15 +3,11 @@ title: else description: Begins an alternate block for if, with, and range statements. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/if - - functions/go-template/range - - functions/go-template/with - - functions/go-template/end - returnType: - signatures: [else VALUE] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [else VALUE] --- Use with the [`if`] statement: @@ -62,7 +58,7 @@ Use `else if` to check multiple conditions. {{ end }} ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`if`]: /functions/go-template/if/ [`with`]: /functions/go-template/with/ diff --git a/docs/content/en/functions/go-template/end.md b/docs/content/en/functions/go-template/end.md index 6fb5bbfd6..6de120724 100644 --- a/docs/content/en/functions/go-template/end.md +++ b/docs/content/en/functions/go-template/end.md @@ -3,16 +3,11 @@ title: end description: Terminates if, with, range, block, and define statements. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/block - - functions/go-template/define - - functions/go-template/if - - functions/go-template/range - - functions/go-template/with - returnType: - signatures: [end] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [end] --- Use with the [`if`] statement: @@ -56,7 +51,7 @@ Use with the [`define`] statement: {{ end }} ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`block`]: /functions/go-template/block/ [`define`]: /functions/go-template/define/ diff --git a/docs/content/en/functions/go-template/if.md b/docs/content/en/functions/go-template/if.md index 9fdf80e99..af2989cca 100644 --- a/docs/content/en/functions/go-template/if.md +++ b/docs/content/en/functions/go-template/if.md @@ -3,18 +3,14 @@ title: if description: Executes the block if the expression is truthy. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/with - - functions/go-template/else - - functions/go-template/end - - functions/collections/IsSet - returnType: - signatures: [if EXPR] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [if EXPR] --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ $var := "foo" }} @@ -49,6 +45,6 @@ Use `else if` to check multiple conditions: {{ end }} ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`else`]: /functions/go-template/else/ diff --git a/docs/content/en/functions/go-template/len.md b/docs/content/en/functions/go-template/len.md index 43f150a5f..6a13784e3 100644 --- a/docs/content/en/functions/go-template/len.md +++ b/docs/content/en/functions/go-template/len.md @@ -3,15 +3,11 @@ title: len description: Returns the length of a string, slice, map, or collection. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Count - - functions/strings/CountRunes - - functions/strings/CountWords - - functions/strings/RuneCount - returnType: int - signatures: [len VALUE] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [len VALUE] aliases: [/functions/len] --- @@ -48,4 +44,4 @@ You may also determine the number of pages in a collection with: {{ site.RegularPages.Len }} → 42 ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/not.md b/docs/content/en/functions/go-template/not.md index 4c7747c7b..fd8b9afae 100644 --- a/docs/content/en/functions/go-template/not.md +++ b/docs/content/en/functions/go-template/not.md @@ -3,13 +3,11 @@ title: not description: Returns the boolean negation of its single argument. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/and - - functions/go-template/or - returnType: bool - signatures: [not VALUE] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [not VALUE] --- Unlike the `and` and `or` operators, the `not` operator always returns a boolean value. @@ -32,4 +30,4 @@ Use the `not` operator, twice in succession, to cast any value to a boolean valu {{ "" | not | not }} → false ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/or.md b/docs/content/en/functions/go-template/or.md index 0d8619608..2f55fe479 100644 --- a/docs/content/en/functions/go-template/or.md +++ b/docs/content/en/functions/go-template/or.md @@ -3,16 +3,14 @@ title: or description: Returns the first truthy argument. If all arguments are falsy, returns the last argument. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/and - - functions/go-template/not - returnType: any - signatures: [or VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: [or VALUE...] --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ or 0 1 2 }} → 1 @@ -23,4 +21,4 @@ action: {{ or 0 "" false }} → false ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/range.md b/docs/content/en/functions/go-template/range.md index 96713c4b7..a06907c79 100644 --- a/docs/content/en/functions/go-template/range.md +++ b/docs/content/en/functions/go-template/range.md @@ -3,20 +3,15 @@ title: range description: Iterates over a non-empty collection, binds context (the dot) to successive elements, and executes the block. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/break - - functions/go-template/continue - - functions/go-template/else - - functions/go-template/end - returnType: - signatures: [range COLLECTION] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [range COLLECTION] aliases: [/functions/range] -toc: true --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -59,9 +54,8 @@ Hugo will throw an error: The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Within the `range` block, if we want to render the page title, we need to get the context passed into the template. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. This template will render the page title three times: @@ -71,11 +65,8 @@ This template will render the page title three times: {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} - -[`seq`]: /functions/collections/seq/ +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. ## Array or slice of scalars @@ -191,8 +182,9 @@ Is rendered to: Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map. -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} -[`else`]: /functions/go-template/else/ [`break`]: /functions/go-template/break/ [`continue`]: /functions/go-template/continue/ +[`else`]: /functions/go-template/else/ +[`seq`]: /functions/collections/seq/ diff --git a/docs/content/en/functions/go-template/return.md b/docs/content/en/functions/go-template/return.md index df5b2496e..eb6ba30cd 100644 --- a/docs/content/en/functions/go-template/return.md +++ b/docs/content/en/functions/go-template/return.md @@ -3,14 +3,11 @@ title: return description: Used within partial templates, terminates template execution and returns the given value, if any. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/partials/Include - - functions/partials/IncludeCached - returnType: any - signatures: ['return [VALUE]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: ['return [VALUE]'] --- 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. @@ -19,21 +16,20 @@ The returned value may be of any data type including, but not limited to, [`bool A `return` statement without a value returns an empty string of type `template.HTML`. -{{% 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 %}} +> [!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. ## Example By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even: -{{< code file="layouts/partials/odd-or-even.html" >}} +```go-html-template {file="layouts/partials/odd-or-even.html"} {{ if math.ModBool . 2 }} <p>{{ . }} is even</p> {{ else }} <p>{{ . }} is odd</p> {{ end }} -{{< /code >}} +``` When called, the partial renders HTML: @@ -43,9 +39,9 @@ When called, the partial renders HTML: Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even: -{{< code file="layouts/partials/is-even.html" >}} +```go-html-template {file="layouts/partials/is-even.html"} {{ return math.ModBool . 2 }} -{{< /code >}} +``` With this template: @@ -66,19 +62,16 @@ Hugo renders: See additional examples in the [partial templates] section. -[partial templates]: /templates/partial/#returning-a-value-from-a-partial - ## Usage -{{% note %}} -Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. -{{% /note %}} +> [!note] +> Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. A partial that returns a value must contain only one `return` statement, placed at the end of the template. For example: -{{< code file="layouts/partials/is-even.html" >}} +```go-html-template {file="layouts/partials/is-even.html"} {{ $result := false }} {{ if math.ModBool . 2 }} {{ $result = "even" }} @@ -86,16 +79,18 @@ For example: {{ $result = "odd" }} {{ end }} {{ return $result }} -{{< /code >}} +``` -{{% note %}} -The construct below is incorrect; it contains more than one `return` statement. -{{% /note %}} +> [!note] +> The construct below is incorrect; it contains more than one `return` statement. -{{< code file="layouts/partials/do-not-do-this.html" >}} +```go-html-template {file="layouts/partials/do-not-do-this.html"} {{ if math.ModBool . 2 }} {{ return "even" }} {{ else }} {{ return "odd" }} {{ end }} -{{< /code >}} +``` + +[partial templates]: /templates/partial/#returning-a-value-from-a-partial +[text/template package]: https://pkg.go.dev/text/template diff --git a/docs/content/en/functions/go-template/template.md b/docs/content/en/functions/go-template/template.md index 0a72acdaa..dac1fa3be 100644 --- a/docs/content/en/functions/go-template/template.md +++ b/docs/content/en/functions/go-template/template.md @@ -3,14 +3,11 @@ title: template description: Executes the given template, optionally passing context. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/define - - functions/partials/Include - - functions/partials/IncludeCached - returnType: - signatures: ['template NAME [CONTEXT]'] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: ['template NAME [CONTEXT]'] --- Use the `template` function to execute [embedded templates]. For example: @@ -42,7 +39,7 @@ The example above can be rewritten using an [inline partial] template: {{ end }} ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`partial`]: /functions/partials/include/ [inline partial]: /templates/partial/#inline-partials diff --git a/docs/content/en/functions/go-template/try.md b/docs/content/en/functions/go-template/try.md index f3385a04c..6aef4da36 100644 --- a/docs/content/en/functions/go-template/try.md +++ b/docs/content/en/functions/go-template/try.md @@ -3,29 +3,28 @@ title: try description: Returns a TryValue object after evaluating the given expression. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: TryValue - signatures: ['try EXPRESSION'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: TryValue + signatures: ['try EXPRESSION'] --- {{< 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. +### 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. +### 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 @@ -88,8 +87,6 @@ Hugo renders the above to: 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 @@ -106,8 +103,9 @@ Instead of failing the build, we can catch the error and emit a warning: ``` 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 %}} -Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. -{{% /note %}} +[`resources.GetRemote`]: /functions/resources/getremote/ +[template context]: /templates/introduction/#template-context +[text/template]: https://pkg.go.dev/text/template diff --git a/docs/content/en/functions/go-template/urlquery.md b/docs/content/en/functions/go-template/urlquery.md index 946828f56..dc97f867e 100644 --- a/docs/content/en/functions/go-template/urlquery.md +++ b/docs/content/en/functions/go-template/urlquery.md @@ -3,12 +3,11 @@ title: urlquery description: Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/collections/Querify - returnType: string - signatures: ['urlquery VALUE [VALUE...]'] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: ['urlquery VALUE [VALUE...]'] aliases: [/functions/urlquery] --- @@ -25,4 +24,4 @@ Is rendered to: <a href="https://example.org?url=https%3A%2F%2Fexample.com">Link</a> ``` -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} diff --git a/docs/content/en/functions/go-template/with.md b/docs/content/en/functions/go-template/with.md index a730f4d2c..c25ce3fba 100644 --- a/docs/content/en/functions/go-template/with.md +++ b/docs/content/en/functions/go-template/with.md @@ -3,20 +3,15 @@ title: with description: Binds context (the dot) to the expression and executes the block if expression is truthy. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/if - - functions/go-template/else - - functions/go-template/end - - functions/collections/IsSet - returnType: - signatures: [with EXPR] +params: + functions_and_methods: + aliases: [] + returnType: + signatures: [with EXPR] aliases: [/functions/with] -toc: true --- -{{% include "functions/go-template/_common/truthy-falsy.md" %}} +{{% include "/_common/functions/truthy-falsy.md" %}} ```go-html-template {{ $var := "foo" }} @@ -78,9 +73,8 @@ Hugo will throw an error: The error occurs because we are trying to use the `.Title` method on an integer instead of a `Page` object. Inside of the `with` block, if we want to render the page title, we need to get the context passed into the template. -{{% note %}} -Use the `$` to get the context passed into the template. -{{% /note %}} +> [!note] +> Use the `$` to get the context passed into the template. This template will render the page title as desired: @@ -90,10 +84,9 @@ This template will render the page title as desired: {{ end }} ``` -{{% note %}} -Gaining a thorough understanding of context is critical for anyone writing template code. -{{% /note %}} +> [!note] +> Gaining a thorough understanding of context is critical for anyone writing template code. -{{% include "functions/go-template/_common/text-template.md" %}} +{{% include "/_common/functions/go-template/text-template.md" %}} [`else`]: /functions/go-template/else/ diff --git a/docs/content/en/functions/hash/FNV32a.md b/docs/content/en/functions/hash/FNV32a.md index b5af77519..b108acff8 100644 --- a/docs/content/en/functions/hash/FNV32a.md +++ b/docs/content/en/functions/hash/FNV32a.md @@ -1,18 +1,13 @@ --- title: hash.FNV32a -description: Returns the 32-bit FNV (Fowler–Noll–Vo) non-cryptographic hash of the given string. +description: Returns the 32-bit FNV (Fowler-Noll-Vo) non-cryptographic hash of the given string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/hash/Xxhash - - functions/crypto/HMAC - - functions/crypto/MD5 - - functions/crypto/SHA1 - - functions/crypto/SHA256 - returnType: int - signatures: [hash.FNV32a STRING] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [hash.FNV32a STRING] aliases: [/functions/crypto.fnv32a] --- diff --git a/docs/content/en/functions/hash/XxHash.md b/docs/content/en/functions/hash/XxHash.md index 7d35c18e5..6a92b2bdc 100644 --- a/docs/content/en/functions/hash/XxHash.md +++ b/docs/content/en/functions/hash/XxHash.md @@ -3,18 +3,15 @@ title: hash.XxHash description: Returns the 64-bit xxHash non-cryptographic hash of the given string. categories: [] keywords: [] -action: - aliases: [xxhash] - related: - - functions/hash/FNV32a - - functions/crypto/HMAC - - functions/crypto/MD5 - - functions/crypto/SHA1 - - functions/crypto/SHA256 - returnType: string - signatures: [hash.XxHash STRING] +params: + functions_and_methods: + aliases: [xxhash] + returnType: string + signatures: [hash.XxHash STRING] --- ```go-html-template {{ hash.XxHash "Hello world" }} → c500b0c912b376d8 ``` + +[xxHash](https://xxhash.com/) is a very fast non-cryptographic hash algorithm. Hugo uses [this Go implementation](https://github.com/cespare/xxhash). diff --git a/docs/content/en/functions/hash/_index.md b/docs/content/en/functions/hash/_index.md index bf21c5b7b..956f7fb8d 100644 --- a/docs/content/en/functions/hash/_index.md +++ b/docs/content/en/functions/hash/_index.md @@ -1,12 +1,7 @@ --- title: Hash functions linkTitle: hash -description: Template functions to create non-cryptographic hashes. +description: Use these functions to create non-cryptographic hashes. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to create non-cryptographic hashes. diff --git a/docs/content/en/functions/hugo/BuildDate.md b/docs/content/en/functions/hugo/BuildDate.md index 1fbdbeac6..a592283b9 100644 --- a/docs/content/en/functions/hugo/BuildDate.md +++ b/docs/content/en/functions/hugo/BuildDate.md @@ -3,11 +3,11 @@ title: hugo.BuildDate description: Returns the compile date of the Hugo binary. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [hugo.BuildDate] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.BuildDate] --- The `hugo.BuildDate` function returns the compile date of the Hugo binary, formatted per [RFC 3339]. diff --git a/docs/content/en/functions/hugo/CommitHash.md b/docs/content/en/functions/hugo/CommitHash.md index cd4f2ce92..324e985d1 100644 --- a/docs/content/en/functions/hugo/CommitHash.md +++ b/docs/content/en/functions/hugo/CommitHash.md @@ -3,11 +3,11 @@ title: hugo.CommitHash description: Returns the Git commit hash of the Hugo binary. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [hugo.CommitHash] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.CommitHash] --- ```go-html-template diff --git a/docs/content/en/functions/hugo/Deps.md b/docs/content/en/functions/hugo/Deps.md index 2f3f75e65..9d8667ee5 100644 --- a/docs/content/en/functions/hugo/Deps.md +++ b/docs/content/en/functions/hugo/Deps.md @@ -3,11 +3,11 @@ title: hugo.Deps description: Returns a slice of project dependencies, either Hugo Modules or local theme components. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: '[]hugo.Dependency' - signatures: [hugo.Deps] +params: + functions_and_methods: + aliases: [] + returnType: '[]hugo.Dependency' + signatures: [hugo.Deps] --- The `hugo.Deps` function returns a slice of project dependencies, either Hugo Modules or local theme components. Each dependency contains: diff --git a/docs/content/en/functions/hugo/Environment.md b/docs/content/en/functions/hugo/Environment.md index 374a39f6c..551306255 100644 --- a/docs/content/en/functions/hugo/Environment.md +++ b/docs/content/en/functions/hugo/Environment.md @@ -3,13 +3,11 @@ title: hugo.Environment description: Returns the current running environment. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/hugo/IsDevelopment - - functions/hugo/IsProduction - returnType: string - signatures: [hugo.Environment] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.Environment] --- The `hugo.Environment` function returns the current running [environment](g) as defined through the `--environment` command line flag. diff --git a/docs/content/en/functions/hugo/Generator.md b/docs/content/en/functions/hugo/Generator.md index 17eb47e1d..dc72a7af2 100644 --- a/docs/content/en/functions/hugo/Generator.md +++ b/docs/content/en/functions/hugo/Generator.md @@ -1,15 +1,15 @@ --- title: hugo.Generator -description: Renders an HTML meta element identifying the software that generated the site. +description: Renders an HTML meta element identifying the software that generated the site. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: template.HTML - signatures: [hugo.Generator] +params: + functions_and_methods: + aliases: [] + returnType: template.HTML + signatures: [hugo.Generator] --- ```go-html-template -{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.141.0"> +{{ hugo.Generator }} → <meta name="generator" content="Hugo 0.144.2"> ``` diff --git a/docs/content/en/functions/hugo/GoVersion.md b/docs/content/en/functions/hugo/GoVersion.md index 34c6266bf..94e310deb 100644 --- a/docs/content/en/functions/hugo/GoVersion.md +++ b/docs/content/en/functions/hugo/GoVersion.md @@ -3,11 +3,11 @@ title: hugo.GoVersion description: Returns the Go version used to compile the Hugo binary categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [hugo.GoVersion] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.GoVersion] --- ```go-html-template diff --git a/docs/content/en/functions/hugo/IsDevelopment.md b/docs/content/en/functions/hugo/IsDevelopment.md index bfbc0eaa1..cea923acd 100644 --- a/docs/content/en/functions/hugo/IsDevelopment.md +++ b/docs/content/en/functions/hugo/IsDevelopment.md @@ -3,13 +3,11 @@ title: hugo.IsDevelopment description: Reports whether the current running environment is "development". categories: [] keywords: [] -action: - aliases: [] - related: - - functions/hugo/IsProduction - - functions/hugo/Environment - returnType: bool - signatures: [hugo.IsDevelopment] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsDevelopment] --- {{< new-in 0.120.0 />}} diff --git a/docs/content/en/functions/hugo/IsExtended.md b/docs/content/en/functions/hugo/IsExtended.md index 9beac6e49..ab7e0f7b1 100644 --- a/docs/content/en/functions/hugo/IsExtended.md +++ b/docs/content/en/functions/hugo/IsExtended.md @@ -3,11 +3,11 @@ title: hugo.IsExtended description: Reports whether the Hugo binary is either the extended or extended/deploy edition. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: bool - signatures: [hugo.IsExtended] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsExtended] --- ```go-html-template diff --git a/docs/content/en/functions/hugo/IsMultihost.md b/docs/content/en/functions/hugo/IsMultihost.md index 5c1cb9f83..605afa79a 100644 --- a/docs/content/en/functions/hugo/IsMultihost.md +++ b/docs/content/en/functions/hugo/IsMultihost.md @@ -3,12 +3,11 @@ title: hugo.IsMultihost description: Reports whether each configured language has a unique base URL. categories: [] keywords: [] -action: - aliases: [] - related: - - /functions/hugo/IsMultilingual - returnType: bool - signatures: [hugo.IsMultihost] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsMultihost] --- {{< new-in 0.124.0 />}} diff --git a/docs/content/en/functions/hugo/IsMultilingual.md b/docs/content/en/functions/hugo/IsMultilingual.md index 91beb0d52..85fc6550f 100644 --- a/docs/content/en/functions/hugo/IsMultilingual.md +++ b/docs/content/en/functions/hugo/IsMultilingual.md @@ -3,11 +3,11 @@ title: hugo.IsMultilingual description: Reports whether there are two or more configured languages. categories: [] keywords: [] -action: - related: - - /functions/hugo/IsMultihost - returnType: bool - signatures: [hugo.IsMultilingual] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsMultilingual] --- {{< new-in 0.124.0 />}} diff --git a/docs/content/en/functions/hugo/IsProduction.md b/docs/content/en/functions/hugo/IsProduction.md index 7e9bda0e3..e5433c239 100644 --- a/docs/content/en/functions/hugo/IsProduction.md +++ b/docs/content/en/functions/hugo/IsProduction.md @@ -3,13 +3,11 @@ title: hugo.IsProduction description: Reports whether the current running environment is "production". categories: [] keywords: [] -action: - aliases: [] - related: - - functions/hugo/IsDevelopment - - functions/hugo/Environment - returnType: bool - signatures: [hugo.IsProduction] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsProduction] --- ```go-html-template diff --git a/docs/content/en/functions/hugo/IsServer.md b/docs/content/en/functions/hugo/IsServer.md index 0fa42fc15..840ff060d 100644 --- a/docs/content/en/functions/hugo/IsServer.md +++ b/docs/content/en/functions/hugo/IsServer.md @@ -3,11 +3,11 @@ title: hugo.IsServer description: Reports whether the built-in development server is running. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: bool - signatures: [hugo.IsServer] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [hugo.IsServer] --- {{< new-in 0.120.0 />}} diff --git a/docs/content/en/functions/hugo/Store.md b/docs/content/en/functions/hugo/Store.md index 4f3250954..08c684146 100644 --- a/docs/content/en/functions/hugo/Store.md +++ b/docs/content/en/functions/hugo/Store.md @@ -3,15 +3,10 @@ title: hugo.Store description: Returns a globally scoped "scratch pad" to store and manipulate data. categories: [] keywords: [] -action: - related: - - methods/page/Store - - methods/site/Store - - methods/shortcode/Store - - functions/collections/NewScratch - returnType: maps.Scratch - signatures: [hugo.Store] -toc: true +params: + functions_and_methods: + returnType: maps.Scratch + signatures: [hugo.Store] --- {{< new-in 0.139.0 />}} @@ -20,7 +15,7 @@ Use the `hugo.Store` function to create a globally scoped [scratch pad](g) to st ## Methods -###### Set +### Set Sets the value of the given key. @@ -28,7 +23,7 @@ Sets the value of the given key. {{ hugo.Store.Set "greeting" "Hello" }} ``` -###### Get +### Get Gets the value of the given key. @@ -37,7 +32,7 @@ Gets the value of the given key. {{ hugo.Store.Get "greeting" }} → Hello ``` -###### Add +### Add Adds the given value to the existing value(s) of the given key. @@ -61,7 +56,7 @@ For single values, `Add` accepts values that support Go's `+` operator. If the f {{ hugo.Store.Get "greetings" }} → [Hello Welcome Cheers] ``` -###### SetInMap +### SetInMap Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`. @@ -71,7 +66,7 @@ Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to th {{ hugo.Store.Get "greetings" }} → map[english:Hello french:Bonjour] ``` -###### DeleteInMap +### DeleteInMap Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. @@ -80,9 +75,9 @@ Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`. {{ hugo.Store.SetInMap "greetings" "french" "Bonjour" }} {{ hugo.Store.DeleteInMap "greetings" "english" }} {{ hugo.Store.Get "greetings" }} → map[french:Bonjour] -``` + ``` -###### GetSortedMapValues +### GetSortedMapValues Returns an array of values from `key` sorted by `mapKey`. @@ -92,7 +87,7 @@ Returns an array of values from `key` sorted by `mapKey`. {{ hugo.Store.GetSortedMapValues "greetings" }} → [Hello Bonjour] ``` -###### Delete +### Delete Removes the given key. diff --git a/docs/content/en/functions/hugo/Version.md b/docs/content/en/functions/hugo/Version.md index e6e1207b8..7925af981 100644 --- a/docs/content/en/functions/hugo/Version.md +++ b/docs/content/en/functions/hugo/Version.md @@ -3,13 +3,13 @@ title: hugo.Version description: Returns the current version of the Hugo binary. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: hugo.VersionString - signatures: [hugo.Version] +params: + functions_and_methods: + aliases: [] + returnType: hugo.VersionString + signatures: [hugo.Version] --- ```go-html-template -{{ hugo.Version }} → 0.141.0 +{{ hugo.Version }} → 0.144.2 ``` diff --git a/docs/content/en/functions/hugo/WorkingDir.md b/docs/content/en/functions/hugo/WorkingDir.md index ac3835ea8..e50102558 100644 --- a/docs/content/en/functions/hugo/WorkingDir.md +++ b/docs/content/en/functions/hugo/WorkingDir.md @@ -3,11 +3,11 @@ title: hugo.WorkingDir description: Returns the project working directory. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [hugo.WorkingDir] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [hugo.WorkingDir] --- ```go-html-template diff --git a/docs/content/en/functions/hugo/_index.md b/docs/content/en/functions/hugo/_index.md index c3ad686da..b1c9216c4 100644 --- a/docs/content/en/functions/hugo/_index.md +++ b/docs/content/en/functions/hugo/_index.md @@ -1,12 +1,7 @@ --- title: Hugo functions linkTitle: hugo -description: Template functions to access information about the Hugo application and the current environment. +description: Use these functions to access information about the Hugo application and the current environment. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to access information about the Hugo application and the current environment. diff --git a/docs/content/en/functions/images/AutoOrient.md b/docs/content/en/functions/images/AutoOrient.md index 8e3708eea..fd8d2ed14 100644 --- a/docs/content/en/functions/images/AutoOrient.md +++ b/docs/content/en/functions/images/AutoOrient.md @@ -3,14 +3,11 @@ title: images.AutoOrient description: Returns an image filter that rotates and flips an image as needed per its EXIF orientation tag. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.AutoOrient] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.AutoOrient] --- {{< new-in 0.121.2 />}} @@ -23,11 +20,10 @@ Create the filter: {{ $filter := images.AutoOrient }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} -{{% note %}} -When using with other filters, specify `images.AutoOrient` first. -{{% /note %}} +> [!note] +> When using with other filters, specify `images.AutoOrient` first. ```go-html-template {{ $filters := slice diff --git a/docs/content/en/functions/images/Brightness.md b/docs/content/en/functions/images/Brightness.md index 0001bcba8..0ddfcba55 100644 --- a/docs/content/en/functions/images/Brightness.md +++ b/docs/content/en/functions/images/Brightness.md @@ -3,14 +3,11 @@ title: images.Brightness description: Returns an image filter that changes the brightness of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Brightness PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Brightness PERCENTAGE] --- The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid black image, and a value of `100` produces a solid white image. @@ -23,7 +20,7 @@ Create the image filter: {{ $filter := images.Brightness 12 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/ColorBalance.md b/docs/content/en/functions/images/ColorBalance.md index 29829f9e6..be4a2bce8 100644 --- a/docs/content/en/functions/images/ColorBalance.md +++ b/docs/content/en/functions/images/ColorBalance.md @@ -3,14 +3,11 @@ title: images.ColorBalance description: Returns an image filter that changes the color balance of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.ColorBalance PCTRED PCTGREEN PCTBLUE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.ColorBalance PCTRED PCTGREEN PCTBLUE] --- The percentage for each channel (red, green, blue) must be in the range [-100, 500]. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.ColorBalance -10 10 50 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Colorize.md b/docs/content/en/functions/images/Colorize.md index c974103b9..6b8cd5966 100644 --- a/docs/content/en/functions/images/Colorize.md +++ b/docs/content/en/functions/images/Colorize.md @@ -3,14 +3,11 @@ title: images.Colorize description: Returns an image filter that produces a colorized version of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Colorize HUE SATURATION PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Colorize HUE SATURATION PERCENTAGE] --- The hue is the angle on the color wheel, typically in the range [0, 360]. @@ -27,7 +24,7 @@ Create the filter: {{ $filter := images.Colorize 180 50 20 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Config.md b/docs/content/en/functions/images/Config.md index 8f79a65f8..59242fb95 100644 --- a/docs/content/en/functions/images/Config.md +++ b/docs/content/en/functions/images/Config.md @@ -3,18 +3,16 @@ title: images.Config description: Returns an image.Config structure from the image at the specified path, relative to the working directory. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: image.Config - signatures: [images.Config PATH] +params: + functions_and_methods: + aliases: [] + returnType: image.Config + signatures: [images.Config PATH] aliases: [/functions/imageconfig] --- See [image processing] for an overview of Hugo's image pipeline. -[image processing]: /content-management/image-processing/ - ```go-html-template {{ $ic := images.Config "/static/images/a.jpg" }} @@ -24,10 +22,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 resources](g), [page resources](g), and [remote resources](g). See the [image processing] section for details. +> [!note] +> 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/ +[`Width`]: /methods/resource/width/ [image processing]: /content-management/image-processing/ -{{% /note %}} diff --git a/docs/content/en/functions/images/Contrast.md b/docs/content/en/functions/images/Contrast.md index 532ae8c9c..f5d607440 100644 --- a/docs/content/en/functions/images/Contrast.md +++ b/docs/content/en/functions/images/Contrast.md @@ -3,14 +3,11 @@ title: images.Contrast description: Returns an image filter that changes the contrast of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Contrast PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Contrast PERCENTAGE] --- The percentage must be in the range [-100, 100] where 0 has no effect. A value of `-100` produces a solid grey image, and a value of `100` produces an over-contrasted image. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Contrast -20 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Dither.md b/docs/content/en/functions/images/Dither.md index d6ae603a8..eab7743f7 100644 --- a/docs/content/en/functions/images/Dither.md +++ b/docs/content/en/functions/images/Dither.md @@ -3,16 +3,11 @@ title: images.Dither description: Returns an image filter that dithers an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - functions/images/Process - - methods/resource/Colors - - methods/resource/Filter - returnType: images.filter - signatures: ['images.Dither [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: ['images.Dither [OPTIONS]'] --- {{< new-in 0.123.0 />}} @@ -28,7 +23,7 @@ method : (`string`) The dithering method. See the [dithering methods](#dithering-methods) section below for a list of the available methods. Default is `FloydSteinberg`. serpentine -: (`bool`) Applicable to error diffusion dithering methods, serpentine controls whether the error diffusion matrix is applied in a serpentine manner, meaning that it goes right-to-left every other line. This greatly reduces line-type artifacts. Default is `true`. +: (`bool`) Applicable to error diffusion dithering methods, whether to apply the error diffusion matrix in a serpentine manner, meaning that it goes right-to-left every other line. This greatly reduces line-type artifacts. Default is `true`. strength : (`float`) The strength at which to apply the dithering matrix, typically a value in the range [0, 1]. A value of `1.0` applies the dithering matrix at 100% strength (no modification of the dither matrix). The `strength` is inversely proportional to contrast; reducing the strength increases the contrast. Setting `strength` to a value such as `0.8` can be useful to reduce noise in the dithered image. Default is `1.0`. @@ -57,13 +52,13 @@ Or create the filter using the default settings: {{ $filter := images.Dither }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Dithering methods See the [Go documentation] for descriptions of each of the dithering methods below. -[Go documentation]: https://pkg.go.dev/github.com/makeworld-the-better-one/dither/v2#pkg-variables +[Go documentation]: https://pkg.go.dev/github.com/makeworld-the-better-one/dither/v2#pkg-variables Error diffusion dithering methods: diff --git a/docs/content/en/functions/images/Filter.md b/docs/content/en/functions/images/Filter.md index 2961d7f47..1f2c268be 100644 --- a/docs/content/en/functions/images/Filter.md +++ b/docs/content/en/functions/images/Filter.md @@ -3,13 +3,11 @@ title: images.Filter description: Applies one or more image filters to the given image resource. categories: [] keywords: [] -action: - aliases: [] - related: - - methods/resource/Filter - returnType: images.ImageResource - signatures: [images.Filter FILTERS... IMAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.ImageResource + signatures: [images.Filter FILTERS... IMAGE] --- Apply one or more [image filters](#image-filters) to the given image. @@ -64,4 +62,4 @@ You can also apply image filters using the [`Filter`] method on a `Resource` obj Use any of these filters with the `images.Filter` function, or with the `Filter` method on a `Resource` object. -{{< list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude >}} +{{% list-pages-in-section path=/functions/images filter=functions_images_no_filters filterType=exclude %}} diff --git a/docs/content/en/functions/images/Gamma.md b/docs/content/en/functions/images/Gamma.md index affbdcfa8..d8cb076f1 100644 --- a/docs/content/en/functions/images/Gamma.md +++ b/docs/content/en/functions/images/Gamma.md @@ -3,14 +3,11 @@ title: images.Gamma description: Returns an image filter that performs gamma correction on an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Gamma GAMMA] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Gamma GAMMA] --- The gamma value must be positive. A value greater than 1 lightens the image, while a value less than 1 darkens the image. The filter has no effect when the gamma value is 1. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Gamma 1.667 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/GaussianBlur.md b/docs/content/en/functions/images/GaussianBlur.md index e2f49a847..c5eb136e2 100644 --- a/docs/content/en/functions/images/GaussianBlur.md +++ b/docs/content/en/functions/images/GaussianBlur.md @@ -3,14 +3,11 @@ title: images.GaussianBlur description: Returns an image filter that applies a gaussian blur to an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.GaussianBlur SIGMA] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.GaussianBlur SIGMA] --- The sigma value must be positive, and indicates how much the image will be blurred. The blur-affected radius is approximately 3 times the sigma value. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.GaussianBlur 5 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Grayscale.md b/docs/content/en/functions/images/Grayscale.md index d8a89b7f2..d3651b8dc 100644 --- a/docs/content/en/functions/images/Grayscale.md +++ b/docs/content/en/functions/images/Grayscale.md @@ -3,14 +3,11 @@ title: images.Grayscale description: Returns an image filter that produces a grayscale version of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Grayscale] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Grayscale] --- ## Usage @@ -21,7 +18,7 @@ Create the filter: {{ $filter := images.Grayscale }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Hue.md b/docs/content/en/functions/images/Hue.md index 6eafac437..f334eebd8 100644 --- a/docs/content/en/functions/images/Hue.md +++ b/docs/content/en/functions/images/Hue.md @@ -3,14 +3,11 @@ title: images.Hue description: Returns an image filter that rotates the hue of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Hue SHIFT] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Hue SHIFT] --- The hue angle shift is typically in the range [-180, 180] where 0 has no effect. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Hue -15 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Invert.md b/docs/content/en/functions/images/Invert.md index 1ee85e514..0f9f9a9d2 100644 --- a/docs/content/en/functions/images/Invert.md +++ b/docs/content/en/functions/images/Invert.md @@ -3,14 +3,11 @@ title: images.Invert description: Returns an image filter that negates the colors of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Invert] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Invert] --- ## Usage @@ -21,7 +18,7 @@ Create the filter: {{ $filter := images.Invert }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Mask.md b/docs/content/en/functions/images/Mask.md index 8116e8946..4f3b4aa3f 100644 --- a/docs/content/en/functions/images/Mask.md +++ b/docs/content/en/functions/images/Mask.md @@ -3,23 +3,19 @@ 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 +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Mask RESOURCE] --- {{< 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 %}} +> [!note] +> Of the formats supported by Hugo's imaging pipeline, 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. 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: @@ -27,8 +23,6 @@ When applying a mask to a non-transparent image format such as JPEG, the masked {{ $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: @@ -59,9 +53,6 @@ You can also apply the filter using the [`Filter`] method on a 'Resource' object {{ end }} ``` -[`images.Filter`]: /functions/images/filter/ -[`Filter`]: /methods/resource/filter/ - ## Example Mask @@ -78,3 +69,7 @@ Mask filterArgs="images/examples/mask.png" example=true >}} + +[`Filter`]: /methods/resource/filter/ +[`images.Filter`]: /functions/images/filter/ +[site configuration]: /configuration/imaging/ diff --git a/docs/content/en/functions/images/Opacity.md b/docs/content/en/functions/images/Opacity.md index 32b1bd23c..b9dcf3fd2 100644 --- a/docs/content/en/functions/images/Opacity.md +++ b/docs/content/en/functions/images/Opacity.md @@ -3,14 +3,11 @@ title: images.Opacity description: Returns an image filter that changes the opacity of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Opacity OPACITY] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Opacity OPACITY] --- {{< new-in 0.119.0 />}} @@ -25,7 +22,7 @@ Create the filter: {{ $filter := images.Opacity 0.65 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} The `images.Opacity` filter is most useful for target formats such as PNG and WebP that support transparency. If the source image does not support transparency, combine this filter with the `images.Process` filter: diff --git a/docs/content/en/functions/images/Overlay.md b/docs/content/en/functions/images/Overlay.md index d1cd7cf3f..8e5eec3d1 100644 --- a/docs/content/en/functions/images/Overlay.md +++ b/docs/content/en/functions/images/Overlay.md @@ -3,14 +3,11 @@ title: images.Overlay description: Returns an image filter that overlays the source image at the given coordinates, relative to the upper left corner. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Overlay RESOURCE X Y] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Overlay RESOURCE X Y] --- ## Usage @@ -35,7 +32,7 @@ Create the filter: {{ $filter := images.Overlay $overlay 20 20 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Padding.md b/docs/content/en/functions/images/Padding.md index e2c2695a1..da15a44ca 100644 --- a/docs/content/en/functions/images/Padding.md +++ b/docs/content/en/functions/images/Padding.md @@ -3,14 +3,11 @@ title: images.Padding description: Returns an image filter that resizes the image canvas without resizing the image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: ['images.Padding V1 [V2] [V3] [V4] [COLOR]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: ['images.Padding V1 [V2] [V3] [V4] [COLOR]'] --- {{< new-in 0.120.0 />}} @@ -28,7 +25,7 @@ Create the filter: {{ $filter := images.Padding 20 40 "#976941" }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} Combine with the [`Colors`] method to create a border with one of the image's most dominant colors: diff --git a/docs/content/en/functions/images/Pixelate.md b/docs/content/en/functions/images/Pixelate.md index 2016877ed..954950c8b 100644 --- a/docs/content/en/functions/images/Pixelate.md +++ b/docs/content/en/functions/images/Pixelate.md @@ -3,14 +3,11 @@ title: images.Pixelate description: Returns an image filter that applies a pixelation effect to an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Pixelate SIZE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Pixelate SIZE] --- ## Usage @@ -21,7 +18,7 @@ Create the filter: {{ $filter := images.Pixelate 4 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Process.md b/docs/content/en/functions/images/Process.md index 959770c65..134c40c5a 100644 --- a/docs/content/en/functions/images/Process.md +++ b/docs/content/en/functions/images/Process.md @@ -3,15 +3,11 @@ title: images.Process description: Returns an image filter that processes the given image using the given specification. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - - methods/resource/Process - returnType: images.filter - signatures: [images.Process SPEC] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Process SPEC] --- {{< new-in 0.119.0 />}} @@ -101,7 +97,7 @@ Create a filter: {{ $filter := images.Process "resize 256x q40 webp" }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/QR.md b/docs/content/en/functions/images/QR.md index e3f914fd1..eee2dff14 100644 --- a/docs/content/en/functions/images/QR.md +++ b/docs/content/en/functions/images/QR.md @@ -2,13 +2,11 @@ title: images.QR description: Encodes the given text into a QR code using the specified options, returning an image resource. keywords: [] -action: - aliases: [] - related: [] - returnType: images.ImageResource - signatures: ['images.QR TEXT [OPTIONS]'] -toc: true -math: true +params: + functions_and_methods: + aliases: [] + returnType: images.ImageResource + signatures: ['images.QR TEXT [OPTIONS]'] --- {{< new-in 0.141.0 />}} @@ -21,19 +19,17 @@ The `images.QR` function encodes the given text into a [QR code] using the speci Although the default option values are sufficient for most applications, you should test the rendered QR code both on-screen and in print. -[QR code]: https://en.wikipedia.org/wiki/QR_code - ## Options level : (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`. -Error correction level|Redundancy -:--|:--|:-- -low|20% -medium|38% -quartile|55% -high|65% + Error correction level|Redundancy + :--|:--|:-- + low|20% + medium|38% + quartile|55% + high|65% scale : (`int`) The number of image pixels per QR code module. Must be greater than or equal to `2`. Default is `4`. @@ -41,8 +37,6 @@ scale targetDir : (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image. Use Unix-style slashes (`/`) to separarate path segments. If empty or not provided, the image is placed directly in the `publishDir` root. Hugo automatically creates the necessary subdirectories if they don't exist. -[`publishDir`]: /getting-started/configuration/#publishdir - ## Examples To create a QR code using the default values for `level` and `scale`: @@ -74,7 +68,7 @@ Specify `level`, `scale`, and `targetDir` as needed to achieve the desired resul To include a QR code that points to the `Permalink` of the current page: -{{< code file=layouts/_default/single.html >}} +```go-html-template {file="layouts/_default/single.html"} {{ with images.QR .Permalink }} <img src="{{ .RelPermalink }}" @@ -85,7 +79,7 @@ To include a QR code that points to the `Permalink` of the current page: loading="lazy" > {{ end }} -{{< /code >}} +``` Then hide the QR code with CSS unless printing the page: @@ -116,9 +110,8 @@ If the QR code will be printed, use the default `scale` value of `4` pixels per Avoid using Hugo's image processing methods to resize QR codes. Resizing can introduce blurring due to anti-aliasing when a QR code module occupies a fractional number of pixels. -{{% note %}} -Always test the rendered QR code both on-screen and in print. -{{% /note %}} +> [!note] +> Always test the rendered QR code both on-screen and in print. ## Shortcode @@ -140,4 +133,6 @@ https://gohugo.io The `qr` shortcode accepts several arguments including `level` and `scale`. See the [related documentation] for details. +[`publishDir`]: /configuration/all/#publishdir +[QR code]: https://en.wikipedia.org/wiki/QR_code [related documentation]: /shortcodes/qr/ diff --git a/docs/content/en/functions/images/Saturation.md b/docs/content/en/functions/images/Saturation.md index 118bd0213..d1dd48b24 100644 --- a/docs/content/en/functions/images/Saturation.md +++ b/docs/content/en/functions/images/Saturation.md @@ -3,14 +3,11 @@ title: images.Saturation description: Returns an image filter that changes the saturation of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Saturation PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Saturation PERCENTAGE] --- The percentage must be in the range [-100, 500] where 0 has no effect. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Saturation 65 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Sepia.md b/docs/content/en/functions/images/Sepia.md index 9f0b7adfb..ae43045db 100644 --- a/docs/content/en/functions/images/Sepia.md +++ b/docs/content/en/functions/images/Sepia.md @@ -3,14 +3,11 @@ title: images.Sepia description: Returns an image filter that produces a sepia-toned version of an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Sepia PERCENTAGE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Sepia PERCENTAGE] --- The percentage must be in the range [0, 100] where 0 has no effect. @@ -23,7 +20,7 @@ Create the filter: {{ $filter := images.Sepia 75 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Sigmoid.md b/docs/content/en/functions/images/Sigmoid.md index 32765f923..9bfcaf91b 100644 --- a/docs/content/en/functions/images/Sigmoid.md +++ b/docs/content/en/functions/images/Sigmoid.md @@ -3,14 +3,11 @@ title: images.Sigmoid description: Returns an image filter that changes the contrast of an image using a sigmoidal function. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.Sigmoid MIDPOINT FACTOR] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.Sigmoid MIDPOINT FACTOR] --- This is a non-linear contrast change useful for photo adjustments; it preserves highlight and shadow detail. @@ -27,7 +24,7 @@ Create the filter: {{ $filter := images.Sigmoid 0.6 -4 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/Text.md b/docs/content/en/functions/images/Text.md index c8d23565c..94cdb4e9d 100644 --- a/docs/content/en/functions/images/Text.md +++ b/docs/content/en/functions/images/Text.md @@ -3,14 +3,11 @@ title: images.Text description: Returns an image filter that adds text to an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: ['images.Text TEXT [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: ['images.Text TEXT [OPTIONS]'] --- ## Options @@ -18,7 +15,7 @@ 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 />}} +: {{< 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 @@ -27,8 +24,6 @@ color 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 - linespacing : (`int`) The number of pixels between each line. For a line height of 1.4, set the `linespacing` to 0.4 multiplied by the `size`. Default is `2`. @@ -41,6 +36,8 @@ x y : (`int`) The vertical offset, in pixels, relative to the top of the image. Default is `10`. +[Go Regular]: https://go.dev/blog/go-fonts#sans-serif + ## Usage Set the text and paths: diff --git a/docs/content/en/functions/images/UnsharpMask.md b/docs/content/en/functions/images/UnsharpMask.md index 9ea58f2b6..9c06eb5e1 100644 --- a/docs/content/en/functions/images/UnsharpMask.md +++ b/docs/content/en/functions/images/UnsharpMask.md @@ -3,14 +3,11 @@ title: images.UnsharpMask description: Returns an image filter that sharpens an image. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/images/Filter - - methods/resource/Filter - returnType: images.filter - signatures: [images.UnsharpMask SIGMA AMOUNT THRESHOLD] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: images.filter + signatures: [images.UnsharpMask SIGMA AMOUNT THRESHOLD] --- The sigma argument is used in a gaussian function and affects the radius of effect. Sigma must be positive. The sharpen radius is approximately 3 times the sigma value. @@ -27,7 +24,7 @@ Create the filter: {{ $filter := images.UnsharpMask 10 0.4 0.03 }} ``` -{{% include "functions/images/_common/apply-image-filter.md" %}} +{{% include "/_common/functions/images/apply-image-filter.md" %}} ## Example diff --git a/docs/content/en/functions/images/_common/_index.md b/docs/content/en/functions/images/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/functions/images/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/functions/images/_common/apply-image-filter.md b/docs/content/en/functions/images/_common/apply-image-filter.md deleted file mode 100644 index 08e08238f..000000000 --- a/docs/content/en/functions/images/_common/apply-image-filter.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Apply the filter using the [`images.Filter`] function: - -[`images.Filter`]: /functions/images/filter/ - -```go-html-template -{{ with resources.Get "images/original.jpg" }} - {{ with . | images.Filter $filter }} - <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> - {{ end }} -{{ end }} -``` - -You can also apply the filter using the [`Filter`] method on a `Resource` object: - -[`Filter`]: /methods/resource/filter/ - -```go-html-template -{{ with resources.Get "images/original.jpg" }} - {{ with .Filter $filter }} - <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt=""> - {{ end }} -{{ end }} -``` diff --git a/docs/content/en/functions/images/_index.md b/docs/content/en/functions/images/_index.md index 13542ea73..f92e16e7a 100644 --- a/docs/content/en/functions/images/_index.md +++ b/docs/content/en/functions/images/_index.md @@ -4,9 +4,4 @@ linkTitle: images description: Use these functions to create an image filter, apply an image filter to an image, and to retrieve image information. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to create an image filter, apply an image filter to an image, and to retrieve image information. diff --git a/docs/content/en/functions/inflect/Humanize.md b/docs/content/en/functions/inflect/Humanize.md index 71b4a5fd2..d3d785243 100644 --- a/docs/content/en/functions/inflect/Humanize.md +++ b/docs/content/en/functions/inflect/Humanize.md @@ -3,13 +3,11 @@ title: inflect.Humanize description: Returns the humanized version of the input with the first letter capitalized. categories: [] keywords: [] -action: - aliases: [humanize] - related: - - functions/inflect/Pluralize - - functions/inflect/Singularize - returnType: string - signatures: [inflect.Humanize INPUT] +params: + functions_and_methods: + aliases: [humanize] + returnType: string + signatures: [inflect.Humanize INPUT] aliases: [/functions/humanize] --- diff --git a/docs/content/en/functions/inflect/Pluralize.md b/docs/content/en/functions/inflect/Pluralize.md index c25f89617..f168770d3 100644 --- a/docs/content/en/functions/inflect/Pluralize.md +++ b/docs/content/en/functions/inflect/Pluralize.md @@ -3,13 +3,11 @@ title: inflect.Pluralize description: Pluralizes the given word according to a set of common English pluralization rules. categories: [] keywords: [] -action: - aliases: [pluralize] - related: - - functions/inflect/Humanize - - functions/inflect/Singularize - returnType: string - signatures: [inflect.Pluralize INPUT] +params: + functions_and_methods: + aliases: [pluralize] + returnType: string + signatures: [inflect.Pluralize INPUT] aliases: [/functions/pluralize] --- diff --git a/docs/content/en/functions/inflect/Singularize.md b/docs/content/en/functions/inflect/Singularize.md index d2a8572f6..41e05b784 100644 --- a/docs/content/en/functions/inflect/Singularize.md +++ b/docs/content/en/functions/inflect/Singularize.md @@ -3,13 +3,11 @@ title: inflect.Singularize description: Singularizes the given word according to a set of common English singularization rules. categories: [] keywords: [] -action: - aliases: [singularize] - related: - - functions/inflect/Humanize - - functions/inflect/Pluralize - returnType: string - signatures: [inflect.Singularize INPUT] +params: + functions_and_methods: + aliases: [singularize] + returnType: string + signatures: [inflect.Singularize INPUT] aliases: [/functions/singularize] --- diff --git a/docs/content/en/functions/inflect/_index.md b/docs/content/en/functions/inflect/_index.md index 601b409e6..2afe4fe33 100644 --- a/docs/content/en/functions/inflect/_index.md +++ b/docs/content/en/functions/inflect/_index.md @@ -1,12 +1,7 @@ --- title: Inflect functions linkTitle: inflect -description: Template functions to inflect English nouns. +description: These functions provide word inflection features such as singularization and pluralization of English nouns. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -These functions provide word inflection features such as singularization and pluralization of English nouns. diff --git a/docs/content/en/functions/js/Babel.md b/docs/content/en/functions/js/Babel.md index 08bce47e5..d0007aaa0 100644 --- a/docs/content/en/functions/js/Babel.md +++ b/docs/content/en/functions/js/Babel.md @@ -3,17 +3,11 @@ title: js.Babel description: Compile the given JavaScript resource with Babel. categories: [] keywords: [] -action: - aliases: [babel] - related: - - functions/js/Batch - - functions/js/Build - - functions/resources/Fingerprint - - functions/resources/Minify - returnType: resource.Resource - signatures: ['js.Babel [OPTIONS] RESOURCE'] -weight: 30 -toc: true +params: + functions_and_methods: + aliases: [babel] + returnType: resource.Resource + signatures: ['js.Babel [OPTIONS] RESOURCE'] --- ```go-html-template @@ -37,18 +31,21 @@ toc: true ## Setup -Step 1 -: Install [Node.js](https://nodejs.org/en/download) +### Step 1 -Step 2 -: Install the required Node.js packages in the root of your project. +Install [Node.js](https://nodejs.org/en/download) + +### Step 2 + +Install the required Node.js packages in the root of your project. ```sh npm install --save-dev @babel/core @babel/cli ``` -Step 3 -: Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: +### Step 3 + +Add the babel executable to Hugo's `security.exec.allow` list in your site configuration: {{< code-toggle file=hugo >}} [security.exec] @@ -75,32 +72,28 @@ module.exports = { ## Options -###### compact - -(`bool`) Whether to remove optional newlines and whitespace. Enabled when `minified` is `true`. Default is `false` - -###### config - -(`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` file in the root of your project. See [details](https://babeljs.io/docs/en/configuration). - -###### minified - -(`bool`) Whether to minify the compiled code. Enables the `compact` option. Default is `false`. - -###### noBabelrc - -(`string`) Whether to ignore `.babelrc` and `.babelignore` files. Default is `false`. +compact +: (`bool`) Whether to remove optional newlines and whitespace. Enabled when `minified` is `true`. Default is `false` -###### noComments +config +: (`string`) Path to the Babel configuration file. Hugo will, by default, look for a `babel.config.js` file in the root of your project. See [details](https://babeljs.io/docs/en/configuration). -(`bool`) Whether to remove comments. Default is `false`. +minified +: (`bool`) Whether to minify the compiled code. Enables the `compact` option. Default is `false`. -###### sourceMap +noBabelrc +: (`string`) Whether to ignore `.babelrc` and `.babelignore` files. Default is `false`. -(`string`) Whether to generate source maps, one of `external`, `inline`, or `none`. Default is `none`. +noComments +: (`bool`) Whether to remove comments. Default is `false`. -<!-- In the above, technically "none" is not one of the enumerated values, but it has the same effect and is easier to document than an empty string. --> +sourceMap +: (`string`) Whether to generate source maps, one of `external`, `inline`, or `none`. Default is `none`. -###### verbose +verbose +: (`bool`) Whether to enable verbose logging. Default is `false` -(`bool`) Whether to enable verbose logging. Default is `false` +<!-- +In the above, technically "none" is not one of the enumerated sourceMap +values but it has the same effect and is easier to document than an empty string. +--> diff --git a/docs/content/en/functions/js/Batch.md b/docs/content/en/functions/js/Batch.md index 08913f61f..a2c8bb893 100644 --- a/docs/content/en/functions/js/Batch.md +++ b/docs/content/en/functions/js/Batch.md @@ -3,40 +3,33 @@ title: js.Batch description: Build JavaScript bundle groups with global code splitting and flexible hooks/runners setup. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/js/Build - - functions/js/Babel - - functions/resources/Fingerprint - - functions/resources/Minify - returnType: js.Batcher - signatures: ['js.Batch [ID]'] -weight: 20 -toc: true +params: + functions_and_methods: + aliases: [] + returnType: js.Batcher + signatures: ['js.Batch [ID]'] --- -{{% note %}} -For a runnable example of this feature, see [this test and demo repo](https://github.com/bep/hugojsbatchdemo/). -{{% /note %}} +> [!note] +> For a runnable example of this feature, see [this test and demo repo](https://github.com/bep/hugojsbatchdemo/). The Batch `ID` is used to create the base directory for this batch. Forward slashes are allowed. `js.Batch` returns an object with an API with this structure: -* [Group] - * [Script] - * [SetOptions] - * [Instance] - * [SetOptions] - * [Runner] - * [SetOptions] - * [Config] - * [SetOptions] +- [Group] + - [Script] + - [SetOptions] + - [Instance] + - [SetOptions] + - [Runner] + - [SetOptions] + - [Config] + - [SetOptions] ## Group The `Group` method take an `ID` (`string`) as argument. No slashes. It returns an object with these methods: -#### Script +### 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. @@ -50,9 +43,9 @@ The `Script` method takes an `ID` (`string`) as argument. No slashes. It returns {{ end }} ``` -`SetOptions` takes a [script options] map. Note that if you want the script to be handled by a [runner], you need to set the `export` option to match what you want to pass on to the runner (default is `*`). +`SetOptions` takes a [script options] map. Note that if you want the script to be handled by a [runner], you need to set the `export` option to match what you want to pass on to the runner (default is `*`). -#### Instance +### Instance The `Instance` method takes two `string` arguments `SCRIPT_ID` and `INSTANCE_ID`. No slashes. It returns an [OptionsSetter] that can be used to set [params options] for this instance. @@ -68,7 +61,7 @@ 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 +### 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. @@ -131,34 +124,34 @@ import * as ReactDOM from 'react-dom/client'; import * as React from 'react'; export default function Run(group) { - console.log('Running react-create-elements.js', group); - const scripts = group.scripts; - for (const script of scripts) { - for (const instance of script.instances) { - /* This is a convention in this project. */ - let elId = `${script.id}-${instance.id}`; - let el = document.getElementById(elId); - if (!el) { - console.warn(`Element with id ${elId} not found`); - continue; - } - const root = ReactDOM.createRoot(el); - const reactEl = React.createElement(script.binding, instance.params); - root.render(reactEl); - } - } + console.log('Running react-create-elements.js', group); + const scripts = group.scripts; + for (const script of scripts) { + for (const instance of script.instances) { + /* This is a convention in this project. */ + let elId = `${script.id}-${instance.id}`; + let el = document.getElementById(elId); + if (!el) { + console.warn(`Element with id ${elId} not found`); + continue; + } + const root = ReactDOM.createRoot(el); + const reactEl = React.createElement(script.binding, instance.params); + root.render(reactEl); + } + } } ``` -#### Config +### 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: -* `targetPath` is set automatically (there may be multiple outputs). -* `format` must be `esm`, currently the only format supporting [code splitting]. -* `params` will be available in the `@params/config` namespace in the scripts. This way you can import both the [script] or [runner] params and the [config] params with: +- `targetPath` is set automatically (there may be multiple outputs). +- ``format` must be `esm`, currently the only format supporting [code splitting]. +- ``params` will be available in the `@params/config` namespace in the scripts. This way you can import both the [script] or [runner] params and the [config] params with: ```js import * as params from "@params"; @@ -185,14 +178,14 @@ Setting the `Config` for a batch can be done from any template (including shortc ## Options -### Build Options +### Build options format -: (`string`) Currently only `esm` is supported in [ESBuild's code splitting]. +: (`string`) Currently only `esm` is supported in ESBuild's [code splitting]. -{{% include "./_common/options.md" %}} +{{% include "/_common/functions/js/options.md" %}} -### Script Options +### Script options resource : The resource to build. This can be a file resource or a virtual resource. @@ -205,18 +198,17 @@ importContext params : A map of parameters that will be passed to the script as JSON. These gets bound to the `@params` namespace: -```js -import * as params from '@params'; -``` -### Script Options + ```js + import * as params from '@params'; + ``` -### Params Options +### Params options params -: A map of parameters that will be passed to the script as JSON. +: A map of parameters that will be passed to the script as JSON. -### Import Context +### Import context Hugo will, by default, first try to resolve any import in [assets](/hugo-pipes/introduction/#asset-directory) and, if not found, let [ESBuild] resolve it (e.g. from `node_modules`). The `importContext` option can be used to set the first context for resolving imports. A common use of this is to resolve imports inside a [page bundle](/content-management/page-bundles/). @@ -243,20 +235,17 @@ An `OptionsSetter` is a special object that is returned once only. This means th The `Build` method returns an object with the following structure: -* Groups (map) - * [`Resources`] +- Groups (map) + - [`Resources`] -Eeach [`Resource`] will be of media type `application/javascript` or `text/css`. +Each [`Resource`] will be of media type `application/javascript` or `text/css`. - In a template you would typically handle one group with a given `ID` (e.g. scripts for the current section). Because of the concurrent build, this needs to be done in a [`templates.Defer`] block: +In a template you would typically handle one group with a given `ID` (e.g. scripts for the current section). Because of the concurrent build, this needs to be done in a [`templates.Defer`] block: -{{% note %}} -The [`templates.Defer`] acts as a synchronisation point to handle scripts added concurrently by different templates. If you have a setup with where the batch is created in one go (in one template), you don't need it. - -See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global-script/53002/5?u=bep) for more. - -[`templates.Defer`]: /functions/templates/defer/ -{{% /note %}} +> [!note] +> The [`templates.Defer`] acts as a synchronisation point to handle scripts added concurrently by different templates. If you have a setup with where the batch is created in one go (in one template), you don't need it. +> +> See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global-script/53002/5?u=bep) for more. ```go-html-template {{ $group := .group }} @@ -279,10 +268,10 @@ See [this discussion](https://discourse.gohugo.io/t/js-batch-with-simple-global- ## Known Issues -In the official documentation for [ESBuild's code splitting], there's a warning note in the header. The two issues are: +In the official documentation for ESBuild's [code splitting], there's a warning note in the header. The two issues are: -* `esm` is currently the only implemented output format. This means that it will not work for very old browsers. See [caniuse](https://caniuse.com/?search=ESM). -* There's a known import ordering issue. + - `esm` is currently the only implemented output format. This means that it will not work for very old browsers. See [caniuse](https://caniuse.com/?search=ESM). + - There's a known import ordering issue. 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: @@ -296,28 +285,23 @@ import './lib2.js'; import './lib1.js'; console.log('entrypoints-workaround.js'); - ``` -[build options]: #build-options [`Resource`]: /methods/resource/ -[`Resources`]: /methods/page/resources/ [`Resources.Mount`]: /methods/page/resources/#mount +[`Resources`]: /methods/page/resources/ +[`templates.Defer`]: /functions/templates/defer/ [`templates.Defer`]: /functions/templates/defer/ +[build options]: #build-options [code splitting]: https://esbuild.github.io/api/#splitting [config]: #config -[ESBuild's code splitting]: https://esbuild.github.io/api/#splitting [ESBuild]: https://github.com/evanw/esbuild -[group]: #group -[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/ -[map]: /functions/collections/dictionary/ [OptionsSetter]: #optionssetter -[page bundles]: /content-management/page-bundles/ [params options]: #params-options [runner]: #runner -[script options]: #script-options [script]: #script +[script options]: #script-options [SetOptions]: #optionssetter [with]: /functions/go-template/with/ diff --git a/docs/content/en/functions/js/Build.md b/docs/content/en/functions/js/Build.md index 9bdc2454a..1bec6b16f 100644 --- a/docs/content/en/functions/js/Build.md +++ b/docs/content/en/functions/js/Build.md @@ -3,17 +3,11 @@ title: js.Build description: Bundle, transpile, tree shake, and minify JavaScript resources. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/js/Batch - - functions/js/Babel - - functions/resources/Fingerprint - - functions/resources/Minify - returnType: resource.Resource - signatures: ['js.Build [OPTIONS] RESOURCE'] -weight: 10 -toc: true +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['js.Build [OPTIONS] RESOURCE'] --- The `js.Build` function uses the [evanw/esbuild] package to: @@ -24,8 +18,6 @@ The `js.Build` function uses the [evanw/esbuild] package to: - Minify - Create source maps -[evanw/esbuild]: https://github.com/evanw/esbuild - ```go-html-template {{ with resources.Get "js/main.js" }} {{ $opts := dict @@ -47,16 +39,13 @@ The `js.Build` function uses the [evanw/esbuild] package to: ## Options -###### targetPath - -(`string`) If not set, the source path will be used as the base target path. -Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. +targetPath +: (`string`) If not set, the source path will be used as the base target path. Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. -###### format +format +: (`string`) The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag. -(`string`) The output format. One of: `iife`, `cjs`, `esm`. Default is `iife`, a self-executing function, suitable for inclusion as a `<script>` tag. - -{{% include "./_common/options.md" %}} +{{% include "/_common/functions/js/options.md" %}} ## Import JS code from the assets directory @@ -99,7 +88,7 @@ And then in your JS file: import * as params from '@params'; ``` -Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/getting-started/configuration/#configure-build). +Hugo will, by default, generate a `assets/jsconfig.json` file that maps the imports. This is useful for navigation/intellisense help inside code editors, but if you don't need/want it, you can [turn it off](/configuration/build/). ## Node.js dependencies @@ -109,9 +98,8 @@ Any imports in a file outside `assets` or that does not resolve to a component i 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. -{{% /note %}} +> [!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. ## Examples @@ -129,3 +117,5 @@ Or with options: {{ $built := resources.Get "scripts/main.js" | js.Build $opts }} <script src="{{ $built.RelPermalink }}" defer></script> ``` + +[evanw/esbuild]: https://github.com/evanw/esbuild diff --git a/docs/content/en/functions/js/_common/_index.md b/docs/content/en/functions/js/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/functions/js/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/functions/js/_common/options.md b/docs/content/en/functions/js/_common/options.md deleted file mode 100644 index 0d6138a7b..000000000 --- a/docs/content/en/functions/js/_common/options.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -###### params - -(`map` or `slice`) Params that can be imported as JSON in your JS files, e.g. - -```go-html-template -{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }} -``` -And then in your JS file: - -```js -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. - -###### minify - -(`bool`) Let `js.Build` handle the minification. - -###### loaders - -{{< new-in 0.140.0 />}} - -(`map`) Configuring a loader for a given file type lets you load that file type with an import statement or a require call. For example configuring the .png file extension to use the data URL loader means importing a .png file gives you a data URLcontaining the contents of that image. Loaders available are `none`, `base64`, `binary`, `copy`, `css`, `dataurl`, `default`, `empty`, `file`, `global-css`, `js`, `json`, `jsx`, `local-css`, `text`, `ts`, `tsx`. See https://esbuild.github.io/api/#loader. - -###### inject - -(`slice`) This option allows you to automatically replace a global variable with an import from another file. The path names must be relative to `assets`. See https://esbuild.github.io/api/#inject. - -###### shims - -(`map`) This option allows swapping out a component with another. A common use case is to load dependencies like React from a CDN (with _shims_) when in production, but running with the full bundled `node_modules` dependency during development: - -```go-html-template -{{ $shims := dict "react" "js/shims/react.js" "react-dom" "js/shims/react-dom.js" }} -{{ $js = $js | js.Build dict "shims" $shims }} -``` - -The _shim_ files may look like these: - -```js -// js/shims/react.js -module.exports = window.React; -``` - -```js -// js/shims/react-dom.js -module.exports = window.ReactDOM; -``` - -With the above, these imports should work in both scenarios: - -```js -import * as React from 'react'; -import * as ReactDOM from 'react-dom/client'; -``` - -###### target - -(`string`) The language target. One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. Default is `esnext`. - -###### platform - -{{< new-in 0.140.0 />}} - -(`string`) One of `browser`, `node`, `neutral`. Default is `browser`. See https://esbuild.github.io/api/#platform. - -###### externals - -(`slice`) External dependencies. Use this to trim dependencies you know will never be executed. See https://esbuild.github.io/api/#external. - -###### defines - -(`map`) Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value. - -```go-html-template -{{ $defines := dict "process.env.NODE_ENV" `"development"` }} -``` - -##### drop - -Edit your source code before building to drop certain constructs: One of `debugger` or `console`. - -{{< new-in 0.144.0 />}} - -See https://esbuild.github.io/api/#drop - -###### sourceMap - -(`string`) Whether to generate `inline`, `linked` or `external` source maps from esbuild. Linked and external source maps will be written to the target with the output file name + ".map". When `linked` a `sourceMappingURL` will also be written to the output file. By default, source maps are not created. Note that the `linked` option was added in Hugo 0.140.0. - -###### 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. - -###### JSXImportSource - -{{< new-in 0.124.0 />}} - -(`string`) Which library to use to automatically import its JSX helper functions from. This only works if `JSX` is set to `automatic`. The specified library needs to be installed through npm and expose certain exports. See https://esbuild.github.io/api/#jsx-import-source. - -The combination of `JSX` and `JSXImportSource` is helpful if you want to use a non-React JSX library like Preact, e.g.: - -```go-html-template -{{ $js := resources.Get "js/main.jsx" | js.Build (dict "JSX" "automatic" "JSXImportSource" "preact") }} -``` - -With the above, you can use Preact components and JSX without having to manually import `h` and `Fragment` every time: - -```jsx -import { render } from 'preact'; - -const App = () => <>Hello world!</>; - -const container = document.getElementById('app'); -if (container) render(<App />, container); -``` diff --git a/docs/content/en/functions/js/_index.md b/docs/content/en/functions/js/_index.md index 3356e7c7b..d3557a2d3 100644 --- a/docs/content/en/functions/js/_index.md +++ b/docs/content/en/functions/js/_index.md @@ -1,12 +1,7 @@ --- title: JavaScript functions linkTitle: js -description: Template functions to work with JavaScript and TypeScript files. +description: Use these functions to work with JavaScript and TypeScript files. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with JavaScript and TypeScript files. diff --git a/docs/content/en/functions/lang/FormatAccounting.md b/docs/content/en/functions/lang/FormatAccounting.md index 70365c216..d2a1d76f6 100644 --- a/docs/content/en/functions/lang/FormatAccounting.md +++ b/docs/content/en/functions/lang/FormatAccounting.md @@ -3,19 +3,15 @@ title: lang.FormatAccounting description: Returns a currency representation of a number for the given currency and precision for the current language and region in accounting notation. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatCurrency - - functions/lang/FormatNumber - - functions/lang/FormatNumberCustom - - functions/lang/FormatPercent - returnType: string - signatures: [lang.FormatAccounting PRECISION CURRENCY NUMBER] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [lang.FormatAccounting PRECISION CURRENCY NUMBER] --- ```go-html-template {{ 512.5032 | lang.FormatAccounting 2 "NOK" }} → NOK512.50 ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} diff --git a/docs/content/en/functions/lang/FormatCurrency.md b/docs/content/en/functions/lang/FormatCurrency.md index bd83c2ec5..327413c07 100644 --- a/docs/content/en/functions/lang/FormatCurrency.md +++ b/docs/content/en/functions/lang/FormatCurrency.md @@ -3,19 +3,15 @@ title: lang.FormatCurrency description: Returns a currency representation of a number for the given currency and precision for the current language and region. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatAccounting - - functions/lang/FormatNumber - - functions/lang/FormatNumberCustom - - functions/lang/FormatPercent - returnType: string - signatures: [lang.FormatCurrency PRECISION CURRENCY NUMBER] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [lang.FormatCurrency PRECISION CURRENCY NUMBER] --- ```go-html-template {{ 512.5032 | lang.FormatCurrency 2 "USD" }} → $512.50 ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} diff --git a/docs/content/en/functions/lang/FormatNumber.md b/docs/content/en/functions/lang/FormatNumber.md index 597df742a..5bf37996a 100644 --- a/docs/content/en/functions/lang/FormatNumber.md +++ b/docs/content/en/functions/lang/FormatNumber.md @@ -3,19 +3,15 @@ title: lang.FormatNumber description: Returns a numeric representation of a number with the given precision for the current language and region. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatAccounting - - functions/lang/FormatCurrency - - functions/lang/FormatNumberCustom - - functions/lang/FormatPercent - returnType: string - signatures: [lang.FormatNumber PRECISION NUMBER] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [lang.FormatNumber PRECISION NUMBER] --- ```go-html-template {{ 512.5032 | lang.FormatNumber 2 }} → 512.50 ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} diff --git a/docs/content/en/functions/lang/FormatNumberCustom.md b/docs/content/en/functions/lang/FormatNumberCustom.md index 603f42087..0a70cd938 100644 --- a/docs/content/en/functions/lang/FormatNumberCustom.md +++ b/docs/content/en/functions/lang/FormatNumberCustom.md @@ -3,15 +3,11 @@ title: lang.FormatNumberCustom description: Returns a numeric representation of a number with the given precision using negative, decimal, and grouping options. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatAccounting - - functions/lang/FormatCurrency - - functions/lang/FormatNumber - - functions/lang/FormatPercent - returnType: string - signatures: ['lang.FormatNumberCustom PRECISION NUMBER [OPTIONS...]'] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: ['lang.FormatNumberCustom PRECISION NUMBER [OPTIONS...]'] aliases: ['/functions/numfmt/'] --- @@ -29,6 +25,6 @@ For a simpler function that adapts to the current language, see [`lang.FormatNum {{ lang.FormatNumberCustom 0 -12345.6789 "-|.| " "|" }} → -12 346 ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} [`lang.FormatNumber`]: /functions/lang/formatnumber/ diff --git a/docs/content/en/functions/lang/FormatPercent.md b/docs/content/en/functions/lang/FormatPercent.md index 529ada67b..aef1fb64c 100644 --- a/docs/content/en/functions/lang/FormatPercent.md +++ b/docs/content/en/functions/lang/FormatPercent.md @@ -3,19 +3,15 @@ title: lang.FormatPercent description: Returns a percentage representation of a number with the given precision for the current language and region. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/lang/FormatAccounting - - functions/lang/FormatCurrency - - functions/lang/FormatNumber - - functions/lang/FormatNumberCustom - returnType: string - signatures: [lang.FormatPercent PRECISION NUMBER] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [lang.FormatPercent PRECISION NUMBER] --- ```go-html-template {{ 512.5032 | lang.FormatPercent 2 }} → 512.50% ``` -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} diff --git a/docs/content/en/functions/lang/Merge.md b/docs/content/en/functions/lang/Merge.md index 75f5cdf01..db40c2669 100644 --- a/docs/content/en/functions/lang/Merge.md +++ b/docs/content/en/functions/lang/Merge.md @@ -3,11 +3,11 @@ title: lang.Merge description: Merge missing translations from other languages. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: any - signatures: [lang.Merge FROM TO] +params: + functions_and_methods: + aliases: [] + returnType: any + signatures: [lang.Merge FROM TO] aliases: [/functions/lang.merge] --- diff --git a/docs/content/en/functions/lang/Translate.md b/docs/content/en/functions/lang/Translate.md index 48c1345e2..00bb0e3f3 100644 --- a/docs/content/en/functions/lang/Translate.md +++ b/docs/content/en/functions/lang/Translate.md @@ -3,31 +3,24 @@ title: lang.Translate description: Translates a string using the translation tables in the i18n directory. categories: [] keywords: [] -action: - aliases: [T, i18n] - related: [] - returnType: string - signatures: ['lang.Translate KEY [CONTEXT]'] -toc: true +params: + functions_and_methods: + aliases: [T, i18n] + returnType: string + signatures: ['lang.Translate KEY [CONTEXT]'] aliases: [/functions/i18n] --- -The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language. +The `lang.Translate` function returns the value associated with given key as defined in the translation table for the current language. If the key is not found in the translation table for the current language, the `lang.Translate` function falls back to the translation table for the [`defaultContentLanguage`]. -[`defaultContentLanguage`]: /getting-started/configuration/#defaultcontentlanguage - If the key is not found in the translation table for the `defaultContentLanguage`, the `lang.Translate` function returns an empty string. -{{% note %}} -To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site. - -To render placeholders for missing and fallback translations, set -[`enableMissingTranslationPlaceholders`] to `true` in your site configuration. - -[`enableMissingTranslationPlaceholders`]: /getting-started/configuration/#enablemissingtranslationplaceholders -{{% /note %}} +> [!note] +> To list missing and fallback translations, use the `--printI18nWarnings` flag when building your site. +> +> To render placeholders for missing and fallback translations, set [`enableMissingTranslationPlaceholders`] to `true` in your site configuration. ## Translation tables @@ -38,7 +31,7 @@ i18n/en.toml i18n/en-US.toml ``` -The base name must match the language key as defined in your site configuration. +The base name must match the [language key] as defined in your site configuration. Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. You may omit the `art-x-` prefix for brevity. For example: @@ -47,10 +40,8 @@ i18n/art-x-hugolang.toml i18n/hugolang.toml ``` -Private use subtags must not exceed 8 alphanumeric characters. - -[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 -[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 +> [!note] +> Private use subtags must not exceed 8 alphanumeric characters. ## Simple translations @@ -76,9 +67,8 @@ privacy = 'prywatność' security = 'bezpieczeństwo' {{< /code-toggle >}} -{{% note %}} -The examples below use the `T` alias for brevity. -{{% /note %}} +> [!note] +> The examples below use the `T` alias for brevity. When viewing the English language site: @@ -106,8 +96,6 @@ i18n/ The Unicode [CLDR Plural Rules chart] describes the pluralization categories for each language. -[CLDR Plural Rules chart]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html - The English translation table: {{< code-toggle file=i18n/en >}} @@ -136,9 +124,8 @@ many = '{{ . }} miesięcy' other = '{{ . }} miesiąca' {{< /code-toggle >}} -{{% note %}} -The examples below use the `T` alias for brevity. -{{% /note %}} +> [!note] +> The examples below use the `T` alias for brevity. When viewing the English language site: @@ -185,16 +172,13 @@ Template code: {{ T "age" (dict "name" "John" "count" 3) }} → John is 3 years old. ``` -{{% note %}} -Translation tables may contain both simple translations and translations with pluralization. -{{% /note %}} +> [!note] +> Translation tables may contain both simple translations and translations with pluralization. ## Reserved keys Hugo uses the [go-i18n] package to look up values in translation tables. This package reserves the following keys for internal use: -[go-i18n]: https://github.com/nicksnyder/go-i18n - id : (`string`) Uniquely identifies the message. @@ -228,8 +212,6 @@ many other : (`string`) The content of the message for the [CLDR] plural form "other". -[CLDR]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html - If you need to provide a translation for one of the reserved keys, you can prepend the word with an underscore. For example: {{< code-toggle file=i18n/es >}} @@ -253,3 +235,12 @@ Then in your templates: {{ T "_zero" }} → cero {{ T "_other" }} → otro ``` + +[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage +[`enableMissingTranslationPlaceholders`]: /configuration/all/#enablemissingtranslationplaceholders +[CLDR]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html +[CLDR Plural Rules chart]: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html +[go-i18n]: https://github.com/nicksnyder/go-i18n +[language key]: /configuration/languages/#language-keys +[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646 +[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 diff --git a/docs/content/en/functions/lang/_index.md b/docs/content/en/functions/lang/_index.md index 934d97bff..de75cad45 100644 --- a/docs/content/en/functions/lang/_index.md +++ b/docs/content/en/functions/lang/_index.md @@ -1,12 +1,7 @@ --- title: Lang functions linkTitle: lang -description: Template functions to adapt your site to meet language and regional requirements. +description: Use these functions to adapt your site to meet language and regional requirements. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to adapt your site to meet language and regional requirements. diff --git a/docs/content/en/functions/math/Abs.md b/docs/content/en/functions/math/Abs.md index 6e907d564..60d8d6d64 100644 --- a/docs/content/en/functions/math/Abs.md +++ b/docs/content/en/functions/math/Abs.md @@ -3,11 +3,11 @@ title: math.Abs description: Returns the absolute value of the given number. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: float64 - signatures: [math.Abs VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Abs VALUE] --- ```go-html-template diff --git a/docs/content/en/functions/math/Acos.md b/docs/content/en/functions/math/Acos.md index abdae4f74..32537e2dd 100644 --- a/docs/content/en/functions/math/Acos.md +++ b/docs/content/en/functions/math/Acos.md @@ -3,18 +3,11 @@ title: math.Acos description: Returns the arccosine, in radians, of the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Asin - - functions/math/Atan - - functions/math/Atan2 - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - returnType: float64 - signatures: [math.Acos VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Acos VALUE] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/Add.md b/docs/content/en/functions/math/Add.md index 25de514e0..cd137c6c7 100644 --- a/docs/content/en/functions/math/Add.md +++ b/docs/content/en/functions/math/Add.md @@ -3,16 +3,11 @@ title: math.Add description: Adds two or more numbers. categories: [] keywords: [] -action: - aliases: [add] - related: - - functions/math/Div - - functions/math/Mul - - functions/math/Product - - functions/math/Sub - - functions/math/Sum - returnType: any - signatures: [math.Add VALUE VALUE...] +params: + functions_and_methods: + aliases: [add] + returnType: any + signatures: [math.Add VALUE VALUE...] --- If one of the numbers is a [`float`](g), the result is a `float`. diff --git a/docs/content/en/functions/math/Asin.md b/docs/content/en/functions/math/Asin.md index 0496a1b45..76114a72e 100644 --- a/docs/content/en/functions/math/Asin.md +++ b/docs/content/en/functions/math/Asin.md @@ -3,18 +3,11 @@ title: math.Asin description: Returns the arcsine, in radians, of the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - returnType: float64 - signatures: [math.Asin VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Asin VALUE] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/Atan.md b/docs/content/en/functions/math/Atan.md index 942b3d2f2..5c8268b47 100644 --- a/docs/content/en/functions/math/Atan.md +++ b/docs/content/en/functions/math/Atan.md @@ -3,18 +3,11 @@ title: math.Atan description: Returns the arctangent, in radians, of the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Atan2 - - functions/math/Asin - - functions/math/Acos - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - returnType: float64 - signatures: [math.Atan VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Atan VALUE] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/Atan2.md b/docs/content/en/functions/math/Atan2.md index efa13b166..942fffdf8 100644 --- a/docs/content/en/functions/math/Atan2.md +++ b/docs/content/en/functions/math/Atan2.md @@ -3,18 +3,11 @@ title: math.Atan2 description: Returns the arctangent, in radians, of the given number pair, determining the correct quadrant from their signs. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Atan - - functions/math/Asin - - functions/math/Acos - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - returnType: float64 - signatures: [math.Atan2 VALUE VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Atan2 VALUE VALUE] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/Ceil.md b/docs/content/en/functions/math/Ceil.md index 9f74991c3..22a9d0299 100644 --- a/docs/content/en/functions/math/Ceil.md +++ b/docs/content/en/functions/math/Ceil.md @@ -3,13 +3,11 @@ title: math.Ceil description: Returns the least integer value greater than or equal to the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Floor - - functions/math/Round - returnType: float64 - signatures: [math.Ceil VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Ceil VALUE] --- ```go-html-template diff --git a/docs/content/en/functions/math/Cos.md b/docs/content/en/functions/math/Cos.md index 3291b24f8..249a064bb 100644 --- a/docs/content/en/functions/math/Cos.md +++ b/docs/content/en/functions/math/Cos.md @@ -3,18 +3,11 @@ title: math.Cos description: Returns the cosine of the given radian number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Pi - - functions/math/Sin - - functions/math/Tan - - functions/math/Asin - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - returnType: float64 - signatures: [math.Cos VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Cos VALUE] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/Counter.md b/docs/content/en/functions/math/Counter.md index 457806b8e..16456cec6 100644 --- a/docs/content/en/functions/math/Counter.md +++ b/docs/content/en/functions/math/Counter.md @@ -3,11 +3,11 @@ title: math.Counter description: Increments and returns a global counter. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: uint64 - signatures: [math.Counter] +params: + functions_and_methods: + aliases: [] + returnType: uint64 + signatures: [math.Counter] --- The counter is global for both monolingual and multilingual sites, and its initial value for each build is 1. @@ -27,9 +27,7 @@ Use this function to: - Create unique warnings as shown above; the [`warnf`] function suppresses duplicate messages - Create unique target paths for the `resources.FromString` function where the target path is also the cache key -[`warnf`]: /functions/fmt/warnf/ -[`resources.FromString`]: /functions/resources/fromstring/ +> [!note] +> Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page. -{{% note %}} -Due to concurrency, the value returned in a given template for a given page will vary from one build to the next. You cannot use this function to assign a static id to each page. -{{% /note %}} +[`warnf`]: /functions/fmt/warnf/ diff --git a/docs/content/en/functions/math/Div.md b/docs/content/en/functions/math/Div.md index b9f7a0a53..0e338a9e9 100644 --- a/docs/content/en/functions/math/Div.md +++ b/docs/content/en/functions/math/Div.md @@ -3,16 +3,11 @@ title: math.Div description: Divides the first number by one or more numbers. categories: [] keywords: [] -action: - aliases: [div] - related: - - functions/math/Add - - functions/math/Mul - - functions/math/Product - - functions/math/Sub - - functions/math/Sum - returnType: any - signatures: [math.Div VALUE VALUE...] +params: + functions_and_methods: + aliases: [div] + returnType: any + signatures: [math.Div VALUE VALUE...] --- If one of the numbers is a [`float`](g), the result is a `float`. diff --git a/docs/content/en/functions/math/Floor.md b/docs/content/en/functions/math/Floor.md index 10ad758b6..dbfd8620e 100644 --- a/docs/content/en/functions/math/Floor.md +++ b/docs/content/en/functions/math/Floor.md @@ -3,13 +3,11 @@ title: math.Floor description: Returns the greatest integer value less than or equal to the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Ceil - - functions/math/Round - returnType: float64 - signatures: [math.Floor VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Floor VALUE] --- ```go-html-template diff --git a/docs/content/en/functions/math/Log.md b/docs/content/en/functions/math/Log.md index 84edcb288..123ffacd7 100644 --- a/docs/content/en/functions/math/Log.md +++ b/docs/content/en/functions/math/Log.md @@ -3,11 +3,11 @@ title: math.Log description: Returns the natural logarithm of the given number. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: float64 - signatures: [math.Log VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Log VALUE] --- ```go-html-template diff --git a/docs/content/en/functions/math/Max.md b/docs/content/en/functions/math/Max.md index 9beff5630..d3a7676fc 100644 --- a/docs/content/en/functions/math/Max.md +++ b/docs/content/en/functions/math/Max.md @@ -3,12 +3,11 @@ title: math.Max description: Returns the greater of all numbers. Accepts scalars, slices, or both. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Min - returnType: float64 - signatures: [math.Max VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Max VALUE...] --- ```go-html-template diff --git a/docs/content/en/functions/math/Min.md b/docs/content/en/functions/math/Min.md index 79e464c74..4f7d7b85a 100644 --- a/docs/content/en/functions/math/Min.md +++ b/docs/content/en/functions/math/Min.md @@ -3,12 +3,11 @@ title: math.Min description: Returns the smaller of all numbers. Accepts scalars, slices, or both. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Max - returnType: float64 - signatures: [math.Min VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Min VALUE...] --- ```go-html-template diff --git a/docs/content/en/functions/math/Mod.md b/docs/content/en/functions/math/Mod.md index d312730c5..6035a361e 100644 --- a/docs/content/en/functions/math/Mod.md +++ b/docs/content/en/functions/math/Mod.md @@ -3,12 +3,11 @@ title: math.Mod description: Returns the modulus of two integers. categories: [] keywords: [] -action: - aliases: [mod] - related: - - functions/math/ModBool - returnType: int64 - signatures: [math.Mod VALUE1 VALUE2] +params: + functions_and_methods: + aliases: [mod] + returnType: int64 + signatures: [math.Mod VALUE1 VALUE2] --- ```go-html-template diff --git a/docs/content/en/functions/math/ModBool.md b/docs/content/en/functions/math/ModBool.md index d915ff614..fc7813d67 100644 --- a/docs/content/en/functions/math/ModBool.md +++ b/docs/content/en/functions/math/ModBool.md @@ -3,12 +3,11 @@ title: math.ModBool description: Reports whether the modulus of two integers equals 0. categories: [] keywords: [] -action: - aliases: [modBool] - related: - - functions/math/Mod - returnType: bool - signatures: [math.ModBool VALUE1 VALUE2] +params: + functions_and_methods: + aliases: [modBool] + returnType: bool + signatures: [math.ModBool VALUE1 VALUE2] --- ```go-html-template diff --git a/docs/content/en/functions/math/Mul.md b/docs/content/en/functions/math/Mul.md index bc143c5ef..69f2dbe1b 100644 --- a/docs/content/en/functions/math/Mul.md +++ b/docs/content/en/functions/math/Mul.md @@ -3,16 +3,11 @@ title: math.Mul description: Multiplies two or more numbers. categories: [] keywords: [] -action: - aliases: [mul] - related: - - functions/math/Add - - functions/math/Div - - functions/math/Product - - functions/math/Sub - - functions/math/Sum - returnType: any - signatures: [math.Mul VALUE VALUE...] +params: + functions_and_methods: + aliases: [mul] + returnType: any + signatures: [math.Mul VALUE VALUE...] --- If one of the numbers is a [`float`](g), the result is a `float`. diff --git a/docs/content/en/functions/math/Pi.md b/docs/content/en/functions/math/Pi.md index f2cf92c7a..0bc74bf03 100644 --- a/docs/content/en/functions/math/Pi.md +++ b/docs/content/en/functions/math/Pi.md @@ -3,18 +3,11 @@ title: math.Pi description: Returns the mathematical constant pi. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Sin - - functions/math/Cos - - functions/math/Tan - - functions/math/Asin - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - returnType: float64 - signatures: [math.Pi] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Pi] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/Pow.md b/docs/content/en/functions/math/Pow.md index 5a1482d73..a4384305d 100644 --- a/docs/content/en/functions/math/Pow.md +++ b/docs/content/en/functions/math/Pow.md @@ -3,12 +3,11 @@ title: math.Pow description: Returns the first number raised to the power of the second number. categories: [] keywords: [] -action: - aliases: [pow] - related: - - functions/math/Sqrt - returnType: float64 - signatures: [math.Pow VALUE1 VALUE2] +params: + functions_and_methods: + aliases: [pow] + returnType: float64 + signatures: [math.Pow VALUE1 VALUE2] --- ```go-html-template diff --git a/docs/content/en/functions/math/Product.md b/docs/content/en/functions/math/Product.md index 1809c560d..ffb1afe46 100644 --- a/docs/content/en/functions/math/Product.md +++ b/docs/content/en/functions/math/Product.md @@ -3,20 +3,13 @@ title: math.Product description: Returns the product of all numbers. Accepts scalars, slices, or both. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Add - - functions/math/Div - - functions/math/Mul - - functions/math/Sub - - functions/math/Sum - returnType: float64 - signatures: [math.Product VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Product VALUE...] --- -{{< new-in 0.114.0 />}} - ```go-html-template {{ math.Product 1 (slice 2 3) 4 }} → 24 ``` diff --git a/docs/content/en/functions/math/Rand.md b/docs/content/en/functions/math/Rand.md index cae6455c0..d659e651f 100644 --- a/docs/content/en/functions/math/Rand.md +++ b/docs/content/en/functions/math/Rand.md @@ -3,11 +3,11 @@ title: math.Rand description: Returns a pseudo-random number in the half-open interval [0.0, 1.0). categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: float64 - signatures: [math.Rand] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Rand] --- {{< new-in 0.121.2 />}} diff --git a/docs/content/en/functions/math/Round.md b/docs/content/en/functions/math/Round.md index e0678eb78..6bc015ce7 100644 --- a/docs/content/en/functions/math/Round.md +++ b/docs/content/en/functions/math/Round.md @@ -3,13 +3,11 @@ title: math.Round description: Returns the nearest integer, rounding half away from zero. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Ceil - - functions/math/Floor - returnType: float64 - signatures: [math.Round VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Round VALUE] --- ```go-html-template diff --git a/docs/content/en/functions/math/Sin.md b/docs/content/en/functions/math/Sin.md index 37936d714..b5ab86bb8 100644 --- a/docs/content/en/functions/math/Sin.md +++ b/docs/content/en/functions/math/Sin.md @@ -3,18 +3,11 @@ title: math.Sin description: Returns the sine of the given radian number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Pi - - functions/math/Cos - - functions/math/Tan - - functions/math/Asin - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - returnType: float64 - signatures: [math.Sin VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Sin VALUE] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/Sqrt.md b/docs/content/en/functions/math/Sqrt.md index 436cb31c3..b2f49fdbd 100644 --- a/docs/content/en/functions/math/Sqrt.md +++ b/docs/content/en/functions/math/Sqrt.md @@ -3,12 +3,11 @@ title: math.Sqrt description: Returns the square root of the given number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Pow - returnType: float64 - signatures: [math.Sqrt VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Sqrt VALUE] --- ```go-html-template diff --git a/docs/content/en/functions/math/Sub.md b/docs/content/en/functions/math/Sub.md index 9f211ef1b..49459cd71 100644 --- a/docs/content/en/functions/math/Sub.md +++ b/docs/content/en/functions/math/Sub.md @@ -1,18 +1,13 @@ --- title: math.Sub -description: Subtracts one or more numbers from the first number. +description: Subtracts one or more numbers from the first number. categories: [] keywords: [] -action: - aliases: [sub] - related: - - functions/math/Add - - functions/math/Div - - functions/math/Mul - - functions/math/Product - - functions/math/Sum - returnType: any - signatures: [math.Sub VALUE VALUE...] +params: + functions_and_methods: + aliases: [sub] + returnType: any + signatures: [math.Sub VALUE VALUE...] --- If one of the numbers is a [`float`](g), the result is a `float`. diff --git a/docs/content/en/functions/math/Sum.md b/docs/content/en/functions/math/Sum.md index 5cf882bee..e14bc924b 100644 --- a/docs/content/en/functions/math/Sum.md +++ b/docs/content/en/functions/math/Sum.md @@ -2,20 +2,13 @@ title: math.Sum description: Returns the sum of all numbers. Accepts scalars, slices, or both. categories: [] -action: - aliases: [] - related: - - functions/math/Add - - functions/math/Div - - functions/math/Mul - - functions/math/Product - - functions/math/Sub - returnType: float64 - signatures: [math.Sum VALUE...] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Sum VALUE...] --- -{{< new-in 0.114.0 />}} - ```go-html-template {{ math.Sum 1 (slice 2 3) 4 }} → 10 ``` diff --git a/docs/content/en/functions/math/Tan.md b/docs/content/en/functions/math/Tan.md index a8691fbca..c4f861c05 100644 --- a/docs/content/en/functions/math/Tan.md +++ b/docs/content/en/functions/math/Tan.md @@ -3,18 +3,11 @@ title: math.Tan description: Returns the tangent of the given radian number. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/Pi - - functions/math/Sin - - functions/math/Cos - - functions/math/Asin - - functions/math/Acos - - functions/math/Atan - - functions/math/Atan2 - returnType: float64 - signatures: [math.Tan VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.Tan VALUE] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/ToDegrees.md b/docs/content/en/functions/math/ToDegrees.md index 54473be72..f01cd4728 100644 --- a/docs/content/en/functions/math/ToDegrees.md +++ b/docs/content/en/functions/math/ToDegrees.md @@ -3,13 +3,11 @@ title: math.ToDegrees description: ToDegrees converts radians into degrees. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/ToRadians - - functions/math/Pi - returnType: float64 - signatures: [math.ToDegrees VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.ToDegrees VALUE] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/ToRadians.md b/docs/content/en/functions/math/ToRadians.md index c587c023c..b5acbb65b 100644 --- a/docs/content/en/functions/math/ToRadians.md +++ b/docs/content/en/functions/math/ToRadians.md @@ -3,13 +3,11 @@ title: math.ToRadians description: ToRadians converts degrees into radians. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/math/ToDegrees - - functions/math/Pi - returnType: float64 - signatures: [math.ToRadians VALUE] +params: + functions_and_methods: + aliases: [] + returnType: float64 + signatures: [math.ToRadians VALUE] --- {{< new-in 0.130.0 />}} diff --git a/docs/content/en/functions/math/_index.md b/docs/content/en/functions/math/_index.md index 76713bc99..c58a5a704 100644 --- a/docs/content/en/functions/math/_index.md +++ b/docs/content/en/functions/math/_index.md @@ -1,11 +1,6 @@ --- title: Math functions linkTitle: math -description: Template functions to perform mathematical operations. +description: Use these functions to perform mathematical operations. categories: [] -menu: - docs: - parent: functions --- - -Use these functions to perform mathematical operations. diff --git a/docs/content/en/functions/openapi3/Unmarshal.md b/docs/content/en/functions/openapi3/Unmarshal.md index 6ee1519e5..d1f928aeb 100644 --- a/docs/content/en/functions/openapi3/Unmarshal.md +++ b/docs/content/en/functions/openapi3/Unmarshal.md @@ -3,11 +3,11 @@ title: openapi3.Unmarshal description: Unmarshals the given resource into an OpenAPI 3 document. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: openapi3.OpenAPIDocument - signatures: ['openapi3.Unmarshal RESOURCE'] +params: + functions_and_methods: + aliases: [] + returnType: openapi3.OpenAPIDocument + signatures: ['openapi3.Unmarshal RESOURCE'] --- Use the `openapi3.Unmarshal` function with [global resources](g), [page resources](g), or [remote resources](g). diff --git a/docs/content/en/functions/openapi3/_index.md b/docs/content/en/functions/openapi3/_index.md index 9b6aa9584..852daf7b5 100644 --- a/docs/content/en/functions/openapi3/_index.md +++ b/docs/content/en/functions/openapi3/_index.md @@ -1,12 +1,7 @@ --- title: OpenAPI functions linkTitle: openapi3 -description: Template functions to work with OpenAPI 3 definitions. +description: Use these functions to work with OpenAPI 3 definitions. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with OpenAPI 3 definitions. diff --git a/docs/content/en/functions/os/FileExists.md b/docs/content/en/functions/os/FileExists.md index b8104a066..b8a01a3e7 100644 --- a/docs/content/en/functions/os/FileExists.md +++ b/docs/content/en/functions/os/FileExists.md @@ -3,19 +3,15 @@ title: os.FileExists description: Reports whether the file or directory exists. categories: [] keywords: [] -action: - aliases: [fileExists] - related: - - functions/os/Getenv - - functions/os/ReadDir - - functions/os/ReadFile - - functions/os/Stat - returnType: bool - signatures: [os.FileExists PATH] +params: + functions_and_methods: + aliases: [fileExists] + returnType: bool + signatures: [os.FileExists PATH] aliases: [/functions/fileexists] --- -The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional. +The `os.FileExists` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional. With this directory structure: diff --git a/docs/content/en/functions/os/Getenv.md b/docs/content/en/functions/os/Getenv.md index 2b7a08881..04215e6c3 100644 --- a/docs/content/en/functions/os/Getenv.md +++ b/docs/content/en/functions/os/Getenv.md @@ -3,17 +3,12 @@ title: os.Getenv description: Returns the value of an environment variable, or an empty string if the environment variable is not set. categories: [] keywords: [] -action: - aliases: [getenv] - related: - - functions/os/FileExists - - functions/os/ReadDir - - functions/os/ReadFile - - functions/os/Stat - returnType: string - signatures: [os.Getenv VARIABLE] +params: + functions_and_methods: + aliases: [getenv] + returnType: string + signatures: [os.Getenv VARIABLE] aliases: [/functions/getenv] -toc: true --- ## Security @@ -30,9 +25,7 @@ To access other environment variables, adjust your site configuration. For examp getenv = ['^HUGO_', '^CI$', '^USER$', '^HOME$'] {{< /code-toggle >}} -Read more about Hugo's [security policy]. - -[security policy]: /about/security/#security-policy +For more information see [configure security](/configuration/security). ## Examples diff --git a/docs/content/en/functions/os/ReadDir.md b/docs/content/en/functions/os/ReadDir.md index f4a5389d9..65c398a31 100644 --- a/docs/content/en/functions/os/ReadDir.md +++ b/docs/content/en/functions/os/ReadDir.md @@ -3,15 +3,11 @@ title: os.ReadDir description: Returns an array of FileInfo structures sorted by file name, one element for each directory entry. categories: [] keywords: [] -action: - aliases: [readDir] - related: - - functions/os/FileExists - - functions/os/Getenv - - functions/os/ReadFile - - functions/os/Stat - returnType: os.FileInfo - signatures: [os.ReadDir PATH] +params: + functions_and_methods: + aliases: [readDir] + returnType: os.FileInfo + signatures: [os.ReadDir PATH] aliases: [/functions/readdir] --- diff --git a/docs/content/en/functions/os/ReadFile.md b/docs/content/en/functions/os/ReadFile.md index 5e733ef2d..7f25327c8 100644 --- a/docs/content/en/functions/os/ReadFile.md +++ b/docs/content/en/functions/os/ReadFile.md @@ -3,19 +3,15 @@ title: os.ReadFile description: Returns the contents of a file. categories: [] keywords: [] -action: - aliases: [readFile] - related: - - functions/os/FileExists - - functions/os/Getenv - - functions/os/ReadDir - - functions/os/Stat - returnType: string - signatures: [os.ReadFile PATH] +params: + functions_and_methods: + aliases: [readFile] + returnType: string + signatures: [os.ReadFile PATH] aliases: [/functions/readfile] --- -The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional. +The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional. With a file named README.md in the root of your project directory: diff --git a/docs/content/en/functions/os/Stat.md b/docs/content/en/functions/os/Stat.md index 6b6f668de..63cb3f26a 100644 --- a/docs/content/en/functions/os/Stat.md +++ b/docs/content/en/functions/os/Stat.md @@ -3,19 +3,15 @@ title: os.Stat description: Returns a FileInfo structure describing a file or directory. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/os/FileExists - - functions/os/Getenv - - functions/os/ReadDir - - functions/os/ReadFile - returnType: os.FileInfo - signatures: [os.Stat PATH] +params: + functions_and_methods: + aliases: [] + returnType: os.FileInfo + signatures: [os.Stat PATH] aliases: [/functions/os.stat] --- -The `os.Stat` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional. +The `os.Stat` function attempts to resolve the path relative to the root of your project directory. If a matching file or directory is not found, it will attempt to resolve the path relative to the [`contentDir`](/configuration/all/#contentdir). A leading path separator (`/`) is optional. ```go-html-template {{ $f := os.Stat "README.md" }} diff --git a/docs/content/en/functions/os/_index.md b/docs/content/en/functions/os/_index.md index c080d0092..b125f7004 100644 --- a/docs/content/en/functions/os/_index.md +++ b/docs/content/en/functions/os/_index.md @@ -1,12 +1,7 @@ --- title: OS functions linkTitle: os -description: Template functions to interact with the operating system. +description: Use these functions to interact with the operating system. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to interact with the operating system. diff --git a/docs/content/en/functions/partials/Include.md b/docs/content/en/functions/partials/Include.md index aa93b4090..eb7eeafdc 100644 --- a/docs/content/en/functions/partials/Include.md +++ b/docs/content/en/functions/partials/Include.md @@ -3,15 +3,11 @@ title: partials.Include description: Executes the given partial template, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output. categories: [] keywords: [] -action: - aliases: [partial] - related: - - functions/go-template/return - - functions/partials/IncludeCached - - functions/go-template/template - - methods/page/Render - returnType: any - signatures: ['partials.Include NAME [CONTEXT]'] +params: + functions_and_methods: + aliases: [partial] + returnType: any + signatures: ['partials.Include NAME [CONTEXT]'] aliases: [/functions/partial] --- diff --git a/docs/content/en/functions/partials/IncludeCached.md b/docs/content/en/functions/partials/IncludeCached.md index 8b57c3399..3905ee15e 100644 --- a/docs/content/en/functions/partials/IncludeCached.md +++ b/docs/content/en/functions/partials/IncludeCached.md @@ -3,18 +3,11 @@ title: partials.IncludeCached description: Executes the given template and caches the result, optionally passing context. If the partial template contains a return statement, returns the given value, else returns the rendered output. categories: [] keywords: [] -action: - aliases: [partialCached] - related: - - functions/go-template/return - - functions/partials/Include - - functions/go-template/template - - methods/page/Render - returnType: any - signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]'] -signatures: - - partials.IncludeCached NAME CONTEXT [VARIANT...] - - partialCached NAME CONTEXT [VARIANT...] +params: + functions_and_methods: + aliases: [partialCached] + returnType: any + signatures: ['partials.IncludeCached LAYOUT CONTEXT [VARIANT...]'] aliases: [/functions/partialcached] --- @@ -22,11 +15,10 @@ Without a [`return`] statement, the `partialCached` function returns a string of The `partialCached` function can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. -{{% note %}} -Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. - -Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result. -{{% /note %}} +> [!note] +> Each Site (or language) has its own `partialCached` cache, so each site will execute a partial once. +> +> Hugo renders pages in parallel, and will render the partial more than once with concurrent calls to the `partialCached` function. After Hugo caches the rendered partial, new pages entering the build pipeline will use the cached result. Here is the simplest usage: @@ -36,9 +28,9 @@ Here is the simplest usage: Pass additional arguments to `partialCached` to create variants of the cached partial. For example, if you have a complex partial that should be identical when rendered for pages within the same section, use a variant based on section so that the partial is only rendered once per section: -{{< code file=partial-cached-example.html >}} +```go-html-template {file="layouts/_default/baseof.html"} {{ partialCached "footer.html" . .Section }} -{{< /code >}} +``` Pass additional arguments, of any data type, as needed to create unique variants: @@ -46,7 +38,7 @@ Pass additional arguments, of any data type, as needed to create unique variants {{ partialCached "footer.html" . .Params.country .Params.province }} ``` -The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys. +The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys. To return a value from a partial template, it must contain only one `return` statement, placed at the end of the template: diff --git a/docs/content/en/functions/partials/_index.md b/docs/content/en/functions/partials/_index.md index 0a7d4d6d0..09b467399 100644 --- a/docs/content/en/functions/partials/_index.md +++ b/docs/content/en/functions/partials/_index.md @@ -1,12 +1,7 @@ --- title: Partial functions linkTitle: partials -description: Template functions to call partial templates. +description: Use these functions to call partial templates. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to call partial templates. diff --git a/docs/content/en/functions/path/Base.md b/docs/content/en/functions/path/Base.md index 2071f8bea..39d52bfcb 100644 --- a/docs/content/en/functions/path/Base.md +++ b/docs/content/en/functions/path/Base.md @@ -1,19 +1,13 @@ --- title: path.Base -description: Replaces path separators with slashes (`/`) and returns the last element of the given path. +description: Replaces path separators with slashes (`/`) and returns the last element of the given path. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/BaseName - - functions/path/Clean - - functions/path/Dir - - functions/path/Ext - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.Base PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Base PATH] aliases: [/functions/path.base] --- diff --git a/docs/content/en/functions/path/BaseName.md b/docs/content/en/functions/path/BaseName.md index 477c8d319..468898a6f 100644 --- a/docs/content/en/functions/path/BaseName.md +++ b/docs/content/en/functions/path/BaseName.md @@ -3,17 +3,11 @@ title: path.BaseName description: Replaces path separators with slashes (`/`) and returns the last element of the given path, removing the extension if present. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/Clean - - functions/path/Dir - - functions/path/Ext - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.BaseName PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.BaseName PATH] aliases: [/functions/path.basename] --- diff --git a/docs/content/en/functions/path/Clean.md b/docs/content/en/functions/path/Clean.md index 57a665c03..b9f2de038 100644 --- a/docs/content/en/functions/path/Clean.md +++ b/docs/content/en/functions/path/Clean.md @@ -3,17 +3,11 @@ title: path.Clean description: Replaces path separators with slashes (`/`) and returns the shortest path name equivalent to the given path. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Dir - - functions/path/Ext - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.Clean PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Clean PATH] aliases: [/functions/path.clean] --- diff --git a/docs/content/en/functions/path/Dir.md b/docs/content/en/functions/path/Dir.md index 6d5e5c975..04d5500f5 100644 --- a/docs/content/en/functions/path/Dir.md +++ b/docs/content/en/functions/path/Dir.md @@ -3,17 +3,11 @@ title: path.Dir description: Replaces path separators with slashes (/) and returns all but the last element of the given path. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Clean - - functions/path/Ext - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.Dir PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Dir PATH] aliases: [/functions/path.dir] --- diff --git a/docs/content/en/functions/path/Ext.md b/docs/content/en/functions/path/Ext.md index f3e47aecd..3646d02d0 100644 --- a/docs/content/en/functions/path/Ext.md +++ b/docs/content/en/functions/path/Ext.md @@ -3,17 +3,11 @@ title: path.Ext description: Replaces path separators with slashes (`/`) and returns the file name extension of the given path. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Clean - - functions/path/Dir - - functions/path/Join - - functions/path/Split - returnType: string - signatures: [path.Ext PATH] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Ext PATH] aliases: [/functions/path.ext] --- diff --git a/docs/content/en/functions/path/Join.md b/docs/content/en/functions/path/Join.md index 394389780..bda46737f 100644 --- a/docs/content/en/functions/path/Join.md +++ b/docs/content/en/functions/path/Join.md @@ -3,18 +3,11 @@ title: path.Join description: Replaces path separators with slashes (`/`), joins the given path elements into a single path, and returns the shortest path name equivalent to the result. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Clean - - functions/path/Dir - - functions/path/Ext - - functions/path/Split - - functions/urls/JoinPath - returnType: string - signatures: [path.Join ELEMENT...] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [path.Join ELEMENT...] aliases: [/functions/path.join] --- diff --git a/docs/content/en/functions/path/Split.md b/docs/content/en/functions/path/Split.md index 329d73954..d4f8d08e0 100644 --- a/docs/content/en/functions/path/Split.md +++ b/docs/content/en/functions/path/Split.md @@ -1,19 +1,13 @@ --- title: path.Split -description: Replaces path separators with slashes (`/`) and splits the resulting path immediately following the final slash, separating it into a directory and file name component. +description: Replaces path separators with slashes (`/`) and splits the resulting path immediately following the final slash, separating it into a directory and file name component. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Base - - functions/path/BaseName - - functions/path/Clean - - functions/path/Dir - - functions/path/Ext - - functions/path/Join - returnType: paths.DirFile - signatures: [path.Split PATH] +params: + functions_and_methods: + aliases: [] + returnType: paths.DirFile + signatures: [path.Split PATH] aliases: [/functions/path.split] --- diff --git a/docs/content/en/functions/path/_index.md b/docs/content/en/functions/path/_index.md index 2d7ce8e90..49b2927ce 100644 --- a/docs/content/en/functions/path/_index.md +++ b/docs/content/en/functions/path/_index.md @@ -1,12 +1,7 @@ --- title: Path functions linkTitle: path -description: Template functions to work with file paths. +description: Use these functions to work with file paths. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with file paths. diff --git a/docs/content/en/functions/reflect/IsMap.md b/docs/content/en/functions/reflect/IsMap.md index ada5a221d..55b9811d7 100644 --- a/docs/content/en/functions/reflect/IsMap.md +++ b/docs/content/en/functions/reflect/IsMap.md @@ -3,12 +3,11 @@ title: reflect.IsMap description: Reports whether the given value is a map. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/reflect/IsSlice - returnType: bool - signatures: [reflect.IsMap INPUT] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [reflect.IsMap INPUT] aliases: [/functions/reflect.ismap] --- diff --git a/docs/content/en/functions/reflect/IsSlice.md b/docs/content/en/functions/reflect/IsSlice.md index cda24a5e1..3a5c1229b 100644 --- a/docs/content/en/functions/reflect/IsSlice.md +++ b/docs/content/en/functions/reflect/IsSlice.md @@ -3,12 +3,11 @@ title: reflect.IsSlice description: Reports whether the given value is a slice. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/reflect/IsMap - returnType: bool - signatures: [reflect.IsSlice INPUT] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [reflect.IsSlice INPUT] aliases: [/functions/reflect.isslice] --- diff --git a/docs/content/en/functions/reflect/_index.md b/docs/content/en/functions/reflect/_index.md index 711908ee2..58f00c3de 100644 --- a/docs/content/en/functions/reflect/_index.md +++ b/docs/content/en/functions/reflect/_index.md @@ -1,12 +1,7 @@ --- title: Reflect functions linkTitle: reflect -description: Template functions to determine a value's data type. +description: Use these functions to determine a value's data type. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to determine a value's data type. diff --git a/docs/content/en/functions/resources/Babel.md b/docs/content/en/functions/resources/Babel.md index 757aff780..799823fc5 100644 --- a/docs/content/en/functions/resources/Babel.md +++ b/docs/content/en/functions/resources/Babel.md @@ -3,15 +3,16 @@ title: resources.Babel description: Compiles the given JavaScript resource with Babel. categories: [] keywords: [] -action: - related: [] - returnType: resource.Resource - signatures: ['resources.Babel [OPTIONS] RESOURCE'] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.Babel [OPTIONS] RESOURCE'] expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`js.Babel`] instead. [`js.Babel`]: /functions/js/babel/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/docs/content/en/functions/resources/ByType.md b/docs/content/en/functions/resources/ByType.md index ba9dcde0c..99e2b9771 100644 --- a/docs/content/en/functions/resources/ByType.md +++ b/docs/content/en/functions/resources/ByType.md @@ -3,16 +3,11 @@ title: resources.ByType description: Returns a collection of global resources of the given media type, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/Get - - functions/resources/GetMatch - - functions/resources/GetRemote - - functions/resources/Match - - methods/page/Resources - returnType: resource.Resources - signatures: [resources.ByType MEDIATYPE] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resources + signatures: [resources.ByType MEDIATYPE] --- The [media type] is typically one of `image`, `text`, `audio`, `video`, or `application`. @@ -23,12 +18,10 @@ The [media type] is typically one of `image`, `text`, `audio`, `video`, or `appl {{ end }} ``` -{{% note %}} -This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. - -For page resources, use the [`Resources.ByType`] method on a `Page` object. +> [!note] +> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. +> +> For page resources, use the [`Resources.ByType`] method on a `Page` object. [`Resources.ByType`]: /methods/page/resources/ -{{% /note %}} - [media type]: https://en.wikipedia.org/wiki/Media_type diff --git a/docs/content/en/functions/resources/Concat.md b/docs/content/en/functions/resources/Concat.md index 6e81f3f44..fe7226e1b 100644 --- a/docs/content/en/functions/resources/Concat.md +++ b/docs/content/en/functions/resources/Concat.md @@ -3,11 +3,11 @@ title: resources.Concat description: Returns a concatenated slice of resources. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: resource.Resource - signatures: ['resources.Concat TARGETPATH [RESOURCE...]'] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.Concat TARGETPATH [RESOURCE...]'] --- 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]. diff --git a/docs/content/en/functions/resources/Copy.md b/docs/content/en/functions/resources/Copy.md index 3be3dfd57..220a3db4c 100644 --- a/docs/content/en/functions/resources/Copy.md +++ b/docs/content/en/functions/resources/Copy.md @@ -2,11 +2,11 @@ title: resources.Copy description: Copies the given resource to the target path. categories: [] -action: - aliases: [] - related: [] - returnType: resource.Resource - signatures: [resources.Copy TARGETPATH RESOURCE] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.Copy TARGETPATH RESOURCE] --- ```go-html-template @@ -23,6 +23,5 @@ The relative URL of the new published resource will be: /img/new-image-name.jpg ``` -{{% note %}} -Use the `resources.Copy` function with global, page, and remote resources. -{{% /note %}} +> [!note] +> Use the `resources.Copy` function with global, page, and remote resources. diff --git a/docs/content/en/functions/resources/ExecuteAsTemplate.md b/docs/content/en/functions/resources/ExecuteAsTemplate.md index 0c90a03b3..bff83832e 100644 --- a/docs/content/en/functions/resources/ExecuteAsTemplate.md +++ b/docs/content/en/functions/resources/ExecuteAsTemplate.md @@ -3,30 +3,25 @@ title: resources.ExecuteAsTemplate description: Returns a resource created from a Go template, parsed and executed with the given context. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/FromString - returnType: resource.Resource - signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.ExecuteAsTemplate TARGETPATH CONTEXT RESOURCE] --- The `resources.ExecuteAsTemplate` function returns a resource created from a Go template, parsed and executed with the given context, caching the result using the target path as its cache key. Hugo publishes the resource to the target path when you call its [`Publish`], [`Permalink`], or [`RelPermalink`] methods. -[`publish`]: /methods/resource/publish/ -[`permalink`]: /methods/resource/permalink/ -[`relpermalink`]: /methods/resource/relpermalink/ - Let's say you have a CSS file that you wish to populate with values from your site configuration: -{{< code file=assets/css/template.css lang=go-html-template >}} +```go-html-template {file="assets/css/template.css"} body { background-color: {{ site.Params.style.bg_color }}; color: {{ site.Params.style.text_color }}; } -{{< /code >}} +``` And your site configuration contains: @@ -54,9 +49,13 @@ The example above: The result is: -{{< code file=public/css/main.css >}} +```css {file="public/css/main.css"} body { background-color: #fefefe; color: #222; } -{{< /code >}} +``` + +[`publish`]: /methods/resource/publish/ +[`permalink`]: /methods/resource/permalink/ +[`relpermalink`]: /methods/resource/relpermalink/ diff --git a/docs/content/en/functions/resources/Fingerprint.md b/docs/content/en/functions/resources/Fingerprint.md index 17222784e..6757a0b6f 100644 --- a/docs/content/en/functions/resources/Fingerprint.md +++ b/docs/content/en/functions/resources/Fingerprint.md @@ -3,16 +3,11 @@ title: resources.Fingerprint description: Cryptographically hashes the content of the given resource. categories: [] keywords: [] -action: - aliases: [fingerprint] - related: - - functions/resources/Minify - - functions/css/Sass - - functions/css/TailwindCSS - - functions/js/Build - - functions/js/Babel - returnType: resource.Resource - signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE'] +params: + functions_and_methods: + aliases: [fingerprint] + returnType: resource.Resource + signatures: ['resources.Fingerprint [ALGORITHM] RESOURCE'] --- ```go-html-template diff --git a/docs/content/en/functions/resources/FromString.md b/docs/content/en/functions/resources/FromString.md index c13db35d6..4cd04f609 100644 --- a/docs/content/en/functions/resources/FromString.md +++ b/docs/content/en/functions/resources/FromString.md @@ -3,12 +3,11 @@ title: resources.FromString description: Returns a resource created from a string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/ExecuteAsTemplate - returnType: resource.Resource - signatures: [resources.FromString TARGETPATH STRING] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.FromString TARGETPATH STRING] --- The `resources.FromString` function returns a resource created from a string, caching the result using the target path as its cache key. diff --git a/docs/content/en/functions/resources/Get.md b/docs/content/en/functions/resources/Get.md index c6450febf..db91f0a9a 100644 --- a/docs/content/en/functions/resources/Get.md +++ b/docs/content/en/functions/resources/Get.md @@ -3,16 +3,11 @@ title: resources.Get description: Returns a global resource from the given path, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/ByType - - functions/resources/GetMatch - - functions/resources/GetRemote - - functions/resources/Match - - methods/page/Resources - returnType: resource.Resource - signatures: [resources.Get PATH] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.Get PATH] --- ```go-html-template @@ -21,10 +16,9 @@ action: {{ end }} ``` -{{% note %}} -This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. - -For page resources, use the [`Resources.Get`] method on a `Page` object. +> [!note] +> This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. +> +> For page resources, use the [`Resources.Get`] method on a `Page` object. [`Resources.Get`]: /methods/page/resources/ -{{% /note %}} diff --git a/docs/content/en/functions/resources/GetMatch.md b/docs/content/en/functions/resources/GetMatch.md index 7af2e7be8..8f1b004fe 100644 --- a/docs/content/en/functions/resources/GetMatch.md +++ b/docs/content/en/functions/resources/GetMatch.md @@ -3,16 +3,11 @@ title: resources.GetMatch description: Returns the first global resource from paths matching the given glob pattern, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/ByType - - functions/resources/Get - - functions/resources/GetRemote - - functions/resources/Match - - methods/page/Resources - returnType: resource.Resource - signatures: [resources.GetMatch PATTERN] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: [resources.GetMatch PATTERN] --- ```go-html-template @@ -21,16 +16,13 @@ action: {{ end }} ``` -{{% note %}} -This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. +> [!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. +> +> For page resources, use the [`Resources.GetMatch`] method on a `Page` object. -For page resources, use the [`Resources.GetMatch`] method on a `Page` object. +Hugo determines a match using a case-insensitive [glob](g) pattern. -[`Resources.GetMatch`]: /methods/page/resources/ -{{% /note %}} - -Hugo determines a match using a case-insensitive [glob pattern]. +{{% include "/_common/glob-patterns.md" %}} -{{% include "functions/_common/glob-patterns.md" %}} - -[glob pattern]: https://github.com/gobwas/glob#example +[`Resources.GetMatch`]: /methods/page/resources/ diff --git a/docs/content/en/functions/resources/GetRemote.md b/docs/content/en/functions/resources/GetRemote.md index 3b294e5a1..c6f6742b3 100644 --- a/docs/content/en/functions/resources/GetRemote.md +++ b/docs/content/en/functions/resources/GetRemote.md @@ -3,19 +3,11 @@ title: resources.GetRemote description: Returns a remote resource from the given URL, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/data/GetCSV - - functions/data/GetJSON - - functions/resources/ByType - - functions/resources/Get - - functions/resources/GetMatch - - functions/resources/Match - - methods/page/Resources - returnType: resource.Resource - signatures: ['resources.GetRemote URL [OPTIONS]'] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.GetRemote URL [OPTIONS]'] --- {{< new-in 0.141.0 >}} @@ -69,11 +61,10 @@ The `resources.GetRemote` function takes an optional map of options. ## Options examples -{{% note %}} -For brevity, the examples below do not include [error handling]. +> [!note] +> For brevity, the examples below do not include [error handling]. [error handling]: #error-handling -{{% /note %}} To include a header: @@ -148,15 +139,12 @@ When retrieving remote data, use the [`transform.Unmarshal`] function to [unmars {{ end }} ``` -{{% note %}} -When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. - -In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: - -`{{ $data = .Content | transform.Unmarshal }}` - -[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type -{{% /note %}} +> [!note] +> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. +> +> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: +> +> `{{ $data = .Content | transform.Unmarshal }}` ## Error handling @@ -164,9 +152,8 @@ Use the [`try`] statement to capture HTTP request errors. If you do not handle t [`try`]: /functions/go-template/try -{{% note %}} -Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. -{{% /note %}} +> [!note] +> Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. ```go-html-template {{ $url := "https://broken-example.org/images/a.jpg" }} @@ -206,9 +193,7 @@ The [`Data`] method on a resource returned by the `resources.GetRemote` function Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details. -By default, Hugo derives the cache key from the arguments passed to the function, the URL and the options map, if any. - -Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource. +By default, Hugo derives the cache key from the arguments passed to the function. Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource. ```go-html-template {{ $url := "https://example.org/images/a.jpg" }} @@ -217,7 +202,7 @@ Override the cache key by setting a `key` in the options map. Use this approach {{ $resource := resources.GetRemote $url $opts }} ``` -[configure file caches]: /getting-started/configuration/#configure-file-caches +[configure file caches]: /configuration/caches/ ## Security @@ -245,7 +230,7 @@ mediaTypes = ['^image/avif$','^application/vnd\.api\+json$'] Note that the entry above is: - An _addition_ to the allowlist; it does not _replace_ the allowlist -- An array of regular expressions +- An array of [regular expressions](g) [allowlist]: https://en.wikipedia.org/wiki/Whitelist [Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type diff --git a/docs/content/en/functions/resources/Match.md b/docs/content/en/functions/resources/Match.md index 3e65555ba..6c7d83649 100644 --- a/docs/content/en/functions/resources/Match.md +++ b/docs/content/en/functions/resources/Match.md @@ -3,16 +3,11 @@ title: resources.Match description: Returns a collection of global resources from paths matching the given glob pattern, or nil if none found. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/resources/ByType - - functions/resources/Get - - functions/resources/GetMatch - - functions/resources/GetRemote - - methods/page/Resources - returnType: resource.Resources - signatures: [resources.Match PATTERN] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resources + signatures: [resources.Match PATTERN] --- ```go-html-template @@ -21,16 +16,14 @@ action: {{ end }} ``` -{{% note %}} -This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. - -For page resources, use the [`Resources.Match`] method on a `Page` object. - -[`Resources.Match`]: /methods/page/resources/ -{{% /note %}} +> [!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. +> +> For page resources, use the [`Resources.Match`] method on a `Page` object. Hugo determines a match using a case-insensitive [glob pattern]. -{{% include "functions/_common/glob-patterns.md" %}} +{{% include "/_common/glob-patterns.md" %}} +[`Resources.Match`]: /methods/page/resources/ [glob pattern]: https://github.com/gobwas/glob#example diff --git a/docs/content/en/functions/resources/Minify.md b/docs/content/en/functions/resources/Minify.md index 25314fd6a..183e6671a 100644 --- a/docs/content/en/functions/resources/Minify.md +++ b/docs/content/en/functions/resources/Minify.md @@ -3,16 +3,11 @@ title: resources.Minify description: Minifies the given resource. categories: [] keywords: [] -action: - aliases: [minify] - related: - - functions/resources/Fingerprint - - functions/css/Sass - - functions/css/TailwindCSS - - functions/js/Build - - functions/js/Babel - returnType: resource.Resource - signatures: [resources.Minify RESOURCE] +params: + functions_and_methods: + aliases: [minify] + returnType: resource.Resource + signatures: [resources.Minify RESOURCE] --- ```go-html-template diff --git a/docs/content/en/functions/resources/PostCSS.md b/docs/content/en/functions/resources/PostCSS.md index 5d3f85a30..3ec0b84cf 100644 --- a/docs/content/en/functions/resources/PostCSS.md +++ b/docs/content/en/functions/resources/PostCSS.md @@ -3,15 +3,16 @@ title: resources.PostCSS description: Processes the given resource with PostCSS using any PostCSS plugin. categories: [] keywords: [] -action: - related: [] - returnType: resource.Resource - signatures: ['resources.PostCSS [OPTIONS] RESOURCE'] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.PostCSS [OPTIONS] RESOURCE'] expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`css.PostCSS`] instead. [`css.PostCSS`]: /functions/css/postcss/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/docs/content/en/functions/resources/PostProcess.md b/docs/content/en/functions/resources/PostProcess.md index b157d5fd9..d70437694 100644 --- a/docs/content/en/functions/resources/PostProcess.md +++ b/docs/content/en/functions/resources/PostProcess.md @@ -3,14 +3,11 @@ title: resources.PostProcess description: Processes the given resource after the build. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/css/PostCSS - - functions/css/Sass - returnType: postpub.PostPublishedResource - signatures: [resources.PostProcess RESOURCE] -toc: true +params: + functions_and_methods: + aliases: [] + returnType: postpub.PostPublishedResource + signatures: [resources.PostProcess RESOURCE] --- The `resources.PostProcess` function delays resource transformation steps until the build is complete, primarily for tasks like removing unused CSS rules. @@ -22,19 +19,11 @@ In this example, after the build is complete, Hugo will: 1. Purge unused CSS using the [PurgeCSS] plugin for [PostCSS] 2. Add vendor prefixes to CSS rules using the [Autoprefixer] plugin for PostCSS 3. [Minify] the CSS -4. [Fingerprint] the CSS - -[autoprefixer]: https://github.com/postcss/autoprefixer -[fingerprint]: /functions/resources/fingerprint/ -[minify]: /functions/resources/minify/ -[postcss]: /functions/css/postcss/ -[purgecss]: https://purgecss.com/plugins/postcss.html +4. [Fingerprint] the CSS Step 1 : Install [Node.js]. -[node.js]: https://nodejs.org/en/download - Step 2 : Install the required Node.js packages in the root of your project: @@ -45,8 +34,6 @@ npm i -D postcss postcss-cli autoprefixer @fullhuman/postcss-purgecss Step 3 : 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`]. -[`config/production`]: /getting-started/configuration/#configuration-directory - {{< code-toggle file=hugo >}} [build.buildStats] enable = true @@ -54,12 +41,10 @@ enable = true See the [configure build] documentation for details and options. -[configure build]: /getting-started/configuration/#configure-build - Step 4 : Create a PostCSS configuration file in the root of your project. -{{< code file="postcss.config.js" copy=true >}} +```js {file="postcss.config.js" copy=true} const autoprefixer = require('autoprefixer'); const purgeCSSPlugin = require('@fullhuman/postcss-purgecss').default; @@ -83,11 +68,10 @@ module.exports = { autoprefixer, ] }; -{{< /code >}} +``` -{{% note %}} -{{% include "functions/resources/_common/postcss-windows-warning.md" %}} -{{% /note %}} +> [!note] +> If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. Step 5 : Place your CSS file within the `assets/css` directory. @@ -132,7 +116,7 @@ HUGO_FILE_X - `postcss.config.js` - `tailwind.config.js` -For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores. This allows you to access these files within your JavaScript, for example: +For each file, Hugo creates a corresponding environment variable named `HUGO_FILE_:filename:`, where `:filename:` is the uppercase version of the filename with periods replaced by underscores. This allows you to access these files within your JavaScript, for example: ```js let tailwindConfig = process.env.HUGO_FILE_TAILWIND_CONFIG_JS || './tailwind.config.js'; @@ -144,10 +128,21 @@ Do not use `resources.PostProcess` when running Hugo's built-in development serv The `resources.PostProcess` function only works within templates that produce HTML files. -You cannot manipulate the values returned from the resource’s methods. For example, the `strings.ToUpper` function in this example will not work as expected: +You cannot manipulate the values returned from the resource's methods. For example, the `strings.ToUpper` function in this example will not work as expected: ```go-html-template {{ $css := resources.Get "css/main.css" }} {{ $css = $css | css.PostCSS | minify | fingerprint | resources.PostProcess }} {{ $css.RelPermalink | strings.ToUpper }} ``` + +[#7333]: https://github.com/gohugoio/hugo/issues/7333 +[`config/production`]: /configuration/introduction/#configuration-directory +[Autoprefixer]: https://github.com/postcss/autoprefixer +[configure build]: /configuration/build/ +[Fingerprint]: /functions/resources/fingerprint/ +[Minify]: /functions/resources/minify/ +[Node.js]: https://nodejs.org/en +[PostCSS]: https://postcss.org/ +[PurgeCSS]: https://github.com/FullHuman/purgecss +[this example]: https://github.com/postcss/postcss-load-config#packagejson diff --git a/docs/content/en/functions/resources/ToCSS.md b/docs/content/en/functions/resources/ToCSS.md index 54c34a6b0..7be1b8d45 100644 --- a/docs/content/en/functions/resources/ToCSS.md +++ b/docs/content/en/functions/resources/ToCSS.md @@ -3,15 +3,16 @@ title: resources.ToCSS description: Transpiles Sass to CSS. categories: [] keywords: [] -action: - related: [] - returnType: resource.Resource - signatures: ['resources.ToCSS [OPTIONS] RESOURCE'] +params: + functions_and_methods: + aliases: [] + returnType: resource.Resource + signatures: ['resources.ToCSS [OPTIONS] RESOURCE'] expiryDate: 2026-06-24 # deprecated 2024-06-24 in v0.128.0 --- -{{% deprecated-in 0.128.0 %}} +{{< deprecated-in 0.128.0 >}} Use [`css.Sass`] instead. [`css.Sass`]: /functions/css/sass/ -{{% /deprecated-in %}} +{{< /deprecated-in >}} diff --git a/docs/content/en/functions/resources/_common/_index.md b/docs/content/en/functions/resources/_common/_index.md deleted file mode 100644 index cb36fea41..000000000 --- a/docs/content/en/functions/resources/_common/_index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -_build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/functions/resources/_common/postcss-windows-warning.md b/docs/content/en/functions/resources/_common/postcss-windows-warning.md deleted file mode 100644 index e2d97850b..000000000 --- a/docs/content/en/functions/resources/_common/postcss-windows-warning.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -If you are a Windows user, and the path to your project contains a space, you must place the PostCSS configuration within the package.json file. See [this example] and issue [#7333]. - -[this example]: https://github.com/postcss/postcss-load-config#packagejson -[#7333]: https://github.com/gohugoio/hugo/issues/7333 diff --git a/docs/content/en/functions/resources/_index.md b/docs/content/en/functions/resources/_index.md index 364b9448d..030cafd42 100644 --- a/docs/content/en/functions/resources/_index.md +++ b/docs/content/en/functions/resources/_index.md @@ -1,12 +1,7 @@ --- title: Resource functions linkTitle: resources -description: Template functions to work with resources. +description: Use these functions to work with resources. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with resources. diff --git a/docs/content/en/functions/safe/CSS.md b/docs/content/en/functions/safe/CSS.md index 5d67789b6..12ebbf8aa 100644 --- a/docs/content/en/functions/safe/CSS.md +++ b/docs/content/en/functions/safe/CSS.md @@ -3,23 +3,17 @@ title: safe.CSS description: Declares the given string as a safe CSS string. categories: [] keywords: [] -action: - aliases: [safeCSS] - related: - - functions/safe/HTML - - functions/safe/HTMLAttr - - functions/safe/JS - - functions/safe/JSStr - - functions/safe/URL - returnType: template.CSS - signatures: [safe.CSS INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeCSS] + returnType: template.CSS + signatures: [safe.CSS INPUT] aliases: [/functions/safecss] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage @@ -34,8 +28,6 @@ Use of this type presents a security risk: the encapsulated content should come See the [Go documentation] for details. -[Go documentation]: https://pkg.go.dev/html/template#CSS - ## Example Without a safe declaration: @@ -51,9 +43,8 @@ Hugo renders the above to: <p style="ZgotmplZ">foo</p> ``` -{{% note %}} -`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. -{{% /note %}} +> [!note] +> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. To declare the string as safe: @@ -67,3 +58,5 @@ Hugo renders the above to: ```html <p style="color: red;">foo</p> ``` + +[Go documentation]: https://pkg.go.dev/html/template#CSS diff --git a/docs/content/en/functions/safe/HTML.md b/docs/content/en/functions/safe/HTML.md index ad1b3a681..25ffb3318 100644 --- a/docs/content/en/functions/safe/HTML.md +++ b/docs/content/en/functions/safe/HTML.md @@ -3,23 +3,17 @@ title: safe.HTML description: Declares the given string as a safeHTML string. categories: [] keywords: [] -action: - aliases: [safeHTML] - related: - - functions/safe/CSS - - functions/safe/HTMLAttr - - functions/safe/JS - - functions/safe/JSStr - - functions/safe/URL - returnType: template.HTML - signatures: [safe.HTML INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeHTML] + returnType: template.HTML + signatures: [safe.HTML INPUT] aliases: [/functions/safehtml] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage diff --git a/docs/content/en/functions/safe/HTMLAttr.md b/docs/content/en/functions/safe/HTMLAttr.md index d01a3908a..7cfefdfb2 100644 --- a/docs/content/en/functions/safe/HTMLAttr.md +++ b/docs/content/en/functions/safe/HTMLAttr.md @@ -3,28 +3,22 @@ title: safe.HTMLAttr description: Declares the given key-value pair as a safe HTML attribute. categories: [] keywords: [] -action: - aliases: [safeHTMLAttr] - related: - - functions/safe/CSS - - functions/safe/HTML - - functions/safe/JS - - functions/safe/JSStr - - functions/safe/URL - returnType: template.HTMLAttr - signatures: [safe.HTMLAttr INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeHTMLAttr] + returnType: template.HTMLAttr + signatures: [safe.HTMLAttr INPUT] aliases: [/functions/safehtmlattr] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage Use the `safe.HTMLAttr` function to encapsulate an HTML attribute from a trusted source. - + 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. See the [Go documentation] for details. diff --git a/docs/content/en/functions/safe/JS.md b/docs/content/en/functions/safe/JS.md index d0d3a227a..0c4d9009d 100644 --- a/docs/content/en/functions/safe/JS.md +++ b/docs/content/en/functions/safe/JS.md @@ -3,23 +3,17 @@ title: safe.JS description: Declares the given string as a safe JavaScript expression. categories: [] keywords: [] -action: - aliases: [safeJS] - related: - - functions/safe/CSS - - functions/safe/HTML - - functions/safe/HTMLAttr - - functions/safe/JSStr - - functions/safe/URL - returnType: template.JS - signatures: [safe.JS INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeJS] + returnType: template.JS + signatures: [safe.JS INPUT] aliases: [/functions/safejs] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage diff --git a/docs/content/en/functions/safe/JSStr.md b/docs/content/en/functions/safe/JSStr.md index e7e232d1b..81946a14c 100644 --- a/docs/content/en/functions/safe/JSStr.md +++ b/docs/content/en/functions/safe/JSStr.md @@ -3,23 +3,17 @@ title: safe.JSStr description: Declares the given string as a safe JavaScript string. categories: [] keywords: [] -action: - aliases: [safeJSStr] - related: - - functions/safe/CSS - - functions/safe/HTML - - functions/safe/HTMLAttr - - functions/safe/JS - - functions/safe/URL - returnType: template.JSStr - signatures: [safe.JSStr INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeJSStr] + returnType: template.JSStr + signatures: [safe.JSStr INPUT] aliases: [/functions/safejsstr] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage diff --git a/docs/content/en/functions/safe/URL.md b/docs/content/en/functions/safe/URL.md index e4b3224da..44bed8064 100644 --- a/docs/content/en/functions/safe/URL.md +++ b/docs/content/en/functions/safe/URL.md @@ -3,23 +3,17 @@ title: safe.URL description: Declares the given string as a safe URL or URL substring. categories: [] keywords: [] -action: - aliases: [safeURL] - related: - - functions/safe/CSS - - functions/safe/HTML - - functions/safe/HTMLAttr - - functions/safe/JS - - functions/safe/JSStr - returnType: template.URL - signatures: [safe.URL INPUT] -toc: true +params: + functions_and_methods: + aliases: [safeURL] + returnType: template.URL + signatures: [safe.URL INPUT] aliases: [/functions/safeurl] --- ## Introduction -{{% include "functions/_common/go-html-template-package.md" %}} +{{% include "/_common/functions/go-html-template-package.md" %}} ## Usage @@ -33,8 +27,6 @@ Use of this type presents a security risk: the encapsulated content should come See the [Go documentation] for details. -[Go documentation]: https://pkg.go.dev/html/template#URL - ## Example Without a safe declaration: @@ -50,9 +42,8 @@ Hugo renders the above to: <a href="#ZgotmplZ">IRC</a> ``` -{{% note %}} -`ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. -{{% /note %}} +> [!note] +> `ZgotmplZ` is a special value that indicates that unsafe content reached a CSS or URL context at runtime. To declare the string as safe: @@ -66,3 +57,5 @@ Hugo renders the above to: ```html <a href="irc://irc.freenode.net/#golang">IRC</a> ``` + +[Go documentation]: https://pkg.go.dev/html/template#URL diff --git a/docs/content/en/functions/safe/_index.md b/docs/content/en/functions/safe/_index.md index f80a2cff4..8d5697b8d 100644 --- a/docs/content/en/functions/safe/_index.md +++ b/docs/content/en/functions/safe/_index.md @@ -1,14 +1,7 @@ --- title: Safe functions linkTitle: safe -description: Template functions to declare a value as safe in the context of Go's html/template package. +description: Use these functions to declare a value as safe in the context of Go's html/template package. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to declare a value as safe in the context of Go's [html/template] package. - -[html/template]: https://pkg.go.dev/html/template diff --git a/docs/content/en/functions/strings/Chomp.md b/docs/content/en/functions/strings/Chomp.md index 8024758ba..1ff2b7f47 100644 --- a/docs/content/en/functions/strings/Chomp.md +++ b/docs/content/en/functions/strings/Chomp.md @@ -3,17 +3,11 @@ title: strings.Chomp description: Returns the given string, removing all trailing newline characters and carriage returns. categories: [] keywords: [] -action: - aliases: [chomp] - related: - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: any - signatures: [strings.Chomp STRING] +params: + functions_and_methods: + aliases: [chomp] + returnType: any + signatures: [strings.Chomp STRING] aliases: [/functions/chomp] --- diff --git a/docs/content/en/functions/strings/Contains.md b/docs/content/en/functions/strings/Contains.md index 0344b2981..e0e3b087c 100644 --- a/docs/content/en/functions/strings/Contains.md +++ b/docs/content/en/functions/strings/Contains.md @@ -3,16 +3,11 @@ title: strings.Contains description: Reports whether the given string contains the given substring. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/ContainsAny - - functions/strings/ContainsNonSpace - - functions/strings/HasPrefix - - functions/strings/HasSuffix - - functions/collections/In - returnType: bool - signatures: [strings.Contains STRING SUBSTRING] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [strings.Contains STRING SUBSTRING] aliases: [/functions/strings.contains] --- diff --git a/docs/content/en/functions/strings/ContainsAny.md b/docs/content/en/functions/strings/ContainsAny.md index f331d09f7..521ff3421 100644 --- a/docs/content/en/functions/strings/ContainsAny.md +++ b/docs/content/en/functions/strings/ContainsAny.md @@ -3,16 +3,11 @@ title: strings.ContainsAny description: Reports whether the given string contains any character within the given set. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Contains - - functions/strings/ContainsNonSpace - - functions/strings/HasPrefix - - functions/strings/HasSuffix - - functions/collections/In - returnType: bool - signatures: [strings.ContainsAny STRING SET] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [strings.ContainsAny STRING SET] aliases: [/functions/strings.containsany] --- diff --git a/docs/content/en/functions/strings/ContainsNonSpace.md b/docs/content/en/functions/strings/ContainsNonSpace.md index eea86f396..7b8dcb730 100644 --- a/docs/content/en/functions/strings/ContainsNonSpace.md +++ b/docs/content/en/functions/strings/ContainsNonSpace.md @@ -3,16 +3,11 @@ title: strings.ContainsNonSpace description: Reports whether the given string contains any non-space characters as defined by Unicode. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Contains - - functions/strings/ContainsAny - - functions/strings/HasPrefix - - functions/strings/HasSuffix - - functions/collections/In - returnType: bool - signatures: [strings.ContainsNonSpace STRING] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [strings.ContainsNonSpace STRING] aliases: [/functions/strings.containsnonspace] --- diff --git a/docs/content/en/functions/strings/Count.md b/docs/content/en/functions/strings/Count.md index 43b5baeff..76378b27d 100644 --- a/docs/content/en/functions/strings/Count.md +++ b/docs/content/en/functions/strings/Count.md @@ -3,15 +3,11 @@ title: strings.Count description: Returns the number of non-overlapping instances of the given substring within the given string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/len - - functions/strings/CountRunes - - functions/strings/CountWords - - functions/strings/RuneCount - returnType: int - signatures: [strings.Count SUBSTR STRING] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [strings.Count SUBSTR STRING] aliases: [/functions/strings.count] --- diff --git a/docs/content/en/functions/strings/CountRunes.md b/docs/content/en/functions/strings/CountRunes.md index 87d9da680..8ad6b00da 100644 --- a/docs/content/en/functions/strings/CountRunes.md +++ b/docs/content/en/functions/strings/CountRunes.md @@ -3,15 +3,11 @@ title: strings.CountRunes description: Returns the number of runes in the given string excluding whitespace. categories: [] keywords: [] -action: - aliases: [countrunes] - related: - - functions/go-template/len - - functions/strings/Count - - functions/strings/CountWords - - functions/strings/RuneCount - returnType: int - signatures: [strings.CountRunes INPUT] +params: + functions_and_methods: + aliases: [countrunes] + returnType: int + signatures: [strings.CountRunes INPUT] aliases: [/functions/countrunes] --- diff --git a/docs/content/en/functions/strings/CountWords.md b/docs/content/en/functions/strings/CountWords.md index 3e4ec0465..e50febf69 100644 --- a/docs/content/en/functions/strings/CountWords.md +++ b/docs/content/en/functions/strings/CountWords.md @@ -3,15 +3,11 @@ title: strings.CountWords description: Returns the number of words in the given string. categories: [] keywords: [] -action: - aliases: [countwords] - related: - - functions/go-template/len - - functions/strings/Count - - functions/strings/CountRunes - - functions/strings/RuneCount - returnType: int - signatures: [strings.CountWords INPUT] +params: + functions_and_methods: + aliases: [countwords] + returnType: int + signatures: [strings.CountWords INPUT] aliases: [/functions/countwords] --- diff --git a/docs/content/en/functions/strings/Diff/index.md b/docs/content/en/functions/strings/Diff/index.md index 281b76763..1426764a9 100644 --- a/docs/content/en/functions/strings/Diff/index.md +++ b/docs/content/en/functions/strings/Diff/index.md @@ -3,10 +3,10 @@ title: strings.Diff description: Returns an anchored diff of the two texts OLD and NEW in the unified diff format. If OLD and NEW are identical, returns an empty string. categories: [] keywords: [] -action: - related: [] - returnType: string - signatures: [strings.Diff OLDNAME OLD NEWNAME NEW] +params: + functions_and_methods: + returnType: string + signatures: [strings.Diff OLDNAME OLD NEWNAME NEW] --- {{< new-in 0.125.0 />}} diff --git a/docs/content/en/functions/strings/FindRESubmatch.md b/docs/content/en/functions/strings/FindRESubmatch.md index 3feb15bbd..d039607fb 100644 --- a/docs/content/en/functions/strings/FindRESubmatch.md +++ b/docs/content/en/functions/strings/FindRESubmatch.md @@ -3,20 +3,17 @@ title: strings.FindRESubmatch description: Returns a slice of all successive matches of the regular expression. Each element is a slice of strings holding the text of the leftmost match of the regular expression and the matches, if any, of its subexpressions. categories: [] keywords: [] -action: - aliases: [findRESubmatch] - related: - - functions/strings/FindRE - - functions/strings/Replace - - functions/strings/ReplaceRE - returnType: '[][]string' - signatures: ['strings.FindRESubmatch PATTERN INPUT [LIMIT]'] +params: + functions_and_methods: + aliases: [findRESubmatch] + returnType: '[][]string' + signatures: ['strings.FindRESubmatch PATTERN INPUT [LIMIT]'] aliases: [/functions/findresubmatch] --- By default, `findRESubmatch` finds all matches. You can limit the number of matches with an optional LIMIT argument. A return value of nil indicates no match. -{{% include "functions/_common/regular-expressions.md" %}} +{{% include "/_common/functions/regular-expressions.md" %}} ## Demonstrative examples @@ -85,6 +82,5 @@ https://example.org https://gohugo.io ``` -{{% note %}} -You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. -{{% /note %}} +> [!note] +> You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. diff --git a/docs/content/en/functions/strings/FindRe.md b/docs/content/en/functions/strings/FindRe.md index 861f38a12..45129ec91 100644 --- a/docs/content/en/functions/strings/FindRe.md +++ b/docs/content/en/functions/strings/FindRe.md @@ -3,19 +3,16 @@ title: strings.FindRE description: Returns a slice of strings that match the regular expression. categories: [] keywords: [] -action: - aliases: [findRE] - related: - - functions/strings/FindRESubmatch - - functions/strings/Replace - - functions/strings/ReplaceRE - returnType: '[]string' - signatures: ['strings.FindRE PATTERN INPUT [LIMIT]'] +params: + functions_and_methods: + aliases: [findRE] + returnType: '[]string' + signatures: ['strings.FindRE PATTERN INPUT [LIMIT]'] aliases: [/functions/findre] --- By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT argument. -{{% include "functions/_common/regular-expressions.md" %}} +{{% include "/_common/functions/regular-expressions.md" %}} This example returns a slice of all second level headings (`h2` elements) within the rendered `.Content`: @@ -31,6 +28,5 @@ To limit the number of matches to one: {{ findRE `(?s)<h2.*?>.*?</h2>` .Content 1 }} ``` -{{% note %}} -You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. -{{% /note %}} +> [!note] +> You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. diff --git a/docs/content/en/functions/strings/FirstUpper.md b/docs/content/en/functions/strings/FirstUpper.md index 8826b4f18..41bf1f70a 100644 --- a/docs/content/en/functions/strings/FirstUpper.md +++ b/docs/content/en/functions/strings/FirstUpper.md @@ -3,14 +3,11 @@ title: strings.FirstUpper description: Returns the given string, capitalizing the first character. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Title - - functions/strings/ToLower - - functions/strings/ToUpper - returnType: string - signatures: [strings.FirstUpper STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.FirstUpper STRING] aliases: [/functions/strings.firstupper] --- diff --git a/docs/content/en/functions/strings/HasPrefix.md b/docs/content/en/functions/strings/HasPrefix.md index 455de0586..2babe8552 100644 --- a/docs/content/en/functions/strings/HasPrefix.md +++ b/docs/content/en/functions/strings/HasPrefix.md @@ -3,16 +3,11 @@ title: strings.HasPrefix description: Reports whether the given string begins with the given prefix. categories: [] keywords: [] -action: - aliases: [hasPrefix] - related: - - functions/strings/Contains - - functions/strings/ContainsAny - - functions/strings/ContainsNonSpace - - functions/strings/HasSuffix - - functions/collections/In - returnType: bool - signatures: [strings.HasPrefix STRING PREFIX] +params: + functions_and_methods: + aliases: [hasPrefix] + returnType: bool + signatures: [strings.HasPrefix STRING PREFIX] aliases: [/functions/hasprefix,/functions/strings.hasprefix] --- diff --git a/docs/content/en/functions/strings/HasSuffix.md b/docs/content/en/functions/strings/HasSuffix.md index 8fb12c527..c6b5f4ded 100644 --- a/docs/content/en/functions/strings/HasSuffix.md +++ b/docs/content/en/functions/strings/HasSuffix.md @@ -3,16 +3,11 @@ title: strings.HasSuffix description: Reports whether the given string ends with the given suffix. categories: [] keywords: [] -action: - aliases: [hasSuffix] - related: - - functions/strings/Contains - - functions/strings/ContainsAny - - functions/strings/ContainsNonSpace - - functions/strings/HasPrefix - - functions/collections/In - returnType: bool - signatures: [strings.HasSuffix STRING SUFFIX] +params: + functions_and_methods: + aliases: [hasSuffix] + returnType: bool + signatures: [strings.HasSuffix STRING SUFFIX] aliases: [/functions/hassuffix,/functions/strings/hassuffix] --- diff --git a/docs/content/en/functions/strings/Repeat.md b/docs/content/en/functions/strings/Repeat.md index 530b0d14b..b6027368e 100644 --- a/docs/content/en/functions/strings/Repeat.md +++ b/docs/content/en/functions/strings/Repeat.md @@ -3,11 +3,11 @@ title: strings.Repeat description: Returns a new string consisting of zero or more copies of another string. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [strings.Repeat COUNT INPUT] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.Repeat COUNT INPUT] aliases: [/functions/strings.repeat] --- diff --git a/docs/content/en/functions/strings/Replace.md b/docs/content/en/functions/strings/Replace.md index 9add6e12b..b449ea84d 100644 --- a/docs/content/en/functions/strings/Replace.md +++ b/docs/content/en/functions/strings/Replace.md @@ -3,14 +3,11 @@ title: strings.Replace description: Returns a copy of INPUT, replacing all occurrences of OLD with NEW. categories: [] keywords: [] -action: - aliases: [replace] - related: - - functions/strings/FindRE - - functions/strings/FindRESubmatch - - functions/strings/ReplaceRE - returnType: string - signatures: ['strings.Replace INPUT OLD NEW [LIMIT]'] +params: + functions_and_methods: + aliases: [replace] + returnType: string + signatures: ['strings.Replace INPUT OLD NEW [LIMIT]'] aliases: [/functions/replace] --- diff --git a/docs/content/en/functions/strings/ReplaceRE.md b/docs/content/en/functions/strings/ReplaceRE.md index 1c32c34fb..dba4bd15a 100644 --- a/docs/content/en/functions/strings/ReplaceRE.md +++ b/docs/content/en/functions/strings/ReplaceRE.md @@ -3,18 +3,15 @@ title: strings.ReplaceRE description: Returns a copy of INPUT, replacing all occurrences of a regular expression with a replacement pattern. categories: [] keywords: [] -action: - aliases: [replaceRE] - related: - - functions/strings/FindRE - - functions/strings/FindRESubmatch - - functions/strings/Replace - returnType: string - signatures: ['strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]'] +params: + functions_and_methods: + aliases: [replaceRE] + returnType: string + signatures: ['strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]'] aliases: [/functions/replacere] --- -{{% include "functions/_common/regular-expressions.md" %}} +{{% include "/_common/functions/regular-expressions.md" %}} ```go-html-template {{ $s := "a-b--c---d" }} @@ -35,9 +32,7 @@ Use `$1`, `$2`, etc. within the replacement string to insert the content of each {{ replaceRE "^https?://([^/]+).*" "$1" $s }} → gohugo.io ``` -{{% note %}} -You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. -{{% /note %}} +> [!note] +> You can write and test your regular expression using [regex101.com]. Be sure to select the Go flavor before you begin. -[RE2]: https://github.com/google/re2/wiki/Syntax -[string literal]: https://go.dev/ref/spec#String_literals +[regex101.com]: https://regex101.com/ diff --git a/docs/content/en/functions/strings/RuneCount.md b/docs/content/en/functions/strings/RuneCount.md index 86aab0c64..8c0e24342 100644 --- a/docs/content/en/functions/strings/RuneCount.md +++ b/docs/content/en/functions/strings/RuneCount.md @@ -3,15 +3,11 @@ title: strings.RuneCount description: Returns the number of runes in the given string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/go-template/len - - functions/strings/Count - - functions/strings/CountRunes - - functions/strings/CountWords - returnType: int - signatures: [strings.RuneCount INPUT] +params: + functions_and_methods: + aliases: [] + returnType: int + signatures: [strings.RuneCount INPUT] aliases: [/functions/strings.runecount] --- diff --git a/docs/content/en/functions/strings/SliceString.md b/docs/content/en/functions/strings/SliceString.md index 377a5eb37..69e4f6f33 100644 --- a/docs/content/en/functions/strings/SliceString.md +++ b/docs/content/en/functions/strings/SliceString.md @@ -3,12 +3,11 @@ title: strings.SliceString description: Returns a substring of the given string, beginning with the start position and ending before the end position. categories: [] keywords: [] -action: - aliases: [slicestr] - related: - - functions/strings/Substr - returnType: string - signatures: ['strings.SliceString STRING [START] [END]'] +params: + functions_and_methods: + aliases: [slicestr] + returnType: string + signatures: ['strings.SliceString STRING [START] [END]'] aliases: [/functions/slicestr] --- diff --git a/docs/content/en/functions/strings/Split.md b/docs/content/en/functions/strings/Split.md index e3e0ee13e..bcab1b4d7 100644 --- a/docs/content/en/functions/strings/Split.md +++ b/docs/content/en/functions/strings/Split.md @@ -3,12 +3,11 @@ title: strings.Split description: Returns a slice of strings by splitting the given string by a delimiter. categories: [] keywords: [] -action: - aliases: [split] - related: - - functions/collections/Delimit - returnType: string - signatures: [strings.Split STRING DELIM] +params: + functions_and_methods: + aliases: [split] + returnType: '[]string' + signatures: [strings.Split STRING DELIM] aliases: [/functions/split] --- @@ -19,8 +18,7 @@ Examples: {{ split "abc" "" }} → ["a", "b", "c"] ``` -{{% note %}} -The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice. +> [!note] +> The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice. [`collections.Delimit`]: /functions/collections/delimit/ -{{% /note %}} diff --git a/docs/content/en/functions/strings/Substr.md b/docs/content/en/functions/strings/Substr.md index 19a029e28..a4c779f7d 100644 --- a/docs/content/en/functions/strings/Substr.md +++ b/docs/content/en/functions/strings/Substr.md @@ -3,16 +3,15 @@ title: strings.Substr description: Returns a substring of the given string, beginning with the start position and ending after the given length. categories: [] keywords: [] -action: - aliases: [substr] - related: - - functions/strings/SliceString - returnType: string - signatures: ['strings.Substr STRING [START] [LENGTH]'] +params: + functions_and_methods: + aliases: [substr] + returnType: string + signatures: ['strings.Substr STRING [START] [LENGTH]'] aliases: [/functions/substr] --- -The start position is zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. Specify a negative START position to extract characters from the end of the string. +The start position is zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. Specify a negative START position to extract characters from the end of the string. If LENGTH is not specified, the substring will include all characters from the START position to the end of the string. If negative, that number of characters will be omitted from the end of string. diff --git a/docs/content/en/functions/strings/Title.md b/docs/content/en/functions/strings/Title.md index b7f1f9e5c..d1b4aca01 100644 --- a/docs/content/en/functions/strings/Title.md +++ b/docs/content/en/functions/strings/Title.md @@ -3,14 +3,11 @@ title: strings.Title description: Returns the given string, converting it to title case. categories: [] keywords: [] -action: - aliases: [title] - related: - - functions/strings/FirstUpper - - functions/strings/ToLower - - functions/strings/ToUpper - returnType: string - signatures: [strings.Title STRING] +params: + functions_and_methods: + aliases: [title] + returnType: string + signatures: [strings.Title STRING] aliases: [/functions/title] --- @@ -29,4 +26,4 @@ The last option is useful if your theme uses the `title` function, and you would [Associated Press Stylebook]: https://www.apstylebook.com/ [Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html -[site configuration]: /getting-started/configuration/#configure-title-case +[site configuration]: /configuration/all/#title-case-style diff --git a/docs/content/en/functions/strings/ToLower.md b/docs/content/en/functions/strings/ToLower.md index 3da047ae4..c329b5e55 100644 --- a/docs/content/en/functions/strings/ToLower.md +++ b/docs/content/en/functions/strings/ToLower.md @@ -3,14 +3,11 @@ title: strings.ToLower description: Returns the given string, converting all characters to lowercase. categories: [] keywords: [] -action: - aliases: [lower] - related: - - functions/strings/FirstUpper - - functions/strings/Title - - functions/strings/ToUpper - returnType: string - signatures: [strings.ToLower INPUT] +params: + functions_and_methods: + aliases: [lower] + returnType: string + signatures: [strings.ToLower INPUT] aliases: [/functions/lower] --- diff --git a/docs/content/en/functions/strings/ToUpper.md b/docs/content/en/functions/strings/ToUpper.md index 617e1e68a..acccb4124 100644 --- a/docs/content/en/functions/strings/ToUpper.md +++ b/docs/content/en/functions/strings/ToUpper.md @@ -3,14 +3,11 @@ title: strings.ToUpper description: Returns the given string, converting all characters to uppercase. categories: [] keywords: [] -action: - aliases: [upper] - related: - - functions/strings/FirstUpper - - functions/strings/Title - - functions/strings/ToLower - returnType: string - signatures: [strings.ToUpper INPUT] +params: + functions_and_methods: + aliases: [upper] + returnType: string + signatures: [strings.ToUpper INPUT] aliases: [/functions/upper] --- diff --git a/docs/content/en/functions/strings/Trim.md b/docs/content/en/functions/strings/Trim.md index a8c4cf92d..1afa0627f 100644 --- a/docs/content/en/functions/strings/Trim.md +++ b/docs/content/en/functions/strings/Trim.md @@ -3,17 +3,11 @@ title: strings.Trim description: Returns the given string, removing leading and trailing characters specified in the cutset. categories: [] keywords: [] -action: - aliases: [trim] - related: - - functions/strings/Chomp - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.Trim INPUT CUTSET] +params: + functions_and_methods: + aliases: [trim] + returnType: string + signatures: [strings.Trim INPUT CUTSET] aliases: [/functions/trim] --- diff --git a/docs/content/en/functions/strings/TrimLeft.md b/docs/content/en/functions/strings/TrimLeft.md index d94aa05a3..c5d6ba60f 100644 --- a/docs/content/en/functions/strings/TrimLeft.md +++ b/docs/content/en/functions/strings/TrimLeft.md @@ -3,17 +3,11 @@ title: strings.TrimLeft description: Returns the given string, removing leading characters specified in the cutset. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimPrefix - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.TrimLeft CUTSET STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.TrimLeft CUTSET STRING] aliases: [/functions/strings.trimleft] --- diff --git a/docs/content/en/functions/strings/TrimPrefix.md b/docs/content/en/functions/strings/TrimPrefix.md index 331c52a03..b897d8777 100644 --- a/docs/content/en/functions/strings/TrimPrefix.md +++ b/docs/content/en/functions/strings/TrimPrefix.md @@ -3,17 +3,11 @@ title: strings.TrimPrefix description: Returns the given string, removing the prefix from the beginning of the string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.TrimPrefix PREFIX STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.TrimPrefix PREFIX STRING] aliases: [/functions/strings.trimprefix] --- diff --git a/docs/content/en/functions/strings/TrimRight.md b/docs/content/en/functions/strings/TrimRight.md index f36597d3d..05c2ed324 100644 --- a/docs/content/en/functions/strings/TrimRight.md +++ b/docs/content/en/functions/strings/TrimRight.md @@ -3,17 +3,11 @@ title: strings.TrimRight description: Returns the given string, removing trailing characters specified in the cutset. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.TrimRight CUTSET STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.TrimRight CUTSET STRING] aliases: [/functions/strings.trimright] --- diff --git a/docs/content/en/functions/strings/TrimSpace.md b/docs/content/en/functions/strings/TrimSpace.md index 7cb293674..cb38b5ab1 100644 --- a/docs/content/en/functions/strings/TrimSpace.md +++ b/docs/content/en/functions/strings/TrimSpace.md @@ -3,16 +3,10 @@ title: strings.TrimSpace description: Returns the given string, removing leading and trailing whitespace as defined by Unicode. categories: [] keywords: [] -action: - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimRight - - functions/strings/TrimSuffix - returnType: string - signatures: [strings.TrimSpace INPUT] +params: + functions_and_methods: + returnType: string + signatures: [strings.TrimSpace INPUT] --- {{< new-in 0.136.3 />}} diff --git a/docs/content/en/functions/strings/TrimSuffix.md b/docs/content/en/functions/strings/TrimSuffix.md index d612ae695..802842105 100644 --- a/docs/content/en/functions/strings/TrimSuffix.md +++ b/docs/content/en/functions/strings/TrimSuffix.md @@ -3,17 +3,11 @@ title: strings.TrimSuffix description: Returns the given string, removing the suffix from the end of the string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/strings/Chomp - - functions/strings/Trim - - functions/strings/TrimSpace - - functions/strings/TrimLeft - - functions/strings/TrimPrefix - - functions/strings/TrimRight - returnType: string - signatures: [strings.TrimSuffix SUFFIX STRING] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [strings.TrimSuffix SUFFIX STRING] aliases: [/functions/strings.trimsuffix] --- diff --git a/docs/content/en/functions/strings/Truncate.md b/docs/content/en/functions/strings/Truncate.md index 2e7693eb5..c4198229e 100644 --- a/docs/content/en/functions/strings/Truncate.md +++ b/docs/content/en/functions/strings/Truncate.md @@ -3,11 +3,11 @@ title: strings.Truncate description: Returns the given string, truncating it to a maximum length without cutting words or leaving unclosed HTML tags. categories: [] keywords: [] -action: - aliases: [truncate] - related: [] - returnType: template.HTML - signatures: ['strings.Truncate SIZE [ELLIPSIS] INPUT'] +params: + functions_and_methods: + aliases: [truncate] + returnType: template.HTML + signatures: ['strings.Truncate SIZE [ELLIPSIS] INPUT'] aliases: [/functions/truncate] --- @@ -17,8 +17,7 @@ Since Go templates are HTML-aware, `truncate` will intelligently handle normal s {{ "<em>Keep my HTML</em>" | safeHTML | truncate 10 }} → <em>Keep my …</em> ``` -{{% note %}} -If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. +> [!note] +> If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. [`safeHTML`]: /functions/safe/html/ -{{% /note %}} diff --git a/docs/content/en/functions/strings/_index.md b/docs/content/en/functions/strings/_index.md index 364522a3a..28f26f170 100644 --- a/docs/content/en/functions/strings/_index.md +++ b/docs/content/en/functions/strings/_index.md @@ -1,12 +1,7 @@ --- title: String functions linkTitle: strings -description: Template functions to work with strings. +description: Use these functions to work with strings. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with strings. diff --git a/docs/content/en/functions/templates/Defer.md b/docs/content/en/functions/templates/Defer.md index c43ef43bf..6a9ca56ae 100644 --- a/docs/content/en/functions/templates/Defer.md +++ b/docs/content/en/functions/templates/Defer.md @@ -3,18 +3,20 @@ title: templates.Defer description: Defer execution of a template until after all sites and output formats have been rendered. categories: [] keywords: [] -toc: true -action: - aliases: [] - related: [] - returnType: string - signatures: [templates.Defer OPTIONS] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [templates.Defer OPTIONS] aliases: [/functions/templates.defer] --- {{< new-in 0.128.0 />}} -In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/getting-started/configuration/#configure-build) to determine which classes and other HTML identifiers are being used in the final output: +> [!note] +> This feature is meant to be used in the main page layout files/templates, and has undefined behavior when used from shortcodes, partials or render hook templates. See [this issue](https://github.com/gohugoio/hugo/issues/13492#issuecomment-2734700391) for more info. + +In some rare use cases, you may need to defer the execution of a template until after all sites and output formats have been rendered. One such example could be [TailwindCSS](/functions/css/tailwindcss/) using the output of [hugo_stats.json](/configuration/build/) to determine which classes and other HTML identifiers are being used in the final output: ```go-html-template {{ with (templates.Defer (dict "key" "global")) }} @@ -42,13 +44,10 @@ In some rare use cases, you may need to defer the execution of a template until {{ end }} ``` -{{% note %}} -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 %}} +> [!note] +> This function only works in combination with the `with` keyword. +> +> Variables defined on the outside are not visible on the inside and vice versa. To pass in data, use the `data` [option](#options). For the above to work well when running the server (or `hugo -w`), you want to have a configuration similar to this: @@ -75,7 +74,7 @@ The `templates.Defer` function takes a single argument, a map with the following key (`string`) : The key to use for the deferred template. This will, combined with a hash of the template content, be used as a cache key. If this is not set, Hugo will execute the deferred template on every render. This is not what you want for shared resources like CSS and JavaScript. -data (`map`) +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 @@ -90,4 +89,4 @@ I18n Outside: {{ i18n "hello" }} {{ end }} ``` -The [Output Format](/templates/output-formats/), [Site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Lang` and `.RelPermalink` will be the same on the inside and the outside of the deferred template. +The [output format](/configuration/output-formats/), [site](/methods/page/site/), and [language](/methods/site/language) will be the same, even if the execution is deferred. In the example above, this means that the `site.Language.Lang` and `.RelPermalink` will be the same on the inside and the outside of the deferred template. diff --git a/docs/content/en/functions/templates/Exists.md b/docs/content/en/functions/templates/Exists.md index e57610488..79fc561c8 100644 --- a/docs/content/en/functions/templates/Exists.md +++ b/docs/content/en/functions/templates/Exists.md @@ -3,11 +3,11 @@ title: templates.Exists description: Reports whether a template file exists under the given path relative to the layouts directory. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: bool - signatures: [templates.Exists PATH] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [templates.Exists PATH] aliases: [/functions/templates.exists] --- diff --git a/docs/content/en/functions/templates/_index.md b/docs/content/en/functions/templates/_index.md index 89da6c38f..a385604ea 100644 --- a/docs/content/en/functions/templates/_index.md +++ b/docs/content/en/functions/templates/_index.md @@ -1,13 +1,7 @@ --- title: Template functions linkTitle: templates -description: +description: Use these functions to query the template system. categories: [] keywords: [] -menu: - docs: - identifier: templates-functions - parent: functions --- - -Use these functions to query the template system. diff --git a/docs/content/en/functions/time/AsTime.md b/docs/content/en/functions/time/AsTime.md index 92040f924..760329a13 100644 --- a/docs/content/en/functions/time/AsTime.md +++ b/docs/content/en/functions/time/AsTime.md @@ -3,17 +3,12 @@ title: time.AsTime description: Returns the given string representation of a date/time value as a time.Time value. categories: [] keywords: [] -action: - aliases: [time] - related: - - functions/time/Duration - - functions/time/Format - - functions/time/Now - - functions/time/ParseDuration - returnType: time.Time - signatures: ['time.AsTime INPUT [TIMEZONE]'] +params: + functions_and_methods: + aliases: [time] + returnType: time.Time + signatures: ['time.AsTime INPUT [TIMEZONE]'] aliases: [/functions/time] -toc: true --- ## Overview @@ -29,7 +24,7 @@ Hugo provides [functions] and [methods] to format, localize, parse, compare, and As shown above, the first argument must be a parsable string representation of a date/time value. For example: -{{% include "functions/time/_common/parsable-date-time-strings.md" %}} +{{% include "/_common/parsable-date-time-strings.md" %}} To override the default time zone, set the [`timeZone`] in your site configuration or provide a second argument to the `time.AsTime` function. For example: @@ -48,6 +43,6 @@ The order of precedence for determining the time zone is: [IANA Time Zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones [`time.Time`]: https://pkg.go.dev/time#Time -[`timeZone`]: /getting-started/configuration/#timezone +[`timeZone`]: /configuration/all/#timezone [functions]: /functions/time/ [methods]: /methods/time/ diff --git a/docs/content/en/functions/time/Duration.md b/docs/content/en/functions/time/Duration.md index 09e5d6725..bd6adfbfa 100644 --- a/docs/content/en/functions/time/Duration.md +++ b/docs/content/en/functions/time/Duration.md @@ -1,17 +1,13 @@ --- title: time.Duration -description: Returns a time.Duration value using the given time unit and number. +description: Returns a time.Duration value using the given time unit and number. categories: [] keywords: [] -action: - aliases: [duration] - related: - - functions/time/AsTime - - functions/time/Format - - functions/time/Now - - functions/time/ParseDuration - returnType: time.Duration - signatures: [time.Duration TIME_UNIT NUMBER] +params: + functions_and_methods: + aliases: [duration] + returnType: time.Duration + signatures: [time.Duration TIME_UNIT NUMBER] aliases: [/functions/duration] --- diff --git a/docs/content/en/functions/time/Format.md b/docs/content/en/functions/time/Format.md index cf7721376..f1b0d6d83 100644 --- a/docs/content/en/functions/time/Format.md +++ b/docs/content/en/functions/time/Format.md @@ -3,17 +3,12 @@ title: time.Format description: Returns the given date/time as a formatted and localized string. categories: [] keywords: [] -action: - aliases: [dateFormat] - related: - - functions/time/AsTime - - functions/time/Duration - - functions/time/Now - - functions/time/ParseDuration - returnType: string - signatures: [time.Format LAYOUT INPUT] +params: + functions_and_methods: + aliases: [dateFormat] + returnType: string + signatures: [time.Format LAYOUT INPUT] aliases: [/functions/dateformat] -toc: true --- Use the `time.Format` function with `time.Time` values: @@ -32,7 +27,7 @@ Or use `time.Format` with a parsable string representation of a date/time value: Examples of parsable string representations: -{{% include "functions/time/_common/parsable-date-time-strings.md" %}} +{{% include "/_common/parsable-date-time-strings.md" %}} To override the default time zone, set the [`timeZone`] in your site configuration. The order of precedence for determining the time zone is: @@ -40,17 +35,17 @@ To override the default time zone, set the [`timeZone`] in your site configurati 1. The time zone specified in your site configuration 1. The `Etc/UTC` time zone -[`timeZone`]: /getting-started/configuration/#timezone +[`timeZone`]: /configuration/all/#timezone ## Layout string -{{% include "functions/_common/time-layout-string.md" %}} +{{% include "/_common/time-layout-string.md" %}} ## Localization Use the `time.Format` function to localize `time.Time` values for the current language and region. -{{% include "functions/_common/locales.md" %}} +{{% include "/_common/functions/locales.md" %}} Use the layout string as described above, or one of the tokens below. For example: diff --git a/docs/content/en/functions/time/Now.md b/docs/content/en/functions/time/Now.md index 2994a9728..9b6fa4692 100644 --- a/docs/content/en/functions/time/Now.md +++ b/docs/content/en/functions/time/Now.md @@ -3,15 +3,11 @@ title: time.Now description: Returns the current local time. categories: [] keywords: [] -action: - aliases: [now] - related: - - functions/time/AsTime - - functions/time/Duration - - functions/time/Format - - functions/time/ParseDuration - returnType: time.Time - signatures: [time.Now] +params: + functions_and_methods: + aliases: [now] + returnType: time.Time + signatures: [time.Now] aliases: [/functions/now] --- diff --git a/docs/content/en/functions/time/ParseDuration.md b/docs/content/en/functions/time/ParseDuration.md index abb516361..af5d73ad5 100644 --- a/docs/content/en/functions/time/ParseDuration.md +++ b/docs/content/en/functions/time/ParseDuration.md @@ -3,15 +3,11 @@ title: time.ParseDuration description: Returns a time.Duration value by parsing the given duration string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/time/AsTime - - functions/time/Duration - - functions/time/Format - - functions/time/Now - returnType: time.Duration - signatures: [time.ParseDuration DURATION] +params: + functions_and_methods: + aliases: [] + returnType: time.Duration + signatures: [time.ParseDuration DURATION] aliases: [/functions/time.parseduration] --- diff --git a/docs/content/en/functions/time/_common/_index.md b/docs/content/en/functions/time/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/functions/time/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/functions/time/_common/parsable-date-time-strings.md b/docs/content/en/functions/time/_common/parsable-date-time-strings.md deleted file mode 100644 index 92842767e..000000000 --- a/docs/content/en/functions/time/_common/parsable-date-time-strings.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -Format|Time zone -:--|:-- -`2023-10-15T13:18:50-07:00`|`America/Los_Angeles` -`2023-10-15T13:18:50-0700`|`America/Los_Angeles` -`2023-10-15T13:18:50Z`|`Etc/UTC` -`2023-10-15T13:18:50`|Default is `Etc/UTC` -`2023-10-15`|Default is `Etc/UTC` -`15 Oct 2023`|Default is `Etc/UTC` - -The last three examples are not fully qualified, and default to the `Etc/UTC` time zone. diff --git a/docs/content/en/functions/time/_index.md b/docs/content/en/functions/time/_index.md index 7e0b82f91..9c2ff2161 100644 --- a/docs/content/en/functions/time/_index.md +++ b/docs/content/en/functions/time/_index.md @@ -1,12 +1,7 @@ --- title: Time functions linkTitle: time -description: Template functions to work with time values. +description: Use these functions to work with time values. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with time values. diff --git a/docs/content/en/functions/transform/CanHighlight.md b/docs/content/en/functions/transform/CanHighlight.md index 039cb12b7..c00445605 100644 --- a/docs/content/en/functions/transform/CanHighlight.md +++ b/docs/content/en/functions/transform/CanHighlight.md @@ -3,13 +3,11 @@ title: transform.CanHighlight description: Reports whether the given code language is supported by the Chroma highlighter. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/transform/Highlight - - functions/transform/HighlightCodeBlock - returnType: bool - signatures: [transform.CanHighlight LANGUAGE] +params: + functions_and_methods: + aliases: [] + returnType: bool + signatures: [transform.CanHighlight LANGUAGE] --- ```go-html-template diff --git a/docs/content/en/functions/transform/Emojify.md b/docs/content/en/functions/transform/Emojify.md index 5ca562db9..31c5dce70 100644 --- a/docs/content/en/functions/transform/Emojify.md +++ b/docs/content/en/functions/transform/Emojify.md @@ -3,11 +3,11 @@ title: transform.Emojify description: Runs a string through the Emoji emoticons processor. categories: [] keywords: [] -action: - aliases: [emojify] - related: [] - returnType: template.HTML - signatures: [transform.Emojify INPUT] +params: + functions_and_methods: + aliases: [emojify] + returnType: template.HTML + signatures: [transform.Emojify INPUT] aliases: [/functions/emojify] --- @@ -15,7 +15,7 @@ aliases: [/functions/emojify] 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; +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! @@ -23,7 +23,5 @@ I :heart: Hugo! I :heart: Hugo! -[configuration]: /getting-started/configuration/ +[`enableEmoji`]: /configuration/all/#enableemoji [emoji shortcodes]: /quick-reference/emojis/ -[sc]: /templates/shortcode/ -[scsource]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes diff --git a/docs/content/en/functions/transform/HTMLEscape.md b/docs/content/en/functions/transform/HTMLEscape.md index bb522769c..069fd92f2 100644 --- a/docs/content/en/functions/transform/HTMLEscape.md +++ b/docs/content/en/functions/transform/HTMLEscape.md @@ -3,12 +3,11 @@ title: transform.HTMLEscape description: Returns the given string, escaping special characters by replacing them with HTML entities. categories: [] keywords: [] -action: - aliases: [htmlEscape] - related: - - functions/transform/HTMLUnescape - returnType: string - signatures: [transform.HTMLEscape INPUT] +params: + functions_and_methods: + aliases: [htmlEscape] + returnType: string + signatures: [transform.HTMLEscape INPUT] aliases: [/functions/htmlescape] --- diff --git a/docs/content/en/functions/transform/HTMLUnescape.md b/docs/content/en/functions/transform/HTMLUnescape.md index 1c88de672..563e63cf6 100644 --- a/docs/content/en/functions/transform/HTMLUnescape.md +++ b/docs/content/en/functions/transform/HTMLUnescape.md @@ -3,12 +3,11 @@ title: transform.HTMLUnescape description: Returns the given string, replacing each HTML entity with its corresponding character. categories: [] keywords: [] -action: - aliases: [htmlUnescape] - related: - - functions/transform/HTMLEscape - returnType: string - signatures: [transform.HTMLUnescape INPUT] +params: + functions_and_methods: + aliases: [htmlUnescape] + returnType: string + signatures: [transform.HTMLUnescape INPUT] aliases: [/functions/htmlunescape] --- diff --git a/docs/content/en/functions/transform/Highlight.md b/docs/content/en/functions/transform/Highlight.md index 5eaa53939..5633f2256 100644 --- a/docs/content/en/functions/transform/Highlight.md +++ b/docs/content/en/functions/transform/Highlight.md @@ -2,22 +2,19 @@ title: transform.Highlight description: Renders code with a syntax highlighter. categories: [] -keywords: [] -action: - aliases: [highlight] - related: - - functions/transform/CanHighlight - - functions/transform/HighlightCodeBlock - returnType: template.HTML - signatures: ['transform.Highlight CODE LANG [OPTIONS]'] +keywords: [highlight] +params: + functions_and_methods: + aliases: [highlight] + returnType: template.HTML + 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 [highlighting styles]. [chroma]: https://github.com/alecthomas/chroma -[available styles]: https://xyproto.github.io/splash/docs/ +[highlighting styles]: /quick-reference/syntax-highlighting-styles/ ## Arguments @@ -30,10 +27,10 @@ LANG : (`string`) The language of the code to highlight. Choose from one of the [supported languages]. This value is case-insensitive. OPTIONS -: (`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. +: (`map or string`) A map or comma-separated key-value pairs wrapped in quotation marks. Set default values for each option in your [site configuration]. The key names are case-insensitive. -[site configuration]: /getting-started/configuration-markup#highlight -[supported languages]: /content-management/syntax-highlighting#list-of-chroma-highlighting-languages +[site configuration]: /configuration/markup#highlight +[supported languages]: /content-management/syntax-highlighting#languages ## Examples @@ -53,4 +50,4 @@ OPTIONS ## Options -{{% include "functions/_common/highlighting-options" %}} +{{% include "_common/syntax-highlighting-options.md" %}} diff --git a/docs/content/en/functions/transform/HighlightCodeBlock.md b/docs/content/en/functions/transform/HighlightCodeBlock.md index dc396bad0..bbebf9459 100644 --- a/docs/content/en/functions/transform/HighlightCodeBlock.md +++ b/docs/content/en/functions/transform/HighlightCodeBlock.md @@ -3,13 +3,11 @@ title: transform.HighlightCodeBlock description: Highlights code received in context within a code block render hook. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/transform/CanHighlight - - functions/transform/Highlight - returnType: highlight.HighlightResult - signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]'] +params: + functions_and_methods: + aliases: [] + returnType: highlight.HighlightResult + signatures: ['transform.HighlightCodeBlock CONTEXT [OPTIONS]'] --- This function is only useful within a code block render hook. diff --git a/docs/content/en/functions/transform/Markdownify.md b/docs/content/en/functions/transform/Markdownify.md index 7a84f43b7..c22de1efe 100644 --- a/docs/content/en/functions/transform/Markdownify.md +++ b/docs/content/en/functions/transform/Markdownify.md @@ -3,13 +3,11 @@ title: transform.Markdownify description: Renders Markdown to HTML. categories: [] keywords: [] -action: - aliases: [markdownify] - related: - - methods/page/RenderString - - methods/page/RenderShortcodes - returnType: template.HTML - signatures: [transform.Markdownify INPUT] +params: + functions_and_methods: + aliases: [markdownify] + returnType: template.HTML + signatures: [transform.Markdownify INPUT] aliases: [/functions/markdownify] --- @@ -21,11 +19,9 @@ If the resulting HTML is a single paragraph, Hugo removes the wrapping `p` tags To keep the wrapping `p` tags for a single paragraph, use the [`RenderString`] method on the `Page` object, setting the `display` option to `block`. -[`RenderString`]: /methods/page/renderstring/ - -{{% note %}} -Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. +> [!note] +> Although the `markdownify` function honors [Markdown render hooks] when rendering Markdown to HTML, use the `RenderString` method instead of `markdownify` if a render hook accesses `.Page` context. See issue [#9692] for details. -[Markdown render hooks]: /render-hooks/ [#9692]: https://github.com/gohugoio/hugo/issues/9692 -{{% /note %}} +[`RenderString`]: /methods/page/renderstring/ +[Markdown render hooks]: /render-hooks/ diff --git a/docs/content/en/functions/transform/Plainify.md b/docs/content/en/functions/transform/Plainify.md index 681d41f72..780cf461a 100644 --- a/docs/content/en/functions/transform/Plainify.md +++ b/docs/content/en/functions/transform/Plainify.md @@ -3,11 +3,11 @@ title: transform.Plainify description: Returns a string with all HTML tags removed. categories: [] keywords: [] -action: - aliases: [plainify] - related: [] - returnType: template.HTML - signatures: [transform.Plainify INPUT] +params: + functions_and_methods: + aliases: [plainify] + returnType: template.HTML + signatures: [transform.Plainify INPUT] aliases: [/functions/plainify] --- diff --git a/docs/content/en/functions/transform/PortableText.md b/docs/content/en/functions/transform/PortableText.md new file mode 100644 index 000000000..7baba99d4 --- /dev/null +++ b/docs/content/en/functions/transform/PortableText.md @@ -0,0 +1,213 @@ +--- +title: transform.PortableText +description: Converts Portable Text to Markdown. +categories: [] +keywords: [] +params: + functions_and_methods: + returnType: string + signatures: [transform.PortableText MAP] +--- + +{{< new-in "0.145.0" />}} + +[Portable Text](https://www.portabletext.org/) is a JSON structure that represent rich text content in the [Sanity](https://www.sanity.io/) CMS. In Hugo, this function is typically used in a [Content Adapter](https://gohugo.io/content-management/content-adapters/) that creates pages from Sanity data. + +## Types supported + +- `block` and `span` +- `image`. Note that the image handling is currently very simple; we link to the `asset.url` using `asset.altText` as the image alt text and `asset.title` as the title. For more fine grained control you may want to process the images in a [image render hook](/render-hooks/images/). +- `code` (see the [code-input](https://www.sanity.io/plugins/code-input) plugin). Code will be rendered as [fenced code blocks](/contribute/documentation/#fenced-code-blocks) with any file name provided passed on as a markdown attribute. + +> [!note] +> Since the Portable Text gets converted to Markdown before it gets passed to Hugo, rendering of links, headings, images and code blocks can be controlled with [Render Hooks](https://gohugo.io/render-hooks/). + +## Example + +### Content Adapter + +```go-html-template {file="content/_content.gotmpl" copy=true} +{{ $projectID := "mysanityprojectid" }} +{{ $useCached := true }} +{{ $api := "api" }} +{{ if $useCached }} + {{/* See https://www.sanity.io/docs/api-cdn */}} + {{ $api = "apicdn" }} +{{ end }} +{{ $url := printf "https://%s.%s.sanity.io/v2021-06-07/data/query/production" $projectID $api }} + +{{/* prettier-ignore-start */ -}} +{{ $q := `*[_type == 'post']{ + title, publishedAt, summary, slug, body[]{ + ..., + _type == "image" => { + ..., + asset->{ + _id, + path, + url, + altText, + title, + description, + metadata { + dimensions { + aspectRatio, + width, + height + } + } + } + } + }, + }` +}} +{{/* prettier-ignore-end */ -}} +{{ $body := dict "query" $q | jsonify }} +{{ $opts := dict "method" "post" "body" $body }} +{{ $r := resources.GetRemote $url $opts }} +{{ $m := $r | transform.Unmarshal }} +{{ $result := $m.result }} +{{ range $result }} + {{ if not .slug }} + {{ continue }} + {{ end }} + {{ $markdown := transform.PortableText .body }} + {{ $content := dict + "mediaType" "text/markdown" + "value" $markdown + }} + {{ $params := dict + "portabletext" (.body | jsonify (dict "indent" " ")) + }} + {{ $page := dict + "content" $content + "kind" "page" + "path" .slug.current + "title" .title + "date" (.publishedAt | time ) + "summary" .summary + "params" $params + }} + {{ $.AddPage $page }} +{{ end }} +``` + +### Sanity setup + +Below outlines a suitable Sanity studio setup for the above example. + +```ts {file="sanity.config.ts" copy=true} +import {defineConfig} from 'sanity' +import {structureTool} from 'sanity/structure' +import {visionTool} from '@sanity/vision' +import {schemaTypes} from './schemaTypes' +import {media} from 'sanity-plugin-media' +import {codeInput} from '@sanity/code-input' + +export default defineConfig({ + name: 'default', + title: 'my-sanity-project', + + projectId: 'mysanityprojectid', + dataset: 'production', + + plugins: [structureTool(), visionTool(), media(),codeInput()], + + schema: { + types: schemaTypes, + }, +}) +``` + +Type/schema definition: + +```ts {file="schemaTypes/postType.ts" copy=true} +import {defineField, defineType} from 'sanity' + +export const postType = defineType({ + name: 'post', + title: 'Post', + type: 'document', + fields: [ + defineField({ + name: 'title', + type: 'string', + validation: (rule) => rule.required(), + }), + defineField({ + name: 'summary', + type: 'string', + validation: (rule) => rule.required(), + }), + defineField({ + name: 'slug', + type: 'slug', + options: {source: 'title'}, + validation: (rule) => rule.required(), + }), + defineField({ + name: 'publishedAt', + type: 'datetime', + initialValue: () => new Date().toISOString(), + validation: (rule) => rule.required(), + }), + defineField({ + name: 'body', + type: 'array', + of: [ + { + type: 'block', + }, + { + type: 'image' + }, + { + type: 'code', + options: { + language: 'css', + languageAlternatives: [ + {title: 'HTML', value: 'html'}, + {title: 'CSS', value: 'css'}, + ], + withFilename: true, + }, + }, + ], + }), + ], +}) +``` + +Note that the above requires some additional plugins to be installed: + +```bash +npm i sanity-plugin-media @sanity/code-input +``` + +```ts {file="schemaTypes/index.ts" copy=true} +import {postType} from './postType' + +export const schemaTypes = [postType] +``` + +## Server setup + +Unfortunately, Sanity's API does not support [RFC 7234](https://tools.ietf.org/html/rfc7234) and their output changes even if the data has not. A recommended setup is therefore to use their cached `apicdn` endpoint (see above) and then set up a reasonable polling and file cache strategy in your Hugo configuration, e.g: + +{{< code-toggle file=hugo >}} +[HTTPCache] + [[HTTPCache.polls]] + disable = false + low = '30s' + high = '3m' + [HTTPCache.polls.for] + includes = ['https://*.*.sanity.io/**'] + +[caches.getresource] + dir = ':cacheDir/:project' + maxAge = "5m" +{{< /code-toggle >}} + +The polling above will be used when running the server/watch mode and rebuild when you push new content in Sanity. + +See [Caching in resources.GetRemote](/functions/resources/getremote/#caching) for more fine grained control. diff --git a/docs/content/en/functions/transform/Remarshal.md b/docs/content/en/functions/transform/Remarshal.md index 24ef4381d..ecf7fc905 100644 --- a/docs/content/en/functions/transform/Remarshal.md +++ b/docs/content/en/functions/transform/Remarshal.md @@ -3,23 +3,20 @@ title: transform.Remarshal description: Marshals a string of serialized data, or a map, into a string of serialized data in the specified format. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/encoding/Jsonify - - functions/transform/Unmarshal - returnType: string - signatures: [transform.Remarshal FORMAT INPUT] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [transform.Remarshal FORMAT INPUT] aliases: [/functions/transform.remarshal] --- The format must be one of `json`, `toml`, `yaml`, or `xml`. If the input is a string of serialized data, it must be valid JSON, TOML, YAML, or XML. -{{% note %}} -This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML. - -This is not a general purpose converter, and may change without notice if required for Hugo's documentation site. -{{% /note %}} +> [!note] +> This function is primarily a helper for Hugo's documentation, used to convert configuration and front matter examples to JSON, TOML, and YAML. +> +> This is not a general purpose converter, and may change without notice if required for Hugo's documentation site. Example 1 : Convert a string of TOML to JSON. diff --git a/docs/content/en/functions/transform/ToMath.md b/docs/content/en/functions/transform/ToMath.md index 10cd256c5..a9f12c546 100644 --- a/docs/content/en/functions/transform/ToMath.md +++ b/docs/content/en/functions/transform/ToMath.md @@ -2,35 +2,27 @@ title: transform.ToMath description: Renders mathematical equations and expressions written in the LaTeX markup language. categories: [] -keywords: [katex,latex,math,typesetting] -action: - aliases: [] - related: - - content-management/mathematics - returnType: types.Result[template.HTML] - signatures: ['transform.ToMath INPUT [OPTIONS]'] +keywords: [] +params: + functions_and_methods: + aliases: [] + returnType: types.Result[template.HTML] + signatures: ['transform.ToMath INPUT [OPTIONS]'] aliases: [/functions/tomath] -toc: true --- {{< new-in 0.132.0 />}} 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. -[KaTeX]: https://katex.org/ - ```go-html-template {{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }} ``` -{{% 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 %}} +> [!note] +> By default, Hugo renders mathematical markup to [MathML], and does not require any CSS to display the result. +> +> To optimize rendering quality and accessibility, use the `htmlAndMathml` output option as described below. This approach requires an external stylesheet. ```go-html-template {{ $opts := dict "output" "htmlAndMathml" }} @@ -41,18 +33,14 @@ To optimize rendering quality and accessibility, use the `htmlAndMathml` output 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`. +: (`bool`) Whether to render in display mode instead of 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`. +: (`bool`) Whether to 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 `{}`. @@ -78,7 +66,7 @@ output <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`. +: (`bool`) Whether to throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTeX. Default is `true`. ## Error handling @@ -94,12 +82,10 @@ The example below demonstrates error handing within a template. 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 +### 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 @@ -109,48 +95,45 @@ 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 %}} +> [!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. -###### Step 2 +### 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 >}} +```go-html-template {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 }} + {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }} {{- else }} {{- .Value }} {{- $.Page.Store.Set "hasMath" true }} {{- end }} {{- end -}} -{{< /code >}} +``` -###### Step 3 +### Step 3 In your base template, conditionally include the KaTeX CSS within the head element. -{{< code file=layouts/_default/baseof.html copy=true >}} +```go-html-template {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 +### Step 4 Add some mathematical markup to your content, then test. -{{< code file=content/example.md >}} +```text {file="content/example.md"} This is an inline \(a^*=x-b^*\) equation. These are block equations: @@ -158,4 +141,24 @@ These are block equations: \[a^*=x-b^*\] $$a^*=x-b^*$$ -{{< /code >}} +``` + +## Chemistry + +{{< new-in 0.144.0 />}} + +You can also use the `transform.ToMath` function to render chemical equations, leveraging the `\ce` and `\pu` functions from the [mhchem] package. + +```text +$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ +``` + +$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$ + +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color +[KaTeX]: https://katex.org/ +[MathML]: https://developer.mozilla.org/en-US/docs/Web/MathML +[mhchem]: https://mhchem.github.io/MathJax-mhchem/ +[passthrough extension]: /configuration/markup/#passthrough +[passthrough render hook]: /render-hooks/passthrough/ +[rendering options]: https://katex.org/docs/options.html diff --git a/docs/content/en/functions/transform/Unmarshal.md b/docs/content/en/functions/transform/Unmarshal.md index e50fc0ee0..d159122f5 100644 --- a/docs/content/en/functions/transform/Unmarshal.md +++ b/docs/content/en/functions/transform/Unmarshal.md @@ -3,16 +3,11 @@ title: transform.Unmarshal description: Parses serialized data and returns a map or an array. Supports CSV, JSON, TOML, YAML, and XML. categories: [] keywords: [] -action: - aliases: [unmarshal] - related: - - functions/transform/Remarshal - - functions/resources/Get - - functions/resources/GetRemote - - functions/encoding/Jsonify - returnType: any - signatures: ['transform.Unmarshal [OPTIONS] INPUT'] -toc: true +params: + functions_and_methods: + aliases: [unmarshal] + returnType: any + signatures: ['transform.Unmarshal [OPTIONS] INPUT'] aliases: [/functions/transform.unmarshal] --- @@ -112,15 +107,12 @@ A remote resource is a file on a remote server, accessible via HTTP or HTTPS. {{ end }} ``` -{{% note %}} -When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. - -In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: - -`{{ $data = .Content | transform.Unmarshal }}` - -[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type -{{% /note %}} +> [!note] +> When retrieving remote data, a misconfigured server may send a response header with an incorrect [Content-Type]. For example, the server may set the Content-Type header to `application/octet-stream` instead of `application/json`. +> +> In these cases, pass the resource `Content` through the `transform.Unmarshal` function instead of passing the resource itself. For example, in the above, do this instead: +> +> `{{ $data = .Content | transform.Unmarshal }}` ## Options @@ -132,8 +124,9 @@ delimiter comment : (`string`) The comment character used in the CSV. If set, lines beginning with the comment character without preceding whitespace are ignored. -lazyQuotes {{< new-in 0.122.0 />}} -: (`bool`) If true, a quote may appear in an unquoted field and a non-doubled quote may appear in a quoted field. Default is `false`. +lazyQuotes +: {{< new-in 0.122.0 />}} +: (`bool`) Whether to allow a quote in an unquoted field, or to allow a non-doubled quote in a quoted field. Default is `false`. ```go-html-template {{ $csv := "a;b;c" | transform.Unmarshal (dict "delimiter" ";") }} @@ -296,4 +289,5 @@ Hugo renders this to: ``` [`index`]: /functions/collections/indexfunction/ +[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type [page bundle]: /content-management/page-bundles/ diff --git a/docs/content/en/functions/transform/XMLEscape.md b/docs/content/en/functions/transform/XMLEscape.md index 291f0f622..9e6c77927 100644 --- a/docs/content/en/functions/transform/XMLEscape.md +++ b/docs/content/en/functions/transform/XMLEscape.md @@ -3,11 +3,11 @@ title: transform.XMLEscape description: Returns the given string, removing disallowed characters then escaping the result to its XML equivalent. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: string - signatures: [transform.XMLEscape INPUT] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [transform.XMLEscape INPUT] --- {{< new-in 0.121.0 />}} @@ -31,9 +31,9 @@ For example: When using `transform.XMLEscape` in a template rendered by Go's [html/template] package, declare the string to be safe HTML to avoid double escaping. For example, in an RSS template: -{{< code file="layouts/_default/rss.xml" >}} +```xml {file="layouts/_default/rss.xml"} <description>{{ .Summary | transform.XMLEscape | safeHTML }}</description> -{{< /code >}} +``` [disallowed characters]: https://www.w3.org/TR/xml/#charsets [html entities]: https://developer.mozilla.org/en-us/docs/glossary/entity diff --git a/docs/content/en/functions/transform/_index.md b/docs/content/en/functions/transform/_index.md index 70e286b24..19c271b65 100644 --- a/docs/content/en/functions/transform/_index.md +++ b/docs/content/en/functions/transform/_index.md @@ -1,12 +1,7 @@ --- title: Transform functions linkTitle: transform -description: Template functions to transform values from one format to another. +description: Use these functions to transform values from one format to another. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to transform values from one format to another. diff --git a/docs/content/en/functions/urls/AbsLangURL.md b/docs/content/en/functions/urls/AbsLangURL.md index 67e1781e7..da45ca224 100644 --- a/docs/content/en/functions/urls/AbsLangURL.md +++ b/docs/content/en/functions/urls/AbsLangURL.md @@ -3,50 +3,56 @@ title: urls.AbsLangURL description: Returns an absolute URL with a language prefix, if any. categories: [] keywords: [] -action: - aliases: [absLangURL] - related: - - functions/urls/AbsURL - - functions/urls/RelLangURL - - functions/urls/RelURL - returnType: string - signatures: [urls.AbsLangURL INPUT] +params: + functions_and_methods: + aliases: [absLangURL] + returnType: string + signatures: [urls.AbsLangURL INPUT] aliases: [/functions/abslangurl] --- Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on: -- Whether the input begins with a slash -- The `baseURL` in site configuration +- Whether the input begins with a slash (`/`) +- The `baseURL` in your site configuration - The language prefix, if any -In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site. +This is the site configuration for the examples that follow: -### Input does not begin with a slash +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = true +[languages.en] +weight = 1 +[languages.es] +weight = 2 +{{< /code-toggle >}} + +## Input does not begin with a slash If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration. -With `baseURL = https://example.org/` +When rendering the `en` site with `baseURL = https://example.org/` ```go-html-template -{{ absLangURL "" }} → https://example.org/en/ -{{ absLangURL "articles" }} → https://example.org/en/articles -{{ absLangURL "style.css" }} → https://example.org/en/style.css +{{ absLangURL "" }} → https://example.org/en/ +{{ absLangURL "articles" }} → https://example.org/en/articles +{{ absLangURL "style.css" }} → https://example.org/en/style.css ``` -With `baseURL = https://example.org/docs/` +When rendering the `en` site with `baseURL = https://example.org/docs/` ```go-html-template -{{ absLangURL "" }} → https://example.org/docs/en/ -{{ absLangURL "articles" }} → https://example.org/docs/en/articles -{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css +{{ absLangURL "" }} → https://example.org/docs/en/ +{{ absLangURL "articles" }} → https://example.org/docs/en/articles +{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css ``` -### Input begins with a slash +## Input begins with a slash If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration. -With `baseURL = https://example.org/` +When rendering the `en` site with `baseURL = https://example.org/` ```go-html-template {{ absLangURL "/" }} → https://example.org/en/ @@ -54,10 +60,13 @@ With `baseURL = https://example.org/` {{ absLangURL "/style.css" }} → https://example.org/en/style.css ``` -With `baseURL = https://example.org/docs/` +When rendering the `en` site with `baseURL = https://example.org/docs/` ```go-html-template {{ absLangURL "/" }} → https://example.org/en/ {{ absLangURL "/articles" }} → https://example.org/en/articles {{ absLangURL "/style.css" }} → https://example.org/en/style.css ``` + +> [!note] +> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash. diff --git a/docs/content/en/functions/urls/AbsURL.md b/docs/content/en/functions/urls/AbsURL.md index 1120eac42..72613cd0b 100644 --- a/docs/content/en/functions/urls/AbsURL.md +++ b/docs/content/en/functions/urls/AbsURL.md @@ -3,23 +3,20 @@ title: urls.AbsURL description: Returns an absolute URL. categories: [] keywords: [] -action: - aliases: [absURL] - related: - - functions/urls/AbsLangURL - - functions/urls/RelLangURL - - functions/urls/RelURL - returnType: string - signatures: [urls.AbsURL INPUT] +params: + functions_and_methods: + aliases: [absURL] + returnType: string + signatures: [urls.AbsURL INPUT] aliases: [/functions/absurl] --- With multilingual configurations, use the [`urls.AbsLangURL`] function instead. The URL returned by this function depends on: -- Whether the input begins with a slash -- The `baseURL` in site configuration +- Whether the input begins with a slash (`/`) +- The `baseURL` in your site configuration -### Input does not begin with a slash +## Input does not begin with a slash If the input does not begin with a slash, the path in the resulting URL will be relative to the `baseURL` in your site configuration. @@ -39,7 +36,7 @@ With `baseURL = https://example.org/docs/` {{ absURL "style.css" }} → https://example.org/docs/style.css ``` -#### Input begins with a slash +## Input begins with a slash If the input begins with a slash, the path in the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration. @@ -59,4 +56,7 @@ With `baseURL = https://example.org/docs/` {{ absURL "/style.css" }} → https://example.org/style.css ``` +> [!note] +> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash. + [`urls.AbsLangURL`]: /functions/urls/abslangurl/ diff --git a/docs/content/en/functions/urls/Anchorize.md b/docs/content/en/functions/urls/Anchorize.md index d8866ae05..d18bd9a4d 100644 --- a/docs/content/en/functions/urls/Anchorize.md +++ b/docs/content/en/functions/urls/Anchorize.md @@ -3,16 +3,15 @@ title: urls.Anchorize description: Returns the given string, sanitized for usage in an HTML id attribute. categories: [] keywords: [] -action: - aliases: [anchorize] - related: - - functions/urls/URLize - returnType: string - signatures: [urls.Anchorize INPUT] +params: + functions_and_methods: + aliases: [anchorize] + returnType: string + signatures: [urls.Anchorize INPUT] aliases: [/functions/anchorize] --- -{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} +{{% include "/_common/functions/urls/anchorize-vs-urlize.md" %}} ## Sanitizing logic @@ -31,7 +30,7 @@ github : Compatible with GitHub. This is the default. github-ascii -: Similar to the `github` setting, but removes non-ASCII characters. +: Similar to the `github` setting, but removes non-ASCII characters. blackfriday : Provided for backwards compatibility with Hugo v0.59.1 and earlier. This option will be removed in a future release. diff --git a/docs/content/en/functions/urls/JoinPath.md b/docs/content/en/functions/urls/JoinPath.md index bdff5f4b2..b9da7e437 100644 --- a/docs/content/en/functions/urls/JoinPath.md +++ b/docs/content/en/functions/urls/JoinPath.md @@ -3,12 +3,11 @@ title: urls.JoinPath description: Joins the provided elements into a URL string and cleans the result of any ./ or ../ elements. If the argument list is empty, JoinPath returns an empty string. categories: [] keywords: [] -action: - aliases: [] - related: - - functions/path/Join - returnType: string - signatures: [urls.JoinPath ELEMENT...] +params: + functions_and_methods: + aliases: [] + returnType: string + signatures: [urls.JoinPath ELEMENT...] aliases: [/functions/urls.joinpath] --- diff --git a/docs/content/en/functions/urls/Parse.md b/docs/content/en/functions/urls/Parse.md index a64116254..7def5fb1d 100644 --- a/docs/content/en/functions/urls/Parse.md +++ b/docs/content/en/functions/urls/Parse.md @@ -3,11 +3,11 @@ title: urls.Parse description: Parses a URL into a URL structure. categories: [] keywords: [] -action: - aliases: [] - related: [] - returnType: url.URL - signatures: [urls.Parse URL] +params: + functions_and_methods: + aliases: [] + returnType: url.URL + signatures: [urls.Parse URL] aliases: [/functions/urls.parse] --- @@ -26,6 +26,7 @@ The `urls.Parse` function parses a URL into a [URL structure](https://godoc.org/ {{ $u.Hostname }} → example.org {{ $u.RequestURI }} → /foo?a=6&b=7 {{ $u.Path }} → /foo +{{ $u.RawQuery }} → a=6&b=7 {{ $u.Query }} → map[a:[6] b:[7]] {{ $u.Query.a }} → [6] {{ $u.Query.Get "a" }} → 6 diff --git a/docs/content/en/functions/urls/Ref.md b/docs/content/en/functions/urls/Ref.md index d8fe6f26c..92abed91a 100644 --- a/docs/content/en/functions/urls/Ref.md +++ b/docs/content/en/functions/urls/Ref.md @@ -1,63 +1,46 @@ --- title: urls.Ref -description: Returns the absolute permalink to a page at the given path. +description: Returns the absolute URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - aliases: [ref] - related: - - functions/urls/RelRef - - methods/page/Ref - - methods/page/RelRef - returnType: string - signatures: - - urls.Ref PAGE PATH - - urls.Ref PAGE OPTIONS +params: + functions_and_methods: + aliases: [ref] + returnType: string + signatures: + - urls.Ref PAGE PATH + - urls.Ref PAGE OPTIONS aliases: [/functions/ref] --- -The first argument is the context of the page from which to resolve relative paths, typically the current page. +## Usage -The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path. +The `ref` function takes two arguments: -```go-html-template -{{ ref . "about" }} -{{ ref . "about#anchor" }} -{{ ref . "about.md" }} -{{ ref . "about.md#anchor" }} -{{ ref . "#anchor" }} -{{ ref . "/blog/my-post" }} -{{ ref . "/blog/my-post.md" }} -``` +1. The context for resolving relative paths (typically the current page). +1. Either the target page's path or an options map (see below). ## Options -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. - -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +{{% include "_common/ref-and-relref-options.md" %}} -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. +## Examples -To return the absolute permalink to another language version of a page: +The following examples show the rendered output for a page on the English version of the site: ```go-html-template -{{ ref . (dict "path" "about.md" "lang" "fr") }} -``` +{{ ref . "/books/book-1" }} → https://example.org/en/books/book-1/ -To return the absolute permalink to another Output Format of a page: +{{ $opts := dict "path" "/books/book-1" }} +{{ ref . $opts }} → https://example.org/en/books/book-1/ -```go-html-template -{{ ref . (dict "path" "about.md" "outputFormat" "rss") }} +{{ $opts := dict "path" "/books/book-1" "lang" "de" }} +{{ ref . $opts }} → https://example.org/de/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} +{{ ref . $opts }} → https://example.org/de/books/book-1/index.json ``` -By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/docs/content/en/functions/urls/RelLangURL.md b/docs/content/en/functions/urls/RelLangURL.md index 883e7dda2..af8bff3d7 100644 --- a/docs/content/en/functions/urls/RelLangURL.md +++ b/docs/content/en/functions/urls/RelLangURL.md @@ -3,52 +3,66 @@ title: urls.RelLangURL description: Returns a relative URL with a language prefix, if any. categories: [] keywords: [] -action: - aliases: [relLangURL] - related: - - functions/urls/AbsLangURL - - functions/urls/AbsURL - - functions/urls/RelURL - returnType: string - signatures: [urls.RelLangURL INPUT] +params: + functions_and_methods: + aliases: [relLangURL] + returnType: string + signatures: [urls.RelLangURL INPUT] aliases: [/functions/rellangurl] --- Use this function with both monolingual and multilingual configurations. The URL returned by this function depends on: -- Whether the input begins with a slash +- Whether the input begins with a slash (`/`) - The `baseURL` in your site configuration - The language prefix, if any -In examples that follow, the project is multilingual with content in both English (`en`) and Spanish (`es`). The returned values are from the English site. +This is the site configuration for the examples that follow: -### Input does not begin with a slash +{{< code-toggle file=hugo >}} +defaultContentLanguage = 'en' +defaultContentLanguageInSubdir = true +[languages.en] +weight = 1 +[languages.es] +weight = 2 +{{< /code-toggle >}} + +## Input does not begin with a slash If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration. -With `baseURL = https://example.org/` +When rendering the `en` site with `baseURL = https://example.org/` ```go-html-template -{{ relLangURL "" }} → /en/ -{{ relLangURL "articles" }} → /en/articles -{{ relLangURL "style.css" }} → /en/style.css -{{ relLangURL "https://example.org/foo" }} → /en/foo +{{ relLangURL "" }} → /en/ +{{ relLangURL "articles" }} → /en/articles +{{ relLangURL "style.css" }} → /en/style.css +{{ relLangURL "https://example.org" }} → https://example.org +{{ relLangURL "https://example.org/" }} → /en +{{ relLangURL "https://www.example.org" }} → https://www.example.org +{{ relLangURL "https://www.example.org/" }} → https://www.example.org/ ``` -With `baseURL = https://example.org/docs/` +When rendering the `en` site with `baseURL = https://example.org/docs/` ```go-html-template -{{ relLangURL "" }} → /docs/en/ -{{ relLangURL "articles" }} → /docs/en/articles -{{ relLangURL "style.css" }} → /docs/en/style.css -{{ relLangURL "https://example.org/docs/foo" }} → /docs/en/foo +{{ relLangURL "" }} → /docs/en/ +{{ relLangURL "articles" }} → /docs/en/articles +{{ relLangURL "style.css" }} → /docs/en/style.css +{{ relLangURL "https://example.org" }} → https://example.org +{{ relLangURL "https://example.org/" }} → https://example.org/ +{{ relLangURL "https://example.org/docs" }} → https://example.org/docs +{{ relLangURL "https://example.org/docs/" }} → /docs/en +{{ relLangURL "https://www.example.org" }} → https://www.example.org +{{ relLangURL "https://www.example.org/" }} → https://www.example.org/ ``` -#### Input begins with a slash +## Input begins with a slash If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration. -With `baseURL = https://example.org/` +When rendering the `en` site with `baseURL = https://example.org/` ```go-html-template {{ relLangURL "/" }} → /en/ @@ -56,10 +70,13 @@ With `baseURL = https://example.org/` {{ relLangURL "/style.css" }} → /en/style.css ``` -With `baseURL = https://example.org/docs/` +When rendering the `en` site with `baseURL = https://example.org/docs/` ```go-html-template {{ relLangURL "/" }} → /en/ {{ relLangURL "/articles" }} → /en/articles {{ relLangURL "/style.css" }} → /en/style.css ``` + +> [!note] +> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash. diff --git a/docs/content/en/functions/urls/RelRef.md b/docs/content/en/functions/urls/RelRef.md index 74e1b5650..aa7acf50b 100644 --- a/docs/content/en/functions/urls/RelRef.md +++ b/docs/content/en/functions/urls/RelRef.md @@ -1,70 +1,46 @@ --- title: urls.RelRef -description: Returns the relative permalink to a page at the given path. +description: Returns the relative URL of the page with the given path, language, and output format. categories: [] keywords: [] -action: - aliases: [relref] - related: - - functions/urls/Ref - - methods/page/Ref - - methods/page/RelRef - returnType: string - signatures: - - urls.RelRef PAGE PATH - - urls.RelRef PAGE OPTIONS +params: + functions_and_methods: + aliases: [relref] + returnType: string + signatures: + - urls.RelRef PAGE PATH + - urls.RelRef PAGE OPTIONS aliases: [/functions/relref] --- -The first argument is the context of the page from which to resolve relative paths, typically the current page. +## Usage -The second argument is a path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. Alternatively, provide an [options map](#options) instead of a path. -. -```go-html-template -{{ relref . "about" }} -{{ relref . "about#anchor" }} -{{ relref . "about.md" }} -{{ relref . "about.md#anchor" }} -{{ relref . "#anchor" }} -{{ relref . "/blog/my-post" }} -{{ relref . "/blog/my-post.md" }} -``` +The `relref` function takes two arguments: -The permalink returned is relative to the protocol+host portion of the baseURL specified in the site configuration. For example: - -Code|baseURL|Permalink -:--|:--|:-- -`{{ relref . "/about" }}`|`https://example.org/`|`/about/` -`{{ relref . "/about" }}`|`https://example.org/x/`|`/x/about/` +1. The context for resolving relative paths (typically the current page). +1. Either the target page's path or an options map (see below). ## Options -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. +{{% include "_common/ref-and-relref-options.md" %}} -lang -: (`string`) The language (site) to search for the page. Default is the current language. Optional. +## Examples -outputFormat -: (`string`) The output format to search for the page. Default is the current output format. Optional. - -To return the relative permalink to another language version of a page: +The following examples show the rendered output for a page on the English version of the site: ```go-html-template -{{ relref . (dict "path" "about.md" "lang" "fr") }} -``` +{{ relref . "/books/book-1" }} → /en/books/book-1/ -To return the relative permalink to another Output Format of a page: +{{ $opts := dict "path" "/books/book-1" }} +{{ relref . $opts }} → /en/books/book-1/ -```go-html-template -{{ relref . (dict "path" "about.md" "outputFormat" "rss") }} +{{ $opts := dict "path" "/books/book-1" "lang" "de" }} +{{ relref . $opts }} → /de/books/book-1/ + +{{ $opts := dict "path" "/books/book-1" "lang" "de" "outputFormat" "json" }} +{{ relref . $opts }} → /de/books/book-1/index.json ``` -By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved. +## Error handling -{{< code-toggle file=hugo >}} -refLinksErrorLevel = 'warning' -refLinksNotFoundURL = '/some/other/url' -{{< /code-toggle >}} +{{% include "_common/ref-and-relref-error-handling.md" %}} diff --git a/docs/content/en/functions/urls/RelURL.md b/docs/content/en/functions/urls/RelURL.md index 18ac24d10..0aef4043f 100644 --- a/docs/content/en/functions/urls/RelURL.md +++ b/docs/content/en/functions/urls/RelURL.md @@ -3,45 +3,50 @@ title: urls.RelURL description: Returns a relative URL. categories: [] keywords: [] -action: - aliases: [relURL] - related: - - functions/urls/AbsLangURL - - functions/urls/AbsURL - - functions/urls/RelLangURL - returnType: string - signatures: [urls.RelURL INPUT] +params: + functions_and_methods: + aliases: [relURL] + returnType: string + signatures: [urls.RelURL INPUT] aliases: [/functions/relurl] --- With multilingual configurations, use the [`urls.RelLangURL`] function instead. The URL returned by this function depends on: -- Whether the input begins with a slash +- Whether the input begins with a slash (`/`) - The `baseURL` in your site configuration -### Input does not begin with a slash +## Input does not begin with a slash If the input does not begin with a slash, the resulting URL will be relative to the `baseURL` in your site configuration. With `baseURL = https://example.org/` ```go-html-template -{{ relURL "" }} → / -{{ relURL "articles" }} → /articles -{{ relURL "style.css" }} → /style.css -{{ relURL "https://example.org/foo" }} → /foo +{{ relURL "" }} → / +{{ relURL "articles" }} → /articles +{{ relURL "style.css" }} → /style.css +{{ relURL "https://example.org" }} → https://example.org +{{ relURL "https://example.org/" }} → / +{{ relURL "https://www.example.org" }} → https://www.example.org +{{ relURL "https://www.example.org/" }} → https://www.example.org/ ``` With `baseURL = https://example.org/docs/` ```go-html-template -{{ relURL "" }} → /docs/ -{{ relURL "articles" }} → /docs/articles -{{ relURL "style.css" }} → /docs/style.css -{{ relURL "https://example.org/docs/foo" }} → /docs/foo +{{ relURL "" }} → /docs/ +{{ relURL "articles" }} → /docs/articles +{{ relURL "style.css" }} → /docs/style.css +{{ relURL "https://example.org" }} → https://example.org +{{ relURL "https://example.org/" }} → https://example.org/ +{{ relURL "https://example.org/docs" }} → https://example.org/docs +{{ relURL "https://example.org/docs/" }} → /docs +{{ relURL "https://www.example.org" }} → https://www.example.org +{{ relURL "https://www.example.org/" }} → https://www.example.org/ ``` -#### Input begins with a slash +## Input begins with a slash If the input begins with a slash, the resulting URL will be relative to the protocol+host of the `baseURL` in your site configuration. @@ -61,4 +66,7 @@ With `baseURL = https://example.org/docs/` {{ relURL "/style.css" }} → /style.css ``` +> [!note] +> As illustrated by the previous example, using a leading slash is rarely desirable and can lead to unexpected outcomes. In nearly all cases, omit the leading slash. + [`urls.RelLangURL`]: /functions/urls/rellangurl/ diff --git a/docs/content/en/functions/urls/URLize.md b/docs/content/en/functions/urls/URLize.md index 12e5203c4..b0cc812ec 100644 --- a/docs/content/en/functions/urls/URLize.md +++ b/docs/content/en/functions/urls/URLize.md @@ -3,16 +3,15 @@ title: urls.URLize description: Returns the given string, sanitized for usage in a URL. categories: [] keywords: [] -action: - aliases: [urlize] - related: - - functions/urls/Anchorize - returnType: string - signatures: [urls.URLize INPUT] +params: + functions_and_methods: + aliases: [urlize] + returnType: string + signatures: [urls.URLize INPUT] aliases: [/functions/urlize] --- -{{% include "/functions/urls/_common/anchorize-vs-urlize.md" %}} +{{% include "/_common/functions/urls/anchorize-vs-urlize.md" %}} ## Example diff --git a/docs/content/en/functions/urls/_common/_index.md b/docs/content/en/functions/urls/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/docs/content/en/functions/urls/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - -<!-- -Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required. - -Include the rendered content using the "include" shortcode. ---> diff --git a/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md b/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md deleted file mode 100644 index 710a3c592..000000000 --- a/docs/content/en/functions/urls/_common/anchorize-vs-urlize.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -_comment: Do not remove front matter. ---- - -The [`anchorize`] and [`urlize`] functions are similar: - -[`anchorize`]: /functions/urls/anchorize/ -[`urlize`]: /functions/urls/urlize/ - -- Use the `anchorize` function to generate an HTML `id` attribute value -- Use the `urlize` function to sanitize a string for usage in a URL - -For example: - -```go-html-template -{{ $s := "A B C" }} -{{ $s | anchorize }} → a-b-c -{{ $s | urlize }} → a-b-c - -{{ $s := "a b c" }} -{{ $s | anchorize }} → a-b---c -{{ $s | urlize }} → a-b-c - -{{ $s := "< a, b, & c >" }} -{{ $s | anchorize }} → -a-b--c- -{{ $s | urlize }} → a-b-c - -{{ $s := "main.go" }} -{{ $s | anchorize }} → maingo -{{ $s | urlize }} → main.go - -{{ $s := "Hugö" }} -{{ $s | anchorize }} → hugö -{{ $s | urlize }} → hug%C3%B6 -``` diff --git a/docs/content/en/functions/urls/_index.md b/docs/content/en/functions/urls/_index.md index 5f16feeeb..3a1962d7a 100644 --- a/docs/content/en/functions/urls/_index.md +++ b/docs/content/en/functions/urls/_index.md @@ -1,12 +1,7 @@ --- title: URL functions linkTitle: urls -description: Template functions to work with URLs. +description: Use these functions to work with URLs. categories: [] keywords: [] -menu: - docs: - parent: functions --- - -Use these functions to work with URLs. |