Hugo Taxonomy Tags

Hugo Taxonomy Templates

The main templates involved are the terms.html and taxonomy.html templates. terms.html is basically like a list.html template, but shows only the available terms. The .Site.Taxonomies.tags variable provides access to the Taxonomy object, which according to the documentation is a map[string]WeightedPages. WeightedPages itself is a slice of pages.

One detail of .Site.Taxonomies.tags is that the keys are (understandably) in lower case. I however wanted certain tags to NOT be in lower case and additionally not be in Title case either (i.e. CSS or HTML). Those tags are obviously in upper case only.

Thankfully because .Site.Taxonomies.tags also contains the actual pages for each tag, it is possible to iterate them and access the .Page.Params.tags variable, which contains the list of all tags for each page in their original form (as specified in the front matter).

That means it is possible to build the list of tags from the pages in the template! Here is the code I currently use to do that in my terms.html.

<!-- Get the main taxonomy dict -->
{{- $all_tags := .Site.Taxonomies.tags -}}
<!-- define a slice to hold our subset of tags -->
{{- $tags := slice -}}
<!-- iterate all our keys / values from the dict.. -->
{{- range $key, $value := $all_tags -}}

  <!-- iterate all the pages in the dict.. -->
  {{- range $value -}}
    {{- with .Params.tags -}}
      {{- range . -}}
        <!-- if the tag is not already in our list, add it.. -->
        {{- if not ( in $tags . ) -}}
          {{- $tags = $tags | append . -}}
        {{- end -}}
      {{- end -}}
    {{- end -}}
  {{- end -}}
{{- end -}}

After the above code block $tags contains a list of tags as defined in the front matter. That way we do NOT have to worry about capitalizing them correctly, except in the front matter data.

This of course assumes you have the tags defined in your front matter.

tags = ["Sample", "Tags"]

Page Count For A Tag

To get the count of pages in a tag I currently use a template like the following.

{{ range sort $tags }}
    <section class="js-section listing">
      <!-- . cotains the tag in the correct case already.. -->
      <!-- we anchorize it for use in anchor tags -->
      <h3 class="section__title" id="{{ anchorize . }}">{{ . }}</h3>
      <p>
      <!-- we use index to lookup the page list from the dict -->
      <!-- it's important to note the keys are in lower case -->
      {{ if gt (len (index $all_tags (lower .))) 1 }}
      There are {{ len (index $all_tags (lower .)) }} posts tagged with <i>{{ lower . }}</i>.
      {{ else }}
      There is {{ len (index $all_tags (lower .)) }} post tagged with <i>{{ lower . }}</i>.
      {{ end }}
      </p>
      <a href="/tags/{{ anchorize . }}" class="link link--light">All {{ . }} Posts</a>
    </section>
{{ end }}

It is a little strange, but now at least I do not have to worry about converting the tags to the proper case for display. I instead have to worry about converting the tags to lower case when doing something with them, which is an easier problem to solve IMO.

This is what is displayed on my site under the /tags/ section.

Pages For A Tag

The taxonomy.html template is essentially just a list.html template. The pages for a tag are available in the .Pages variable. For my current theme the only difference between the templates is that I skip showing the list of tags, since all the posts are already for a single tag.

The .Params.tags variable is available on any .Page so you can iterate it the same as the above example regardless of if you are in a list.html template, or a single.html template. That is what I currently do to show the list of tags for a specific post, or all tags on the list page.

Hopefully this gives you some examples to make use of tags in your own hugo site.

Enjoy!