mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-29 22:29:56 +02:00
Merge commit 'a0c28c943c2f4714fa340b22a583b96f5013090b'
This commit is contained in:
Bjørn Erik Pedersen
@@ -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" -}}
|
||||
{{ .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
|
||||
{{ with .OutputFormats.Get "json" -}}
|
||||
<a href="{{ .Permalink }}">{{ .Name }}</a>
|
||||
{{ .RelPermalink }} > /that-page/index.json
|
||||
{{ with .OutputFormats.Get "html" -}}
|
||||
{{ .RelPermalink }} > /that-page/
|
||||
{{- end }}
|
||||
```
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -124,6 +124,18 @@ Taxonomies can be ordered by either alphabetical key or by the number of content
|
||||
|
||||
### Order Alphabetically Example
|
||||
|
||||
In Hugo 0.55 and later you can do:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ range .Data.Terms.Alphabetical }}
|
||||
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
Before that you would have to do something like:
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ $type := .Type }}
|
||||
@@ -137,35 +149,6 @@ Taxonomies can be ordered by either alphabetical key or by the number of content
|
||||
</ul>
|
||||
```
|
||||
|
||||
### Order by Popularity Example
|
||||
|
||||
```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 }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
### Order by Least Popular Example
|
||||
|
||||
```go-html-template
|
||||
<ul>
|
||||
{{ $type := .Type }}
|
||||
{{ range $key, $value := .Data.Terms.ByCount.Reverse }}
|
||||
{{ $name := .Name }}
|
||||
{{ $count := .Count }}
|
||||
{{ with $.Site.GetPage (printf "/%s/%s" $type $name) }}
|
||||
<li><a href="{{ .Permalink }}">{{ $name }}</a> {{ $count }}</li>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
|
||||
<!-- [See Also Taxonomy Lists](/templates/list/) -->
|
||||
|
||||
@@ -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 }}
|
||||
|
||||
Reference in New Issue
Block a user