Merge commit '77b976dd92'

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:

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" "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 "c" }}
+{{ $s }} → [a b c]
 ```
 
-The same example appending a slice to a slice:
+Append two elements to a slice:
 
 ```go-html-template
-{{ $s := slice "a" "b" "c" }}
+{{ $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" }}
+{{ $s }} → [a b]
+
+{{ $s = $s | append (slice "c" "d") }}
+{{ $s }} → [a b c d]
+```
+
+Start with an empty slice:
+
+```go-html-template
+{{ $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]]
 ```
 
-The `append` function works for all types, including `Pages`.
+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]]
+```
+
+
+
+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 }}
+```

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:
 

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" }}
+```

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: []
 ---

docs/content/en/functions/echoparam.md

@@ -6,7 +6,7 @@ menu:
   docs:
     parent: functions
 keywords: []
-signature: ["echoParam DICTIONARY KEY"]
+signature: ["echoParam MAP KEY"]
 relatedfuncs: []
 ---
 

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

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

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:

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.

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

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.

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

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/).

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.

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.

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

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

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.
 

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

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>{
+   &#34;baseURL&#34;: &#34;https://example.org/&#34;,
+   &#34;languageCode&#34;: &#34;en-US&#34;,
+   &#34;title&#34;: &#34;ABC Widgets&#34;
+}
+</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
+```