mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-21 21:35:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '9b0050e9aabe4be65c78ccf292a348f309d50ccd' as 'docs'

Browse Source 
```
git subtree add --prefix=docs/ https://github.com/gohugoio/hugoDocs.git master --squash
```

Closes #11925
This commit is contained in:
Bjørn Erik Pedersen
2024-01-27 10:48:33 +01:00
parent fc7de7136a 9b0050e9aa
commit 5fd1e74903
1158 changed files with 64103 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/content/en/functions/go-template/_common/_index.md Normal file
View 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
docs/content/en/functions/go-template/_common/text-template.md Normal file
View File

@@ -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
docs/content/en/functions/go-template/_common/truthy-falsy.md Normal file
View 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
docs/content/en/functions/go-template/_index.md Normal file
View 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
docs/content/en/functions/go-template/and.md Normal file
View 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
docs/content/en/functions/go-template/block.md Normal file
View 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
docs/content/en/functions/go-template/break.md Normal file
View 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
docs/content/en/functions/go-template/continue.md Normal file
View 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
docs/content/en/functions/go-template/define.md Normal file
View 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
docs/content/en/functions/go-template/else.md Normal file
View 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
docs/content/en/functions/go-template/end.md Normal file
View 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
docs/content/en/functions/go-template/if.md Normal file
View 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
docs/content/en/functions/go-template/len.md Normal file
View 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
docs/content/en/functions/go-template/not.md Normal file
View 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
docs/content/en/functions/go-template/or.md Normal file
View 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
docs/content/en/functions/go-template/range.md Normal file
View 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
docs/content/en/functions/go-template/return.md Normal file
View 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
docs/content/en/functions/go-template/template.md Normal file
View 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
docs/content/en/functions/go-template/urlquery.md Normal file
View 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
docs/content/en/functions/go-template/with.md Normal file
View 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