hugo/content/templates/taxonomy-templates.md at ec4e6f9df2ab9ffdc62a3f59675369096e0d3f77

mirror of https://github.com/gohugoio/hugo.git synced 2024-11-14 20:37:55 -05:00

Bjørn Erik Pedersen ec4e6f9df2 Squashed 'docs/' content from commit f887bd7b

git-subtree-dir: docs
git-subtree-split: f887bd7b4e3e7c7e76cd63951e5b0d37d8fe0ac7

2017-08-10 17:18:22 +02:00

12 KiB

Raw Blame History

title

description

date

publishdate

lastmod

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

A taxonomy will be rendered at /PLURAL/TERM/ (e.g., http://spf13.com/topics/golang/) according to the following lookup order:

/layouts/taxonomy/<SINGULAR>.html
/layouts/_default/taxonomy.html
/layouts/_default/list.html
/themes/<THEME>/layouts/taxonomy/<SINGULAR>.html
/themes/<THEME>/layouts/_default/taxonomy.html
/themes/<THEME>/layouts/_default/list.html

Taxonomy Terms Template

Taxonomy Terms Templates Lookup Order

A taxonomy terms page will be rendered at example.com/<PLURALTAXONOMYNAME>/ (e.g., http://spf13.com/topics/) according to the following lookup order:

/layouts/taxonomy/<SINGULAR>.terms.html
/layouts/_default/terms.html
/themes/<THEME>/layouts/taxonomy/<SINGULAR>.terms.html
/themes/<THEME>/layouts/_default/terms.html

{{% warning "The Taxonomy Terms Template has a Unique Lookup Order" %}} If Hugo does not find a terms template in layout/ or /themes/<THEME>/layouts/, Hugo will not render a taxonomy terms page. {{% /warning %}}

Hugo makes a set of values and methods available on the various Taxonomy structures.

Taxonomy Methods

A Taxonomy is a map[string]WeightedPages.

.Get(term): Returns the WeightedPages for a term.
.Count(term): The number of pieces of content assigned to this term.
.Alphabetical: Returns an OrderedTaxonomy (slice) ordered by Term.
.ByCount: Returns an OrderedTaxonomy (slice) ordered by number of entries.

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.
.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(term): The number of pieces of content assigned to 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 it's 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 .Data.Pages as such:

<ul>
  {{ range .Data.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>
  {{ $data := .Data }}
  {{ range $key, $value := .Data.Taxonomy.Alphabetical }}
  <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.Count }} </li>
  {{ end }}
</ul>

Order by Popularity Example

<ul>
  {{ $data := .Data }}
  {{ range $key, $value := .Data.Taxonomy.ByCount }}
  <li><a href="{{ $.Site.LanguagePrefix }}/{{ $data.Plural }}/{{ $value.Name | urlize }}"> {{ $value.Name }} </a> {{ $value.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, than the more recent content will be displayed first. The default weight for any piece of content is 0.

Assign Weight

Content can be assigned weight for each taxonomy that it's assigned to.

+++
tags = [ "a", "b", "c" ]
tags_weight = 22
categories = ["d"]
title = "foo"
categories_weight = 44
+++
Front Matter with weighted tags and categories

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

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

Display a Single Piece of Content's Taxonomies

Within your content templates, you may wish to display the taxonomies that piece of content is assigned to.

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

<ul id="tags">
  {{ range .Params.tags }}
    <li><a href="{{ "/tags/" | relLangURL }}{{ . | urlize }}">{{ . }}</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

{{ if .Params.directors }}
  <strong>Director{{ if gt (len .Params.directors) 1 }}s{{ end }}:</strong>
  {{ range $index, $director := .Params.directors }}{{ if gt $index 0 }}, {{ end }}<a href="{{ "directors/" | relURL }}{{ . | urlize }}">{{ . }}</a>{{ end }}
{{ end }}

Alternatively, you may use the delimit template function as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion.

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.

Example: Grouping "Featured" 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 id="all-tags">
  {{ range $name, $taxonomy := .Site.Taxonomies.tags }}
    <li><a href="{{ "/tags/" | relLangURL }}{{ $name | urlize }}">{{ $name }}</a></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" download="all-taxonomies.html" download="all-taxonomies.html" >}}

{{ $taxonomyname }}
- {{ $key }}

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

{{ .Title}}

12 KiB Raw Blame History