From: Bjørn Erik Pedersen Date: Sun, 8 May 2022 14:56:42 +0000 (+0200) Subject: Merge commit '327aaed6d8ca57d8e5e3acb99ff53402ff1c556d' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=1c7759028;p=brevno-suite%2Fhugo Merge commit '327aaed6d8ca57d8e5e3acb99ff53402ff1c556d' --- 1c7759028ed02170f128c1ede3b098e470803a26 diff --cc docs/content/en/content-management/build-options.md index c3f6f04c9,000000000..7bbb772df mode 100644,000000..100644 --- a/docs/content/en/content-management/build-options.md +++ b/docs/content/en/content-management/build-options.md @@@ -1,119 -1,0 +1,116 @@@ +--- +title: Build Options +linktitle: Build Options +description: Build options help define how Hugo must treat a given page when building the site. +date: 2020-03-02 +publishdate: 2020-03-02 +keywords: [build,content,front matter, page resources] +categories: ["content management"] +menu: + docs: + parent: "content-management" + weight: 31 +weight: 31 #rem +draft: false +aliases: [/content/build-options/] +toc: true +--- + +They are stored in a reserved Front Matter object named `_build` with the following defaults: + +{{< code-toggle >}} +_build: + render: always + list: always + publishResources: true +{{< /code-toggle >}} + +#### render +If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink. + +{{< new-in "0.76.0" >}} We extended this property from a boolean to an enum in Hugo 0.76.0. Valid values are: + +never +: The page will not be included in any page collection. + +always (default) +: The page will be rendered to disk and get a `RelPermalink` etc. + +link +: The page will be not be rendered to disk, but will get a `RelPermalink`. + +#### list + +Note that we extended this property from a boolean to an enum in Hugo 0.68.0. + +Valid values are: + +never +: The page will not be included in any page collection. + +always (default) +: The page will be included in all page collections, e.g. `site.RegularPages`, `$page.Pages`. + +local +: The page will be included in any _local_ page collection, e.g. `$page.RegularPages`, `$page.Pages`. One use case for this would be to create fully navigable, but headless content sections. {{< new-in "0.68.0" >}} + +If true, the page will be treated as part of the project's collections and, when appropriate, returned by Hugo's listing methods (`.Pages`, `.RegularPages` etc...). + +#### publishResources + +If set to true the [Bundle's Resources]({{< relref "content-management/page-bundles" >}}) will be published. +Setting this to false will still publish Resources on demand (when a resource's `.Permalink` or `.RelPermalink` is invoked from the templates) but will skip the others. + +{{% note %}} +Any page, regardless of their build options, will always be available using the [`.GetPage`]({{< relref "functions/GetPage" >}}) methods. +{{% /note %}} + +------ + +### Illustrative use cases + +#### Not publishing a page +Project needs a "Who We Are" content file for Front Matter and body to be used by the homepage but nowhere else. + +```yaml +# content/who-we-are.md` +title: Who we are +_build: + list: false + render: false +``` + +```go-html-template +{{/* layouts/index.html */}} +
+{{ with site.GetPage "who-we-are" }} + {{ .Content }} +{{ end }} +
+``` + +#### Listing pages without publishing them + +Website needs to showcase a few of the hundred "testimonials" available as content files without publishing any of them. + +To avoid setting the build options on every testimonials, one can use [`cascade`]({{< relref "/content-management/front-matter#front-matter-cascade" >}}) on the testimonial section's content file. + - ```yaml - #content/testimonials/_index.md ++{{< code-toggle >}} +title: Testimonials - # section build options: +_build: + render: true - # children build options with cascade +cascade: + _build: + render: false + list: true # default - ``` ++{{< /code-toggle >}} + +```go-html-template +{{/* layouts/_defaults/testimonials.html */}} +
+{{ range first 5 .Pages }} +
+ {{ .Content }} +
+{{ end }} +
diff --cc docs/content/en/templates/introduction.md index 751ed3f29,000000000..801df71cc mode 100644,000000..100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@@ -1,698 -1,0 +1,686 @@@ +--- +title: Introduction to Hugo Templating +linktitle: Templating +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-25 +categories: [templates,fundamentals] +keywords: [go] +menu: + docs: + parent: "templates" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/] +toc: true +--- + +{{% 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/). +{{% /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]({{< relref +"#variables" >}}) section below) or a custom variable (like the +`$address` example in that same section). + + +```go-html-template +{{ .Title }} +{{ $address }} +``` + +Parameters for functions are separated using spaces. The general syntax is: + +``` +{{ FUNCTION ARG1 ARG2 .. }} +``` + +The following example calls the `add` function with inputs of `1` and `2`: + +```go-html-template +{{ add 1 2 }} +``` + +#### Methods and Fields are Accessed via dot Notation + +Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. + +```go-html-template +{{ .Params.bar }} +``` + +#### Parentheses Can be Used to Group Items Together + +```go-html-template +{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +``` + +#### A Single Statement Can be Split over Multiple Lines + +```go-html-template +{{ if or + (isset .Params "alt") + (isset .Params "caption") +}} +``` + +#### Raw String Literals Can Include Newlines + +```go-html-template +{{ $msg := `Line one. +Line two.` }} +``` + +## Variables {#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]. + +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`): + +```go-html-template +{{ .Title }} +``` + +Values can also be stored in custom variables and referenced later: + +{{% note %}} +The custom variables need to be prefixed with `$`. +{{% /note %}} + +```go-html-template +{{ $address := "123 Main St." }} +{{ $address }} +``` - - {{% warning %}} - For Hugo v0.47 and older versions, variables defined inside `if` - conditionals and similar are not visible on the outside. - See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). - - Hugo has created a workaround for this issue in [Scratch](/functions/scratch). - {{% /warning %}} - - For **Hugo v0.48** and newer, variables can be re-defined using the - new `=` operator (new in Go 1.11). - - Below example will work only in these newer Hugo versions. The example ++Vriables 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: + +```go-html-template +{{ $var := "Hugo Page" }} +{{ if .IsHome }} + {{ $var = "Hugo Home" }} +{{ end }} +Var is {{ $var }} +``` + +## Functions + +Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. + +[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. + +### Example 1: Adding Numbers + +```go-html-template +{{ add 1 2 }} + +``` + +### Example 2: Comparing Numbers + +```go-html-template +{{ lt 1 2 }} + +``` + +Note that both examples make use of Go Template's [math]][] functions. + +{{% note "Additional Boolean Operators" %}} +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 %}} + +## Includes + +When including another template, you will need to pass it the data that it would +need to access. + +{{% note %}} +To pass along the current context, please remember to include a trailing **dot**. +{{% /note %}} + +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/