How I Added a Tag Page to My Hugo Site

Recently, I decided to add a dedicated tag page to my Hugo-powered blog. This guide outlines each step I took.

1. Creating terms.html in layouts/taxonomy

First, I wanted a template to list all tags with their counts. I created a file at layouts/taxonomy/terms.html and added the following code:

{{ define "main" }}
<main>
  <ul>
    {{ range .Data.Terms }}
      <li>
          {{ $key := .Page.Title | replaceRE "[- ]" "_" }}
          <a href="{{ .Page.Permalink }}">{{ i18n $key | default .Page.Title }}</a> ({{ .Count }})
      </li>
    {{ end }}
  </ul>
</main>
{{ end }}

• This template uses Hugo’s templating language to loop through all tags. Each tag gets its name (optionally internationalized), permalink, and usage count displayed.

Tip: Make sure you have a baseof.html layout file so “main” can be properly filled into your site’s structure.

2. Adding the Tag Page to the Menu (hugo.toml)

To make the tag page easy to find, I added a menu item to my site’s configuration (hugo.toml):

text[[menu.main]]
name = "Tags"
url = "/tags/"
weight = 8

• Adjust weight to control the item’s order in your navigation.

3. Ensuring tags Is a Defined Taxonomy

To ensure the tags page generates correctly, Hugo must treat tags as a taxonomy. In your hugo.toml, you should define taxonomies like this:

[taxonomies]
  tag = "tags"
  category = "categories"

If you use the default Hugo configuration, tags are set up for you, but it’s good to check, especially if you’ve customized taxonomies.

4. Adding Tags to Your Content Front Matter

Double-check that your posts include tags in their front matter:

in TOML Example:

tags = ["Hugo", "Static Site", "Tutorial"]

Without this, Hugo won’t generate the tag listings.

5. (Optional) Customizing Individual Tag Pages

If you want each tag (e.g., /tags/hugo/) to have a custom appearance, create or edit layouts/taxonomy/tag.html or layouts/_default/terms.html for finer control. This step is optional, but recommended for consistent branding.

6. (Optional) Testing & Rebuilding

After making changes, run hugo server to preview your site locally. Visit /tags/ to ensure everything renders correctly and menu items appear.

That’s it. With these steps, you get a working, navigable tag page that enhances discoverability on your Hugo site. If you skipped defining the taxonomy or forgot to add tags to your posts, the tag page might not appear or might be empty, so be sure to include those steps as needed.