diff options
| author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2019-04-20 16:19:38 +0300 |
|---|---|---|
| committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2019-04-20 16:19:38 +0300 |
| commit | 0508ca1856e57421fca699c6427cc19531b55b7a (patch) | |
| tree | db015657f0268054adff358ebec4b4a329d931a0 /docs/content/en/templates | |
| parent | c7dd66bfe2e32430f9b1a3126c67014e40d8405e (diff) | |
| parent | a0c28c943c2f4714fa340b22a583b96f5013090b (diff) | |
Merge commit 'a0c28c943c2f4714fa340b22a583b96f5013090b'
Diffstat (limited to 'docs/content/en/templates')
| -rw-r--r-- | docs/content/en/templates/output-formats.md | 26 | ||||
| -rw-r--r-- | docs/content/en/templates/partials.md | 42 | ||||
| -rw-r--r-- | docs/content/en/templates/taxonomy-templates.md | 43 |
3 files changed, 82 insertions, 29 deletions
diff --git a/docs/content/en/templates/output-formats.md b/docs/content/en/templates/output-formats.md index 37c48b75e..1ab45e4c7 100644 --- a/docs/content/en/templates/output-formats.md +++ b/docs/content/en/templates/output-formats.md @@ -68,7 +68,7 @@ Given a media type and some additional configuration, you get an **Output Format This is the full set of Hugo's built-in output formats: -{{< datatable "output" "formats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly">}} +{{< datatable "output" "formats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly" "permalinkable" >}} * A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `AMP` vs. `HTML`. `AMP` has the value `amp` for `Path` so it doesn't overwrite the `HTML` version; e.g. we can now have both `/index.html` and `/amp/index.html`. * The `MediaType` must match the `Type` of an already defined media type. @@ -120,6 +120,9 @@ The following is the full list of configuration options for output formats and t `notAlternative` : enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term *alternative* and not *alternate* here, as it does not necessarily replace the other format. **Default:** `false`. +`permalinkable` +: make `.Permalink` and `.RelPermalink` return the rendering Output Format rather than main ([see below](#link-to-output-formats)). This is enabled by default for `HTML` and `AMP`. **Default:** `false`. + ## Output Formats for Pages A `Page` in Hugo can be rendered to multiple *output formats* on the file @@ -173,7 +176,7 @@ outputs: --- ``` -## Link to Output Formats +## List Output formats Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`: @@ -183,13 +186,26 @@ Each `Page` has both an `.OutputFormats` (all formats, including the current) an {{ end -}} ``` -Note that `.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). +## Link to Output Formats -This is how you link to a given output format: +`.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template file they are being called from. +__from `single.json.json`:__ ```go-html-template +{{ .RelPermalink }} > /that-page/ {{ with .OutputFormats.Get "json" -}} -<a href="{{ .Permalink }}">{{ .Name }}</a> +{{ .RelPermalink }} > /that-page/index.json +{{- end }} +``` + +In order for them to return the output format of the current template file instead, the given output format should have its `permalinkable` setting set to true. + +__Same template file as above with json output format's `permalinkable` set to true:__ + +```go-html-template +{{ .RelPermalink }} > /that-page/index.json +{{ with .OutputFormats.Get "html" -}} +{{ .RelPermalink }} > /that-page/ {{- end }} ``` diff --git a/docs/content/en/templates/partials.md b/docs/content/en/templates/partials.md index c7b35222c..725e946fb 100644 --- a/docs/content/en/templates/partials.md +++ b/docs/content/en/templates/partials.md @@ -77,7 +77,47 @@ The second argument in a partial call is the variable being passed down. The abo This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`. -### Cached Partials +## Returning a value from a Partial + +In addition to outputting markup, partials can be used to return a value of any type. In order to return a value, a partial must include a lone `return` statement. + +### Example GetFeatured +```go-html-template +{{/* layouts/partials/GetFeatured.html */}} +{{ return first . (where site.RegularPages ".Params.featured" true) }} +``` + +```go-html-template +{{/* layouts/index.html */}} +{{ range partial "GetFeatured.html" 5 }} + [...] +{{ end }} +``` +### Example GetImage +```go-html-template +{{/* layouts/partials/GetImage.html */}} +{{ $image := false }} +{{ with .Params.gallery }} + {{ $image = index . 0 }} +{{ end }} +{{ with .Params.image }} + {{ $image = . }} +{{ end }} +{{ return $image }} +``` + +```go-html-template +{{/* layouts/_default/single.html */}} +{{ with partial "GetImage.html" . }} + [...] +{{ end }} +``` + +{{% note %}} +Only one `return` statement is allowed per partial file. +{{% /note %}} + +## Cached Partials The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows: diff --git a/docs/content/en/templates/taxonomy-templates.md b/docs/content/en/templates/taxonomy-templates.md index c827376c2..b82a5175c 100644 --- a/docs/content/en/templates/taxonomy-templates.md +++ b/docs/content/en/templates/taxonomy-templates.md @@ -124,40 +124,22 @@ Taxonomies can be ordered by either alphabetical key or by the number of content ### Order Alphabetically Example -```go-html-template -<ul> - {{ $type := .Type }} - {{ range $key, $value := .Data.Terms.Alphabetical }} - {{ $name := .Name }} - {{ $count := .Count }} - {{ with $.Site.GetPage (printf "/%s/%s" $type $name) }} - <li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li> - {{ end }} - {{ end }} -</ul> -``` - -### Order by Popularity Example +In Hugo 0.55 and later you can do: ```go-html-template <ul> - {{ $type := .Type }} - {{ range $key, $value := .Data.Terms.ByCount }} - {{ $name := .Name }} - {{ $count := .Count }} - {{ with $.Site.GetPage (printf "/%s/%s" $type $name) }} - <li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li> - {{ end }} + {{ range .Data.Terms.Alphabetical }} + <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li> {{ end }} </ul> ``` -### Order by Least Popular Example +Before that you would have to do something like: ```go-html-template <ul> {{ $type := .Type }} - {{ range $key, $value := .Data.Terms.ByCount.Reverse }} + {{ range $key, $value := .Data.Terms.Alphabetical }} {{ $name := .Name }} {{ $count := .Count }} {{ with $.Site.GetPage (printf "/%s/%s" $type $name) }} @@ -167,6 +149,7 @@ Taxonomies can be ordered by either alphabetical key or by the number of content </ul> ``` + <!-- [See Also Taxonomy Lists](/templates/list/) --> ## Order Content within Taxonomies @@ -311,6 +294,20 @@ The following example displays all terms in a site's tags taxonomy: ### Example: List All Site Tags {#example-list-all-site-tags} +In Hugo 0.55 and later you can simply do: + +```go-html-template +<ul> + {{ range .Site.Taxonomies.tags }} + <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li> + {{ end }} +</ul> +``` + +Before that you would do something like this: + +{{< todo >}}Clean up rest of the taxonomy examples re Hugo 0.55.{{< /todo >}} + ```go-html-template <ul id="all-tags"> {{ range $name, $taxonomy := .Site.Taxonomies.tags }} |