Introduction
From the beginning of the blog, I wanted to include tags to my posts. This way the content can be categorized and grouped effectively. This feature is built into hugo from the beginning, so it is way easier than you think.
Relationships between your content are defined using taxonomies. A taxonomy example is tags. In actuality, it is one of the two default taxonomies that Hugo automatically supports.
What are tags / taxonomies ?
Hugo’s powerful features, tags and taxonomies, are essential for classifying and arranging the material on your website.
A tag in Hugo is a term or label connected to a certain piece of content. It enables you to give your posts, articles, or other content types descriptive terms. You could, for instance, tag your blog posts with terms like “technology,” “web development,” or “productivity”. This establishes a logical framework that makes it simple for users to identify and explore related information.
On the other hand, taxonomies in Hugo are higher-level organizational structures that encompass tags. Taxonomies enable you to group content into broader categories or topics. For instance, you could create a taxonomy called “Topics” with categories like “Technology,” “Design,” and “Business.” Within each category, you can assign specific tags to further refine the classification.
On the other side, Hugo’s taxonomies are more advanced organizing frameworks that include tags. You can organize content into more general groups or topics using taxonomies. You could, for instance, make a taxonomy named “Topics” that includes sections for “Technology”, “Design” and “Business”.
Why are tags important ?
Hugo offers a number of advantages through the usage of tags and taxonomy. They offer a flexible and scalable approach to manage and arrange the content of your website. You may clearly define linkages between various types of information by categorizing content with pertinent tags. By making it easier for users to easily explore relevant topics, this improves the user experience.
Second, tags and taxonomy help with content optimization and search engine visibility. Through tags, material may be quickly identified and accessed by both search engines and visitors, which may result in better search results and more visitors.
The ability to create dynamic navigation menus, filtered content displays, and tag-based archives is another advantage provided by tags and taxonomies. They let you to display material based on particular tags or taxonomies, giving your audience more specialized experiences.
In conclusion, utilizing the power of tags and taxonomies in Hugo helps to improve website organization, content discoverability, and visitor-tailored experiences.
Technologies & Versions
I am using Hugo version 0.114.0 in this blog post. If you use another version, please take a look in their documentation, as the support for tags can change in the future.
How to use tags in Hugo
Configuration
As the tag’s taxonomy is a default in Hugo there is no need to configure it at all. There are two options that are activated as default in Hugo - tags and categories. As I do not have a use case for the categories right now, I removed the support for it. Now, my hugo.toml has a taxonomies part in it:
#layouts/_default/taxonomy.html
[taxonomies]
tag = 'tags'
If you want to read more about how to create custom taxonomies and more take a look at the documentation
Add tags to a blog post
In my case, all my blog posts make use of the _default/single.html file, as all posts should look the same.
The _default folder is a special one as it is the base of the specific page templates. If you want to read more about this topic, take a look at the hugo documentation.
I included the following part into the single.html file.
<!-- layouts/_default/single.html -->
{{ with .GetTerms "tags" }}
<!-- Removed the class identifier to reduce the load -->
<div class="tags">
<h3>Tags</h3>
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">#{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
</div>
{{ end }}
The with statement of hugo gets the tags from the front matter and sets the current state in the block to the tags list. This way we can simply loop over . which will return us the tag objects.
Now we need to include the tags in the front matter of the post. We can simply add the following into our post:
tags: ["Hugo", "GoLang"]
This is it to handle tags in a post. Now we move onto the other important page templates.
Add a terms page
The terms page is a specific page where we can list all of our terms or tags. There we can sort, filter or simply show all. For my blog, I decided to show all tags with a simple headline and a count on how many tags are there in the blog.
For terms and taxonomy list, there are specific default files which we can use, so every page looks and feels the same. Of course, you can customize everything, but I like it if it displays the same thing it should look the same.
Now we create a html file layouts/_default/terms.html which will be our file to display all tags. In my case, the file looks like this:
<!-- layouts/_default/terms.html -->
{{ define "main"}}
<main class="tags">
<h1>{{ .Title }} ({{ len .Data.Terms }})</h1>
<div>
<ul>
{{ range .Data.Terms.Alphabetical }}
<li>
<a href="{{ .Page.RelPermalink}}">#{{ .Term }} ({{ .Count }})</a>
</li>
{{ end }}
</ul>
</div>
</main>
{{ end }}
In this case we have to loop over the .Data.Terms as this is the place where all tags of the blog are saved. To show the count of all the tags I used the function len. It works as in JS with array.length and so we get back the length. .Count returns the number of posts assigned to that specific term.
Add a taxonomy list page
For the taxonomy list page, it is way easier than you think. This page behaves nearly exact the same as the normal list page, so you can nearly copy the code there. Even though I discourage copying code as it is better to move duplicated code into partials, but of course this is up to you.
The code to include tags into the taxonomy file is the same as we used in the single.html file.
<!-- layouts/_default/taxonomy.html -->
{{ with .GetTerms "tags" }}
<!-- Removed the class identifier to reduce the load -->
<div class="tags">
<h3>Tags</h3>
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">#{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
</div>
{{ end }}
I used this as a partial, so I can include this code in the specific places as needed.
Include the terms page into the navigation
There are multiple ways to include the terms page in the navbar. You can specify the menu in the hugo.toml file and then use this config option in the navbar, or you can simply use the link hard-coded, as it will not change anyway.
We go with the easier way here:
<!-- layouts/partials/navbar.html -->
<a class="navbar-item" href="/tags"> All Tags </a>
You can even go a step further and list your best tags in the navbar if you want to.
Here is an example where we want to show the two most used tags in the navbar.
{{ range first 2 .Data.Terms.ByCount }}
<a href="{{ .Page.RelPermalink}}">#{{ .Term }} ({{ .Count }})</a>
{{ end }}
With first {number} we take the exact amount and just display two links in this case.
Summary
As we saw, the tags/taxonomy feature of hugo is great and works nearly out of the box. Surely there are sometimes some problems if you are not concentrated and forget which variables you can use, e.g. in the terms page we used .Data.Terms but if you are careful and always take a look in the documentation there should be no problems.
Now it is your part to build the taxonomy feature into your hugo blog!