mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-09-01 22:42:45 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '87de22d7464e239c775fbd48ebce1665d5b1e80d'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2023-07-29 11:17:28 +02:00
parent bec9b80d95 87de22d746
commit 8859be1c01
177 changed files with 1623 additions and 1556 deletions
Download Patch File Download Diff File Expand all files Collapse all files

192
docs/content/en/templates/taxonomy-templates.md
View File

@@ -1,13 +1,13 @@
---
title: Taxonomy Templates
title: Taxonomy templates
description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates.
categories: [templates]
keywords: [taxonomies,metadata,front matter,terms,templates]
menu:
docs:
parent: templates
weight: 50
weight: 50
weight: 90
weight: 90
aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/]
toc: true
---
@@ -23,21 +23,21 @@ Hugo provides multiple ways to use taxonomies throughout your project templates:
* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-templates)
* List a single content's taxonomy terms within a [single page template]
## Taxonomy List Templates
## Taxonomy list templates
Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists].
### Taxonomy List Template Lookup Order
### Taxonomy list template lookup order
See [Template Lookup](/templates/lookup-order/).
## Taxonomy Terms Templates
## Taxonomy terms templates
### Taxonomy Terms Templates Lookup Order
### Taxonomy terms templates lookup order
See [Template Lookup](/templates/lookup-order/).
### Taxonomy Methods
### Taxonomy methods
A Taxonomy is a `map[string]WeightedPages`.
@@ -95,40 +95,40 @@ type WeightedPages []WeightedPage
.Pages
: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists].
## Displaying custom metadata in Taxonomy Terms Templates
## Displaying custom metadata in taxonomy terms templates
If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in its front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-metadata-to-a-taxonomy-or-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Pages` as such:
```go-html-template
<ul>
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
{{ .Params.wikipedia }}
</li>
{{ end }}
{{ range .Pages }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
{{ .Params.wikipedia }}
</li>
{{ end }}
</ul>
```
<!-- Begin /taxonomies/ordering/ -->
## Order Taxonomies
## Order taxonomies
Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.
### Order Alphabetically Example
### Order alphabetically example
```go-html-template
<ul>
{{ range .Data.Terms.Alphabetical }}
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
{{ end }}
{{ range .Data.Terms.Alphabetical }}
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
{{ end }}
</ul>
```
<!-- [See Also Taxonomy Lists](/templates/list/) -->
## Order Content within Taxonomies
## Order content within taxonomies
Hugo uses both `date` and `weight` to order content within taxonomies.
@@ -140,11 +140,10 @@ The default weight for any piece of content is 0. Zero means "does not have a we
Weights of zero are thus treated specially: if two pages have unequal weights, and one of them is zero, then the zero-weighted page will always appear after the other one, regardless of the other's weight. Zero weights should thus be used with care: for example, if both positive and negative weights are used to extend a sequence in both directions, a zero-weighted page will appear not in the middle of the list, but at the end.
### Assign Weight
### Assign weight
Content can be assigned weight for each taxonomy that it's assigned to.
{{< code-toggle file="content/example.md" fm=true copy=false >}}
tags = [ "a", "b", "c" ]
tags_weight = 22
@@ -186,79 +185,75 @@ using the [list templates](/templates/lists/):
3. You can list all terms for a taxonomy
4. You can list all taxonomies (with their terms)
## Display a Single Piece of Content's Taxonomies
## List terms assigned to a page
Within your content templates, you may wish to display the taxonomies that piece of content is assigned to.
List the terms assigned to a page using the `.Page.GetTerms` method.
Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.<TAXONOMYPLURAL>`).
### Example: List Tags in a Single Page Template
To render an unordered list:
```go-html-template
<ul>
{{ range (.GetTerms "tags") }}
<li><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
{{ $taxonomy := "tags" }}
{{ with .GetTerms $taxonomy }}
<p>{{ (site.GetPage $taxonomy).LinkTitle }}:</p>
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
```
If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter.
To list such taxonomies, use the following:
### Example: Comma-delimit Tags in a Single Page Template
```go-html-template
{{ $taxo := "directors" }} <!-- Use the plural form here -->
{{ with .Param $taxo }}
<strong>Director{{ if gt (len .) 1 }}s{{ end }}:</strong>
{{ range $index, $director := . }}
{{- if gt $index 0 }}, {{ end -}}
{{ with $.Site.GetPage (printf "/%s/%s" $taxo $director) -}}
<a href="{{ .Permalink }}">{{ $director }}</a>
{{- end -}}
{{- end -}}
</ul>
{{ end }}
```
Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion.
To render a comma-delimited list:
## List Content with the Same Taxonomy Term
```go-html-template
{{ $taxonomy := "tags" }}
{{ with .GetTerms $taxonomy }}
<p>
{{ (site.GetPage $taxonomy).LinkTitle }}:
{{ range $k, $_ := . -}}
{{ if $k }}, {{ end }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{- end }}
</p>
{{ end }}
```
## List content with the same taxonomy term
If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content:
### Example: Showing Content in Same Series
### Example: showing content in same series
```go-html-template
<ul>
{{ range .Site.Taxonomies.series.golang }}
<li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
{{ end }}
{{ range .Site.Taxonomies.series.golang }}
<li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
{{ end }}
</ul>
```
## List All content in a Given taxonomy
## List all content in a given taxonomy
This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content.
### Example: Grouping "Featured" Content
### Example: grouping "featured" content
```go-html-template
<section id="menu">
<ul>
{{ range $key, $taxonomy := .Site.Taxonomies.featured }}
<li>{{ $key }}</li>
<ul>
{{ range $taxonomy.Pages }}
<li hugo-nav="{{ .RelPermalink }}"><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
<ul>
{{ range $key, $taxonomy := .Site.Taxonomies.featured }}
<li>{{ $key }}</li>
<ul>
{{ range $taxonomy.Pages }}
<li hugo-nav="{{ .RelPermalink }}"><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
</ul>
{{ end }}
</ul>
</section>
```
## Render a Site's Taxonomies
## Render a site's taxonomies
If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page.
@@ -266,57 +261,56 @@ This may take the form of a tag cloud, a menu, or simply a list.
The following example displays all terms in a site's tags taxonomy:
### Example: List All Site Tags {#example-list-all-site-tags}
### Example: list all site tags
```go-html-template
<ul>
{{ range .Site.Taxonomies.tags }}
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
{{ end }}
{{ range .Site.Taxonomies.tags }}
<li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
{{ end }}
</ul>
```
### Example: List All Taxonomies, Terms, and Assigned Content
### Example: list all taxonomies, terms, and assigned content
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
{{< code file="layouts/partials/all-taxonomies.html" >}}
<section>
<ul id="all-taxonomies">
{{ range $taxonomy_term, $taxonomy := .Site.Taxonomies }}
{{ with $.Site.GetPage (printf "/%s" $taxonomy_term) }}
<li><a href="{{ .Permalink }}">{{ $taxonomy_term }}</a>
<ul>
{{ range $key, $value := $taxonomy }}
<li>{{ $key }}</li>
<ul>
{{ range $value.Pages }}
<li hugo-nav="{{ .RelPermalink }}">
<a href="{{ .Permalink }}">{{ .LinkTitle }}</a>
</li>
{{ end }}
</ul>
{{ end }}
</ul>
</li>
{{ end }}
<ul>
{{ range $taxonomy, $terms := site.Taxonomies }}
<li>
{{ with site.GetPage $taxonomy }}
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
{{ end }}
<ul>
{{ range $term, $weightedPages := $terms }}
<li>
<a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a>
<ul>
{{ range $weightedPages }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
</li>
{{ end }}
</ul>
</section>
</ul>
</li>
{{ end }}
</ul>
{{< /code >}}
## `.Site.GetPage` for Taxonomies
## `.Site.GetPage` for taxonomies
Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the ["List All Site Tags" example above](#example-list-all-site-tags):
{{< code file="links-to-all-tags.html" >}}
{{ $taxo := "tags" }}
<ul class="{{ $taxo }}">
{{ with ($.Site.GetPage (printf "/%s" $taxo)) }}
{{ range .Pages }}
<li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
{{ end }}
{{ with ($.Site.GetPage (printf "/%s" $taxo)) }}
{{ range .Pages }}
<li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
{{ end }}
{{ end }}
</ul>
{{< /code >}}