diff options
| author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-07-29 11:17:28 +0200 |
|---|---|---|
| committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-07-29 11:17:28 +0200 |
| commit | 8859be1c01eac8b7423b9ff515c2d8c5c3d9d754 (patch) | |
| tree | 5b503e5ef88c6569228f77936d5fb723c8a512b1 /docs/content/en/functions | |
| parent | bec9b80d95d1be8270bcda080037c588614f3be1 (diff) | |
| parent | 87de22d7464e239c775fbd48ebce1665d5b1e80d (diff) | |
Merge commit '87de22d7464e239c775fbd48ebce1665d5b1e80d'
Diffstat (limited to 'docs/content/en/functions')
23 files changed, 67 insertions, 60 deletions
diff --git a/docs/content/en/functions/GetPage.md b/docs/content/en/functions/GetPage.md index f4f4405c6..17d2bd972 100644 --- a/docs/content/en/functions/GetPage.md +++ b/docs/content/en/functions/GetPage.md @@ -37,15 +37,15 @@ And since `Page` also provides a `.GetPage` method, the above is the same as: {{ end }} ``` -## .GetPage and Multilingual Sites +## .GetPage and multilingual sites -The previous examples have used the full content filename to look up the post. Depending on how you have organized your content (whether you have the language code in the file name or not, e.g. `my-post.en.md`), you may want to do the lookup without extension. This will get you the current language's version of the page: +The previous examples have used the full content file name to look up the post. Depending on how you have organized your content (whether you have the language code in the file name or not, e.g. `my-post.en.md`), you may want to do the lookup without extension. This will get you the current language's version of the page: ```go-html-template {{ with .Site.GetPage "/blog/my-post" }}{{ .Title }}{{ end }} ``` -## .GetPage Example +## .GetPage example This code snippet---in the form of a [partial template][partials]---allows you to do the following: @@ -63,7 +63,7 @@ This code snippet---in the form of a [partial template][partials]---allows you t </ul> {{< /code >}} -## `.GetPage` on Page Bundles +## `.GetPage` on page bundles If the page retrieved by `.GetPage` is a [Leaf Bundle][leaf_bundle], and you need to get the nested _**page** resources_ in that, you will need to use the diff --git a/docs/content/en/functions/_index.md b/docs/content/en/functions/_index.md index fd45fb6dd..4f8aa47ca 100644 --- a/docs/content/en/functions/_index.md +++ b/docs/content/en/functions/_index.md @@ -1,11 +1,14 @@ --- -title: Functions Quick Reference +title: Functions +linkTitle: Overview description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples. keywords: [] menu: docs: + identifier: functions-overview parent: functions -weight: 01 + weight: 10 +weight: 10 aliases: [/layout/functions/,/templates/functions] --- diff --git a/docs/content/en/functions/after.md b/docs/content/en/functions/after.md index b608784e3..5318d3b0c 100644 --- a/docs/content/en/functions/after.md +++ b/docs/content/en/functions/after.md @@ -20,7 +20,7 @@ The following shows `after` being used in conjunction with the [`slice` function → ["three", "four"] ``` -## Example of `after` with `first`: 2nd–4th Most Recent Articles +## Example of `after` with `first`: 2nd–4th most recent articles You can use `after` in combination with the [`first` function] and Hugo's [powerful sorting methods][lists]. Let's assume you have a list page at `example.com/articles`. You have 10 articles, but you want your templating for the [list/section page] to show only two rows: diff --git a/docs/content/en/functions/anchorize.md b/docs/content/en/functions/anchorize.md index cf04a9640..bdf322a6e 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`](https://gohugo.io/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#configure-markup) does for markdown headers. categories: [functions] menu: docs: @@ -10,7 +10,7 @@ signature: ["anchorize INPUT"] relatedfuncs: [humanize] --- -If [Goldmark](https://gohugo.io/getting-started/configuration-markup#goldmark) is set as `defaultMarkdownHandler`, the sanitizing logic adheres to the setting [`markup.goldmark.parser.autoHeadingIDType`](https://gohugo.io/getting-started/configuration-markup#goldmark). +If [Goldmark](/getting-started/configuration-markup#goldmark) is set as `defaultMarkdownHandler`, the sanitizing logic adheres to the setting [`markup.goldmark.parser.autoHeadingIDType`](/getting-started/configuration-markup#goldmark). Since the `defaultMarkdownHandler` and this template function use the same sanitizing logic, you can use the latter to determine the ID of a header for linking with anchor tags. diff --git a/docs/content/en/functions/apply.md b/docs/content/en/functions/apply.md index 0bc071e7b..b9dbd81e7 100644 --- a/docs/content/en/functions/apply.md +++ b/docs/content/en/functions/apply.md @@ -1,6 +1,6 @@ --- title: apply -description: Given a map, array, or slice, `apply` returns a new slice with a function applied over it. +description: Given an array or slice, `apply` returns a new slice with a function applied over it. categories: [functions] menu: docs: diff --git a/docs/content/en/functions/dict.md b/docs/content/en/functions/dict.md index 27a786bec..d4fbc1bea 100644 --- a/docs/content/en/functions/dict.md +++ b/docs/content/en/functions/dict.md @@ -18,7 +18,7 @@ Note that the `key` can be either a `string` or a `string slice`. The latter is {{ $m := dict (slice "a" "b" "c") "value" }} ``` -## Example: Using `dict` to pass multiple values to a `partial` +## Example: using `dict` to pass multiple values to a `partial` The partial below creates an SVG and expects `fill`, `height` and `width` from the caller: diff --git a/docs/content/en/functions/emojify.md b/docs/content/en/functions/emojify.md index 45753af13..beded710a 100644 --- a/docs/content/en/functions/emojify.md +++ b/docs/content/en/functions/emojify.md @@ -14,12 +14,12 @@ relatedfuncs: [] See the [Emoji cheat sheet][emojis] 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][config]. Then you can write emoji shorthand directly into your content files; e.g. <code>I :</code><code>heart</code><code>: Hugo!</code>: +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; e.g. <code>I :</code><code>heart</code><code>: Hugo!</code>: I :heart: Hugo! -[config]: /getting-started/configuration/ +[configuration]: /getting-started/configuration/ [emojis]: https://www.webfx.com/tools/emoji-cheat-sheet/ [sc]: /templates/shortcode-templates/ [scsource]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes diff --git a/docs/content/en/functions/errorf.md b/docs/content/en/functions/errorf.md index b3e0fd280..8caaf0554 100644 --- a/docs/content/en/functions/errorf.md +++ b/docs/content/en/functions/errorf.md @@ -40,6 +40,6 @@ This will produce: ``` ERROR 2021/06/07 17:47:38 You should consider fixing this. -If you feel that this should not be logged as an ERROR, you can ignore it by adding this to your site config: +If you feel that this should not be logged as an ERROR, you can ignore it by adding this to your site configuration: ignoreErrors = ["my-custom-error"] ``` diff --git a/docs/content/en/functions/format.md b/docs/content/en/functions/format.md index af34cbf7e..d30f0bdf2 100644 --- a/docs/content/en/functions/format.md +++ b/docs/content/en/functions/format.md @@ -25,7 +25,7 @@ Assuming a key-value of `date: 2017-03-03` in a content file's front matter, you For formatting *any* string representations of dates defined in your front matter, see the [`dateFormat` function][dateFormat], which will still leverage the Go layout string explained below but uses a slightly different syntax. -## Go's Layout String +## Go's layout string Hugo templates [format your dates][time] via layout strings that point to a specific reference time: @@ -42,7 +42,7 @@ Here is a visual explanation [taken directly from the Go docs][gdex]: => 1 2 3 4 5 6 -7 ``` -### Hugo Date and Time Templating Reference +### Hugo date and time templating reference The following examples show the layout string followed by the rendered output. @@ -84,7 +84,7 @@ date: 2017-03-03T14:15:59-06:00 More examples can be found in Go's [documentation for the time package][timeconst]. -### Cardinal Numbers and Ordinal Abbreviations +### Cardinal s Spelled-out cardinal numbers (e.g. "one", "two", and "three") are not currently supported. diff --git a/docs/content/en/functions/hasPrefix.md b/docs/content/en/functions/hasPrefix.md index cf29315e2..264044577 100644 --- a/docs/content/en/functions/hasPrefix.md +++ b/docs/content/en/functions/hasPrefix.md @@ -1,6 +1,5 @@ --- title: hasprefix -linktitle: hasPrefix description: Tests whether a string begins with prefix. date: 2017-02-01 publishdate: 2017-02-01 diff --git a/docs/content/en/functions/hasSuffix.md b/docs/content/en/functions/hasSuffix.md index 9906cc2c3..5ab38866d 100644 --- a/docs/content/en/functions/hasSuffix.md +++ b/docs/content/en/functions/hasSuffix.md @@ -1,6 +1,6 @@ --- title: hassuffix -linktitle: hasSuffix +linkTitle: hasSuffix description: Tests whether a string ends with suffix. date: 2023-03-01 publishdate: 2023-03-01 @@ -18,4 +18,4 @@ deprecated: false aliases: [] --- -* `{{ hasSuffix "Hugo" "go" }}` → true
\ No newline at end of file +* `{{ hasSuffix "Hugo" "go" }}` → true diff --git a/docs/content/en/functions/highlight.md b/docs/content/en/functions/highlight.md index 2ca125467..1a47fe37f 100644 --- a/docs/content/en/functions/highlight.md +++ b/docs/content/en/functions/highlight.md @@ -91,8 +91,8 @@ Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the f {{ $input := `echo "Hello World!"` }} {{ $lang := "bash" }} -{{ $options := slice "lineNos=table" "style=dracula" }} -{{ transform.Highlight $input $lang (delimit $options ",") }} +{{ $options := dict "lineNos" "table" "style" "dracula" }} +{{ transform.Highlight $input $lang $options }} ``` [Chroma]: https://github.com/alecthomas/chroma diff --git a/docs/content/en/functions/images/index.md b/docs/content/en/functions/images/index.md index 9cd772e5b..4a04ce0ac 100644 --- a/docs/content/en/functions/images/index.md +++ b/docs/content/en/functions/images/index.md @@ -1,5 +1,5 @@ --- -title: Image Filters +title: Image filters description: The images namespace provides a list of filters and other image related functions. categories: [functions] aliases: [/functions/imageconfig/] diff --git a/docs/content/en/functions/index-function.md b/docs/content/en/functions/index-function.md index 6fb9f0fec..e5ba47262 100644 --- a/docs/content/en/functions/index-function.md +++ b/docs/content/en/functions/index-function.md @@ -37,7 +37,7 @@ You may write multiple indices as a slice: {{ index $map $slice }} => 20 ``` -## Example: Load Data from a Path Based on Front Matter Params +## Example: load data from a path based on front matter parameters Assume you want to add a `location = ""` field to your front matter for every article written in `content/vacations/`. You want to use this field to populate information about the location at the bottom of the article in your `single.html` template. You also have a directory in `data/locations/` that looks like the following: diff --git a/docs/content/en/functions/intersect.md b/docs/content/en/functions/intersect.md index 99ab0943e..9c3ed6292 100644 --- a/docs/content/en/functions/intersect.md +++ b/docs/content/en/functions/intersect.md @@ -19,7 +19,7 @@ A useful example is to use it as `AND` filters when combined with where: {{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }} ``` -The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page params. +The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters. See [union](/functions/union) for `OR`. diff --git a/docs/content/en/functions/isset.md b/docs/content/en/functions/isset.md index 9c00c15fc..0a8de7367 100644 --- a/docs/content/en/functions/isset.md +++ b/docs/content/en/functions/isset.md @@ -17,6 +17,6 @@ Takes either a slice, array, or channel and an index or a map and a key as input ``` {{% note %}} -All site-level configuration keys are stored as lower case. Therefore, a `myParam` key-value set in your [site configuration file](/getting-started/configuration/) needs to be accessed with `{{ if isset .Site.Params "myparam" }}` and *not* with `{{ if isset .Site.Params "myParam" }}`. Note that you can still access the same config key with `.Site.Params.myParam` *or* `.Site.Params.myparam`, for example, when using [`with`](/functions/with). +All site-level configuration keys are stored as lower case. Therefore, a `myParam` key-value set in your [site configuration file](/getting-started/configuration/) needs to be accessed with `{{ if isset .Site.Params "myparam" }}` and *not* with `{{ if isset .Site.Params "myParam" }}`. Note that you can still access the same configuration key with `.Site.Params.myParam` *or* `.Site.Params.myparam`, for example, when using [`with`](/functions/with). This restriction also applies when accessing page-level front matter keys from within [shortcodes](/content-management/shortcodes/). {{% /note %}} diff --git a/docs/content/en/functions/math.md b/docs/content/en/functions/math.md index c36b8ea0b..708921f68 100644 --- a/docs/content/en/functions/math.md +++ b/docs/content/en/functions/math.md @@ -11,24 +11,26 @@ signature: [] relatedfuncs: [] --- -| Function | Description | Example | -|--------------|-----------------------------------------------------------------------------|-------------------------------------| -| `add` | Adds two or more numbers. | `{{ add 12 3 2 }}` → `17` | -| | *If one of the numbers is a float, the result is a float.* | `{{ add 1.1 2 }}` → `3.1` | -| `sub` | Subtracts one or more numbers from the first number. | `{{ sub 12 3 2 }}` → `7` | -| | *If one of the numbers is a float, the result is a float.* | `{{ sub 3 2.5 }}` → `0.5` | -| `mul` | Multiplies two or more numbers. | `{{ mul 12 3 2 }}` → `72` | -| | *If one of the numbers is a float, the result is a float.* | `{{ mul 2 3.1 }}` → `6.2` | -| `div` | Divides the first number by one or more numbers. | `{{ div 12 3 2 }}` → `2` | -| | *If one of the numbers is a float, the result is a float.* | `{{ div 6 4.0 }}` → `1.5` | -| `mod` | Modulus of two integers. | `{{ mod 15 3 }}` → `0` | -| `modBool` | Boolean of modulus of two integers. Evaluates to `true` if result equals 0. | `{{ modBool 15 3 }}` → `true` | -| `math.Abs` | Returns the absolute value of the given number. | `{{ math.Abs -2.1 }}` → `2.1` | -| `math.Ceil` | Returns the least integer value greater than or equal to the given number. | `{{ math.Ceil 2.1 }}` → `3` | -| `math.Floor` | Returns the greatest integer value less than or equal to the given number. | `{{ math.Floor 1.9 }}` → `1` | -| `math.Log` | Returns the natural logarithm of the given number. | `{{ math.Log 42 }}` → `3.737` | -| `math.Max` | Returns the greater of two or more numbers. | `{{ math.Max 12 3 2 }}` → `12` | -| `math.Min` | Returns the smaller of two or more numbers. | `{{ math.Min 12 3 2 }}` → `2` | -| `math.Pow` | Returns the first number raised to the power of the second number. | `{{ math.Pow 2 3 }}` → `8` | -| `math.Round` | Returns the nearest integer, rounding half away from zero. | `{{ math.Round 1.5 }}` → `2` | -| `math.Sqrt` | Returns the square root of the given number. | `{{ math.Sqrt 81 }}` → `9` | +| Function | Description | Example | +|-----------------|-----------------------------------------------------------------------------|---------------------------------------------------| +| `add` | Adds two or more numbers. | `{{ add 12 3 2 }}` → `17` | +| | *If one of the numbers is a float, the result is a float.* | `{{ add 1.1 2 }}` → `3.1` | +| `sub` | Subtracts one or more numbers from the first number. | `{{ sub 12 3 2 }}` → `7` | +| | *If one of the numbers is a float, the result is a float.* | `{{ sub 3 2.5 }}` → `0.5` | +| `mul` | Multiplies two or more numbers. | `{{ mul 12 3 2 }}` → `72` | +| | *If one of the numbers is a float, the result is a float.* | `{{ mul 2 3.1 }}` → `6.2` | +| `div` | Divides the first number by one or more numbers. | `{{ div 12 3 2 }}` → `2` | +| | *If one of the numbers is a float, the result is a float.* | `{{ div 6 4.0 }}` → `1.5` | +| `mod` | Modulus of two integers. | `{{ mod 15 3 }}` → `0` | +| `modBool` | Boolean of modulus of two integers. Evaluates to `true` if result equals 0. | `{{ modBool 15 3 }}` → `true` | +| `math.Abs` | Returns the absolute value of the given number. | `{{ math.Abs -2.1 }}` → `2.1` | +| `math.Ceil` | Returns the least integer value greater than or equal to the given number. | `{{ math.Ceil 2.1 }}` → `3` | +| `math.Floor` | Returns the greatest integer value less than or equal to the given number. | `{{ math.Floor 1.9 }}` → `1` | +| `math.Log` | Returns the natural logarithm of the given number. | `{{ math.Log 42 }}` → `3.737` | +| `math.Max` | Returns the greater of all numbers. Accepts scalars, slices, or both. | `{{ math.Max 1 (slice 2 3) 4 }}` → `4` | +| `math.Min` | Returns the smaller of all numbers. Accepts scalars, slices, or both. | `{{ math.Min 1 (slice 2 3) 4 }}` → `1` | +| `math.Product` | Returns the product of all numbers. Accepts scalars, slices, or both. | `{{ math.Product 1 (slice 2 3) 4 }}` → `24` | +| `math.Pow` | Returns the first number raised to the power of the second number. | `{{ math.Pow 2 3 }}` → `8` | +| `math.Round` | Returns the nearest integer, rounding half away from zero. | `{{ math.Round 1.5 }}` → `2` | +| `math.Sqrt` | Returns the square root of the given number. | `{{ math.Sqrt 81 }}` → `9` | +| `math.Sum` | Returns the sum of all numbers. Accepts scalars, slices, or both. | `{{ math.Sum 1 (slice 2 3) 4 }}` → `10` | diff --git a/docs/content/en/functions/readdir.md b/docs/content/en/functions/readdir.md index 3ad43126a..9fc4d3013 100644 --- a/docs/content/en/functions/readdir.md +++ b/docs/content/en/functions/readdir.md @@ -1,6 +1,6 @@ --- title: readDir -description: Returns an array of FileInfo structures sorted by filename, one element for each directory entry. +description: Returns an array of FileInfo structures sorted by file name, one element for each directory entry. categories: [functions] menu: docs: diff --git a/docs/content/en/functions/safeHTMLAttr.md b/docs/content/en/functions/safeHTMLAttr.md index ac7f32d7a..bced1ba10 100644 --- a/docs/content/en/functions/safeHTMLAttr.md +++ b/docs/content/en/functions/safeHTMLAttr.md @@ -34,12 +34,16 @@ Will produce: `ZgotmplZ` is a special value, inserted by Go's [template/html] package, that indicates that unsafe content reached a CSS or URL context. -To override the safety check, use the `safeHTMLAttr` function: +To indicate that the HTML attribute is safe: ```go-html-template {{ range site.Menus.main }} <a {{ printf "href=%q" .URL | safeHTMLAttr }}>{{ .Name }}</a> {{ end }} -``` +``` + +{{% note %}} +As demonstrated above, you must pass the HTML attribute name _and_ value through the function. Applying `safeHTMLAttr` to the attribute value has no effect. +{{% /note %}} [template/html]: https://pkg.go.dev/html/template diff --git a/docs/content/en/functions/time.md b/docs/content/en/functions/time.md index 7cb55f6f1..1fb6cc350 100644 --- a/docs/content/en/functions/time.md +++ b/docs/content/en/functions/time.md @@ -19,7 +19,7 @@ relatedfuncs: [] {{ mul 1000 (time "2016-05-28T10:30:00.00+10:00").Unix }} → 1464395400000, or Unix time in milliseconds ``` -## Using Locations +## 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. @@ -33,7 +33,7 @@ If no `TIMEZONE` is set, the `timeZone` from site configuration will be used. {{ time "2020-01-20" "America/Los_Angeles" }} → 2020-01-20 00:00:00 -0800 PST ``` -## Example: Using `time` to get Month Index +## Example: Using `time` to get month index The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"` in a content's front matter---converts the timestamp (string) to an integer using the [`int` function][int], and then uses [`printf`] to convert the `Month` property of `time` into an index. diff --git a/docs/content/en/functions/transform.Unmarshal.md b/docs/content/en/functions/transform.Unmarshal.md index d238565e2..ca5433761 100644 --- a/docs/content/en/functions/transform.Unmarshal.md +++ b/docs/content/en/functions/transform.Unmarshal.md @@ -27,7 +27,7 @@ In both the above examples, you get a map you can work with: The above prints `Hello Hugo`. -## CSV Options +## CSV options Unmarshal with CSV as input has some options you can set: @@ -61,7 +61,7 @@ To get the contents of `<title>` in the document below, you use `{{ .message.tit The following example lists the items of an RSS feed: ```go-html-template -{{ with resources.Get "https://example.com/rss.xml" | transform.Unmarshal }} +{{ with resources.GetRemote "https://example.com/rss.xml" | transform.Unmarshal }} {{ range .channel.item }} <strong>{{ .title | plainify | htmlUnescape }}</strong><br /> <p>{{ .description | plainify | htmlUnescape }}</p> diff --git a/docs/content/en/functions/union.md b/docs/content/en/functions/union.md index b73e06d38..86a874c91 100644 --- a/docs/content/en/functions/union.md +++ b/docs/content/en/functions/union.md @@ -36,6 +36,6 @@ This is also very useful to use as `OR` filters when combined with where: {{ $pages = $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }} ``` -The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page params. +The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page parameters. See [intersect](/functions/intersect) for `AND`. diff --git a/docs/content/en/functions/where.md b/docs/content/en/functions/where.md index 871d04e9b..af92619dc 100644 --- a/docs/content/en/functions/where.md +++ b/docs/content/en/functions/where.md @@ -73,7 +73,7 @@ The following logical operators are available with `where`: `intersec |