diff --git a/.cspell.json b/.cspell.json index de66ff601..1a4756c28 100644 --- a/.cspell.json +++ b/.cspell.json @@ -20,13 +20,11 @@ ], "ignoreRegExpList": [ "# cspell: ignore fenced code blocks", - "^(\\s*`{3,}).*[\\s\\S]*?^\\1", + "^(\\s*`{3,}).*[\\s\\S]*?^\\1$", "# cspell: ignore words joined with dot", "\\w+\\.\\w+", "# cspell: ignore strings within backticks", "`.+`", - "# cspell: ignore strings within single quotes", - "'.+'", "# cspell: ignore strings within double quotes", "\".+\"", "# cspell: ignore strings within brackets", diff --git a/content/en/about/hugo-and-gdpr.md b/content/en/about/hugo-and-gdpr.md index daf4e80f0..489005e2f 100644 --- a/content/en/about/hugo-and-gdpr.md +++ b/content/en/about/hugo-and-gdpr.md @@ -22,7 +22,7 @@ aliases: [/privacy/,/gdpr/] Note that: * These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings. - * These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect. + * These settings work with the [embedded templates](/templates/embedded/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect. * We will continue this work and improve this further in future Hugo versions. ## All privacy settings diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md index c0d9ce14d..31640e56e 100644 --- a/content/en/content-management/comments.md +++ b/content/en/content-management/comments.md @@ -37,7 +37,7 @@ For many websites, this is enough configuration. However, you also have the opti ### Render Hugo's built-in Disqus partial template -Disqus has its own [internal template](/templates/internal/#disqus) available, to render it add the following code where you want comments to appear: +Disqus has its own [internal template](/templates/embedded/#disqus) available, to render it add the following code where you want comments to appear: ```go-html-template {{ template "_internal/disqus.html" . }} @@ -66,7 +66,7 @@ Open-source commenting systems: - [Utterances](https://utteranc.es/) [configuration]: /getting-started/configuration/ -[disquspartial]: /templates/internal/#disqus +[disquspartial]: /templates/embedded/#disqus [disqussetup]: https://disqus.com/profile/signup/ [forum]: https://discourse.gohugo.io [front matter]: /content-management/front-matter/ diff --git a/content/en/content-management/toc.md b/content/en/content-management/toc.md index 161c7503b..2ff9c81bf 100644 --- a/content/en/content-management/toc.md +++ b/content/en/content-management/toc.md @@ -110,7 +110,7 @@ A collection of textile samples lay spread out on the table - Samsa was a travel Hugo will take this AsciiDoc and create a table of contents store it in the page variable `.TableOfContents`, in the same as described for Markdown. -[conditionals]: /templates/introduction/#conditionals +[conditionals]: /templates/introduction/#conditional-blocks [front matter]: /content-management/front-matter/ [pagevars]: /methods/page/ [partials]: /templates/partials/ diff --git a/content/en/functions/collections/Where.md b/content/en/functions/collections/Where.md index d56b80867..629d11eeb 100644 --- a/content/en/functions/collections/Where.md +++ b/content/en/functions/collections/Where.md @@ -243,7 +243,7 @@ To return a collection of future 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: +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. To be safe, filter the pages by ranging through the collection: ```go-html-template {{ $events := where .Site.RegularPages "Type" "events" }} diff --git a/content/en/functions/go-template/template.md b/content/en/functions/go-template/template.md index 41aa2e578..687d8b0c8 100644 --- a/content/en/functions/go-template/template.md +++ b/content/en/functions/go-template/template.md @@ -13,7 +13,7 @@ action: signatures: ['template NAME [CONTEXT]'] --- -Use the `template` function to execute [internal templates]. For example: +Use the `template` function to execute [embedded templates]. For example: ```go-html-template {{ range (.Paginate .Pages).Pages }} @@ -46,4 +46,4 @@ The example above can be rewritten using an [inline partial] template: [`partial`]: /functions/partials/include/ [inline partial]: /templates/partials/#inline-partials -[internal templates]: /templates/internal/ +[embedded templates]: /templates/embedded/ diff --git a/content/en/functions/resources/FromString.md b/content/en/functions/resources/FromString.md index 3e616c21c..14bc986cf 100644 --- a/content/en/functions/resources/FromString.md +++ b/content/en/functions/resources/FromString.md @@ -37,7 +37,7 @@ Place this in your baseof.html template: {{ $m := dict "hugo_version" hugo.Version "build_date" (now.Format $rfc3339) - "last_modified" (site.LastChange.Format $rfc3339) + "last_modified" (site.Lastmod.Format $rfc3339) }} {{ $json := jsonify $m }} {{ $r := resources.FromString "site.json" $json }} @@ -61,7 +61,7 @@ Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your stri {{ $m := dict "hugo_version" hugo.Version "build_date" (now.Format $rfc3339) - "last_modified" (site.LastChange.Format $rfc3339) + "last_modified" (site.Lastmod.Format $rfc3339) }} {{ $json := jsonify $m }} ` diff --git a/content/en/functions/strings/ContainsNonSpace.md b/content/en/functions/strings/ContainsNonSpace.md index 188aa14ba..d4c72eea0 100644 --- a/content/en/functions/strings/ContainsNonSpace.md +++ b/content/en/functions/strings/ContainsNonSpace.md @@ -1,6 +1,6 @@ --- title: strings.ContainsNonSpace -description: Reports whether the given string contains any non-space characters as defined by Unicode’s White Space property. +description: Reports whether the given string contains any non-space characters as defined by Unicode's White Space property. categories: [] keywords: [] action: @@ -24,7 +24,7 @@ aliases: [/functions/strings.containsnonspace] {{ strings.ContainsNonSpace "\n abc" }} → true ``` -Common white space characters include: +Common whitespace characters include: ```text '\t', '\n', '\v', '\f', '\r', ' ' diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md index ed8a67e6f..f5de90473 100644 --- a/content/en/getting-started/glossary.md +++ b/content/en/getting-started/glossary.md @@ -98,7 +98,7 @@ A template called with the `.Page.Render` method. See [details](/templates/ ###### context -Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#the-dot). +Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#context). ###### default sort order @@ -363,6 +363,14 @@ A numbered sequence of elements. Unlike Go's [array](#array) data type, slices a A sequence of bytes. For example, `"What is 6 times 7?"` . +###### string literal (interpreted) + +Interpreted string literals are character sequences between double quotes, as in "foo". Within the quotes, any character may appear except a newline and an unescaped double quote. The text between the quotes forms the value of the literal, with backslash escapes interpreted. See [details](https://go.dev/ref/spec#String_literals). + +###### string literal (raw) + +Raw string literals are character sequences between backticks, as in \`bar\`. Within the backticks, any character may appear except a backtick. Backslashes have no special meaning and the string may contain newlines. Carriage return characters ('\r') inside raw string literals are discarded from the raw string value. See [details](https://go.dev/ref/spec#String_literals). + ###### taxonomic weight Defined in front matter and unique to each taxonomy, this [weight](#weight) determines the sort order of page collections contained within a [taxonomy object](#taxonomy-object). See [details](/templates/taxonomy-templates/#assign-weight). diff --git a/content/en/methods/page/Path.md b/content/en/methods/page/Path.md index e9e3e14fe..b65120d4d 100644 --- a/content/en/methods/page/Path.md +++ b/content/en/methods/page/Path.md @@ -108,7 +108,7 @@ Methods|Functions|Shortcodes [`Shortcode.Ref`]|| [`Shortcode.RelRef`]|| -[`urls.Ref`]: functions/urls/ref/ +[`urls.Ref`]: /functions/urls/ref/ [`urls.RelRef`]: /functions/urls/relref/ [`Page.GetPage`]: /methods/page/getpage/ [`Site.GetPage`]: /methods/site/getpage/ diff --git a/content/en/methods/page/PlainWords.md b/content/en/methods/page/PlainWords.md index 14035f083..4f70193fe 100644 --- a/content/en/methods/page/PlainWords.md +++ b/content/en/methods/page/PlainWords.md @@ -15,7 +15,7 @@ action: The `PlainWords` method on a `Page` object calls the [`Plain`] method, then uses Go's [`strings.Fields`] function to split the result into words. {{% note %}} -_Fields splits the string s around each instance of one or more consecutive white space characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only white space._ +_Fields splits the string s around each instance of one or more consecutive whitespace characters, as defined by [`unicode.IsSpace`], returning a slice of substrings of s or an empty slice if s contains only whitespace._ [`unicode.IsSpace`]: https://pkg.go.dev/unicode#IsSpace {{% /note %}} diff --git a/content/en/methods/site/Params.md b/content/en/methods/site/Params.md index f0ca3ad28..95e016b81 100644 --- a/content/en/methods/site/Params.md +++ b/content/en/methods/site/Params.md @@ -33,7 +33,7 @@ Access the custom parameters by [chaining] the [identifiers]: {{ .Site.Params.author.name }} → John Smith {{ $layout := .Site.Params.layouts.rfc_1123 }} -{{ .Site.LastChange.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT +{{ .Site.Lastmod.Format $layout }} → Tue, 17 Oct 2023 13:21:02 PDT ``` In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function: diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md index ac160edd6..8300143e9 100755 --- a/content/en/render-hooks/images.md +++ b/content/en/render-hooks/images.md @@ -72,7 +72,7 @@ block = true ## Examples {{% note %}} -With inline elements such as images and links, remove leading and trailing white space using the `{{‑ ‑}}` delimiter notation to prevent white space between adjacent inline elements and text. +With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text. {{% /note %}} In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing: diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md index f29044fcf..e4c875c5c 100755 --- a/content/en/render-hooks/links.md +++ b/content/en/render-hooks/links.md @@ -55,7 +55,7 @@ Link render hook templates receive the following context: ## Examples {{% note %}} -With inline elements such as images and links, remove leading and trailing white space using the `{{‑ ‑}}` delimiter notation to prevent white space between adjacent inline elements and text. +With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text. {{% /note %}} In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing: diff --git a/content/en/templates/internal.md b/content/en/templates/embedded.md similarity index 85% rename from content/en/templates/internal.md rename to content/en/templates/embedded.md index 96902a979..681cc386a 100644 --- a/content/en/templates/internal.md +++ b/content/en/templates/embedded.md @@ -1,6 +1,6 @@ --- -title: Internal templates -description: Hugo ships with a group of boilerplate templates that cover the most common use cases for static websites. +title: Embedded templates +description: Hugo provides embedded templates for common use cases. categories: [templates] keywords: [internal, analytics,] menu: @@ -9,12 +9,9 @@ menu: weight: 190 weight: 190 toc: true +aliases: [/templates/internal] --- -{{% note %}} -While the following internal templates are called similar to partials, they do *not* observe the partial template lookup order. -{{% /note %}} - ## Disqus {{% note %}} @@ -26,7 +23,16 @@ To override Hugo's embedded Disqus template, copy the [source code] to a file wi [source code]: {{% eturl disqus %}} {{% /note %}} -Hugo includes an embedded template for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up for the free service][disqussignup]. +Hugo includes an embedded template for [Disqus], a popular commenting system for both static and dynamic websites. To effectively use Disqus, secure a Disqus "shortname" by [signing up] for the free service. + +[Disqus]: https://disqus.com +[signing up]: https://disqus.com/profile/signup/ + +To include the embedded template: + +```go-html-template +{{ template "_internal/disqus.html" . }} +``` ### Configure Disqus @@ -45,17 +51,9 @@ Hugo's Disqus template accesses this value with: You can also set the following in the front matter for a given piece of content: -* `disqus_identifier` -* `disqus_title` -* `disqus_url` - -### Use the Disqus template - -To add Disqus, include the following line in the templates where you want your comments to appear: - -```go-html-template -{{ template "_internal/disqus.html" . }} -``` +- `disqus_identifier` +- `disqus_title` +- `disqus_url` ### Conditional loading of Disqus comments @@ -106,6 +104,12 @@ Hugo includes an embedded template supporting [Google Analytics 4]. [Google Analytics 4]: https://support.google.com/analytics/answer/10089681 +To include the embedded template: + +```go-html-template +{{ template "_internal/google_analytics.html" . }} +``` + ### Configure Google Analytics Provide your tracking ID in your configuration file: @@ -116,15 +120,7 @@ Provide your tracking ID in your configuration file: ID = "G-MEASUREMENT_ID" {{}} -### Use the Google Analytics template - -Include the Google Analytics internal template in your templates where you want the code to appear: - -```go-html-template -{{ template "_internal/google_analytics.html" . }} -``` - -To create your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`. +To use this value in your own template, access the configured ID with `{{ site.Config.Services.GoogleAnalytics.ID }}`. ## Open Graph @@ -140,6 +136,12 @@ To override Hugo's embedded Open Graph template, copy the [source code] to a fil Hugo includes an embedded template for the [Open Graph protocol](https://ogp.me/), metadata that enables a page to become a rich object in a social graph. This format is used for Facebook and some other sites. +To include the embedded template: + +```go-html-template +{{ template "_internal/opengraph.html" . }} +``` + ### Configure Open Graph Hugo's Open Graph template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. @@ -177,14 +179,6 @@ Various optional metadata can also be set: If using YouTube this will produce a og:video tag like ``. Use the `https://youtu.be/` format with YouTube videos (example: `https://youtu.be/qtIqKaDlqXo`). -### Use the Open Graph template - -To add Open Graph metadata, include the following line between the `` tags in your templates: - -```go-html-template -{{ template "_internal/opengraph.html" . }} -``` - ## Schema {{% note %}} @@ -200,10 +194,10 @@ Hugo includes an embedded template to render [microdata] `meta` elements within [microdata]: https://html.spec.whatwg.org/multipage/microdata.html#microdata -To call the embedded template from your templates: +To include the embedded template: ```go-html-template -{{ template "_internal/schema.xml" . }} +{{ template "_internal/schema.html" . }} ``` ## Twitter Cards @@ -220,6 +214,12 @@ To override Hugo's embedded Twitter Cards template, copy the [source code] to a Hugo includes an embedded template for [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards/overview/abouts-cards), metadata used to attach rich media to Tweets linking to your site. +To include the embedded template: + +```go-html-template +{{ template "_internal/twitter_cards.html" . }} +``` + ### Configure Twitter Cards Hugo's Twitter Card template is configured using a mix of configuration variables and [front-matter](/content-management/front-matter/) on individual pages. @@ -254,16 +254,3 @@ NOTE: The `@` will be added for you ```html ``` - -### Use the Twitter Cards template - -To add Twitter card metadata, include the following line immediately after the `` element in your templates: - -```go-html-template -{{ template "_internal/twitter_cards.html" . }} -``` - - - -[disqus]: https://disqus.com -[disqussignup]: https://disqus.com/profile/signup/ diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index 64a92261c..1e49672f3 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -1,674 +1,562 @@ --- -title: Templating -linkTitle: Templating -description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. +title: Introduction to templating +linkTitle: Introduction +description: Create templates to render your content, resources, and data. categories: [templates,fundamentals] -keywords: [go] +keywords: [] menu: docs: + identifier: templates-introduction parent: templates weight: 20 weight: 20 toc: true -aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/] --- +A template is a file in the layouts directory of a project, theme, or module. Templates use [variables] , [functions], and [methods] to transform your content, resources, and data into a published page. + +[functions]: /functions/ +[methods]: /methods/ +[variables]: #variables + {{% note %}} -The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](https://golang.org/pkg/text/template/). +Hugo uses Go's [text/template] and [html/template] packages. + +The text/template package implements data-driven templates for generating textual output, while the html/template package implements data-driven templates for generating HTML output safe against code injection. + +By default, Hugo uses the html/template package when rendering HTML files. + +[text/template]: https://pkg.go.dev/text/template +[html/template]: https://pkg.go.dev/html/template {{% /note %}} -Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. - -## Basic syntax - -Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`. - -### Access a predefined variable - -A _predefined variable_ could be a variable already existing in the -current scope (like the `.Title` example in the [Variables](#variables) section below) or a custom variable (like the -`$address` example in that same section). +For example, this HTML template initializes the `$v1` and `$v2` variables, then displays them and their product within an HTML paragraph. ```go-html-template -{{ .Title }} -{{ $address }} +{{ $v1 := 6 }} +{{ $v2 := 7 }} +

The product of {{ $v1 }} and {{ $v2 }} is {{ mul $v1 $v2 }}.

``` -Parameters for functions are separated using spaces. The general syntax is: +While HTML templates are the most common, you can create templates for any [output format] including CSV, JSON, RSS, and plain text. -```go-html-template -{{ FUNCTION ARG1 ARG2 .. }} +[output format]: /templates/output-formats/ + +## Context + +The most important concept to understand before creating a template is _context_, the data passed into each template. The data may be a simple value, or more commonly [objects] and associated [methods]. + +[objects]: /getting-started/glossary/#object +[methods]: /getting-started/glossary/#method + +For example, a template for a single page receives a `Page` object, and the `Page` object provides methods to return values or perform actions. + +### Current context + +Within a template, the dot (`.`) represents the current context. + +{{< code file=layouts/_default/single.html >}} +

{{ .Title }}

+{{< /code >}} + +In the example above the dot represents the `Page` object, and we call its [`Title`] method to return the title as defined in [front matter]. + +[front matter]: /content-management/front-matter/ +[`Title`]: /methods/page/title + +The current context may change within a template. For example, at the top of a template the context might be a `Page` object, but we can rebind the context to another value or object within [`range`] or [`with`] blocks. + +[`range`]: /functions/go-template/range/ +[`with`]: /functions/go-template/with/ + +{{< code file=layouts/_default/single.html >}} +

{{ .Title }}

+ +{{ range slice "foo" "bar" }} +

{{ . }}

+{{ end }} + +{{ with "baz" }} +

{{ . }}

+{{ end }} +{{< /code >}} + +In the example above, the context changes as we `range` through the [slice] of values. In the first iteration the context is "foo", and in the second iteration the context is "bar". Inside of the `with` block the context is "baz". Hugo renders the above to: + +[slice]: /getting-started/glossary/#slice + +```html +

My Page Title

+

foo

+

bar

+

baz

``` -The following example calls the `add` function with inputs of `1` and `2`: +### Template context -```go-html-template -{{ add 1 2 }} +Within a `range` or `with` block you can access the context passed into the template by prepending a dollar sign (`$`) to the dot: + +{{< code file=layouts/_default/single.html >}} +{{ with "foo" }} +

{{ $.Title }} - {{ . }}

+{{ end }} +{{< /code >}} + +Hugo renders this to: + +```html +

My Page Title - foo ``` -#### Methods and fields are accessed via dot notation +{{% note %}} +Make sure that you thoroughly understand the concept of _context_ before you continue reading. The most common templating errors made by new users relate to context. +{{% /note %}} -Accessing the Page Parameter `bar` defined in a piece of content's [front matter]. +## Actions -```go-html-template -{{ .Params.bar }} +In the examples above the paired opening and closing braces represent the beginning and end of a template action, a data evaluation or control structure within a template. + +A template action may contain literal values ([boolean], [string], [integer], and [float]), variables, functions, and methods. + +[boolean]: /getting-started/glossary/#boolean +[string]: /getting-started/glossary/#string +[integer]: /getting-started/glossary/#integer +[float]: /getting-started/glossary/#float + +{{< code file=layouts/_default/single.html >}} +{{ $convertToLower := true }} +{{ if $convertToLower }} +

{{ strings.ToLower .Title }}

+{{ end }} +{{< /code >}} + +In the example above: + +- `$convertToLower` is a variable +- `true` is a literal boolean value +- `strings.ToLower` is a function that converts all characters to lowercase +- `Title` is a method on a the `Page` object + +Hugo renders the above to: + +```html + + +

my page title

+ ``` -#### Parentheses can be used to group items together +### Whitespace -```go-html-template -{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +Notice the blank lines and indentation in the previous example? Although irrelevant in production when you typically minify the output, you can remove the adjacent whitespace by using template action delimiters with hyphens: + +{{< code file=layouts/_default/single.html >}} +{{- $convertToLower := true -}} +{{- if $convertToLower -}} +

{{ strings.ToLower .Title }}

+{{- end -}} +{{< /code >}} + +Hugo renders this to: + +```html +

my page title

``` -#### A single statement can be split over multiple lines +Whitespace includes spaces, horizontal tabs, carriage returns, and newlines. + +### Pipes + +Within a template action you may [pipe] a value to function or method. The piped value becomes the final argument to the function or method. For example, these are equivalent: + +[pipe]: /getting-started/glossary/#pipeline ```go-html-template -{{ if or - (isset .Params "alt") - (isset .Params "caption") +{{ strings.ToLower "Hugo" }} → hugo +{{ "Hugo" | strings.ToLower }} → hugo +``` + +You can pipe the result of one function or method into another. For example, these are equivalent: + +```go-html-template +{{ strings.TrimSuffix "o" (strings.ToLower "Hugo") }} → Hug +{{ "Hugo" | strings.ToLower | strings.TrimSuffix "o" }} → Hug +``` + +These are also equivalent: + +```go-html-template +{{ mul 6 (add 2 5) }} → 42 +{{ 2 | add 5 | mul 6 }} → 42 +``` + +{{% note %}} +Remember that the piped value becomes the final argument to the function or method to which you are piping. +{{% /note %}} + +### Line splitting + +You can split a template action over two or more lines. For example, these are equivalent: + +```go-html-template +{{ $v := or .Site.Language.LanguageCode .Site.Language.Lang }} + +{{ $v := or + .Site.Language.LanguageCode + .Site.Language.Lang }} ``` -#### Raw string literals can include newlines +You can also split [raw string literals] over two or more lines. For example, these are equivalent: + +[raw string literals]: /getting-started/glossary/#string-literal-raw ```go-html-template -{{ $msg := `Line one. -Line two.` }} +{{ $msg := "This is line one.\nThis is line two." }} + +{{ $msg := `This is line one. +This is line two.` +}} ``` ## Variables -Each Go Template gets a data object. In Hugo, each template is passed -a `Page`. In the below example, `.Title` is one of the elements -accessible in that [`Page` variable][pagevars]. +A variable is a user-defined [identifier] prefaced with a dollar sign (`$`), representing a value of any data type, initialized or assigned within a template action. For example, `$foo` and `$bar` are variables. -With the `Page` being the default scope of a template, the `Title` -element in current scope (`.` -- "the **dot**") is accessible simply -by the dot-prefix (`.Title`): +[identifier]: /getting-started/glossary/#identifier + +Variables may contain [scalars], [slices], [maps], or [objects]. + +[scalars]: /getting-started/glossary/#scalar +[slices]: /getting-started/glossary/#slice +[maps]: /getting-started/glossary/#map +[objects]: /getting-started/glossary/#object + +Use `:=` to initialize a variable, and use `=` to assign a value to a variable that has been previously initialized. For example: ```go-html-template -{{ .Title }} +{{ $total := 3 }} +{{ range slice 7 11 21 }} + {{ $total = add $total . }} +{{ end }} +{{ $v1 }} → 42 ``` -Values can also be stored in custom variables and referenced later: +Variables initialized inside of an `if`, `range`, or `with` block are scoped to the block. Variables initialized outside of these blocks are scoped to the template. + +With variables that represent a slice or map, use the [`index`] function to return the desired value. + +[`index`]: /functions/collections/indexfunction/ + +```go-html-template +{{ $slice := slice "foo" "bar" "baz" }} +{{ index $slice 2 }} → baz + +{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }} +{{ index $map "c" }} → baz +``` {{% note %}} -The custom variables need to be prefixed with `$`. +Slices and arrays are zero-based; element 0 is the first element. {{% /note %}} -```go-html-template -{{ $address := "123 Main St." }} -{{ $address }} -``` +With variables that represent a map or object, [chain] identifiers to return the desired value or to access the desired method. -Variables can be re-defined using the `=` operator. The example below -prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on -all other pages: +[chain]: /getting-started/glossary/#chain ```go-html-template -{{ $var := "Hugo Page" }} -{{ if .IsHome }} - {{ $var = "Hugo Home" }} -{{ end }} -Var is {{ $var }} +{{ $map := dict "a" "foo" "b" "bar" "c" "baz" }} +{{ $map.c }} → baz + +{{ $homePage := .Site.Home }} +{{ $homePage.Title }} → My Homepage ``` -Variable names must conform to Go's naming rules for [identifiers][identifier]. +{{% note %}} +As seen above, object and method names are capitalized. Although not required, to avoid confusion we recommend beginning variable and map key names with a lowercase letter or underscore. +{{% /note %}} ## Functions -Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. +Used within a template action, a function takes one or more arguments and returns a value. Unlike methods, functions are not associated with an object. -[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. +Go's text/template and html/template packages provide a small set of functions, operators, and statements for general use. See the [go-templates] section of the function documentation for details. -### Example 1: adding numbers +[go-templates]: /functions/go-template/ + +Hugo provides hundreds of custom [functions] categorized by namespace. For example, the `strings` namespace includes these and other functions: + +[functions]: /functions + +Function|Alias +:--|:-- +[`strings.ToLower`](/functions/strings/tolower)|`lower` +[`strings.ToUpper`](/functions/strings/toupper)|`upper` +[`strings.Replace`](/functions/strings/replace)|`replace` + +As shown above, frequently used functions have an alias. Use aliases in your templates to reduce code length. + +When calling a function, separate the arguments from the function, and from each other, with a space. For example: ```go-html-template -{{ add 1 2 }} - +{{ $total := add 1 2 3 4 }} → 10 ``` -### Example 2: comparing numbers +## Methods -```go-html-template -{{ lt 1 2 }} - -``` +Used within a template action and associated with an object, a method takes zero or more arguments and either returns a value or performs an action. -Note that both examples make use of Go Template's [math][math] functions. +The most commonly accessed objects are the [`Page`] and [`Site`] objects. This is a small sampling of the [methods] available to each object. -{{% note %}} -There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions). -{{% /note %}} +[`Site`]: /methods/site/ +[`Page`]: /methods/page/ +[methods]: /methods/ -## Includes +Object|Method|Description +:--|:--|:-- +`Page`|[`Date`](methods/page/date/)|Returns the date of the given page. +`Page`|[`Params`](methods/page/params/)|Returns a map of custom parameters as defined in the front matter of the given page. +`Page`|[`Title`](methods/page/title/)|Returns the title of the given page. +`Site`|[`Data`](methods/site/data/)|Returns a data structure composed from the files in the data directory. +`Site`|[`Params`](methods/site/params/)|Returns a map of custom parameters as defined in the site configuration. +`Site`|[`Title`](methods/site/title/)|Returns the title as defined in the site configuration. -When including another template, you will need to pass it the data that it would -need to access. +Chain the method to its object with a dot (`.`) as shown below, remembering that the leading dot represents the [current context]. -{{% note %}} -To pass along the current context, please remember to include a trailing **dot**. -{{% /note %}} +[current context]: #current-context -The templates location will always be starting at the `layouts/` directory -within Hugo. - -### Partial - -The [`partial`][partials] function is used to include _partial_ templates using -the syntax `{{ partial "/." . }}`. - -Example of including a `layouts/partials/header.html` partial: - -```go-html-template -{{ partial "header.html" . }} -``` - -### Template - -The `template` function was used to include _partial_ templates -in much older Hugo versions. Now it's useful only for calling -[_internal_ templates][internal templates]. The syntax is `{{ template -"_internal/