Taxonomies

What is a taxonomy?

Hugo includes support for user-defined groupings of content called taxonomies. Taxonomies are classifications of logical relationships between content.

Definitions

Taxonomy : A categorization that can be used to classify content

Term : A key within the taxonomy

Value : A piece of content assigned to a term

Example taxonomy: movie website

Let's assume you are making a website about movies. You may want to include the following taxonomies:

• Actors
• Directors
• Studios
• Genre
• Year
• Awards

Then, in each of the movies, you would specify terms for each of these taxonomies (i.e., in the front matter of each of your movie content files). From these terms, Hugo would automatically create pages for each Actor, Director, Studio, Genre, Year, and Award, with each listing all of the Movies that matched that specific Actor, Director, Studio, Genre, Year, and Award.

Movie taxonomy organization

To continue with the example of a movie site, the following demonstrates content relationships from the perspective of the taxonomy:

Actor                    <- Taxonomy
    Bruce Willis         <- Term
        The Sixth Sense  <- Value
        Unbreakable      <- Value
        Moonrise Kingdom <- Value
    Samuel L. Jackson    <- Term
        Unbreakable      <- Value
        The Avengers     <- Value
        xXx              <- Value

From the perspective of the content, the relationships would appear differently, although the data and labels used are the same:

Unbreakable                 <- Value
    Actors                  <- Taxonomy
        Bruce Willis        <- Term
        Samuel L. Jackson   <- Term
    Director                <- Taxonomy
        M. Night Shyamalan  <- Term
    ...
Moonrise Kingdom            <- Value
    Actors                  <- Taxonomy
        Bruce Willis        <- Term
        Bill Murray         <- Term
    Director                <- Taxonomy
        Wes Anderson        <- Term
    ...

Default destinations

When taxonomies are used Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a categories taxonomy declared in your configuration and used in your content front matter will create the following pages:

• A single page at example.com/categories/ that lists all the terms within the taxonomy
• Individual taxonomy list pages (e.g., /categories/development/) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's front matter

Configuration

See configure taxonomies.

Assign terms to content

To assign one or more terms to a page, create a front matter field using the plural name of the taxonomy, then add terms to the corresponding array. For example:

{{< code-toggle file=content/example.md fm=true >}} title = 'Example' tags = ['Tag A','Tag B'] categories = ['Category A','Category B'] {{< /code-toggle >}}

Taxonomic weight

{{% glossary-term "taxonomic weight" %}}

Assign a taxonomic weight using a front matter key named [taxonomy_name]_weight.

{{< code-toggle file="content/courses/organic-chemistry.md" fm=true >}} title = 'Organic Chemistry' weight = 10 tags_weight = 1000 tags = ['chemistry','science'] {{</ code-toggle >}}

With the front matter above, the "Organic Chemistry" page will float towards the top of the list on section and home pages, and it will sink towards the bottom of the list on the "chemistry" and "science" term pages.

Metadata

Display metadata about each term by creating a corresponding branch bundle in the content directory.

For example, create an "authors" taxonomy:

{{< code-toggle file=hugo >}} [taxonomies] author = 'authors' {{< /code-toggle >}}

Then create content with one branch bundle for each term:

content/
└── authors/
    ├── jsmith/
    │   ├── _index.md
    │   └── portrait.jpg
    └── rjones/
        ├── _index.md
        └── portrait.jpg

Then add front matter to each term page:

{{< code-toggle file=content/authors/jsmith/_index.md fm=true >}} title = 'John Smith' affiliation = 'University of Chicago' {{< /code-toggle >}}

Then create a taxonomy template specific to the "authors" taxonomy:

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Data.Terms.Alphabetical }}
    <h2><a href="{{ .Page.RelPermalink }}">{{ .Page.LinkTitle }}</a></h2>
    <p>Affiliation: {{ .Page.Params.Affiliation }}</p>
    {{ with .Page.Resources.Get "portrait.jpg" }}
      {{ with .Fill "100x100" }}
        
      {{ end }}
    {{ end }}
  {{ end }}
{{ end }}

In the example above we list each author including their affiliation and portrait.

Or create a term template specific to the "authors" taxonomy:

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  <p>Affiliation: {{ .Params.affiliation }}</p>
  {{ with .Resources.Get "portrait.jpg" }}
    {{ with .Fill "100x100" }}
      
    {{ end }}
  {{ end }}
  {{ .Content }}
  {{ range .Pages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
  {{ end }}
{{ end }}

In the example above we display the author including their affiliation and portrait, then a list of associated content.