diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-08-30 19:24:34 +0200 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-08-30 19:24:34 +0200 |
commit | db45dbbee8ad59c9f585db2828dcf9284220b62f (patch) | |
tree | d7cfb67244ea2558d5b6da2688f0b46ed67e8cd6 /docs/content/en/functions | |
parent | e847a98db62872a72b9aa95933f1d7262a9d1c0b (diff) | |
parent | 77b976dd92b4f66657d83d875aef0c617df492d9 (diff) |
Merge commit '77b976dd92b4f66657d83d875aef0c617df492d9'
Diffstat (limited to 'docs/content/en/functions')
21 files changed, 211 insertions, 49 deletions
diff --git a/docs/content/en/functions/anchorize.md b/docs/content/en/functions/anchorize.md index 51ef67bb2..91d6b4fe7 100644 --- a/docs/content/en/functions/anchorize.md +++ b/docs/content/en/functions/anchorize.md @@ -1,6 +1,6 @@ --- title: anchorize -description: Takes a string and sanitizes it the same way as the [`defaultMarkdownHandler`](/getting-started/configuration-markup#configure-markup) does for markdown headers. +description: Takes a string and sanitizes it the same way as the [`defaultMarkdownHandler`](/getting-started/configuration-markup#default-configuration) does for markdown headers. categories: [functions] menu: docs: diff --git a/docs/content/en/functions/append.md b/docs/content/en/functions/append.md index 6d7ffa245..e734eac2b 100644 --- a/docs/content/en/functions/append.md +++ b/docs/content/en/functions/append.md @@ -1,37 +1,99 @@ --- title: append -description: "`append` appends one or more values to a slice and returns the resulting slice." +description: Appends one or more elements to a slice and returns the resulting slice. categories: [functions] menu: docs: parent: functions keywords: [collections] -signature: ["COLLECTION | append VALUE [VALUE]...", "COLLECTION | append COLLECTION"] +signature: ["COLLECTION | append ELEMENT [ELEMENT]...", "COLLECTION | append COLLECTION"] relatedfuncs: [last,first,where,slice] --- -An example appending single values: +This function appends all elements, excluding the last, to the last element. This allows [pipe](/getting-started/glossary/#pipeline) constructs as shown below. + +Append a single element to a slice: + +```go-html-template +{{ $s := slice "a" "b" }} +{{ $s }} → [a b] + +{{ $s = $s | append "c" }} +{{ $s }} → [a b c] +``` + +Append two elements to a slice: + +```go-html-template +{{ $s := slice "a" "b" }} +{{ $s }} → [a b] + +{{ $s = $s | append "c" "d" }} +{{ $s }} → [a b c d] +``` + +Append two elements, as a slice, to a slice. This produces the same result as the previous example: ```go-html-template -{{ $s := slice "a" "b" "c" }} -{{ $s = $s | append "d" "e" }} -{{/* $s now contains a []string with elements "a", "b", "c", "d", and "e" */}} +{{ $s := slice "a" "b" }} +{{ $s }} → [a b] +{{ $s = $s | append (slice "c" "d") }} +{{ $s }} → [a b c d] ``` -The same example appending a slice to a slice: +Start with an empty slice: ```go-html-template -{{ $s := slice "a" "b" "c" }} +{{ $s := slice }} +{{ $s }} → [] + +{{ $s = $s | append "a" }} +{{ $s }} → [a] + +{{ $s = $s | append "b" "c" }} +{{ $s }} → [a b c] + {{ $s = $s | append (slice "d" "e") }} +{{ $s }} → [a b c d e] ``` -If a slice contains other slices, further slices will be appended as values: +If you start with a slice of a slice: ```go-html-template -{{ $s := slice (slice "a" "b") (slice "c" "d") }} -{{ $s = $s | append (slice "e" "f") (slice "g" "h") }} -{{/* $s now contains a [][]string containing four slices: ["a" "b"], ["c" "d"], ["e" "f"], and ["g" "h"] */}} +{{ $s := slice (slice "a" "b") }} +{{ $s }} → [[a b]] + +{{ $s = $s | append (slice "c" "d") }} +{{ $s }} → [[a b] [c d]] +``` + +To create a slice of slices, starting with an empty slice: + +```go-html-template +{{ $s := slice }} +{{ $s }} → [] + +{{ $s = $s | append (slice (slice "a" "b")) }} +{{ $s }} → [[a b]] + +{{ $s = $s | append (slice "c" "d") }} +{{ $s }} → [[a b] [c d]] ``` -The `append` function works for all types, including `Pages`. + + +Although the elements in the examples above are strings, you can use the `append` function with any data type, including Pages. For example, on the home page of a corporate site, to display links to the two most recent press releases followed by links to the four most recent articles: + +```go-html-template +{{ $p := where site.RegularPages "Type" "press-releases" | first 2 }} +{{ $p = $p | append (where site.RegularPages "Type" "articles" | first 4) }} + +{{ with $p }} + <ul> + {{ range . }} + <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li> + {{ end }} + </ul> +{{ end }} +``` diff --git a/docs/content/en/functions/apply.md b/docs/content/en/functions/apply.md index b9dbd81e7..c507a35bf 100644 --- a/docs/content/en/functions/apply.md +++ b/docs/content/en/functions/apply.md @@ -10,11 +10,11 @@ signature: ["apply COLLECTION FUNCTION [PARAM...]"] relatedfuncs: [] --- -`apply` expects at least three parameters, depending on the function being applied. +`apply` expects at least three arguments, depending on the function being applied. -1. The first parameter is the sequence to operate on. -2. The second parameter is the name of the function as a string, which must be the name of a valid [Hugo function][functions]. -3. After that, the parameters to the applied function are provided, with the string `"."` standing in for each element of the sequence the function is to be applied against. +1. The first argument is the sequence to operate on. +2. The second argument is the name of the function as a string, which must be the name of a valid [Hugo function][functions]. +3. After that, the arguments to the applied function are provided, with the string `"."` standing in for each element of the sequence the function is to be applied against. Here is an example of a content file with `names:` as a front matter field: diff --git a/docs/content/en/functions/cond.md b/docs/content/en/functions/cond.md index 8f87563d9..9bd0a0e2b 100644 --- a/docs/content/en/functions/cond.md +++ b/docs/content/en/functions/cond.md @@ -1,26 +1,40 @@ --- title: cond -description: "Return one of two arguments, depending on the value of a third argument." +description: Returns one of two arguments depending on the value of the control argument. categories: [functions] +keywords: [conditional, ternary] menu: docs: parent: functions -signature: ["cond CONTROL VAR1 VAR2"] +signature: [cond CONTROL ARG1 ARG2] relatedfuncs: [default] --- -`cond` returns *VAR1* if *CONTROL* is true, or *VAR2* if it is not. - -Example: +The CONTROL argument is a boolean value that indicates whether the function should return ARG1 or ARG2. If CONTROL is `true`, the function returns ARG1. Otherwise, the function returns ARG2. ```go-html-template -{{ cond (eq (len $geese) 1) "goose" "geese" }} +{{ $qty := 42 }} +{{ cond (le $qty 3) "few" "many" }} → "many" ``` -Would emit "goose" if the `$geese` array has exactly 1 item, or "geese" otherwise. +The CONTROL argument must be either `true` or `false`. To cast a non-boolean value to boolean, pass it through the `not` operator twice. + +```go-html-template +{{ cond (42 | not | not) "truthy" "falsy" }} → "truthy" +{{ cond ("" | not | not) "truthy" "falsy" }} → "falsy" +``` {{% note %}} -Whenever you use a `cond` function, *both* variable expressions are *always* evaluated. This means that a usage like `cond false (div 1 0) 27` will throw an error because `div 1 0` will be evaluated *even though the condition is false*. +Unlike [ternary operators] in other languages, the `cond` function does not perform [short-circuit evaluation]. The function evaluates both ARG1 and ARG2, regardless of the CONTROL value. -In other words, the `cond` function does *not* provide [short-circuit evaluation](https://en.wikipedia.org/wiki/Short-circuit_evaluation) and does *not* work like a normal [ternary operator](https://en.wikipedia.org/wiki/%3F:) that will pass over the first expression if the condition returns `false`. +[short-circuit evaluation]: https://en.wikipedia.org/wiki/Short-circuit_evaluation +[ternary operators]: https://en.wikipedia.org/wiki/Ternary_conditional_operator {{% /note %}} + + +Due to the absence of short-circuit evaluation, these examples throw an error: + +```go-html-template +{{ cond true "true" (div 1 0) }} +{{ cond false (div 1 0) "false" }} +``` diff --git a/docs/content/en/functions/dict.md b/docs/content/en/functions/dict.md index d4fbc1bea..0fc2c530b 100644 --- a/docs/content/en/functions/dict.md +++ b/docs/content/en/functions/dict.md @@ -1,11 +1,11 @@ --- title: dict -description: Creates a dictionary from a list of key and value pairs. +description: Creates a map from a list of key and value pairs. categories: [functions] menu: docs: parent: functions -keywords: [dictionary] +keywords: [collections] signature: ["dict KEY VALUE [KEY VALUE]..."] relatedfuncs: [] --- diff --git a/docs/content/en/functions/echoparam.md b/docs/content/en/functions/echoparam.md index 840acf51c..7b80e1439 100644 --- a/docs/content/en/functions/echoparam.md +++ b/docs/content/en/functions/echoparam.md @@ -6,7 +6,7 @@ menu: docs: parent: functions keywords: [] -signature: ["echoParam DICTIONARY KEY"] +signature: ["echoParam MAP KEY"] relatedfuncs: [] --- diff --git a/docs/content/en/functions/findRe.md b/docs/content/en/functions/findRe.md index 3c977118c..104db0f27 100644 --- a/docs/content/en/functions/findRe.md +++ b/docs/content/en/functions/findRe.md @@ -11,7 +11,7 @@ signature: - "strings.FindRE PATTERN INPUT [LIMIT]" relatedfuncs: [findRESubmatch, replaceRE] --- -By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT parameter. +By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT argument. {{% readfile file="/functions/common/regular-expressions.md" %}} diff --git a/docs/content/en/functions/findresubmatch.md b/docs/content/en/functions/findresubmatch.md index 1f0f26b49..f51ccdb97 100644 --- a/docs/content/en/functions/findresubmatch.md +++ b/docs/content/en/functions/findresubmatch.md @@ -12,7 +12,7 @@ signature: relatedfuncs: [findRE, replaceRE] --- -By default, `findRESubmatch` finds all matches. You can limit the number of matches with an optional LIMIT parameter. A return value of nil indicates no match. +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. {{% readfile file="/functions/common/regular-expressions.md" %}} diff --git a/docs/content/en/functions/highlight.md b/docs/content/en/functions/highlight.md index 1a47fe37f..f91c1f562 100644 --- a/docs/content/en/functions/highlight.md +++ b/docs/content/en/functions/highlight.md @@ -12,7 +12,7 @@ toc: true --- The `highlight` function uses the [Chroma] syntax highlighter, supporting over 200 languages with more than 40 available styles. -## Parameters +## Arguments INPUT : The code to highlight. @@ -67,7 +67,7 @@ Substitute this number of spaces for each tab character in your highlighted code guessSyntax : Boolean. Default is `false`.\ -If the `LANG` parameter is blank or an unrecognized language, auto-detect the language if possible, otherwise use a fallback language. +If the `LANG` argument is blank or an unrecognized language, auto-detect the language if possible, otherwise use a fallback language. {{% note %}} Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation: diff --git a/docs/content/en/functions/images/index.md b/docs/content/en/functions/images/index.md index 4a04ce0ac..e42f4cdd8 100644 --- a/docs/content/en/functions/images/index.md +++ b/docs/content/en/functions/images/index.md @@ -39,7 +39,7 @@ The above will overlay `$logo` in the upper left corner of `$img` (at position ` Using the `Text` filter, you can add text to an image. {{% funcsig %}} -images.Text TEXT DICT) +images.Text TEXT MAP) {{% /funcsig %}} The following example will add the text `Hugo rocks!` to the image with the specified color, size and position. diff --git a/docs/content/en/functions/index-function.md b/docs/content/en/functions/index-function.md index e5ba47262..b2193c9c5 100644 --- a/docs/content/en/functions/index-function.md +++ b/docs/content/en/functions/index-function.md @@ -68,7 +68,7 @@ location = "oslo" The content of `oslo.toml` can be accessed from your template using the following node path: `.Site.Data.locations.oslo`. However, the specific file you need is going to change according to the front matter. -This is where the `index` function is needed. `index` takes 2 parameters in this use case: +This is where the `index` function is needed. `index` takes 2 arguments in this use case: 1. The node path 2. A string corresponding to the desired data; e.g.— diff --git a/docs/content/en/functions/jsonify.md b/docs/content/en/functions/jsonify.md index da40b8fcf..e94fb7cd4 100644 --- a/docs/content/en/functions/jsonify.md +++ b/docs/content/en/functions/jsonify.md @@ -10,9 +10,7 @@ signature: ["jsonify INPUT", "jsonify OPTIONS INPUT"] relatedfuncs: [plainify] --- -Jsonify encodes a given object to JSON. - -To customize the printing of the JSON, pass a dictionary of options as the first +To customize the printing of the JSON, pass a map of options as the first argument. Supported options are "prefix" and "indent". Each JSON element in the output will begin on a new line beginning with *prefix* followed by one or more copies of *indent* according to the indentation nesting. diff --git a/docs/content/en/functions/merge.md b/docs/content/en/functions/merge.md index ed370549e..5fef26153 100644 --- a/docs/content/en/functions/merge.md +++ b/docs/content/en/functions/merge.md @@ -5,7 +5,7 @@ categories: [functions] menu: docs: parent: functions -keywords: [dictionary] +keywords: [collections] signature: ["collections.Merge MAP MAP...", "merge MAP MAP..."] relatedfuncs: [dict, append, reflect.IsMap, reflect.IsSlice] --- diff --git a/docs/content/en/functions/partialCached.md b/docs/content/en/functions/partialCached.md index d443864f2..7eed566f6 100644 --- a/docs/content/en/functions/partialCached.md +++ b/docs/content/en/functions/partialCached.md @@ -22,18 +22,18 @@ Here is the simplest usage: {{ partialCached "footer.html" . }} ``` -You can also pass additional parameters 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, you could use a variant based upon section so that the partial is only rendered once per section: +You can also 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, you could use a variant based upon section so that the partial is only rendered once per section: {{< code file="partial-cached-example.html" >}} {{ partialCached "footer.html" . .Section }} {{< /code >}} -If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need: +If you need to pass additional arguments to create unique variants, you can pass as many variant arguments as you need: ```go-html-template {{ partialCached "footer.html" . .Params.country .Params.province }} ``` -Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key. Since Hugo `0.61.0` you can use any object as cache key(s), not just strings. +Note that the variant arguments are not made available to the underlying partial template. They are only use to create a unique cache key. Since Hugo `0.61.0` you can use any object as cache key(s), not just strings. See also [The Full Partial Series Part 1: Caching!](https://regisphilibert.com/blog/2019/12/hugo-partial-series-part-1-caching-with-partialcached/). diff --git a/docs/content/en/functions/ref.md b/docs/content/en/functions/ref.md index 32bf79ca1..2d05ca427 100644 --- a/docs/content/en/functions/ref.md +++ b/docs/content/en/functions/ref.md @@ -10,7 +10,7 @@ signature: ["ref . PAGE"] relatedfuncs: [relref] --- -This function takes two parameters: +This function takes two arguments: - The context of the page from which to resolve relative paths, typically the current page (`.`) - The 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. diff --git a/docs/content/en/functions/relref.md b/docs/content/en/functions/relref.md index f60d5559b..98ad724f7 100644 --- a/docs/content/en/functions/relref.md +++ b/docs/content/en/functions/relref.md @@ -10,7 +10,7 @@ signature: ["relref . PAGE"] relatedfuncs: [ref] --- -This function takes two parameters: +This function takes two arguments: - The context of the page from which to resolve relative paths, typically the current page (`.`) - The 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. diff --git a/docs/content/en/functions/replace.md b/docs/content/en/functions/replace.md index fea92ab68..4c150bfef 100644 --- a/docs/content/en/functions/replace.md +++ b/docs/content/en/functions/replace.md @@ -13,7 +13,7 @@ relatedfuncs: [replaceRE] --- Replace returns a copy of `INPUT` with all occurrences of `OLD` replaced with `NEW`. -The number of replacements can be limited with an optional `LIMIT` parameter. +The number of replacements can be limited with an optional `LIMIT` argument. ``` `{{ replace "Batman and Robin" "Robin" "Catwoman" }}` diff --git a/docs/content/en/functions/replacere.md b/docs/content/en/functions/replacere.md index 8c3cc13c2..4dba19bfe 100644 --- a/docs/content/en/functions/replacere.md +++ b/docs/content/en/functions/replacere.md @@ -11,7 +11,7 @@ signature: - "strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]" relatedfuncs: [findRE, FindRESubmatch, replace] --- -By default, `replaceRE` replaces all matches. You can limit the number of matches with an optional LIMIT parameter. +By default, `replaceRE` replaces all matches. You can limit the number of matches with an optional LIMIT argument. {{% readfile file="/functions/common/regular-expressions.md" %}} diff --git a/docs/content/en/functions/substr.md b/docs/content/en/functions/substr.md index 6a5f15592..90ee47b55 100644 --- a/docs/content/en/functions/substr.md +++ b/docs/content/en/functions/substr.md @@ -12,7 +12,7 @@ signature: relatedfuncs: [] --- -It normally takes two parameters: `start` and `length`. It can also take one parameter: `start`, i.e. `length` is omitted, in which case the substring starting from start until the end of the string will be returned. +It normally takes two argument: `start` and `length`. It can also take one argument: `start`, i.e. `length` is omitted, in which case the substring starting from start until the end of the string will be returned. To extract characters from the end of the string, use a negative start number. diff --git a/docs/content/en/functions/time.md b/docs/content/en/functions/time.md index 1fb6cc350..99182f317 100644 --- a/docs/content/en/functions/time.md +++ b/docs/content/en/functions/time.md @@ -21,7 +21,7 @@ relatedfuncs: [] ## Using locations -The optional `TIMEZONE` parameter is a string that sets a default time zone (or more specific, the location, which represents the collection of time offsets in a geographical area) that is associated with the specified time value. If the time value has an explicit timezone or offset specified, it will take precedence over the `TIMEZONE` parameter. +The optional `TIMEZONE` argument is a string that sets a default time zone (or more specific, the location, which represents the collection of time offsets in a geographical area) that is associated with the specified time value. If the time value has an explicit timezone or offset specified, it will take precedence over the `TIMEZONE` argument. The list of valid locations may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). diff --git a/docs/content/en/functions/transform.Remarshal.md b/docs/content/en/functions/transform.Remarshal.md new file mode 100644 index 000000000..e1605197f --- /dev/null +++ b/docs/content/en/functions/transform.Remarshal.md @@ -0,0 +1,88 @@ +--- +title: transform.Remarshal +description: Marshals a string of serialized data, or a map, into a string of serialized data in the specified format. +categories: [functions] +menu: + docs: + parent: functions +keywords: [] +signature: [ transform.Remarshal FORMAT INPUT ] +--- + +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 %}} + +Example 1 +: Convert a string of TOML to JSON. + +```go-html-template +{{ $s := ` + baseURL = 'https://example.org/' + languageCode = 'en-US' + title = 'ABC Widgets' +`}} +<pre>{{ transform.Remarshal "json" $s }}</pre> +``` + +Resulting HTML: + +```html +<pre>{ + "baseURL": "https://example.org/", + "languageCode": "en-US", + "title": "ABC Widgets" +} +</pre> +``` + +Rendered in browser: + +```text +{ + "baseURL": "https://example.org/", + "languageCode": "en-US", + "title": "ABC Widgets" +} +``` + +Example 2 +: Convert a map to YAML. + +```go-html-template +{{ $m := dict + "a" "Hugo rocks!" + "b" (dict "question" "What is 6x7?" "answer" 42) + "c" (slice "foo" "bar") +}} +<pre>{{ transform.Remarshal "yaml" $m }}</pre> +``` + +Resulting HTML: + +```html +<pre>a: Hugo rocks! +b: + answer: 42 + question: What is 6x7? +c: +- foo +- bar +</pre> +``` + +Rendered in browser: + +```text +a: Hugo rocks! +b: + answer: 42 + question: What is 6x7? +c: +- foo +- bar +``` |