hugo/content/en/templates/taxonomy-templates.md
Bjørn Erik Pedersen e509cac533 Squashed 'docs/' changes from 7ef2dbce4..cb18a5183
cb18a5183 Fix broken link
07a0198bf Config: Place Google Analytics tag ID under the services key
4bf0c719f Fix typo
50d8ad1af Fix muiltilingual menu definition instructions
1a32519a9 Fix typos
6f34ca8e0 Explain usage of front matter to target a template
5bd977257 Improve goldmark config docs
447632938 Remove Docker notes from installation instructions
84741d173 Update reference to hugo.work
0338d7c71 Fix menu template
f5d2f5ed4 Fix typos in content/en/functions/fmt
a3a40ff99 Add return type to functions
85ac3e779 Remove outdated feature image
d47d889e4 Fix signatures
7551ba28f Document safe.JSStr function
e77993be0 Document keyVals function
4dba20db3 Update theme
babf91544 Update echoparam
8c8203efa Adjust related functions
4cb1b30fc Fix example
ba95eca64 Improve showcase prose
5d3dcf366 Add Overmind Studios showcase
8d634ac70 Change code blocks from indented to fenced
cfab978e6 Add missing code fences
407dd5c47 Limit related pages for functions to other functions
9fa67d981 Fix .Site.LastChange doc
393aa16d0 netlify: Hugo 0.119.0
f864af97a docs: Even more about images.Process
9d772d5f0 docs: More about images.Process
bc655f869 docs: Regen docshelper
41c3536d1 Merge commit '9aec42c5452b3eb224888c50ba1c3f3b68a447e9'
918ed53f4 Add images.Process filter
573645883 Add $image.Process
a1151b0fd Add images.Opacity filter

git-subtree-dir: docs
git-subtree-split: cb18a5183fc62f301ffde50b8c39f03e4b897aec
2023-10-20 09:42:39 +02:00

11 KiB

title description categories keywords menu weight aliases toc
Taxonomy templates Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates.
templates
taxonomies
metadata
front matter
terms
templates
docs
parent weight
templates 90
90
/taxonomies/displaying/
/templates/terms/
/indexes/displaying/
/taxonomies/templates/
/indexes/ordering/
/templates/taxonomies/
/templates/taxonomy/
true

Hugo includes support for user-defined groupings of content called taxonomies. Taxonomies are classifications that demonstrate logical relationships between content. See Taxonomies under Content Management if you are unfamiliar with how Hugo leverages this powerful feature.

Hugo provides multiple ways to use taxonomies throughout your project templates:

Taxonomy list templates

Taxonomy list page templates are lists and therefore have all the variables and methods available to list pages.

Taxonomy list template lookup order

See Template Lookup.

Taxonomy terms templates

Taxonomy terms templates lookup order

See Template Lookup.

Taxonomy methods

A Taxonomy is a map[string]WeightedPages.

.Get TERM
Returns the WeightedPages for a given term. For example: ; site.Taxonomies.tags.Get "tag-a".
.Count TERM
The number of pieces of content assigned to the given term. For example:
site.Taxonomies.tags.Count "tag-a".
.Alphabetical
Returns an OrderedTaxonomy (slice) ordered by term.
.ByCount
Returns an OrderedTaxonomy (slice) ordered by number of entries.
.Reverse
Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy.

OrderedTaxonomy

Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order.

[]struct {
    Name          string
    WeightedPages WeightedPages
}

Each element of the slice has:

.Term
The Term used.
.WeightedPages
A slice of Weighted Pages.
.Count
The number of pieces of content assigned to this term.
.Page
Returns a page reference for this term.
.Pages
All Pages assigned to this term. All list methods are available to this.

WeightedPages

WeightedPages is simply a slice of WeightedPage.

type WeightedPages []WeightedPage
.Count
The number of pieces of content assigned to this term.
.Page
Returns a page reference for this term.
.Pages
Returns a slice of pages, which then can be ordered using any of the list methods.

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. 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:

<ul>
  {{ range .Pages }}
    <li>
      <a href="{{ .Permalink }}">{{ .Title }}</a>
      {{ .Params.wikipedia }}
    </li>
  {{ end }}
</ul>

Order taxonomies

Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key.

Order alphabetically example

<ul>
  {{ range .Data.Terms.Alphabetical }}
    <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
  {{ end }}
</ul>

Order content within taxonomies

Hugo uses both date and weight to order content within taxonomies.

Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to.

When iterating over content within taxonomies, the default sort is the same as that used for section and list pages: first by weight, then by date. This means that if the weights for two pieces of content are the same, then the more recent content will be displayed first.

The default weight for any piece of content is 0. Zero means "does not have a weight", not "has a weight of numerical value zero".

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

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 categories = ["d"] title = "Example" categories_weight = 44 {{< /code-toggle >}}

The convention is taxonomyname_weight.

In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy.

It has also been assigned the weight of 44 when rendering the 'd' category.

With this the same piece of content can appear in different positions in different taxonomies.

Currently taxonomies only support the default ordering of content which is weight -> date.

There are two different templates that the use of taxonomies will require you to provide.

Both templates are covered in detail in the templates section.

A list template is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages.

A taxonomy template is a template used to generate the list of terms for a given template.

There are four common ways you can display the data in your taxonomies in addition to the automatic taxonomy pages created by hugo using the list templates:

  1. For a given piece of content, you can list the terms attached
  2. For a given piece of content, you can list other content with the same term
  3. You can list all terms for a taxonomy
  4. You can list all taxonomies (with their terms)

List terms assigned to a page

List the terms assigned to a page using the .Page.GetTerms method.

To render an unordered list:

{{ $taxonomy := "tags" }}
{{ with .GetTerms $taxonomy }}
  <p>{{ (site.GetPage $taxonomy).LinkTitle }}:</p>
  <ul>
    {{ range . }}
      <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
    {{ end }}
  </ul>
{{ end }}

To render a comma-delimited list:

{{ $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

<ul>
  {{ range .Site.Taxonomies.series.golang }}
    <li><a href="{{ .Page.RelPermalink }}">{{ .Page.Title }}</a></li>
  {{ end }}
</ul>

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.

<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>
    {{ end }}
  </ul>
</section>

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 available on every page.

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

<ul>
  {{ range .Site.Taxonomies.tags }}
    <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> {{ .Count }}</li>
  {{ end }}
</ul>

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" >}}

    {{ range $taxonomy, $terms := site.Taxonomies }}
  • {{ with site.GetPage $taxonomy }} {{ .LinkTitle }} {{ end }}
      {{ range $term, $weightedPages := $terms }}
    • {{ .Page.LinkTitle }}
        {{ range $weightedPages }}
      • {{ .LinkTitle }}
      • {{ end }}
    • {{ end }}
  • {{ end }}
{{< /code >}}

.Site.GetPage for taxonomies

Because taxonomies are lists, the .GetPage function 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:

{{< code file="links-to-all-tags.html" >}} {{ $taxo := "tags" }}

    {{ with ($.Site.GetPage (printf "/%s" $taxo)) }} {{ range .Pages }}
  • {{ .Title }}
  • {{ end }} {{ end }}
{{< /code >}}