Manage HUGO Taxonomies Like a Boss


Live view:

Quelle: Manage HUGO taxonomies like a boss von guayom

Taxonomien sind eine der nützlichsten Funktionen in Hugo. Hier folgt eine sehr detaillierte Erklärung zur Verwendung von Taxonomien in einer Hugo-Site. Kein hackish Code oder komplizierte Tricks. Es gibt eine Dokumentation zu diesem Thema, aber man muss an 3 verschiedenen Stellen suchen und einige Beispiele fehlen. So kann es manchmal sehr verwirrend sein, zumindest für mich war es so.

Mit den folgenden Erklärungen sollte es möglich sein:

  • eigene Taxonomien zu erstellen,
  • benutzerdefinierte Metadaten zu den Taxonomien hinzuzufügen,
  • eine Listenvorlage für Taxonomiebegriffe mit allen benutzerdefinierten Metadaten zu erstellen, die der Taxonomie hinzugefügt werden,
  • Begriffe ohne eine entsprechende Datei zu behandeln und Standardwerte in den Vorlagen zu definieren,
  • eine Vorlage für Begriffe mit allen dazugehörigen Daten zu erstellen,
  • die Erstellung von Begriffsseiten mit Hilfe von Archetypen zu beschleunigen.

Eigene Taxonomien erstellen

in config.toml

  mood = "moods"

Und dann werden sie auf einer Mood-Seite aufgelistet:

title: "Mood - Wetter"
description: "Hier wird beschrieben, wie das Wetter die Stimmung beeinflusst "
tags: [happiness]
categories: [Stimmung]
moods: [happy]
date:  2019-08-12T09:25:03+02:00
draft: false

Add custom metadata to your taxonomies

Let’s say you want to add a logo, website link and description for each brand. You need to place that information in your taxonomy terms pages. For example: /content/brands/adidas/

Attention Note that the structure is important. <taxonomy>/<term>/

title: "Adidas"
description: "This is the description for Adidas"
website: ""
logo: "/images/adidas.png"

Create an index template for taxonomy terms using all the custom metadata you added to the taxonomy (terms.html)

Now to create an index for your taxonomies, and display all the custom metadata you added for each term, you need to edit your terms template. You can add it here: /layouts/_default/terms.html

Range dynamically through all the term pages with .Data.Pages

  {{ range .Data.Pages }}
      <a href="{{ .Permalink }}">{{ .Title }}</a>
        <dt>Link to the brand page</dt><dd><a href="{{ .Permalink }}">{{ .Permalink }}</a></dd>

        <!-- Handling brands that don't have a corresponding page by using 'with' -->
        {{ with }}
          <dt>Website</dt><dd>{{ . }}</dd>
        {{ end }}
        {{ with .Params.description }}
          <dt>Description</dt><dd>{{ . }}</dd>
        {{ end }}

        Handling brands that don't have a corresponding page by using an 'if' statement.
        This let's you add default values to your template.
        {{ if ne .Params.logo nil }}
          <img src="{{ .Params.logo }}" height="90" />
        {{ else }}
          <img src="" height="90" />
        {{ end }}
  {{ end }}

Handle terms without a corresponding file and define default values in your templates

You might create some terms for which you haven’t created a corresponding page (/content/brands/terms/

As an example, I added a product called New Balance Shoe. It’s brand is “New Balance”. But if you search in my content/brands folder, you won’t find a /new-balance/ file. I haven’t created it.

In that case you will have to add some default parameters here. Take a look at the comments in the snippets above to find a couple ways to handle terms without a corresponding page.

Now, you can edit the template for each term page. For example, the page for the brand “Nike” would be: /brands/nike. Edit this template at: /layouts/_default/taxonomy.html

You can list all the pages that are labeled with the current term via .Data.Pages, as you can see on the example below. Just as we did before, we can handle the terms that don’t have a corresponding page by using with or if statements.

{{ with .Params.description }}
{{ end }}

  {{ range .Data.Pages }}
       <a href="{{ .Permalink}}">{{ .Title }}</a>
  {{ end }}

Speed up the creation of terms pages by using archetypes

Having to create a <taxonomy>/<term>/ file for each term, can be a real hassle. But you can save a lot of time by taking advantage of Archetypes. This is a HUGE TIME SAVER. With the setup I’ll show you, whenever you want to create a new taxonomy term (brand), all you have to do is type hugo new <taxonomy>/<term>/ on your terminal and your brand page will be created and even filled with the correct title.

Just create a new archetype for your taxonomy. archetypes/<taxonomy>.md. In my case, archetypes/

title: {{ $term := index ( split .File.Dir "/") 1 }}"{{ replace $term "-" " " | title }}"
description: "This is the description for {{ $term | title }}"
website: "http://{{ $term }}.com"
logo: "/images/{{  $term }}.jpg"
date: {{ .Date }}
draft: false

Note that I defined the variable $term in the first line. It takes the variable .File.Dir, splits it into an array, indexes it and grabs the second value. This value will serve as your title, and you can use it to dynamically create default values based on your file name. That way, when you create pages by the CLI, all you have to do is name them correctly, and all your data will be filled with the correct title.

Try it out: On your terminal type: hugo new brands/test/

It will use whatever value you use in the place of test as your title. This is what it would render:

title: "Test"
description: "This is the description for Test"
website: ""
logo: "/images/test.jpg"
date: 2017-08-07T12:04:03-06:00
draft: false

Important: If your term contains special characters, for example “Ügly brand”, when you type the command on your terminal, you have to remove the special characters and replace spaces with “-” (ugly-brand). Then on your the spaces will be taken care of, but you will have to add any special character you replaced.

That’s it

Now you can use taxonomies like a boss. Please if stumble into any problems by using this method, don’t hesitate to contact me via the forum, or adding an issue on this repo.