mirror of
https://github.com/gohugoio/hugo.git
synced 2025-05-07 11:16:26 +03:00
Squashed 'docs/' content from commit 5c085a37b
git-subtree-dir: docs git-subtree-split: 5c085a37b297bf12f59efeaae591418ec025c10d
This commit is contained in:
Bjørn Erik Pedersen
commit
9b0050e9aa
1158 changed files with 64103 additions and 0 deletions
13
content/en/functions/_common/_index.md
Normal file
13
content/en/functions/_common/_index.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
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.
|
||||
-->
|
||||
23
content/en/functions/_common/glob-patterns.md
Normal file
23
content/en/functions/_common/glob-patterns.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
---
|
||||
# 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`
|
||||
10
content/en/functions/_common/locales.md
Normal file
10
content/en/functions/_common/locales.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
# 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 %}}
|
||||
12
content/en/functions/_common/regular-expressions.md
Normal file
12
content/en/functions/_common/regular-expressions.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
# 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
|
||||
46
content/en/functions/_common/time-layout-string.md
Normal file
46
content/en/functions/_common/time-layout-string.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
---
|
||||
# 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`.
|
||||
17
content/en/functions/_index.md
Normal file
17
content/en/functions/_index.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
title: Functions
|
||||
linkTitle: Overview
|
||||
description: A list of Hugo template functions including examples.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: functions-overview
|
||||
parent: functions
|
||||
weight: 10
|
||||
weight: 10
|
||||
showSectionMenu: true
|
||||
aliases: [/layout/functions/,/templates/functions]
|
||||
---
|
||||
|
||||
Use these functions within your templates and archetypes.
|
||||
48
content/en/functions/cast/ToFloat.md
Normal file
48
content/en/functions/cast/ToFloat.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/float]
|
||||
---
|
||||
|
||||
With a decimal (base 10) input:
|
||||
|
||||
```go-html-template
|
||||
{{ float 11 }} → 11 (float64)
|
||||
{{ float "11" }} → 11 (float64)
|
||||
|
||||
{{ float 11.1 }} → 11.1 (float64)
|
||||
{{ float "11.1" }} → 11.1 (float64)
|
||||
|
||||
{{ float 11.9 }} → 11.9 (float64)
|
||||
{{ float "11.9" }} → 11.9 (float64)
|
||||
```
|
||||
|
||||
With a binary (base 2) input:
|
||||
|
||||
```go-html-template
|
||||
{{ float 0b11 }} → 3 (float64)
|
||||
```
|
||||
|
||||
With an octal (base 8) input (use either notation):
|
||||
|
||||
```go-html-template
|
||||
{{ float 011 }} → 9 (float64)
|
||||
{{ float "011" }} → 11 (float64)
|
||||
|
||||
{{ float 0o11 }} → 9 (float64)
|
||||
```
|
||||
|
||||
With a hexadecimal (base 16) input:
|
||||
|
||||
```go-html-template
|
||||
{{ float 0x11 }} → 17 (float64)
|
||||
```
|
||||
53
content/en/functions/cast/ToInt.md
Normal file
53
content/en/functions/cast/ToInt.md
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/int]
|
||||
---
|
||||
|
||||
With a decimal (base 10) input:
|
||||
|
||||
```go-html-template
|
||||
{{ int 11 }} → 11 (int)
|
||||
{{ int "11" }} → 11 (int)
|
||||
|
||||
{{ int 11.1 }} → 11 (int)
|
||||
{{ int 11.9 }} → 11 (int)
|
||||
```
|
||||
|
||||
With a binary (base 2) input:
|
||||
|
||||
```go-html-template
|
||||
{{ int 0b11 }} → 3 (int)
|
||||
{{ int "0b11" }} → 3 (int)
|
||||
```
|
||||
|
||||
With an octal (base 8) input (use either notation):
|
||||
|
||||
```go-html-template
|
||||
{{ int 011 }} → 9 (int)
|
||||
{{ int "011" }} → 9 (int)
|
||||
|
||||
{{ int 0o11 }} → 9 (int)
|
||||
{{ int "0o11" }} → 9 (int)
|
||||
```
|
||||
|
||||
With a hexadecimal (base 16) input:
|
||||
|
||||
```go-html-template
|
||||
{{ int 0x11 }} → 17 (int)
|
||||
{{ 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:
|
||||
|
||||
`{{ strings/TrimLeft "0" "0011" | int }} → 11`
|
||||
{{% /note %}}
|
||||
51
content/en/functions/cast/ToString.md
Normal file
51
content/en/functions/cast/ToString.md
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/string]
|
||||
---
|
||||
|
||||
With a decimal (base 10) input:
|
||||
|
||||
```go-html-template
|
||||
{{ string 11 }} → 11 (string)
|
||||
{{ string "11" }} → 11 (string)
|
||||
|
||||
{{ string 11.1 }} → 11.1 (string)
|
||||
{{ string "11.1" }} → 11.1 (string)
|
||||
|
||||
{{ string 11.9 }} → 11.9 (string)
|
||||
{{ string "11.9" }} → 11.9 (string)
|
||||
```
|
||||
|
||||
With a binary (base 2) input:
|
||||
|
||||
```go-html-template
|
||||
{{ string 0b11 }} → 3 (string)
|
||||
{{ string "0b11" }} → 0b11 (string)
|
||||
```
|
||||
|
||||
With an octal (base 8) input (use either notation):
|
||||
|
||||
```go-html-template
|
||||
{{ string 011 }} → 9 (string)
|
||||
{{ string "011" }} → 011 (string)
|
||||
|
||||
{{ string 0o11 }} → 9 (string)
|
||||
{{ string "0o11" }} → 0o11 (string)
|
||||
```
|
||||
|
||||
With a hexadecimal (base 16) input:
|
||||
|
||||
```go-html-template
|
||||
{{ string 0x11 }} → 17 (string)
|
||||
{{ string "0x11" }} → 0x11 (string)
|
||||
```
|
||||
12
content/en/functions/cast/_index.md
Normal file
12
content/en/functions/cast/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Cast functions
|
||||
linkTitle: cast
|
||||
description: Template 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.
|
||||
71
content/en/functions/collections/After.md
Normal file
71
content/en/functions/collections/After.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/after]
|
||||
---
|
||||
|
||||
The following shows `after` being used in conjunction with the [`slice`]function:
|
||||
|
||||
```go-html-template
|
||||
{{ $data := slice "one" "two" "three" "four" }}
|
||||
<ul>
|
||||
{{ range after 2 $data }}
|
||||
<li>{{ . }}</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
The template above is rendered to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li>three</li>
|
||||
<li>four</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
|
||||
2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
|
||||
|
||||
{{< code file=layouts/section/articles.html >}}
|
||||
{{ define "main" }}
|
||||
<section class="row featured-article">
|
||||
<h2>Featured Article</h2>
|
||||
{{ range first 1 .Pages.ByPublishDate.Reverse }}
|
||||
<header>
|
||||
<h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
|
||||
</header>
|
||||
<p>{{ .Description }}</p>
|
||||
{{ end }}
|
||||
</section>
|
||||
<div class="row recent-articles">
|
||||
<h2>Recent Articles</h2>
|
||||
{{ range first 3 (after 1 .Pages.ByPublishDate.Reverse) }}
|
||||
<section class="recent-article">
|
||||
<header>
|
||||
<h3><a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
|
||||
</header>
|
||||
<p>{{ .Description }}</p>
|
||||
</section>
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
[`first`]: /functions/collections/first
|
||||
[list/section page]: /templates/section-templates
|
||||
[lists]: /templates/lists/#sort-content
|
||||
[`slice`]: /functions/collections/slice/
|
||||
101
content/en/functions/collections/Append.md
Normal file
101
content/en/functions/collections/Append.md
Normal file
|
|
@ -0,0 +1,101 @@
|
|||
---
|
||||
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
|
||||
aliases: [/functions/append]
|
||||
---
|
||||
|
||||
This function appends all elements, excluding the last, to the last element. This allows [pipe](/getting-started/glossary/#pipeline) constructs as shown below.
|
||||
|
||||
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" }}
|
||||
{{ $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 you start with a slice of a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $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]]
|
||||
```
|
||||
|
||||
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 }}
|
||||
```
|
||||
26
content/en/functions/collections/Apply.md
Normal file
26
content/en/functions/collections/Apply.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
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...]
|
||||
aliases: [/functions/apply]
|
||||
---
|
||||
|
||||
The `apply` function takes three or more arguments, depending on the function being applied to the collection elements.
|
||||
|
||||
The first argument is the collection itself, the second argument is the function name, and the remaining arguments are passed to the function, with the string `"."` representing the collection element.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "hello" "world" }}
|
||||
|
||||
{{ $s = apply $s "strings.FirstUpper" "." }}
|
||||
{{ $s }} → [Hello World]
|
||||
|
||||
{{ $s = apply $s "strings.Replace" "." "l" "_" }}
|
||||
{{ $s }} → [He__o Wor_d]
|
||||
```
|
||||
80
content/en/functions/collections/Complement.md
Normal file
80
content/en/functions/collections/Complement.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
---
|
||||
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...]']
|
||||
aliases: [/functions/complement]
|
||||
---
|
||||
|
||||
To find the elements within `$c3` that do not exist in `$c1` or `$c2`:
|
||||
|
||||
```go-html-template
|
||||
{{ $c1 := slice 3 }}
|
||||
{{ $c2 := slice 4 5 }}
|
||||
{{ $c3 := slice 1 2 3 4 5 }}
|
||||
|
||||
{{ 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 %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $c3 | complement $c1 $c2 }} → [1 2]
|
||||
```
|
||||
|
||||
You can also use the `complement` function with page collections. Let's say your site has five content types:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── blog/
|
||||
├── books/
|
||||
├── faqs/
|
||||
├── films/
|
||||
└── songs/
|
||||
```
|
||||
|
||||
To list everything except blog articles (`blog`) and frequently asked questions (`faqs`):
|
||||
|
||||
```go-html-template
|
||||
{{ $blog := where site.RegularPages "Type" "blog" }}
|
||||
{{ $faqs := where site.RegularPages "Type" "faqs" }}
|
||||
{{ range site.RegularPages | complement $blog $faqs }}
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Although the example above demonstrates the `complement` function, you could use the [`where`] function as well:
|
||||
|
||||
[`where`]: /functions/collections/where
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ range where site.RegularPages "Type" "not in" (slice "blog" "faqs") }}
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
In this example we use the `complement` function to remove [stop words] from a sentence:
|
||||
|
||||
```go-html-template
|
||||
{{ $text := "The quick brown fox jumps over the lazy dog" }}
|
||||
{{ $stopWords := slice "a" "an" "in" "over" "the" "under" }}
|
||||
{{ $filtered := split $text " " | complement $stopWords }}
|
||||
|
||||
{{ delimit $filtered " " }} → The quick brown fox jumps lazy dog
|
||||
```
|
||||
|
||||
[stop words]: https://en.wikipedia.org/wiki/Stop_word
|
||||
33
content/en/functions/collections/Delimit.md
Normal file
33
content/en/functions/collections/Delimit.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
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]']
|
||||
aliases: [/functions/delimit]
|
||||
---
|
||||
|
||||
Delimit a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "b" "a" "c" }}
|
||||
{{ delimit $s ", " }} → b, a, c
|
||||
{{ delimit $s ", " " and "}} → b, a and c
|
||||
```
|
||||
|
||||
Delimit a map:
|
||||
|
||||
{{% note %}}
|
||||
The `delimit` function sorts maps by key, returning the values.
|
||||
{{% /note %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict "b" 2 "a" 1 "c" 3 }}
|
||||
{{ delimit $m ", " }} → 1, 2, 3
|
||||
{{ delimit $m ", " " and "}} → 1, 2 and 3
|
||||
```
|
||||
68
content/en/functions/collections/Dictionary.md
Normal file
68
content/en/functions/collections/Dictionary.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: collections.Dictionary
|
||||
description: Creates a map from a list of key and value pairs.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [dict]
|
||||
related:
|
||||
- functions/collections/Slice
|
||||
returnType: mapany
|
||||
signatures: ['collections.Dictionary KEY VALUE [VALUE...]']
|
||||
aliases: [/functions/dict]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict "a" 1 "b" 2 }}
|
||||
```
|
||||
|
||||
The above produces this data structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"a": 1,
|
||||
"b": 2
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Note that the `key` can be either a `string` or a `string slice`. The latter is useful to create a deeply nested structure, e.g.:
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict (slice "a" "b" "c") "value" }}
|
||||
```
|
||||
|
||||
The above produces this data structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"a": {
|
||||
"b": {
|
||||
"c": "value"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Pass values to a partial template
|
||||
|
||||
The partial below creates an SVG and expects `fill`, `height` and `width` from the caller:
|
||||
|
||||
### Partial definition
|
||||
|
||||
{{< code file=layouts/partials/svgs/external-links.svg >}}
|
||||
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link">
|
||||
<path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>
|
||||
</svg>
|
||||
{{< /code >}}
|
||||
|
||||
### Partial call
|
||||
|
||||
The `fill`, `height` and `width` values can be stored in one object with `dict` and passed to the partial:
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
{{ partial "svgs/external-links.svg" (dict "fill" "#01589B" "width" 10 "height" 20 ) }}
|
||||
{{< /code >}}
|
||||
|
||||
[partials]: /templates/partials/
|
||||
37
content/en/functions/collections/First.md
Normal file
37
content/en/functions/collections/First.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/first]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ range first 5 .Pages }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Set `N` to zero to return an empty collection.
|
||||
|
||||
```go-html-template
|
||||
{{ $emptyPageCollection := first 0 .Pages}}
|
||||
```
|
||||
|
||||
Use `first` and [`where`] together.
|
||||
|
||||
```go-html-template
|
||||
{{ range where .Pages "Section" "articles" | first 5 }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[`where`]: /functions/collections/where
|
||||
31
content/en/functions/collections/Group.md
Normal file
31
content/en/functions/collections/Group.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/group]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $new := .Site.RegularPages | first 10 | group "New" }}
|
||||
{{ $old := .Site.RegularPages | last 10 | group "Old" }}
|
||||
{{ $groups := slice $new $old }}
|
||||
{{ range $groups }}
|
||||
<h3>{{ .Key }}{{/* Prints "New", "Old" */}}</h3>
|
||||
<ul>
|
||||
{{ range .Pages }}
|
||||
<li>
|
||||
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
|
||||
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>
|
||||
</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The page group you get from `group` is of the same type you get from the built-in [group methods](/templates/lists#group-content) in Hugo. The above example can be [paginated](/templates/pagination/#list-paginator-pages).
|
||||
43
content/en/functions/collections/In.md
Normal file
43
content/en/functions/collections/In.md
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/in]
|
||||
---
|
||||
|
||||
The `SET` can be an [array], [slice], or [string].
|
||||
|
||||
[array]: /getting-started/glossary/#array
|
||||
[slice]: /getting-started/glossary/#slice
|
||||
[string]: /getting-started/glossary/#string
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "a" "b" "c" }}
|
||||
{{ in $s "b" }} → true
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice 1 2 3 }}
|
||||
{{ in $s 2 }} → true
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice 1.11 2.22 3.33 }}
|
||||
{{ in $s 2.22 }} → true
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $s := "abc" }}
|
||||
{{ in $s "b" }} → true
|
||||
```
|
||||
95
content/en/functions/collections/IndexFunction.md
Normal file
95
content/en/functions/collections/IndexFunction.md
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
---
|
||||
title: collections.Index
|
||||
description: Looks up the index(es) or key(s) of the data structure passed into it.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [index]
|
||||
related: []
|
||||
returnType: any
|
||||
signatures:
|
||||
- collections.Index COLLECTION INDEXES
|
||||
- collections.Index COLLECTION KEYS
|
||||
aliases: [/functions/index,/functions/index-function]
|
||||
---
|
||||
|
||||
The `index` functions returns the result of indexing its first argument by the following arguments. Each indexed item must be a map or a slice, e.g.:
|
||||
|
||||
```go-html-template
|
||||
{{ $slice := slice "a" "b" "c" }}
|
||||
{{ index $slice 0 }} → a
|
||||
{{ index $slice 1 }} → b
|
||||
|
||||
{{ $map := dict "a" 100 "b" 200 }}
|
||||
{{ index $map "b" }} → 200
|
||||
```
|
||||
|
||||
The function takes multiple indices as arguments, and this can be used to get nested values, e.g.:
|
||||
|
||||
```go-html-template
|
||||
{{ $map := dict "a" 100 "b" 200 "c" (slice 10 20 30) }}
|
||||
{{ index $map "c" 1 }} → 20
|
||||
{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
|
||||
{{ index $map "c" "e" }} → 20
|
||||
```
|
||||
|
||||
You may write multiple indices as a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $map := dict "a" 100 "b" 200 "c" (dict "d" 10 "e" 20) }}
|
||||
{{ $slice := slice "c" "e" }}
|
||||
{{ index $map $slice }} → 20
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```text
|
||||
data/
|
||||
└── locations/
|
||||
├── abilene.toml
|
||||
├── chicago.toml
|
||||
├── oslo.toml
|
||||
└── provo.toml
|
||||
```
|
||||
|
||||
Here is an example:
|
||||
|
||||
{{< code-toggle file=data/locations/oslo >}}
|
||||
website = "https://www.oslo.kommune.no"
|
||||
pop_city = 658390
|
||||
pop_metro = 1717900
|
||||
{{< /code-toggle >}}
|
||||
|
||||
The example we will use will be an article on Oslo, whose front matter should be set to exactly the same name as the corresponding file name in `data/locations/`:
|
||||
|
||||
{{< code-toggle file=content/articles/oslo.md fm=true >}}
|
||||
title = "My Norwegian Vacation"
|
||||
location = "oslo"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
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 arguments in this use case:
|
||||
|
||||
1. The node path
|
||||
2. A string corresponding to the desired data; e.g.—
|
||||
|
||||
```go-html-template
|
||||
{{ index .Site.Data.locations "oslo" }}
|
||||
```
|
||||
|
||||
The variable for `.Params.location` is a string and can therefore replace `oslo` in the example above:
|
||||
|
||||
```go-html-template
|
||||
{{ index .Site.Data.locations .Params.location }}
|
||||
=> map[website:https://www.oslo.kommune.no pop_city:658390 pop_metro:1717900]
|
||||
```
|
||||
|
||||
Now the call will return the specific file according to the location specified in the content's front matter, but you will likely want to write specific properties to the template. You can do this by continuing down the node path via dot notation (`.`):
|
||||
|
||||
```go-html-template
|
||||
{{ (index .Site.Data.locations .Params.location).pop_city }}
|
||||
=> 658390
|
||||
```
|
||||
30
content/en/functions/collections/Intersect.md
Normal file
30
content/en/functions/collections/Intersect.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/intersect]
|
||||
---
|
||||
|
||||
A useful example is to use it as `AND` filters when combined with where:
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
|
||||
{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }}
|
||||
{{ $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 parameters.
|
||||
|
||||
See [union](/functions/collections/union) for `OR`.
|
||||
|
||||
[partials]: /templates/partials/
|
||||
[single]: /templates/single-page-templates/
|
||||
45
content/en/functions/collections/IsSet.md
Normal file
45
content/en/functions/collections/IsSet.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/isset]
|
||||
---
|
||||
|
||||
For example, consider this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[params]
|
||||
showHeroImage = false
|
||||
{{< /code-toggle >}}
|
||||
|
||||
It the value of `showHeroImage` is `true`, we can detect that it exists using either `if` or `with`:
|
||||
|
||||
```go-html-template
|
||||
{{ if site.Params.showHeroImage }}
|
||||
{{ site.Params.showHeroImage }} → true
|
||||
{{ end }}
|
||||
|
||||
{{ with site.Params.showHeroImage }}
|
||||
{{ . }} → true
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
But if the value of `showHeroImage` is `false`, we can't use either `if` or `with` to detect its existence. In this case, you must use the `isset` function:
|
||||
|
||||
```go-html-template
|
||||
{{ if isset site.Params "showheroimage" }}
|
||||
<p>The showHeroImage parameter is set to {{ site.Params.showHeroImage }}.<p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
When using the `isset` function you must reference the key using lower case. See the previous example.
|
||||
{{% /note %}}
|
||||
43
content/en/functions/collections/KeyVals.md
Normal file
43
content/en/functions/collections/KeyVals.md
Normal file
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
title: collections.KeyVals
|
||||
description: Returns a KeyVals struct.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [keyVals]
|
||||
related:
|
||||
- methods/pages/Related
|
||||
returnType: types.KeyValues
|
||||
signatures: [collections.KeyVals KEY VALUES...]
|
||||
aliases: [/functions/keyvals]
|
||||
---
|
||||
|
||||
The primary application for this function is the definition of the `namedSlices` parameter in the options map passed to the [`Related`] method on the `Pages` object.
|
||||
|
||||
[`Related`]: /methods/pages/related
|
||||
|
||||
See [related content](/content-management/related).
|
||||
|
||||
```go-html-template
|
||||
{{ $kv := keyVals "foo" "a" "b" "c" }}
|
||||
```
|
||||
|
||||
The resulting data structure is:
|
||||
|
||||
```json
|
||||
{
|
||||
"Key": "foo",
|
||||
"Values": [
|
||||
"a",
|
||||
"b",
|
||||
"c"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
To extract the key and values:
|
||||
|
||||
```go-html-template
|
||||
{{ $kv.Key }} → foo
|
||||
{{ $kv.Values }} → [a b c]
|
||||
```
|
||||
34
content/en/functions/collections/Last.md
Normal file
34
content/en/functions/collections/Last.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/last]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ range last 10 .Pages }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Set `N` to zero to return an empty collection.
|
||||
|
||||
```go-html-template
|
||||
{{ $emptyPageCollection := last 0 .Pages}}
|
||||
```
|
||||
|
||||
Use `last` and [`where`] together.
|
||||
|
||||
```go-html-template
|
||||
{{ range where .Pages "Section" "articles" | last 5 }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
```
|
||||
69
content/en/functions/collections/Merge.md
Normal file
69
content/en/functions/collections/Merge.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
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...]
|
||||
aliases: [/functions/merge]
|
||||
---
|
||||
|
||||
Returns the result of merging two or more maps from left to right. If a key already exists, `merge` updates its value. If a key is absent, `merge` inserts the value under the new key.
|
||||
|
||||
Key handling is case-insensitive.
|
||||
|
||||
The following examples use these map definitions:
|
||||
|
||||
```go-html-template
|
||||
{{ $m1 := dict "x" "foo" }}
|
||||
{{ $m2 := dict "x" "bar" "y" "wibble" }}
|
||||
{{ $m3 := dict "x" "baz" "y" "wobble" "z" (dict "a" "huey") }}
|
||||
```
|
||||
|
||||
Example 1
|
||||
|
||||
```go-html-template
|
||||
{{ $merged := merge $m1 $m2 $m3 }}
|
||||
|
||||
{{ $merged.x }} → baz
|
||||
{{ $merged.y }} → wobble
|
||||
{{ $merged.z.a }} → huey
|
||||
```
|
||||
|
||||
Example 2
|
||||
|
||||
```go-html-template
|
||||
{{ $merged := merge $m3 $m2 $m1 }}
|
||||
|
||||
{{ $merged.x }} → foo
|
||||
{{ $merged.y }} → wibble
|
||||
{{ $merged.z.a }} → huey
|
||||
```
|
||||
|
||||
Example 3
|
||||
|
||||
```go-html-template
|
||||
{{ $merged := merge $m2 $m3 $m1 }}
|
||||
|
||||
{{ $merged.x }} → foo
|
||||
{{ $merged.y }} → wobble
|
||||
{{ $merged.z.a }} → huey
|
||||
```
|
||||
|
||||
Example 4
|
||||
|
||||
```go-html-template
|
||||
{{ $merged := merge $m1 $m3 $m2 }}
|
||||
|
||||
{{ $merged.x }} → bar
|
||||
{{ $merged.y }} → wibble
|
||||
{{ $merged.z.a }} → huey
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Regardless of depth, merging only applies to maps. For slices, use [append](/functions/collections/append).
|
||||
{{% /note %}}
|
||||
124
content/en/functions/collections/NewScratch.md
Normal file
124
content/en/functions/collections/NewScratch.md
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
---
|
||||
title: collections.NewScratch
|
||||
description: Returns a locally scoped "scratch pad" to store and manipulate data.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [newScratch]
|
||||
related:
|
||||
- methods/page/scratch
|
||||
- methods/page/store
|
||||
- methods/shortcode/scratch
|
||||
returnType: maps.Scratch
|
||||
signatures: [collections.NewScratch ]
|
||||
---
|
||||
|
||||
The `collections.NewScratch` function creates a locally scoped [scratch pad] to store and manipulate data. To create a scratch pad that is attached to a `Page` object, use the [`Scratch`] or [`Store`] method.
|
||||
|
||||
[`Scratch`]: /methods/page/scratch
|
||||
[`Store`]: /methods/page/store
|
||||
[scratch pad]: /getting-started/glossary/#scratch-pad
|
||||
|
||||
## Methods
|
||||
|
||||
###### Set
|
||||
|
||||
Sets the value of a given key.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.Set "greeting" "Hello" }}
|
||||
```
|
||||
|
||||
###### Get
|
||||
|
||||
Gets the value of a given key.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.Set "greeting" "Hello" }}
|
||||
{{ $s.Get "greeting" }} → Hello
|
||||
```
|
||||
|
||||
###### Add
|
||||
|
||||
Adds a given value to existing value(s) of the given key.
|
||||
|
||||
For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.Set "greeting" "Hello" }}
|
||||
{{ $s.Add "greeting" "Welcome" }}
|
||||
{{ $s.Get "greeting" }} → HelloWelcome
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.Set "total" 3 }}
|
||||
{{ $s.Add "total" 7 }}
|
||||
{{ $s.Get "total" }} → 10
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.Set "greetings" (slice "Hello") }}
|
||||
{{ $s.Add "greetings" (slice "Welcome" "Cheers") }}
|
||||
{{ $s.Get "greetings" }} → [Hello Welcome Cheers]
|
||||
```
|
||||
|
||||
###### SetInMap
|
||||
|
||||
Takes a `key`, `mapKey` and `value` and adds a map of `mapKey` and `value` to the given `key`.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ $s.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ $s.Get "greetings" }} → map[english:Hello french:Bonjour]
|
||||
```
|
||||
|
||||
###### DeleteInMap
|
||||
|
||||
Takes a `key` and `mapKey` and removes the map of `mapKey` from the given `key`.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ $s.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ $s.DeleteInMap "greetings" "english" }}
|
||||
{{ $s.Get "greetings" }} → map[french:Bonjour]
|
||||
```
|
||||
|
||||
###### GetSortedMapValues
|
||||
|
||||
Returns an array of values from `key` sorted by `mapKey`.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ $s.SetInMap "greetings" "french" "Bonjour" }}
|
||||
{{ $s.GetSortedMapValues "greetings" }} → [Hello Bonjour]
|
||||
```
|
||||
|
||||
###### Delete
|
||||
|
||||
Removes the given key.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.Set "greeting" "Hello" }}
|
||||
{{ $s.Delete "greeting" }}
|
||||
```
|
||||
|
||||
###### Values
|
||||
|
||||
Returns the raw backing map. Do not use with `Scratch` or `Store` methods on a `Page` object due to concurrency issues.
|
||||
|
||||
```go-html-template
|
||||
{{ $s := newScratch }}
|
||||
{{ $s.SetInMap "greetings" "english" "Hello" }}
|
||||
{{ $s.SetInMap "greetings" "french" "Bonjour" }}
|
||||
|
||||
{{ $map := $s.Values }}
|
||||
```
|
||||
32
content/en/functions/collections/Querify.md
Normal file
32
content/en/functions/collections/Querify.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
title: collections.Querify
|
||||
description: Takes a set or slice of key-value pairs and returns a query string to be appended to URLs.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [querify]
|
||||
related:
|
||||
- functions/go-template/urlquery.md
|
||||
returnType: string
|
||||
signatures:
|
||||
- collections.Querify VALUE [VALUE...]
|
||||
- collections.Querify COLLECTION
|
||||
aliases: [/functions/querify]
|
||||
---
|
||||
|
||||
`querify` takes a set or slice of key-value pairs and returns a [query string](https://en.wikipedia.org/wiki/Query_string) that can be appended to a URL.
|
||||
|
||||
The following examples create a link to a search results page on Google.
|
||||
|
||||
```go-html-template
|
||||
<a href="https://www.google.com?{{ (querify "q" "test" "page" 3) | safeURL }}">Search</a>
|
||||
|
||||
{{ $qs := slice "q" "test" "page" 3 }}
|
||||
<a href="https://www.google.com?{{ (querify $qs) | safeURL }}">Search</a>
|
||||
```
|
||||
|
||||
Both of these examples render the following HTML:
|
||||
|
||||
```html
|
||||
<a href="https://www.google.com?page=3&q=test">Search</a>
|
||||
```
|
||||
19
content/en/functions/collections/Reverse.md
Normal file
19
content/en/functions/collections/Reverse.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/collections.reverse]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ slice 2 1 3 | collections.Reverse }} → [3 1 2]
|
||||
```
|
||||
36
content/en/functions/collections/Seq.md
Normal file
36
content/en/functions/collections/Seq.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
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
|
||||
aliases: [/functions/seq]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ seq 2 }} → [1 2]
|
||||
{{ seq 0 2 }} → [0 1 2]
|
||||
{{ seq -2 2 }} → [-2 -1 0 1 2]
|
||||
{{ seq -2 2 2 }} → [-2 0 2]
|
||||
```
|
||||
|
||||
A contrived example of iterating over a sequence of integers:
|
||||
|
||||
```go-html-template
|
||||
{{ $product := 1 }}
|
||||
{{ range seq 4 }}
|
||||
{{ $product = mul $product . }}
|
||||
{{ end }}
|
||||
{{ $product }} → 24
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
The slice created by the `seq` function is limited to 2000 elements.
|
||||
{{% /note %}}
|
||||
22
content/en/functions/collections/Shuffle.md
Normal file
22
content/en/functions/collections/Shuffle.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/shuffle]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ shuffle (seq 1 2 3) }} → [3 1 2]
|
||||
{{ shuffle (slice "a" "b" "c") }} → [b a c]
|
||||
```
|
||||
|
||||
The result will vary from one build to the next.
|
||||
18
content/en/functions/collections/Slice.md
Normal file
18
content/en/functions/collections/Slice.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: collections.Slice
|
||||
description: Creates a slice of all passed arguments.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [slice]
|
||||
related:
|
||||
- functions/collections/Dictionary
|
||||
returnType: any
|
||||
signatures: [collections.Slice ITEM...]
|
||||
aliases: [/functions/slice]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "a" "b" "c" }}
|
||||
{{ $s }} → [a b c]
|
||||
```
|
||||
156
content/en/functions/collections/Sort.md
Normal file
156
content/en/functions/collections/Sort.md
Normal file
|
|
@ -0,0 +1,156 @@
|
|||
---
|
||||
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
|
||||
aliases: [/functions/sort]
|
||||
---
|
||||
|
||||
The `KEY` is optional when sorting slices in ascending order, otherwise it is required. When sorting slices, use the literal `value` in place of the `KEY`. See examples below.
|
||||
|
||||
The `ORDER` may be either `asc` (ascending) or `desc` (descending). The default sort order is ascending.
|
||||
|
||||
## Sort a slice
|
||||
|
||||
The examples below assume this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[params]
|
||||
grades = ['b','a','c']
|
||||
{{< /code-toggle >}}
|
||||
|
||||
### Ascending order {#slice-ascending-order}
|
||||
|
||||
Sort slice elements in ascending order using either of these constructs:
|
||||
|
||||
```go-html-template
|
||||
{{ sort site.Params.grades }} → [a b c]
|
||||
{{ sort site.Params.grades "value" "asc" }} → [a b c]
|
||||
```
|
||||
|
||||
In the examples above, `value` is the `KEY` representing the value of the slice element.
|
||||
|
||||
### Descending order {#slice-descending-order}
|
||||
|
||||
Sort slice elements in descending order:
|
||||
|
||||
```go-html-template
|
||||
{{ sort site.Params.grades "value" "desc" }} → [c b a]
|
||||
```
|
||||
|
||||
In the example above, `value` is the `KEY` representing the value of the slice element.
|
||||
|
||||
## Sort a map
|
||||
|
||||
The examples below assume this site configuration:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[params.authors.a]
|
||||
firstName = "Marius"
|
||||
lastName = "Pontmercy"
|
||||
[params.authors.b]
|
||||
firstName = "Victor"
|
||||
lastName = "Hugo"
|
||||
[params.authors.c]
|
||||
firstName = "Jean"
|
||||
lastName = "Valjean"
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{% note %}}
|
||||
When sorting maps, the `KEY` argument must be lowercase.
|
||||
{{% /note %}}
|
||||
|
||||
### Ascending order {#map-ascending-order}
|
||||
|
||||
Sort map objects in ascending order using either of these constructs:
|
||||
|
||||
```go-html-template
|
||||
{{ range sort site.Params.authors "firstname" }}
|
||||
{{ .firstName }}
|
||||
{{ end }}
|
||||
|
||||
{{ range sort site.Params.authors "firstname" "asc" }}
|
||||
{{ .firstName }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
These produce:
|
||||
|
||||
```text
|
||||
Jean Marius Victor
|
||||
```
|
||||
|
||||
### Descending order {#map-descending-order}
|
||||
|
||||
Sort map objects in descending order:
|
||||
|
||||
```go-html-template
|
||||
{{ range sort site.Params.authors "firstname" "desc" }}
|
||||
{{ .firstName }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
This produces:
|
||||
|
||||
```text
|
||||
Victor Marius Jean
|
||||
```
|
||||
|
||||
### First level key removal
|
||||
|
||||
Hugo removes the first level keys when sorting a map.
|
||||
|
||||
Original map:
|
||||
|
||||
```json
|
||||
{
|
||||
"felix": {
|
||||
"breed": "malicious",
|
||||
"type": "cat"
|
||||
},
|
||||
"spot": {
|
||||
"breed": "boxer",
|
||||
"type": "dog"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
After sorting:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"breed": "malicious",
|
||||
"type": "cat"
|
||||
},
|
||||
{
|
||||
"breed": "boxer",
|
||||
"type": "dog"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 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 %}}
|
||||
|
||||
In this contrived example, sort the site's regular pages by `.Type` in descending order:
|
||||
|
||||
```go-html-template
|
||||
{{ range sort site.RegularPages "Type" "desc" }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
```
|
||||
24
content/en/functions/collections/SymDiff.md
Normal file
24
content/en/functions/collections/SymDiff.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/symdiff]
|
||||
---
|
||||
|
||||
Example:
|
||||
|
||||
```go-html-template
|
||||
{{ slice 1 2 3 | symdiff (slice 3 4) }} → [1 2 4]
|
||||
```
|
||||
|
||||
Also see <https://en.wikipedia.org/wiki/Symmetric_difference>.
|
||||
46
content/en/functions/collections/Union.md
Normal file
46
content/en/functions/collections/Union.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
---
|
||||
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]
|
||||
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) nil }}
|
||||
<!-- returns [1 2 3] -->
|
||||
|
||||
{{ union nil (slice 1 2 3) }}
|
||||
<!-- returns [1 2 3] -->
|
||||
|
||||
{{ union nil nil }}
|
||||
<!-- returns an error because both arrays/slices have to be of the same type -->
|
||||
```
|
||||
|
||||
## OR filter in where query
|
||||
|
||||
This is also very useful to use as `OR` filters when combined with where:
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }}
|
||||
{{ $pages = $pages | union (where .Site.RegularPages "Params.pinned" true) }}
|
||||
{{ $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 parameters.
|
||||
|
||||
See [intersect](/functions/collections/intersect) for `AND`.
|
||||
20
content/en/functions/collections/Uniq.md
Normal file
20
content/en/functions/collections/Uniq.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/uniq]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ slice 1 3 2 1 | uniq }} → [1 3 2]
|
||||
```
|
||||
446
content/en/functions/collections/Where.md
Normal file
446
content/en/functions/collections/Where.md
Normal file
|
|
@ -0,0 +1,446 @@
|
|||
---
|
||||
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
|
||||
aliases: [/functions/where]
|
||||
---
|
||||
|
||||
The `where` function returns the given collection, removing elements that do not satisfy the comparison condition. The comparison condition is comprised of the `KEY`, `OPERATOR`, and `VALUE` arguments:
|
||||
|
||||
```text
|
||||
collections.Where COLLECTION KEY [OPERATOR] VALUE
|
||||
--------------------
|
||||
comparison condition
|
||||
```
|
||||
|
||||
Hugo will test for equality if you do not provide an `OPERATOR` argument. For example:
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Section" "books" }}
|
||||
{{ $books := where .Site.Data.books "genres" "suspense" }}
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
The where function takes three or four arguments. The `OPERATOR` argument is optional.
|
||||
|
||||
COLLECTION
|
||||
: (`any`) A [page collection] or a [slice] of [maps].
|
||||
|
||||
[maps]: /getting-started/glossary/#map
|
||||
[page collection]: /getting-started/glossary/#page-collection
|
||||
[slice]: /getting-started/glossary/#slice
|
||||
|
||||
KEY
|
||||
: (`string`) The key of the page or map value to compare with `VALUE`. With page collections, commonly used comparison keys are `Section`, `Type`, and `Params`. To compare with a member of the page `Params` map, [chain] the subkey as shown below:
|
||||
|
||||
```go-html-template
|
||||
{{ $result := where .Site.RegularPages "Params.foo" "bar" }}
|
||||
```
|
||||
|
||||
[chain]: /getting-started/glossary/#chain
|
||||
|
||||
OPERATOR
|
||||
: (`string`) The logical comparison [operator](#operators).
|
||||
|
||||
VALUE
|
||||
: (`any`) The value with which to compare. The values to compare must have comparable data types. For example:
|
||||
|
||||
Comparison|Result
|
||||
:--|:--
|
||||
`"123" "eq" "123"`|`true`
|
||||
`"123" "eq" 123`|`false`
|
||||
`false "eq" "false"`|`false`
|
||||
`false "eq" false`|`true`
|
||||
|
||||
When one or both of the values to compare is a slice, use the `in`, `not in`, or `intersect` operators as described below.
|
||||
|
||||
## Operators
|
||||
|
||||
Use any of the following logical operators:
|
||||
|
||||
`=`, `==`, `eq`
|
||||
: (`bool`) Reports whether the given field value is equal to `VALUE`.
|
||||
|
||||
`!=`, `<>`, `ne`
|
||||
: (`bool`) Reports whether the given field value is not equal to `VALUE`.
|
||||
|
||||
`>=`, `ge`
|
||||
: (`bool`) Reports whether the given field value is greater than or equal to `VALUE`.
|
||||
|
||||
`>`, `gt`
|
||||
: `true` Reports whether the given field value is greater than `VALUE`.
|
||||
|
||||
`<=`, `le`
|
||||
: (`bool`) Reports whether the given field value is less than or equal to `VALUE`.
|
||||
|
||||
`<`, `lt`
|
||||
: (`bool`) Reports whether the given field value is less than `VALUE`.
|
||||
|
||||
`in`
|
||||
: (`bool`) Reports whether the given field value is a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
|
||||
|
||||
`not in`
|
||||
: (`bool`) Reports whether the given field value is not a member of `VALUE`. Compare string to slice, or string to string. See [details](/functions/collections/in).
|
||||
|
||||
`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.
|
||||
|
||||
{{% note %}}
|
||||
The examples below perform comparisons within a page collection, but the same comparisons are applicable to a slice of maps.
|
||||
{{% /note %}}
|
||||
|
||||
## String comparison
|
||||
|
||||
Compare the value of the given field to a [`string`]:
|
||||
|
||||
[`string`]: /getting-started/glossary/#string
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Section" "eq" "books" }}
|
||||
{{ $pages := where .Site.RegularPages "Section" "ne" "books" }}
|
||||
```
|
||||
|
||||
## Numeric comparison
|
||||
|
||||
Compare the value of the given field to an [`int`] or [`float`]:
|
||||
|
||||
[`int`]: /getting-started/glossary/#int
|
||||
[`float`]: /getting-started/glossary/#float
|
||||
|
||||
```go-html-template
|
||||
{{ $books := where site.RegularPages "Section" "eq" "books" }}
|
||||
|
||||
{{ $pages := where $books "Params.price" "eq" 42 }}
|
||||
{{ $pages := where $books "Params.price" "ne" 42.67 }}
|
||||
{{ $pages := where $books "Params.price" "ge" 42 }}
|
||||
{{ $pages := where $books "Params.price" "gt" 42.67 }}
|
||||
{{ $pages := where $books "Params.price" "le" 42 }}
|
||||
{{ $pages := where $books "Params.price" "lt" 42.67 }}
|
||||
```
|
||||
|
||||
## Boolean comparison
|
||||
|
||||
Compare the value of the given field to a [`bool`]:
|
||||
|
||||
[`bool`]: /getting-started/glossary/#bool
|
||||
|
||||
```go-html-template
|
||||
{{ $books := where site.RegularPages "Section" "eq" "books" }}
|
||||
|
||||
{{ $pages := where $books "Params.fiction" "eq" true }}
|
||||
{{ $pages := where $books "Params.fiction" "eq" false }}
|
||||
{{ $pages := where $books "Params.fiction" "ne" true }}
|
||||
{{ $pages := where $books "Params.fiction" "ne" false }}
|
||||
```
|
||||
|
||||
## Member comparison
|
||||
|
||||
Compare a [`scalar`] to a [`slice`].
|
||||
|
||||
[`scalar`]: /getting-started/glossary/#scalar
|
||||
[`slice`]: /getting-started/glossary/#slice
|
||||
|
||||
For example, to return a collection of pages where the `color` page parameter is either "red" or "yellow":
|
||||
|
||||
```go-html-template
|
||||
{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
|
||||
|
||||
{{ $colors := slice "red" "yellow" }}
|
||||
{{ $pages := where $fruit "Params.color" "in" $colors }}
|
||||
```
|
||||
|
||||
To return a collection of pages where the "color" page parameter is neither "red" nor "yellow":
|
||||
|
||||
```go-html-template
|
||||
{{ $fruit := where site.RegularPages "Section" "eq" "fruit" }}
|
||||
|
||||
{{ $colors := slice "red" "yellow" }}
|
||||
{{ $pages := where $fruit "Params.color" "not in" $colors }}
|
||||
```
|
||||
|
||||
## Intersection comparison
|
||||
|
||||
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":
|
||||
|
||||
```go-html-template
|
||||
{{ $books := where site.RegularPages "Section" "eq" "books" }}
|
||||
|
||||
{{ $genres := slice "suspense" "romance" }}
|
||||
{{ $pages := where $books "Params.genres" "intersect" $genres }}
|
||||
```
|
||||
|
||||
## Regular expression comparison
|
||||
|
||||
{{< new-in 0.116.0 >}}
|
||||
|
||||
To return a collection of pages where the "author" page parameter begins with either "victor" or "Victor":
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Params.author" "like" `(?i)^victor` }}
|
||||
```
|
||||
|
||||
{{% include "functions/_common/regular-expressions.md" %}}
|
||||
|
||||
{{% note %}}
|
||||
Use the `like` operator to compare string values. Comparing other data types will result in an empty collection.
|
||||
{{% /note %}}
|
||||
|
||||
## Date comparison
|
||||
|
||||
### Predefined dates
|
||||
|
||||
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
|
||||
{{ $startOfYear := time.AsTime (printf "%d-01-01" now.Year) }}
|
||||
{{ $pages := where .Site.RegularPages "Date" "lt" $startOfYear }}
|
||||
```
|
||||
|
||||
### Custom dates
|
||||
|
||||
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 %}}
|
||||
|
||||
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" >}}
|
||||
+++
|
||||
title = '2024 User Conference"
|
||||
eventDate = 2024-04-01
|
||||
+++
|
||||
{{< /code >}}
|
||||
|
||||
To return a collection of future events:
|
||||
|
||||
```go-html-template
|
||||
{{ $events := where .Site.RegularPages "Type" "events" }}
|
||||
{{ $futureEvents := where $events "Params.eventDate" "gt" now }}
|
||||
```
|
||||
|
||||
When working with YAML or JSON, or quoted TOML values, custom dates are strings; you cannot compare them with `time.Time` values. String comparisons may be possible if the custom date layout is consistent from one page to the next. However, to be safe, filter the pages by ranging through the collection:
|
||||
|
||||
```go-html-template
|
||||
{{ $events := where .Site.RegularPages "Type" "events" }}
|
||||
{{ $futureEvents := slice }}
|
||||
{{ range $events }}
|
||||
{{ if gt (time.AsTime .Params.eventDate) now }}
|
||||
{{ $futureEvents = $futureEvents | append . }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Nil comparison
|
||||
|
||||
To return a collection of pages where the "color" parameter is present in front matter, compare to `nil`:
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Params.color" "ne" nil }}
|
||||
```
|
||||
|
||||
To return a collection of pages where the "color" parameter is not present in front matter, compare to `nil`:
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Params.color" "eq" nil }}
|
||||
```
|
||||
|
||||
In both examples above, note that `nil` is not quoted.
|
||||
|
||||
## Nested comparison
|
||||
|
||||
These are equivalent:
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where .Site.RegularPages "Type" "tutorials" }}
|
||||
{{ $pages = where $pages "Params.level" "eq" "beginner" }}
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $pages := where (where .Site.RegularPages "Type" "tutorials") "Params.level" "eq" "beginner" }}
|
||||
```
|
||||
|
||||
## Portable section comparison
|
||||
|
||||
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 }}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Boolean/undefined comparison
|
||||
|
||||
Consider this site content:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── posts/
|
||||
│ ├── _index.md
|
||||
│ ├── post-1.md <-- front matter: exclude = false
|
||||
│ ├── post-2.md <-- front matter: exclude = true
|
||||
│ └── post-3.md <-- front matter: exclude not defined
|
||||
└── _index.md
|
||||
```
|
||||
|
||||
The first two pages have an "exclude" field in front matter, but the last page does not. When testing for _equality_, the third page is _excluded_ from the result. When testing for _inequality_, the third page is _included_ in the result.
|
||||
|
||||
### Equality test
|
||||
|
||||
This template:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range where .Site.RegularPages "Params.exclude" "eq" false }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/posts/post-1/">Post 1</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
This template:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range where .Site.RegularPages "Params.exclude" "eq" true }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/posts/post-2/">Post 2</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
### Inequality test
|
||||
|
||||
This template:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range where .Site.RegularPages "Params.exclude" "ne" false }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/posts/post-2/">Post 2</a></li>
|
||||
<li><a href="/posts/post-3/">Post 3</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
This template:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range where .Site.RegularPages "Params.exclude" "ne" true }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/posts/post-1/">Post 1</a></li>
|
||||
<li><a href="/posts/post-3/">Post 3</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
To exclude a page with an undefined field from a boolean _inequality_ test:
|
||||
|
||||
1. Create a collection using a boolean comparison
|
||||
2. Create a collection using a nil comparison
|
||||
3. Subtract the second collection from the first collection using the [`collections.Complement`] function.
|
||||
|
||||
[`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 }}
|
||||
<ul>
|
||||
{{ range $p1 | complement $p2 }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/posts/post-1/">Post 1</a></li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
This template:
|
||||
|
||||
```go-html-template
|
||||
{{ $p1 := where .Site.RegularPages "Params.exclude" "ne" false }}
|
||||
{{ $p2 := where .Site.RegularPages "Params.exclude" "eq" nil }}
|
||||
<ul>
|
||||
{{ range $p1 | complement $p2 }}
|
||||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<ul>
|
||||
<li><a href="/posts/post-1/">Post 2</a></li>
|
||||
</ul>
|
||||
```
|
||||
12
content/en/functions/collections/_index.md
Normal file
12
content/en/functions/collections/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Collections functions
|
||||
linkTitle: collections
|
||||
description: Template 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.
|
||||
41
content/en/functions/compare/Conditional.md
Normal file
41
content/en/functions/compare/Conditional.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/cond]
|
||||
---
|
||||
|
||||
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
|
||||
{{ $qty := 42 }}
|
||||
{{ cond (le $qty 3) "few" "many" }} → many
|
||||
```
|
||||
|
||||
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 %}}
|
||||
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.
|
||||
|
||||
[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" }}
|
||||
```
|
||||
48
content/en/functions/compare/Default.md
Normal file
48
content/en/functions/compare/Default.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
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]
|
||||
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 %}}
|
||||
|
||||
The `default` function returns the second argument if set:
|
||||
|
||||
```go-html-template
|
||||
{{ default 42 1 }} → 1
|
||||
{{ default 42 "foo" }} → foo
|
||||
{{ default 42 (dict "k" "v") }} → map[k:v]
|
||||
{{ default 42 (slice "a" "b") }} → [a b]
|
||||
{{ default 42 true }} → true
|
||||
|
||||
<!-- As noted above, the boolean "false" is considered set -->
|
||||
{{ default 42 false }} → false
|
||||
```
|
||||
|
||||
The `default` function returns the first argument if the second argument is not set:
|
||||
|
||||
```go-html-template
|
||||
{{ default 42 0 }} → 42
|
||||
{{ default 42 "" }} → 42
|
||||
{{ default 42 dict }} → 42
|
||||
{{ default 42 slice }} → 42
|
||||
{{ default 42 <nil> }} → 42
|
||||
```
|
||||
27
content/en/functions/compare/Eq.md
Normal file
27
content/en/functions/compare/Eq.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
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...]']
|
||||
aliases: [/functions/eq]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ eq 1 1 }} → true
|
||||
{{ eq 1 2 }} → false
|
||||
|
||||
{{ eq 1 1 1 }} → true
|
||||
{{ eq 1 1 2 }} → true
|
||||
{{ eq 1 2 1 }} → true
|
||||
{{ eq 1 2 2 }} → false
|
||||
```
|
||||
32
content/en/functions/compare/Ge.md
Normal file
32
content/en/functions/compare/Ge.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
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...]']
|
||||
aliases: [/functions/ge]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ ge 1 1 }} → true
|
||||
{{ ge 1 2 }} → false
|
||||
{{ ge 2 1 }} → true
|
||||
|
||||
{{ ge 1 1 1 }} → true
|
||||
{{ ge 1 1 2 }} → false
|
||||
{{ ge 1 2 1 }} → false
|
||||
{{ ge 1 2 2 }} → false
|
||||
|
||||
{{ ge 2 1 1 }} → true
|
||||
{{ ge 2 1 2 }} → true
|
||||
{{ ge 2 2 1 }} → true
|
||||
```
|
||||
32
content/en/functions/compare/Gt.md
Normal file
32
content/en/functions/compare/Gt.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
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...]']
|
||||
aliases: [/functions/gt]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ gt 1 1 }} → false
|
||||
{{ gt 1 2 }} → false
|
||||
{{ gt 2 1 }} → true
|
||||
|
||||
{{ gt 1 1 1 }} → false
|
||||
{{ gt 1 1 2 }} → false
|
||||
{{ gt 1 2 1 }} → false
|
||||
{{ gt 1 2 2 }} → false
|
||||
|
||||
{{ gt 2 1 1 }} → true
|
||||
{{ gt 2 1 2 }} → false
|
||||
{{ gt 2 2 1 }} → false
|
||||
```
|
||||
32
content/en/functions/compare/Le.md
Normal file
32
content/en/functions/compare/Le.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
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...]']
|
||||
aliases: [/functions/le]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ le 1 1 }} → true
|
||||
{{ le 1 2 }} → true
|
||||
{{ le 2 1 }} → false
|
||||
|
||||
{{ le 1 1 1 }} → true
|
||||
{{ le 1 1 2 }} → true
|
||||
{{ le 1 2 1 }} → true
|
||||
{{ le 1 2 2 }} → true
|
||||
|
||||
{{ le 2 1 1 }} → false
|
||||
{{ le 2 1 2 }} → false
|
||||
{{ le 2 2 1 }} → false
|
||||
```
|
||||
32
content/en/functions/compare/Lt.md
Normal file
32
content/en/functions/compare/Lt.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
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...]']
|
||||
aliases: [/functions/lt]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ lt 1 1 }} → false
|
||||
{{ lt 1 2 }} → true
|
||||
{{ lt 2 1 }} → false
|
||||
|
||||
{{ lt 1 1 1 }} → false
|
||||
{{ lt 1 1 2 }} → false
|
||||
{{ lt 1 2 1 }} → false
|
||||
{{ lt 1 2 2 }} → true
|
||||
|
||||
{{ lt 2 1 1 }} → false
|
||||
{{ lt 2 1 2 }} → false
|
||||
{{ lt 2 2 1 }} → false
|
||||
```
|
||||
27
content/en/functions/compare/Ne.md
Normal file
27
content/en/functions/compare/Ne.md
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
---
|
||||
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...]']
|
||||
aliases: [/functions/ne]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ ne 1 1 }} → false
|
||||
{{ ne 1 2 }} → true
|
||||
|
||||
{{ ne 1 1 1 }} → false
|
||||
{{ ne 1 1 2 }} → false
|
||||
{{ ne 1 2 1 }} → false
|
||||
{{ ne 1 2 2 }} → true
|
||||
```
|
||||
12
content/en/functions/compare/_index.md
Normal file
12
content/en/functions/compare/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Compare functions
|
||||
linkTitle: compare
|
||||
description: Template functions to compare two or more values.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
Use these functions to compare two or more values.
|
||||
22
content/en/functions/crypto/FNV32a.md
Normal file
22
content/en/functions/crypto/FNV32a.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
title: crypto.FNV32a
|
||||
description: Returns the FNV (Fowler–Noll–Vo) 32-bit hash of a given string.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/crypto/HMAC
|
||||
- functions/crypto/MD5
|
||||
- functions/crypto/SHA1
|
||||
- functions/crypto/SHA256
|
||||
returnType: int
|
||||
signatures: [crypto.FNV32a STRING]
|
||||
aliases: [/functions/crypto.fnv32a]
|
||||
---
|
||||
|
||||
This function calculates the 32-bit [FNV1a hash](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV-1a_hash) of a given string according to the [specification](https://datatracker.ietf.org/doc/html/draft-eastlake-fnv-12):
|
||||
|
||||
```go-html-template
|
||||
{{ crypto.FNV32a "Hello world" }} → 1498229191
|
||||
```
|
||||
31
content/en/functions/crypto/HMAC.md
Normal file
31
content/en/functions/crypto/HMAC.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
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]']
|
||||
aliases: [/functions/hmac]
|
||||
---
|
||||
|
||||
Set the `HASH_TYPE` argument to `md5`, `sha1`, `sha256`, or `sha512`.
|
||||
|
||||
Set the optional `ENCODING` argument to either `hex` (default) or `binary`.
|
||||
|
||||
```go-html-template
|
||||
{{ hmac "sha256" "Secret key" "Secret message" }}
|
||||
5cceb491f45f8b154e20f3b0a30ed3a6ff3027d373f85c78ffe8983180b03c84
|
||||
|
||||
{{ hmac "sha256" "Secret key" "Secret message" "hex" }}
|
||||
5cceb491f45f8b154e20f3b0a30ed3a6ff3027d373f85c78ffe8983180b03c84
|
||||
|
||||
{{ hmac "sha256" "Secret key" "Secret message" "binary" | base64Encode }}
|
||||
XM60kfRfixVOIPOwow7Tpv8wJ9Nz+Fx4/+iYMYCwPIQ=
|
||||
```
|
||||
26
content/en/functions/crypto/MD5.md
Normal file
26
content/en/functions/crypto/MD5.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/md5]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ md5 "Hello world" }} → 3e25960a79dbc69b674cd4ec67a72c62
|
||||
```
|
||||
|
||||
This can be useful if you want to use [Gravatar](https://en.gravatar.com/) for generating a unique avatar:
|
||||
|
||||
```html
|
||||
<img src="https://www.gravatar.com/avatar/{{ md5 "your@email.com" }}?s=100&d=identicon">
|
||||
```
|
||||
20
content/en/functions/crypto/SHA1.md
Normal file
20
content/en/functions/crypto/SHA1.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/sha,/functions/sha1]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ sha1 "Hello world" }} → 7b502c3a1f48c8609ae212cdfb639dee39673f5e
|
||||
```
|
||||
20
content/en/functions/crypto/SHA256.md
Normal file
20
content/en/functions/crypto/SHA256.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/sha256]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ sha256 "Hello world" }} → 64ec88ca00b268e5ba1a35678a1b5316d212f4f366b2477232534a8aeca37f3c
|
||||
```
|
||||
12
content/en/functions/crypto/_index.md
Normal file
12
content/en/functions/crypto/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Crypto functions
|
||||
linkTitle: crypto
|
||||
description: Template functions to create cryptographic hashes.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
Use these functions to create cryptographic hashes.
|
||||
140
content/en/functions/data/GetCSV.md
Normal file
140
content/en/functions/data/GetCSV.md
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
---
|
||||
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:
|
||||
- functions/data/GetJSON
|
||||
- functions/resources/Get
|
||||
- functions/resources/GetRemote
|
||||
- methods/page/Resources
|
||||
returnType: '[][]string'
|
||||
signatures: ['data.GetCSV SEPARATOR INPUT... [OPTIONS]']
|
||||
toc: true
|
||||
---
|
||||
|
||||
Given the following directory structure:
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── other-files/
|
||||
└── pets.csv
|
||||
```
|
||||
|
||||
Access the data with either of the following:
|
||||
|
||||
```go-html-template
|
||||
{{ $data := getCSV "," "other-files/pets.csv" }}
|
||||
{{ $data := getCSV "," "other-files/" "pets.csv" }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
When working with local data, the filepath is relative to the working directory.
|
||||
|
||||
You must not place CSV files in the project's data directory.
|
||||
{{% /note %}}
|
||||
|
||||
Access remote data with either of the following:
|
||||
|
||||
```go-html-template
|
||||
{{ $data := getCSV "," "https://example.org/pets.csv" }}
|
||||
{{ $data := getCSV "," "https://example.org/" "pets.csv" }}
|
||||
```
|
||||
|
||||
The resulting data structure is an array of arrays:
|
||||
|
||||
```json
|
||||
[
|
||||
["name","type","breed","age"],
|
||||
["Spot","dog","Collie","3"],
|
||||
["Felix","cat","Malicious","7"]
|
||||
]
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
Add headers to the request by providing an options map:
|
||||
|
||||
```go-html-template
|
||||
{{ $opts := dict "Authorization" "Bearer abcd" }}
|
||||
{{ $data := getCSV "," "https://example.org/pets.csv" $opts }}
|
||||
```
|
||||
|
||||
Add multiple headers using a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $opts := dict "X-List" (slice "a" "b" "c") }}
|
||||
{{ $data := getCSV "," "https://example.org/pets.csv" $opts }}
|
||||
```
|
||||
|
||||
## Global resource alternative
|
||||
|
||||
Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource.
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── assets/
|
||||
└── data/
|
||||
└── pets.csv
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $data := "" }}
|
||||
{{ $p := "data/pets.csv" }}
|
||||
{{ with resources.Get $p }}
|
||||
{{ $opts := dict "delimiter" "," }}
|
||||
{{ $data = . | transform.Unmarshal $opts }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get resource %q" $p }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Page resource alternative
|
||||
|
||||
Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource.
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── content/
|
||||
└── posts/
|
||||
└── my-pets/
|
||||
├── index.md
|
||||
└── pets.csv
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $data := "" }}
|
||||
{{ $p := "pets.csv" }}
|
||||
{{ with .Resources.Get $p }}
|
||||
{{ $opts := dict "delimiter" "," }}
|
||||
{{ $data = . | transform.Unmarshal $opts }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get resource %q" $p }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Remote resource alternative
|
||||
|
||||
Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control.
|
||||
|
||||
```go-html-template
|
||||
{{ $data := "" }}
|
||||
{{ $u := "https://example.org/pets.csv" }}
|
||||
{{ with resources.GetRemote $u }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "%s" . }}
|
||||
{{ else }}
|
||||
{{ $opts := dict "delimiter" "," }}
|
||||
{{ $data = . | transform.Unmarshal $opts }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $u }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[`Resources.Get`]: methods/page/Resources
|
||||
[`resources.GetRemote`]: /functions/resources/getremote
|
||||
[`resources.Get`]: /functions/resources/get
|
||||
[`transform.Unmarshal`]: /functions/transform/unmarshal
|
||||
142
content/en/functions/data/GetJSON.md
Normal file
142
content/en/functions/data/GetJSON.md
Normal file
|
|
@ -0,0 +1,142 @@
|
|||
---
|
||||
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:
|
||||
- functions/data/GetCSV
|
||||
- functions/resources/Get
|
||||
- functions/resources/GetRemote
|
||||
- methods/page/Resources
|
||||
returnType: any
|
||||
signatures: ['data.GetJSON INPUT... [OPTIONS]']
|
||||
toc: true
|
||||
---
|
||||
|
||||
Given the following directory structure:
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── other-files/
|
||||
└── books.json
|
||||
```
|
||||
|
||||
Access the data with either of the following:
|
||||
|
||||
```go-html-template
|
||||
{{ $data := getJSON "other-files/books.json" }}
|
||||
{{ $data := getJSON "other-files/" "books.json" }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
When working with local data, the filepath is relative to the working directory.
|
||||
{{% /note %}}
|
||||
|
||||
Access remote data with either of the following:
|
||||
|
||||
```go-html-template
|
||||
{{ $data := getJSON "https://example.org/books.json" }}
|
||||
{{ $data := getJSON "https://example.org/" "books.json" }}
|
||||
```
|
||||
|
||||
The resulting data structure is a JSON object:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"author": "Victor Hugo",
|
||||
"rating": 5,
|
||||
"title": "Les Misérables"
|
||||
},
|
||||
{
|
||||
"author": "Victor Hugo",
|
||||
"rating": 4,
|
||||
"title": "The Hunchback of Notre Dame"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
Add headers to the request by providing an options map:
|
||||
|
||||
```go-html-template
|
||||
{{ $opts := dict "Authorization" "Bearer abcd" }}
|
||||
{{ $data := getJSON "https://example.org/books.json" $opts }}
|
||||
```
|
||||
|
||||
Add multiple headers using a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ $opts := dict "X-List" (slice "a" "b" "c") }}
|
||||
{{ $data := getJSON "https://example.org/books.json" $opts }}
|
||||
```
|
||||
|
||||
## Global resource alternative
|
||||
|
||||
Consider using the [`resources.Get`] function with [`transform.Unmarshal`] when accessing a global resource.
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── assets/
|
||||
└── data/
|
||||
└── books.json
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $data := "" }}
|
||||
{{ $p := "data/books.json" }}
|
||||
{{ with resources.Get $p }}
|
||||
{{ $data = . | transform.Unmarshal }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get resource %q" $p }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Page resource alternative
|
||||
|
||||
Consider using the [`Resources.Get`] method with [`transform.Unmarshal`] when accessing a page resource.
|
||||
|
||||
```text
|
||||
my-project/
|
||||
└── content/
|
||||
└── posts/
|
||||
└── reading-list/
|
||||
├── books.json
|
||||
└── index.md
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $data := "" }}
|
||||
{{ $p := "books.json" }}
|
||||
{{ with .Resources.Get $p }}
|
||||
{{ $data = . | transform.Unmarshal }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get resource %q" $p }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
## Remote resource alternative
|
||||
|
||||
Consider using the [`resources.GetRemote`] function with [`transform.Unmarshal`] when accessing a remote resource to improve error handling and cache control.
|
||||
|
||||
```go-html-template
|
||||
{{ $data := "" }}
|
||||
{{ $u := "https://example.org/books.json" }}
|
||||
{{ with resources.GetRemote $u }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "%s" . }}
|
||||
{{ else }}
|
||||
{{ $data = . | transform.Unmarshal }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $u }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[`Resources.Get`]: methods/page/Resources
|
||||
[`resources.GetRemote`]: /functions/resources/getremote
|
||||
[`resources.Get`]: /functions/resources/get
|
||||
[`transform.Unmarshal`]: /functions/transform/unmarshal
|
||||
12
content/en/functions/data/_index.md
Normal file
12
content/en/functions/data/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Data functions
|
||||
linkTitle: data
|
||||
description: Template functions to read local or remote data files.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
Use these functions to read local or remote data files.
|
||||
45
content/en/functions/debug/Dump.md
Normal file
45
content/en/functions/debug/Dump.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
title: debug.Dump
|
||||
description: Returns an object dump as a string.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related: []
|
||||
returnType: string
|
||||
signatures: [debug.Dump VALUE]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ $data := "" }}
|
||||
{{ $p := "data/books.json" }}
|
||||
{{ with resources.Get $p }}
|
||||
{{ $opts := dict "delimiter" "," }}
|
||||
{{ $data = . | transform.Unmarshal $opts }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get resource %q" $p }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
<pre>{{ debug.Dump $data }}</pre>
|
||||
```
|
||||
|
||||
```text
|
||||
[]interface {}{
|
||||
map[string]interface {}{
|
||||
"author": "Victor Hugo",
|
||||
"rating": 5.0,
|
||||
"title": "Les Misérables",
|
||||
},
|
||||
map[string]interface {}{
|
||||
"author": "Victor Hugo",
|
||||
"rating": 4.0,
|
||||
"title": "The Hunchback of Notre Dame",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Output from this function may change from one release to the next. Use for debugging only.
|
||||
{{% /note %}}
|
||||
37
content/en/functions/debug/Timer.md
Normal file
37
content/en/functions/debug/Timer.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
{{< new-in 0.120.0 >}}
|
||||
|
||||
Use the `debug.Timer` function to determine execution time for a block of code, useful for finding performance bottle necks in templates.
|
||||
|
||||
The timer starts when you instantiate it, and stops when you call its `Stop` method.
|
||||
|
||||
```go-html-template
|
||||
{{ $t := debug.Timer "TestSqrt" }}
|
||||
{{ range seq 2000 }}
|
||||
{{ $f := math.Sqrt . }}
|
||||
{{ end }}
|
||||
{{ $t.Stop }}
|
||||
```
|
||||
|
||||
Use the `--logLevel info` command line flag when you build the site.
|
||||
|
||||
```sh
|
||||
hugo --logLevel info
|
||||
```
|
||||
|
||||
The results are displayed in the console at the end of the build. You can have as many timers as you want and if you don't stop them, they will be stopped at the end of build.
|
||||
|
||||
```text
|
||||
INFO timer: name TestSqrt total 12.429355ms
|
||||
```
|
||||
12
content/en/functions/debug/_index.md
Normal file
12
content/en/functions/debug/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Debug functions
|
||||
linkTitle: debug
|
||||
description: Template functions to debug your templates.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
Use these functions to debug your templates.
|
||||
113
content/en/functions/diagrams/Goat.md
Normal file
113
content/en/functions/diagrams/Goat.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
title: diagrams.Goat
|
||||
description: Converts ASCII art to an SVG diagram, returning a GoAT diagram object.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related: []
|
||||
returnType: diagrams.goatDiagram
|
||||
signatures: ['diagrams.Goat INPUT']
|
||||
toc: true
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
[GoAT]: https://github.com/blampe/goat#readme
|
||||
[render hook]: https://gohugo.io/templates/render-hooks/
|
||||
|
||||
Inner
|
||||
: (`template.HTML`) Returns the SVG child elements without a wrapping `svg` element, allowing you to create your own wrapper.
|
||||
|
||||
Wrapped
|
||||
: (`template.HTML`) Returns the SVG child elements wrapped in an `svg` element.
|
||||
|
||||
Width
|
||||
: (`int`) Returns the width of the rendered diagram, in pixels.
|
||||
|
||||
Height
|
||||
: (`int`) Returns the height of the rendered diagram, in pixels.
|
||||
|
||||
## GoAT Diagrams
|
||||
|
||||
Hugo natively supports [GoAT] diagrams.
|
||||
|
||||
This markdown:
|
||||
|
||||
````
|
||||
```goat
|
||||
.---. .-. .-. .-. .---.
|
||||
| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B |
|
||||
'---' '-' '+' '+' '---'
|
||||
```
|
||||
````
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<div class="goat svg-container">
|
||||
<svg xmlns="http://www.w3.org/2000/svg" font-family="Menlo,Lucida Console,monospace" viewBox="0 0 352 57">
|
||||
...
|
||||
</svg>
|
||||
</div>
|
||||
```
|
||||
|
||||
Which appears in your browser as:
|
||||
|
||||
```goat {class="mw6-ns"}
|
||||
.---. .-. .-. .-. .---.
|
||||
| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B |
|
||||
'---' '-' '+' '+' '---'
|
||||
```
|
||||
|
||||
To customize rendering, override Hugo's [built-in code block render hook] for GoAT diagrams.
|
||||
|
||||
[built-in code block render hook]: https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/_markup/render-codeblock-goat.html
|
||||
|
||||
## Code block render hook
|
||||
|
||||
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 >}}
|
||||
{{ $caption := or .Attributes.caption "" }}
|
||||
{{ $class := or .Attributes.class "diagram" }}
|
||||
{{ $id := or .Attributes.id (printf "diagram-%d" (add 1 .Ordinal)) }}
|
||||
|
||||
<figure id="{{ $id }}">
|
||||
{{ with diagrams.Goat (trim .Inner "\n\r") }}
|
||||
<svg class="{{ $class }}" width="{{ .Width }}" height="{{ .Height }}" xmlns="http://www.w3.org/2000/svg" version="1.1">
|
||||
{{ .Inner }}
|
||||
</svg>
|
||||
{{ end }}
|
||||
<figcaption>{{ $caption }}</figcaption>
|
||||
</figure>
|
||||
{{< /code >}}
|
||||
|
||||
This markdown:
|
||||
|
||||
{{< code file=content/example.md lang=text >}}
|
||||
```goat {class="foo" caption="Diagram 1: Example"}
|
||||
.---. .-. .-. .-. .---.
|
||||
| A +--->| 1 |<--->| 2 |<--->| 3 |<---+ B |
|
||||
'---' '-' '+' '+' '---'
|
||||
```
|
||||
{{< /code >}}
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<figure id="diagram-1">
|
||||
<svg class="foo" width="272" height="57" xmlns="http://www.w3.org/2000/svg" version="1.1">
|
||||
...
|
||||
</svg>
|
||||
<figcaption>Diagram 1: Example</figcaption>
|
||||
</figure>
|
||||
```
|
||||
|
||||
Use CSS to style the SVG as needed:
|
||||
|
||||
```css
|
||||
svg.foo {
|
||||
font-family: "Segoe UI","Noto Sans",Helvetica,Arial,sans-serif
|
||||
}
|
||||
```
|
||||
12
content/en/functions/diagrams/_index.md
Normal file
12
content/en/functions/diagrams/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Diagram functions
|
||||
linkTitle: diagrams
|
||||
description: Template functions to render diagrams.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
Use these functions to render diagrams.
|
||||
40
content/en/functions/encoding/Base64Decode.md
Normal file
40
content/en/functions/encoding/Base64Decode.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/base64Decode]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ "SHVnbw==" | base64Decode }} → Hugo
|
||||
```
|
||||
|
||||
Use the `base64Decode` function to decode responses from APIs. For example, the result of this call to GitHub's API contains the base64-encoded representation of the repository's README file:
|
||||
|
||||
```text
|
||||
https://api.github.com/repos/gohugoio/hugo/readme
|
||||
```
|
||||
|
||||
To retrieve and render the content:
|
||||
|
||||
```go-html-template
|
||||
{{ $u := "https://api.github.com/repos/gohugoio/hugo/readme" }}
|
||||
{{ with resources.GetRemote $u }}
|
||||
{{ with .Err }}
|
||||
{{ errorf "%s" . }}
|
||||
{{ else }}
|
||||
{{ with . | transform.Unmarshal }}
|
||||
{{ .content | base64Decode | markdownify }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "Unable to get remote resource %q" $u }}
|
||||
{{ end }}
|
||||
```
|
||||
17
content/en/functions/encoding/Base64Encode.md
Normal file
17
content/en/functions/encoding/Base64Encode.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/base64, /functions/base64Encode]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ "Hugo" | base64Encode }} → SHVnbw==
|
||||
```
|
||||
37
content/en/functions/encoding/Jsonify.md
Normal file
37
content/en/functions/encoding/Jsonify.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
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
|
||||
aliases: [/functions/jsonify]
|
||||
---
|
||||
|
||||
To customize the printing of the JSON, pass an options map 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.
|
||||
|
||||
```go-html-template
|
||||
{{ dict "title" .Title "content" .Plain | jsonify }}
|
||||
{{ dict "title" .Title "content" .Plain | jsonify (dict "indent" " ") }}
|
||||
{{ dict "title" .Title "content" .Plain | jsonify (dict "prefix" " " "indent" " ") }}
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
indent
|
||||
: (`string`) Indentation to use. Default is "".
|
||||
|
||||
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`.
|
||||
12
content/en/functions/encoding/_index.md
Normal file
12
content/en/functions/encoding/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Encoding functions
|
||||
linkTitle: encoding
|
||||
description: Template functions to encode and decode data.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
Use these functions to encode and decode data.
|
||||
26
content/en/functions/fmt/Errorf.md
Normal file
26
content/en/functions/fmt/Errorf.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
title: fmt.Errorf
|
||||
description: Log an ERROR from a template.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [errorf]
|
||||
related:
|
||||
- functions/fmt/Erroridf
|
||||
- functions/fmt/Warnf
|
||||
returnType: string
|
||||
signatures: ['fmt.Errorf FORMAT [INPUT]']
|
||||
aliases: [/functions/errorf]
|
||||
---
|
||||
|
||||
{{% include "functions/fmt/_common/fmt-layout.md" %}}
|
||||
|
||||
The `errorf` function evaluates the format string, then prints the result to the ERROR log and fails the build.
|
||||
|
||||
```go-html-template
|
||||
{{ errorf "The %q shortcode requires a src parameter. See %s" .Name .Position }}
|
||||
```
|
||||
|
||||
Use the [`erroridf`] function to allow optional suppression of specific errors.
|
||||
|
||||
[`erroridf`]: /functions/fmt/erroridf
|
||||
40
content/en/functions/fmt/Erroridf.md
Normal file
40
content/en/functions/fmt/Erroridf.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
title: fmt.Erroridf
|
||||
description: Log a suppressable ERROR from a template.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [erroridf]
|
||||
related:
|
||||
- functions/fmt/Errorf
|
||||
- functions/fmt/Warnf
|
||||
returnType: string
|
||||
signatures: ['fmt.Erroridf ID FORMAT [INPUT]']
|
||||
aliases: [/functions/erroridf]
|
||||
---
|
||||
|
||||
{{% include "functions/fmt/_common/fmt-layout.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 `ignoreErrors` array in your site configuration.
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ erroridf "error-42" "You should consider fixing this." }}
|
||||
```
|
||||
|
||||
Produces this console log:
|
||||
|
||||
```text
|
||||
ERROR You should consider fixing this.
|
||||
You can suppress this error by adding the following to your site configuration:
|
||||
ignoreErrors = ['error-42']
|
||||
```
|
||||
|
||||
To suppress this message:
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
ignoreErrors = ["error-42"]
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[`errorf`]: /functions/fmt/errorf
|
||||
20
content/en/functions/fmt/Print.md
Normal file
20
content/en/functions/fmt/Print.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/print]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ print "foo" }} → foo
|
||||
{{ print "foo" "bar" }} → foobar
|
||||
{{ print (slice 1 2 3) }} → [1 2 3]
|
||||
```
|
||||
39
content/en/functions/fmt/Printf.md
Normal file
39
content/en/functions/fmt/Printf.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
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]']
|
||||
aliases: [/functions/printf]
|
||||
---
|
||||
|
||||
{{% include "functions/fmt/_common/fmt-layout.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "world" }}
|
||||
{{ printf "Hello %s." $var }} → Hello world.
|
||||
```
|
||||
|
||||
```go-html-template
|
||||
{{ $pi := 3.14159265 }}
|
||||
{{ printf "Pi is approximately %.2f." $pi }} → 3.14
|
||||
```
|
||||
|
||||
Use the `printf` function with the `safeHTMLAttr` function:
|
||||
|
||||
```go-html-template
|
||||
{{ $desc := "Eat at Joe's" }}
|
||||
<meta name="description" {{ printf "content=%q" $desc | safeHTMLAttr }}>
|
||||
```
|
||||
|
||||
Hugo renders this to:
|
||||
|
||||
```html
|
||||
<meta name="description" content="Eat at Joe's">
|
||||
```
|
||||
18
content/en/functions/fmt/Println.md
Normal file
18
content/en/functions/fmt/Println.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/println]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ println "foo" }} → foo\n
|
||||
```
|
||||
33
content/en/functions/fmt/Warnf.md
Normal file
33
content/en/functions/fmt/Warnf.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
title: fmt.Warnf
|
||||
description: Log a WARNING from a template.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: [warnf]
|
||||
related:
|
||||
- functions/fmt/Errorf
|
||||
- functions/fmt/Erroridf
|
||||
returnType: string
|
||||
signatures: ['fmt.Warnf FORMAT [INPUT]']
|
||||
aliases: [/functions/warnf]
|
||||
---
|
||||
|
||||
{{% include "functions/fmt/_common/fmt-layout.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.
|
||||
|
||||
```go-html-template
|
||||
{{ warnf "The %q shortcode was unable to find %s. See %s" .Name $file .Position }}
|
||||
```
|
||||
|
||||
To prevent suppression of duplicate messages when using `warnf` for debugging, make each message unique with the [`math.Counter`] function. For example:
|
||||
|
||||
|
||||
```go-html-template
|
||||
{{ range site.RegularPages }}
|
||||
{{ .Section | warnf "%#[2]v [%[1]d]" math.Counter }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[`math.Counter`]: /functions/math/counter
|
||||
13
content/en/functions/fmt/_common/_index.md
Normal file
13
content/en/functions/fmt/_common/_index.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
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.
|
||||
-->
|
||||
7
content/en/functions/fmt/_common/fmt-layout.md
Normal file
7
content/en/functions/fmt/_common/fmt-layout.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
# 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
|
||||
12
content/en/functions/fmt/_index.md
Normal file
12
content/en/functions/fmt/_index.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
---
|
||||
title: Fmt functions
|
||||
linkTitle: fmt
|
||||
description: Template 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.
|
||||
11
content/en/functions/global/_index.md
Normal file
11
content/en/functions/global/_index.md
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
---
|
||||
title: Global functions
|
||||
linkTitle: global
|
||||
description: Global template functions to access page and site data.
|
||||
categories: []
|
||||
menu:
|
||||
docs:
|
||||
parent: functions
|
||||
---
|
||||
|
||||
Use these global functions to access page and site data.
|
||||
109
content/en/functions/global/page.md
Normal file
109
content/en/functions/global/page.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
title: page
|
||||
description: Provides global access to a Page object.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/global/site
|
||||
returnType:
|
||||
signatures: [page]
|
||||
toc: true
|
||||
aliases: [/functions/page]
|
||||
---
|
||||
|
||||
{{< new-in 0.111.0 >}}
|
||||
|
||||
At the top level of a template that receives a `Page` object in context, these are equivalent:
|
||||
|
||||
```go-html-template
|
||||
{{ .Params.foo }}
|
||||
{{ .Page.Params.foo }}
|
||||
{{ page.Params.foo }}
|
||||
```
|
||||
|
||||
When a `Page` object is not in context, you can use the global `page` function:
|
||||
|
||||
```go-html-template
|
||||
{{ 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 %}}
|
||||
|
||||
## 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 `.` variable in the template.
|
||||
|
||||
But when you are deeply nested inside of a [content view], [partial], or [render hook], it is not always practical or possible to access the `Page` object.
|
||||
|
||||
Use the global `page` function to access the `Page` object from anywhere in any template.
|
||||
|
||||
## Warnings
|
||||
|
||||
### Be aware of top-level context
|
||||
|
||||
The global `page` function accesses the `Page` object passed into the top-level template.
|
||||
|
||||
With this content structure:
|
||||
|
||||
```text
|
||||
content/
|
||||
├── posts/
|
||||
│ ├── post-1.md
|
||||
│ ├── post-2.md
|
||||
│ └── post-3.md
|
||||
└── _index.md <-- title is "My Home Page"
|
||||
```
|
||||
|
||||
And this code in the home page template:
|
||||
|
||||
```go-html-template
|
||||
{{ range site.Sections }}
|
||||
{{ range .Pages }}
|
||||
{{ page.Title }}
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The rendered output will be:
|
||||
|
||||
```text
|
||||
My Home Page
|
||||
My Home Page
|
||||
My Home Page
|
||||
```
|
||||
|
||||
In the example above, the global `page` function accesses the `Page` object passed into the home page template; it does not access the `Page` object of the iterated pages.
|
||||
|
||||
### Be aware of caching
|
||||
|
||||
Do not use the global `page` function in:
|
||||
|
||||
- Shortcodes
|
||||
- Partials called by shortcodes
|
||||
- Partials cached by the [`partialCached`] function
|
||||
|
||||
Hugo caches rendered shortcodes. If you use the global `page` function within a shortcode, and the page content is rendered in two or more templates, the cached shortcode may be incorrect.
|
||||
|
||||
Consider this section template:
|
||||
|
||||
```go-html-template
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ .Summary }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
When you call the [`Summary`] method, Hugo renders the page content including shortcodes. In this case, within a shortcode, the global `page` function accesses the `Page` object of the section page, not the content page.
|
||||
|
||||
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
|
||||
[content view]: /getting-started/glossary/#content-view
|
||||
[partial]: /getting-started/glossary/#partial
|
||||
[render hook]: /getting-started/glossary/#render-hook
|
||||
[shortcode]: getting-started/glossary/#shortcode
|
||||
30
content/en/functions/global/site.md
Normal file
30
content/en/functions/global/site.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: site
|
||||
description: Provides global access to the current Site object.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related:
|
||||
- functions/global/page
|
||||
returnType:
|
||||
signatures: [site]
|
||||
aliases: [/functions/site]
|
||||
---
|
||||
|
||||
At the top level of a template that receives the `Site` object in context, these are equivalent:
|
||||
|
||||
```go-html-template
|
||||
{{ .Site.Params.foo }}
|
||||
{{ site.Params.foo }}
|
||||
```
|
||||
|
||||
When the `Site` object is not in context, use the global `site` function:
|
||||
|
||||
```go-html-template
|
||||
{{ site.Params.foo }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
To simplify your templates, use the global `site` function regardless of whether the `Site` object is in context.
|
||||
{{% /note %}}
|
||||
13
content/en/functions/go-template/_common/_index.md
Normal file
13
content/en/functions/go-template/_common/_index.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
---
|
||||
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.
|
||||
-->
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
See Go's [text/template] documentation for more information.
|
||||
|
||||
[text/template]: https://pkg.go.dev/text/template
|
||||
5
content/en/functions/go-template/_common/truthy-falsy.md
Normal file
5
content/en/functions/go-template/_common/truthy-falsy.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
---
|
||||
# Do not remove front matter.
|
||||
---
|
||||
|
||||
In Go templates, the falsy values are `false`, `0`, any nil pointer or interface value, and any array, slice, map, or string of length zero. Everything else is truthy.
|
||||
14
content/en/functions/go-template/_index.md
Normal file
14
content/en/functions/go-template/_index.md
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
---
|
||||
title: Go template functions, operators, and statements
|
||||
linkTitle: go template
|
||||
description: Template 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
|
||||
26
content/en/functions/go-template/and.md
Normal file
26
content/en/functions/go-template/and.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
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...]
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ and 1 0 "" }} → 0 (int)
|
||||
{{ and 1 false 0 }} → false (bool)
|
||||
|
||||
{{ and 1 2 3 }} → 3 (int)
|
||||
{{ and "a" "b" "c" }} → c (string)
|
||||
{{ and "a" 1 true }} → true (bool)
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
55
content/en/functions/go-template/block.md
Normal file
55
content/en/functions/go-template/block.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
A block is shorthand for defining a template:
|
||||
|
||||
```go-html-template
|
||||
{{ define "name" }} T1 {{ end }}
|
||||
```
|
||||
|
||||
and then executing it in place:
|
||||
|
||||
```go-html-template
|
||||
{{ template "name" pipeline }}
|
||||
```
|
||||
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 >}}
|
||||
<body>
|
||||
<main>
|
||||
{{ block "main" . }}
|
||||
{{ print "default value if 'main' template is empty" }}
|
||||
{{ end }}
|
||||
</main>
|
||||
</body>
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=layouts/_default/single.html >}}
|
||||
{{ define "main" }}
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{< code file=layouts/_default/list.html >}}
|
||||
{{ define "main" }}
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
{{ range .Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
33
content/en/functions/go-template/break.md
Normal file
33
content/en/functions/go-template/break.md
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
{{ if eq . "bar" }}
|
||||
{{ break }}
|
||||
{{ end }}
|
||||
<p>{{ . }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>foo</p>
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
34
content/en/functions/go-template/continue.md
Normal file
34
content/en/functions/go-template/continue.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
{{ if eq . "bar" }}
|
||||
{{ continue }}
|
||||
{{ end }}
|
||||
<p>{{ . }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>foo</p>
|
||||
<p>baz</p>
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
55
content/en/functions/go-template/define.md
Normal file
55
content/en/functions/go-template/define.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
Use with the [`block`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ block "main" . }}
|
||||
{{ print "default value if 'main' template is empty" }}
|
||||
{{ end }}
|
||||
|
||||
{{ define "main" }}
|
||||
<h1>{{ .Title }}</h1>
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`partial`] function:
|
||||
|
||||
```go-html-template
|
||||
{{ partial "inline/foo.html" (dict "answer" 42) }}
|
||||
|
||||
{{ define "partials/inline/foo.html" }}
|
||||
{{ printf "The answer is %v." .answer }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`template`] function:
|
||||
|
||||
```go-html-template
|
||||
{{ template "foo" (dict "answer" 42) }}
|
||||
|
||||
{{ define "foo" }}
|
||||
{{ printf "The answer is %v." .answer }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
[`block`]: /functions/go-template/block
|
||||
[`template`]: /functions/go-template/block
|
||||
[`partial`]: /functions/partials/include/
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
69
content/en/functions/go-template/else.md
Normal file
69
content/en/functions/go-template/else.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
Use with the [`if`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ if $var }}
|
||||
{{ $var }} → foo
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`with`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ with $var }}
|
||||
{{ . }} → foo
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`range`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := slice 1 2 3 }}
|
||||
{{ range $var }}
|
||||
{{ . }} → 1 2 3
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use `else if` to check multiple conditions.
|
||||
|
||||
```go-html-template
|
||||
{{ $var := 12 }}
|
||||
{{ if eq $var 6 }}
|
||||
{{ print "var is 6" }}
|
||||
{{ else if eq $var 7 }}
|
||||
{{ print "var is 7" }}
|
||||
{{ else if eq $var 42 }}
|
||||
{{ print "var is 42" }}
|
||||
{{ else }}
|
||||
{{ print "var is something else" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`if`]: /functions/go-template/if
|
||||
[`with`]: /functions/go-template/with
|
||||
[`range`]: /functions/go-template/range
|
||||
65
content/en/functions/go-template/end.md
Normal file
65
content/en/functions/go-template/end.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
Use with the [`if`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ if $var }}
|
||||
{{ $var }} → foo
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`with`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ with $var }}
|
||||
{{ . }} → foo
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`range`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := slice 1 2 3 }}
|
||||
{{ range $var }}
|
||||
{{ . }} → 1 2 3
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`block`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ block "main" . }}{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`define`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ define "main" }}
|
||||
{{ print "this is the main section" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`block`]: /functions/go-template/block
|
||||
[`define`]: /functions/go-template/define
|
||||
[`if`]: /functions/go-template/if
|
||||
[`range`]: /functions/go-template/range
|
||||
[`with`]: /functions/go-template/with
|
||||
54
content/en/functions/go-template/if.md
Normal file
54
content/en/functions/go-template/if.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ if $var }}
|
||||
{{ $var }} → foo
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`else`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ if $var }}
|
||||
{{ $var }} → foo
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use `else if` to check multiple conditions.
|
||||
|
||||
```go-html-template
|
||||
{{ $var := 12 }}
|
||||
{{ if eq $var 6 }}
|
||||
{{ print "var is 6" }}
|
||||
{{ else if eq $var 7 }}
|
||||
{{ print "var is 7" }}
|
||||
{{ else if eq $var 42 }}
|
||||
{{ print "var is 42" }}
|
||||
{{ else }}
|
||||
{{ print "var is something else" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`else`]: /functions/go-template/else
|
||||
51
content/en/functions/go-template/len.md
Normal file
51
content/en/functions/go-template/len.md
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/len]
|
||||
---
|
||||
|
||||
With a string:
|
||||
|
||||
```go-html-template
|
||||
{{ "ab" | len }} → 2
|
||||
{{ "" | len }} → 0
|
||||
```
|
||||
|
||||
With a slice:
|
||||
|
||||
```go-html-template
|
||||
{{ slice "a" "b" | len }} → 2
|
||||
{{ slice | len }} → 0
|
||||
```
|
||||
|
||||
With a map:
|
||||
|
||||
```go-html-template
|
||||
{{ dict "a" 1 "b" 2 | len }} → 2
|
||||
{{ dict | len }} → 0
|
||||
```
|
||||
|
||||
With a collection:
|
||||
|
||||
```go-html-template
|
||||
{{ site.RegularPages | len }} → 42
|
||||
```
|
||||
|
||||
You may also determine the number of pages in a collection with:
|
||||
|
||||
```go-html-template
|
||||
{{ site.RegularPages.Len }} → 42
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
35
content/en/functions/go-template/not.md
Normal file
35
content/en/functions/go-template/not.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
Unlike the `and` and `or` operators, the `not` operator always returns a boolean value.
|
||||
|
||||
```go-html-template
|
||||
{{ not true }} → false
|
||||
{{ not false }} → true
|
||||
|
||||
{{ not 1 }} → false
|
||||
{{ not 0 }} → true
|
||||
|
||||
{{ not "x" }} → false
|
||||
{{ not "" }} → true
|
||||
```
|
||||
|
||||
Use the `not` operator, twice in succession, to cast any value to a boolean value. For example:
|
||||
|
||||
```go-html-template
|
||||
{{ 42 | not | not }} → true
|
||||
{{ "" | not | not }} → false
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
26
content/en/functions/go-template/or.md
Normal file
26
content/en/functions/go-template/or.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
---
|
||||
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...]
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ or 0 1 2 }} → 1
|
||||
{{ or false "a" 1 }} → a
|
||||
{{ or 0 true "a" }} → true
|
||||
|
||||
{{ or false "" 0 }} → 0
|
||||
{{ or 0 "" false }} → false
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
199
content/en/functions/go-template/range.md
Normal file
199
content/en/functions/go-template/range.md
Normal file
|
|
@ -0,0 +1,199 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/range]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
{{ . }} → foo bar baz
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`else`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
<p>{{ . }}</p>
|
||||
{{ else }}
|
||||
<p>The collection is empty</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Within a range block:
|
||||
|
||||
- Use the [`continue`] statement to stop the innermost iteration and continue to the next iteration
|
||||
- Use the [`break`] statement to stop the innermost iteration and bypass all remaining iterations
|
||||
|
||||
## Understanding context
|
||||
|
||||
At the top of a page template, the [context] (the dot) is a `Page` object. Within the `range` block, the context is bound to each successive element.
|
||||
|
||||
With this contrived example that uses the [`seq`] function to generate a slice of integers:
|
||||
|
||||
```go-html-template
|
||||
{{ range seq 3 }}
|
||||
{{ .Title }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Hugo will throw an error:
|
||||
|
||||
can't evaluate field Title in type int
|
||||
|
||||
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 %}}
|
||||
|
||||
This template will render the page title three times:
|
||||
|
||||
```go-html-template
|
||||
{{ range seq 3 }}
|
||||
{{ $.Title }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Gaining a thorough understanding of context is critical for anyone writing template code.
|
||||
{{% /note %}}
|
||||
|
||||
[`seq`]: functions/collections/seq/
|
||||
[context]: /getting-started/glossary/#context
|
||||
|
||||
## Array or slice of scalars
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $s }}
|
||||
<p>{{ . }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>foo</p>
|
||||
<p>bar</p>
|
||||
<p>baz</p>
|
||||
```
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $v := $s }}
|
||||
<p>{{ $v }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>foo</p>
|
||||
<p>bar</p>
|
||||
<p>baz</p>
|
||||
```
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $s := slice "foo" "bar" "baz" }}
|
||||
{{ range $k, $v := $s }}
|
||||
<p>{{ $k }}: {{ $v }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>0: foo</p>
|
||||
<p>1: bar</p>
|
||||
<p>2: baz</p>
|
||||
```
|
||||
|
||||
## Array or slice of maps
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $m := slice
|
||||
(dict "name" "John" "age" 30)
|
||||
(dict "name" "Will" "age" 28)
|
||||
(dict "name" "Joey" "age" 24)
|
||||
}}
|
||||
{{ range $m }}
|
||||
<p>{{ .name }} is {{ .age }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<p>John is 30</p>
|
||||
<p>Will is 28</p>
|
||||
<p>Joey is 24</p>
|
||||
```
|
||||
|
||||
## Array or slice of pages
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ range where site.RegularPages "Type" "articles" }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<h2><a href="/articles/article-3/">Article 3</a></h2>
|
||||
<h2><a href="/articles/article-2/">Article 2</a></h2>
|
||||
<h2><a href="/articles/article-1/">Article 1</a></h2>
|
||||
```
|
||||
|
||||
## Maps
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $m := dict "name" "John" "age" 30 }}
|
||||
{{ range $k, $v := $m }}
|
||||
<p>key = {{ $k }} value = {{ $v }}</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```go-html-template
|
||||
<p>key = age value = 30</p>
|
||||
<p>key = name value = John</p>
|
||||
```
|
||||
|
||||
Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map.
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`else`]: /functions/go-template/else
|
||||
[`break`]: /functions/go-template/break
|
||||
[`continue`]: /functions/go-template/continue
|
||||
110
content/en/functions/go-template/return.md
Normal file
110
content/en/functions/go-template/return.md
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
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
|
||||
---
|
||||
|
||||
The `return` statement is a custom addition to Go's [text/template] package. Used within partial templates, the `return` statement terminates template execution and returns the given value, if any.
|
||||
|
||||
The returned value may be of any data type including, but not limited to, [`bool`], [`float`], [`int`], [`map`], [`resource`], [`slice`], and [`string`].
|
||||
|
||||
A `return` statement without a value returns an empty string of type `template.HTML`.
|
||||
|
||||
[`bool`]: /getting-started/glossary/#bool
|
||||
[`float`]: /getting-started/glossary/#float
|
||||
[`int`]: /getting-started/glossary/#int
|
||||
[`map`]: /getting-started/glossary/#map
|
||||
[`resource`]: /getting-started/glossary/#resource
|
||||
[`slice`]: /getting-started/glossary/#slice
|
||||
[`string`]: /getting-started/glossary/#string
|
||||
[text/template]: https://pkg.go.dev/text/template
|
||||
|
||||
{{% note %}}
|
||||
Unlike `return` statements in other languages, Hugo executes the first occurrence of the `return` statement regardless of its position within logical blocks. See [usage](#usage) notes below.
|
||||
{{% /note %}}
|
||||
|
||||
## 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" >}}
|
||||
{{ if math.ModBool . 2 }}
|
||||
<p>{{ . }} is even</p>
|
||||
{{ else }}
|
||||
<p>{{ . }} is odd</p>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
When called, the partial renders HTML:
|
||||
|
||||
```go-html-template
|
||||
{{ partial "odd-or-even.html" 42 }} → <p>42 is even</p>
|
||||
```
|
||||
|
||||
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" >}}
|
||||
{{ return math.ModBool . 2 }}
|
||||
{{< /code >}}
|
||||
|
||||
With this template:
|
||||
|
||||
```go-html-template
|
||||
{{ $number := 42 }}
|
||||
{{ if partial "is-even.html" $number }}
|
||||
<p>{{ $number }} is even</p>
|
||||
{{ else }}
|
||||
<p>{{ $number }} is odd</p>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Hugo renders:
|
||||
|
||||
```html
|
||||
<p>42 is even</p>
|
||||
```
|
||||
|
||||
See additional examples in the [partial templates] section.
|
||||
|
||||
[partial templates]: /templates/partials/#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 %}}
|
||||
|
||||
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" >}}
|
||||
{{ $result := false }}
|
||||
{{ if math.ModBool . 2 }}
|
||||
{{ $result = "even" }}
|
||||
{{ else }}
|
||||
{{ $result = "odd" }}
|
||||
{{ end }}
|
||||
{{ return $result }}
|
||||
{{< /code >}}
|
||||
|
||||
{{% note %}}
|
||||
The construct below is incorrect; it contains more than one `return` statement.
|
||||
{{% /note %}}
|
||||
|
||||
{{< code file="layouts/partials/do-not-do-this.html" >}}
|
||||
{{ if math.ModBool . 2 }}
|
||||
{{ return "even" }}
|
||||
{{ else }}
|
||||
{{ return "odd" }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
49
content/en/functions/go-template/template.md
Normal file
49
content/en/functions/go-template/template.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
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]']
|
||||
---
|
||||
|
||||
Use the `template` function to execute [internal templates]. For example:
|
||||
|
||||
```go-html-template
|
||||
{{ range (.Paginate .Pages).Pages }}
|
||||
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
|
||||
{{ end }}
|
||||
{{ template "_internal/pagination.html" . }}
|
||||
```
|
||||
|
||||
You can also use the `template` function to execute a defined template:
|
||||
|
||||
```go-html-template
|
||||
{{ template "foo" (dict "answer" 42) }}
|
||||
|
||||
{{ define "foo" }}
|
||||
{{ printf "The answer is %v." .answer }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
The example above can be rewritten using an [inline partial] template:
|
||||
|
||||
```go-html-template
|
||||
{{ partial "inline/foo.html" (dict "answer" 42) }}
|
||||
|
||||
{{ define "partials/inline/foo.html" }}
|
||||
{{ printf "The answer is %v." .answer }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`partial`]: /functions/partials/include/
|
||||
[inline partial]: /templates/partials/#inline-partials
|
||||
[internal templates]: /templates/internal
|
||||
28
content/en/functions/go-template/urlquery.md
Normal file
28
content/en/functions/go-template/urlquery.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
---
|
||||
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...]']
|
||||
aliases: [/functions/urlquery]
|
||||
---
|
||||
|
||||
This template code:
|
||||
|
||||
```go-html-template
|
||||
{{ $u := urlquery "https://" "example.com" | safeURL }}
|
||||
<a href="https://example.org?url={{ $u }}">Link</a>
|
||||
```
|
||||
|
||||
Is rendered to:
|
||||
|
||||
```html
|
||||
<a href="https://example.org?url=https%3A%2F%2Fexample.com">Link</a>
|
||||
```
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
87
content/en/functions/go-template/with.md
Normal file
87
content/en/functions/go-template/with.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
---
|
||||
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]
|
||||
aliases: [/functions/with]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{% include "functions/go-template/_common/truthy-falsy.md" %}}
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ with $var }}
|
||||
{{ . }} → foo
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Use with the [`else`] statement:
|
||||
|
||||
```go-html-template
|
||||
{{ $var := "foo" }}
|
||||
{{ with $var }}
|
||||
{{ . }} → foo
|
||||
{{ else }}
|
||||
{{ print "var is falsy" }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Initialize a variable, scoped to the current block:
|
||||
|
||||
```go-html-template
|
||||
{{ with $var := 42 }}
|
||||
{{ . }} → 42
|
||||
{{ $var }} → 42
|
||||
{{ end }}
|
||||
{{ $var }} → undefined
|
||||
```
|
||||
|
||||
## Understanding context
|
||||
|
||||
At the top of a page template, the [context] (the dot) is a `Page` object. Inside of the `with` block, the context is bound to the value passed to the `with` statement.
|
||||
|
||||
With this contrived example:
|
||||
|
||||
```go-html-template
|
||||
{{ with 42 }}
|
||||
{{ .Title }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Hugo will throw an error:
|
||||
|
||||
can't evaluate field Title in type int
|
||||
|
||||
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 %}}
|
||||
|
||||
This template will render the page title as desired:
|
||||
|
||||
```go-html-template
|
||||
{{ with 42 }}
|
||||
{{ $.Title }}
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
Gaining a thorough understanding of context is critical for anyone writing template code.
|
||||
{{% /note %}}
|
||||
|
||||
[context]: /getting-started/glossary/#context
|
||||
|
||||
{{% include "functions/go-template/_common/text-template.md" %}}
|
||||
|
||||
[`else`]: /functions/go-template/else
|
||||
19
content/en/functions/hugo/BuildDate.md
Normal file
19
content/en/functions/hugo/BuildDate.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
---
|
||||
title: hugo.BuildDate
|
||||
description: Returns the compile date of the Hugo binary.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related: []
|
||||
returnType: string
|
||||
signatures: [hugo.BuildDate]
|
||||
---
|
||||
|
||||
The `hugo.BuildDate` function returns the compile date of the Hugo binary, formatted per [RFC 3339].
|
||||
|
||||
[RFC 3339]: https://datatracker.ietf.org/doc/html/rfc3339
|
||||
|
||||
```go-html-template
|
||||
{{ hugo.BuildDate }} → 2023-11-01T17:57:00Z
|
||||
```
|
||||
15
content/en/functions/hugo/CommitHash.md
Normal file
15
content/en/functions/hugo/CommitHash.md
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
---
|
||||
title: hugo.CommitHash
|
||||
description: Returns the Git commit hash of the Hugo binary.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
aliases: []
|
||||
related: []
|
||||
returnType: string
|
||||
signatures: [hugo.CommitHash]
|
||||
---
|
||||
|
||||
```go-html-template
|
||||
{{ hugo.CommitHash }} → a4892a07b41b7b3f1f143140ee4ec0a9a5cf3970
|
||||
```
|
||||
66
content/en/functions/hugo/Deps.md
Normal file
66
content/en/functions/hugo/Deps.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
The `hugo.Deps` function returns a slice of project dependencies, either Hugo Modules or local theme components. Each dependency contains:
|
||||
|
||||
Owner
|
||||
: (`hugo.Dependency`) In the dependency tree, this is the first module that defines this module as a dependency (e.g., `github.com/gohugoio/hugo-mod-bootstrap-scss/v5`).
|
||||
|
||||
Path
|
||||
: (`string`) The module path or the path below your `themes` directory (e.g., `github.com/gohugoio/hugo-mod-jslibs-dist/popperjs/v2`).
|
||||
|
||||
Replace
|
||||
: (`hugo.Dependency`) Replaced by this dependency.
|
||||
|
||||
Time
|
||||
: (`time.Time`) The time that the version was created (e.g., `2022-02-13 15:11:28 +0000 UTC`).
|
||||
|
||||
Vendor
|
||||
: (`bool`) Reports whether the dependency is vendored.
|
||||
|
||||
Version
|
||||
: (`string`) The module version (e.g., `v2.21100.20000`).
|
||||
|
||||
An example table listing the dependencies:
|
||||
|
||||
```go-html-template
|
||||
<h2>Dependencies</h2>
|
||||
<table class="table table-dark">
|
||||
<thead>
|
||||
<tr>
|
||||
<th scope="col">#</th>
|
||||
<th scope="col">Owner</th>
|
||||
<th scope="col">Path</th>
|
||||
<th scope="col">Version</th>
|
||||
<th scope="col">Time</th>
|
||||
<th scope="col">Vendor</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ range $index, $element := hugo.Deps }}
|
||||
<tr>
|
||||
<th scope="row">{{ add $index 1 }}</th>
|
||||
<td>{{ with $element.Owner }}{{ .Path }}{{ end }}</td>
|
||||
<td>
|
||||
{{ $element.Path }}
|
||||
{{ with $element.Replace }}
|
||||
=> {{ .Path }}
|
||||
{{ end }}
|
||||
</td>
|
||||
<td>{{ $element.Version }}</td>
|
||||
<td>{{ with $element.Time }}{{ . }}{{ end }}</td>
|
||||
<td>{{ $element.Vendor }}</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
```
|
||||
30
content/en/functions/hugo/Environment.md
Normal file
30
content/en/functions/hugo/Environment.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
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]
|
||||
---
|
||||
|
||||
The `hugo.Environment` function returns the current running [environment] as defined through the `--environment` command line flag.
|
||||
|
||||
```go-html-template
|
||||
{{ hugo.Environment }} → production
|
||||
```
|
||||
|
||||
Command line examples:
|
||||
|
||||
Command|Environment
|
||||
:--|:--
|
||||
`hugo`|`production`
|
||||
`hugo --environment staging`|`staging`
|
||||
`hugo server`|`development`
|
||||
`hugo server --environment staging`|`staging`
|
||||
|
||||
[environment]: /getting-started/glossary/#environment
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue