diff options
Diffstat (limited to 'docs/content/en/functions/go-template')
| -rw-r--r-- | docs/content/en/functions/go-template/block.md | 6 | ||||
| -rw-r--r-- | docs/content/en/functions/go-template/define.md | 19 | ||||
| -rw-r--r-- | docs/content/en/functions/go-template/range.md | 55 | ||||
| -rw-r--r-- | docs/content/en/functions/go-template/return.md | 11 | ||||
| -rw-r--r-- | docs/content/en/functions/go-template/template.md | 34 |
5 files changed, 68 insertions, 57 deletions
diff --git a/docs/content/en/functions/go-template/block.md b/docs/content/en/functions/go-template/block.md index bffab1f8c..383a3d72e 100644 --- a/docs/content/en/functions/go-template/block.md +++ b/docs/content/en/functions/go-template/block.md @@ -23,7 +23,7 @@ and then executing it in place: ``` The typical use is to define a set of root templates that are then customized by redefining the block templates within. -```go-html-template {file="layouts/_default/baseof.html"} +```go-html-template {file="layouts/baseof.html"} <body> <main> {{ block "main" . }} @@ -33,14 +33,14 @@ The typical use is to define a set of root templates that are then customized by </body> ``` -```go-html-template {file="layouts/_default/single.html"} +```go-html-template {file="layouts/page.html"} {{ define "main" }} <h1>{{ .Title }}</h1> {{ .Content }} {{ end }} ``` -```go-html-template {file="layouts/_default/list.html"} +```go-html-template {file="layouts/section.html"} {{ define "main" }} <h1>{{ .Title }}</h1> {{ .Content }} diff --git a/docs/content/en/functions/go-template/define.md b/docs/content/en/functions/go-template/define.md index 19762a3d6..40d495bd9 100644 --- a/docs/content/en/functions/go-template/define.md +++ b/docs/content/en/functions/go-template/define.md @@ -28,7 +28,7 @@ Use with the [`partial`] function: ```go-html-template {{ partial "inline/foo.html" (dict "answer" 42) }} -{{ define "partials/inline/foo.html" }} +{{ define "_partials/inline/foo.html" }} {{ printf "The answer is %v." .answer }} {{ end }} ``` @@ -43,8 +43,21 @@ Use with the [`template`] function: {{ end }} ``` +> [!warning] +> Only [template comments] are allowed outside of the `define` and `end` statements. Avoid placing any other text, including HTML comments, outside of these boundaries. Doing so will cause rendering issues, potentially resulting in a blank page. See the example below. + +```go-html-template {file="layouts/do-not-do-this.html"} +<div>This div element broke your template.</div> +{{ define "main" }} + <h2>{{ .Title }}</h2> + {{ .Content }} +{{ end }} +<!-- An HTML comment will break your template too. --> +``` + +{{% include "/_common/functions/go-template/text-template.md" %}} + [`block`]: /functions/go-template/block/ [`template`]: /functions/go-template/block/ [`partial`]: /functions/partials/include/ - -{{% include "/_common/functions/go-template/text-template.md" %}} +[template comments]: /templates/introduction/#comments diff --git a/docs/content/en/functions/go-template/range.md b/docs/content/en/functions/go-template/range.md index a06907c79..50f714140 100644 --- a/docs/content/en/functions/go-template/range.md +++ b/docs/content/en/functions/go-template/range.md @@ -11,7 +11,7 @@ params: aliases: [/functions/range] --- -{{% include "/_common/functions/truthy-falsy.md" %}} +The collection may be a slice, a map, or an integer. ```go-html-template {{ $s := slice "foo" "bar" "baz" }} @@ -40,19 +40,22 @@ Within a range block: At the top of a page template, the [context](g) (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: +With this contrived example: ```go-html-template -{{ range seq 3 }} - {{ .Title }} +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} + {{ .Title }} {{ end }} ``` Hugo will throw an error: - can't evaluate field Title in type int +```text +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. +The error occurs because we are trying to use the `.Title` method on a string 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. @@ -60,15 +63,18 @@ The error occurs because we are trying to use the `.Title` method on an integer This template will render the page title three times: ```go-html-template -{{ range seq 3 }} - {{ $.Title }} +{{ $s := slice "foo" "bar" "baz" }} +{{ range $s }} + {{ $.Title }} {{ end }} ``` > [!note] > Gaining a thorough understanding of context is critical for anyone writing template code. -## Array or slice of scalars +## Examples + +### Slice of scalars This template code: @@ -121,7 +127,7 @@ Is rendered to: <p>2: baz</p> ``` -## Array or slice of maps +### Slice of maps This template code: @@ -144,7 +150,7 @@ Is rendered to: <p>Joey is 24</p> ``` -## Array or slice of pages +### Slice of pages This template code: @@ -162,7 +168,7 @@ Is rendered to: <h2><a href="/articles/article-1/">Article 1</a></h2> ``` -## Maps +### Maps This template code: @@ -182,9 +188,32 @@ Is rendered to: Unlike ranging over an array or slice, Hugo sorts by key when ranging over a map. +### Integers + +{{< new-in 0.123.0 />}} + +Ranging over a positive integer `n` executes the block `n` times, with the context starting at zero and incrementing by one in each iteration. + +```go-html-template +{{ $s := slice }} +{{ range 1 }} + {{ $s = $s | append . }} +{{ end }} +{{ $s }} → [0] +``` + +```go-html-template +{{ $s := slice }} +{{ range 3 }} + {{ $s = $s | append . }} +{{ end }} +{{ $s }} → [0 1 2] +``` + +Ranging over a non-positive integer executes the block zero times. + {{% include "/_common/functions/go-template/text-template.md" %}} [`break`]: /functions/go-template/break/ [`continue`]: /functions/go-template/continue/ [`else`]: /functions/go-template/else/ -[`seq`]: /functions/collections/seq/ diff --git a/docs/content/en/functions/go-template/return.md b/docs/content/en/functions/go-template/return.md index eb6ba30cd..911c0925c 100644 --- a/docs/content/en/functions/go-template/return.md +++ b/docs/content/en/functions/go-template/return.md @@ -23,7 +23,7 @@ A `return` statement without a value returns an empty string of type `template.H By way of example, let's create a partial template that _renders_ HTML, describing whether the given number is odd or even: -```go-html-template {file="layouts/partials/odd-or-even.html"} +```go-html-template {file="layouts/_partials/odd-or-even.html"} {{ if math.ModBool . 2 }} <p>{{ . }} is even</p> {{ else }} @@ -39,7 +39,7 @@ When called, the partial renders HTML: Instead of rendering HTML, let's create a partial that _returns_ a boolean value, reporting whether the given number is even: -```go-html-template {file="layouts/partials/is-even.html"} +```go-html-template {file="layouts/_partials/is-even.html"} {{ return math.ModBool . 2 }} ``` @@ -60,8 +60,6 @@ Hugo renders: <p>42 is even</p> ``` -See additional examples in the [partial templates] section. - ## Usage > [!note] @@ -71,7 +69,7 @@ A partial that returns a value must contain only one `return` statement, placed For example: -```go-html-template {file="layouts/partials/is-even.html"} +```go-html-template {file="layouts/_partials/is-even.html"} {{ $result := false }} {{ if math.ModBool . 2 }} {{ $result = "even" }} @@ -84,7 +82,7 @@ For example: > [!note] > The construct below is incorrect; it contains more than one `return` statement. -```go-html-template {file="layouts/partials/do-not-do-this.html"} +```go-html-template {file="layouts/_partials/do-not-do-this.html"} {{ if math.ModBool . 2 }} {{ return "even" }} {{ else }} @@ -92,5 +90,4 @@ For example: {{ end }} ``` -[partial templates]: /templates/partial/#returning-a-value-from-a-partial [text/template package]: https://pkg.go.dev/text/template diff --git a/docs/content/en/functions/go-template/template.md b/docs/content/en/functions/go-template/template.md index 053cfcc22..903f1490a 100644 --- a/docs/content/en/functions/go-template/template.md +++ b/docs/content/en/functions/go-template/template.md @@ -10,27 +10,7 @@ params: signatures: ['template NAME [CONTEXT]'] --- -Use the `template` function to execute any of these [embedded templates](g): - -- [`disqus.html`] -- [`google_analytics.html`] -- [`opengraph.html`] -- [`pagination.html`] -- [`schema.html`] -- [`twitter_cards.html`] - - - -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: +Use the `template` function to execute a defined template: ```go-html-template {{ template "foo" (dict "answer" 42) }} @@ -40,12 +20,12 @@ You can also use the `template` function to execute a defined template: {{ end }} ``` -The example above can be rewritten using an [inline partial] template: +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" }} +{{ define "_partials/inline/foo.html" }} {{ printf "The answer is %v." .answer }} {{ end }} ``` @@ -58,13 +38,5 @@ The key distinctions between the preceding two examples are: {{% include "/_common/functions/go-template/text-template.md" %}} -[`disqus.html`]: /templates/embedded/#disqus -[`google_analytics.html`]: /templates/embedded/#google-analytics -[`opengraph.html`]: /templates/embedded/#open-graph -[`pagination.html`]: /templates/embedded/#pagination [`partialCached`]: /functions/partials/includecached/ -[`partial`]: /functions/partials/include/ [`return`]: /functions/go-template/return/ -[`schema.html`]: /templates/embedded/#schema -[`twitter_cards.html`]: /templates/embedded/#x-twitter-cards -[inline partial]: /templates/partial/#inline-partials |