hugo/docs/content/en/variables/taxonomy.md
2023-05-22 16:47:07 +02:00

3.8 KiB

title description categories keywords menu toc weight
Taxonomy Variables Hugo's taxonomy system exposes variables to taxonomy and term templates.
variables and params
taxonomy
term
docs
parent weight
variables 30
true 30

Taxonomy templates

Pages rendered by taxonomy templates have .Kind set to taxonomy and .Type set to the taxonomy name.

In taxonomy templates you may access .Site, .Page. .Section, and .File variables, as well as the following taxonomy variables:

.Data.Singular
The singular name of the taxonomy (e.g., tags => tag).
.Data.Plural
The plural name of the taxonomy (e.g., tags => tags).
.Data.Pages
The collection of term pages related to this taxonomy. Aliased by .Pages.
.Data.Terms
A map of terms and weighted pages related to this taxonomy.
.Data.Terms.Alphabetical
A map of terms and weighted pages related to this taxonomy, sorted alphabetically in ascending order. Reverse the sort order with.Data.Terms.Alphabetical.Reverse.
.Data.Terms.ByCount
A map of terms and weighted pages related to this taxonomy, sorted by count in ascending order. Reverse the sort order with.Data.Terms.ByCount.Reverse.

Term templates

Pages rendered by term templates have .Kind set to term and .Type set to the taxonomy name.

In term templates you may access .Site, .Page. .Section, and .File variables, as well as the following term variables:

.Data.Singular
The singular name of the taxonomy (e.g., tags => tag).
.Data.Plural
The plural name of the taxonomy (e.g., tags => tags).
.Data.Pages
The collection of content pages related to this taxonomy. Aliased by .Pages.
.Data.Term
The term itself (e.g., tag-one).

Access taxonomy data from any template

Access the entire taxonomy data structure from any template with site.Taxonomies. This returns a map of taxonomies, terms, and a collection of weighted content pages related to each term. For example:

{
  "categories": {
    "news": [
      {
        "Weight": 0,
        "Page": {
          "Title": "Post 1",
          "Date": "2022-12-18T15:13:35-08:00"
          ...
          }
      },
      {
        "Weight": 0,
        "Page": {
          "Title": "Post 2",
          "Date": "2022-12-18T15:13:46-08:00",
          ...
        }
      }
    ]
  },
  "tags": {
    "international": [
      {
        "Weight": 0,
        "Page": {
          "Title": "Post 1",
          "Date": "2021-01-01T00:00:00Z"
          ... 
        }
      }
    ]
  }
}

Access a subset of the taxonomy data structure by chaining one or more identifiers, or by using the index function with one or more keys. For example, to access the collection of weighted content pages related to the news category, use either of the following:

{{ $pages := site.Taxonomies.categories.news }}
{{ $pages := index site.Taxonomies "categories" "news" }}

For example, to render the entire taxonomy data structure as a nested unordered list:

<ul>
  {{ range $taxonomy, $terms := site.Taxonomies }}
    <li>
      {{ with site.GetPage $taxonomy }}
        <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
      {{ end }}
      <ul>
        {{ range $term, $weightedPages := $terms }}
        <li>
          {{ with site.GetPage (path.Join $taxonomy $term) }}
            <a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
          {{ end }}
        </li>
          <ul>
            {{ range $weightedPages }}
              <li>
                <a href="{{ .RelPermalink }}"> {{ .LinkTitle }}</a>
              </li>
            {{ end }}
          </ul>
        {{ end }}
      </ul>
    </li>
  {{ end }}
</ul>

See Taxonomy Templates for more examples.