Adding a Custom Taxonomy in Hugo to Group Content by Series

Desired outcome

Create a custom taxonomy called "series" so that pages sharing the same series value are automatically grouped and accessible via URLs like /series/my‑series/.

Prerequisites

• Hugo installed (version 0.120 or newer recommended).
• An existing Hugo site initialized with hugo new site mysite.
• Basic familiarity with editing TOML/YAML/JSON configuration and Markdown front matter.

Procedure

1. Define the taxonomy in the site configuration

   Open the site’s config file (hugo.toml, hugo.yaml or hugo.json) and add a taxonomies section. Example for TOML:

   [taxonomies]
     series = "series"
   

   If you use YAML, the equivalent is:

   taxonomies:
     series: series
   

   Save the file.

2. Add the taxonomy term to content front matter

   For each Markdown content file that should belong to a series, include a front‑matter key matching the taxonomy name (case‑sensitive). Example:

   ---
   title: "Building a Blog"
   date: 2026-09-01
   series: ["Hugo Tutorials"]
   ---
   # Content here
   

   You can assign multiple series values by providing an array.

3. (Optional) Create custom templates

   Hugo provides default templates for taxonomies at layouts/_default/taxonomy.html (list of terms) and layouts/_default/term.html (pages for a single term). If you need custom markup, copy these files from Hugo’s internal templates or create them in your project.

   Example minimal layouts/_default/term.html:

   {{ define "main" }}
   Series: {{ .Page.Title }}
   
     {{ range .Pages }}
       
   {{ .Title }}
     {{ end }}
   
   {{ end }}
   

4. Build and preview the site

   Run the development server from the site root:

   hugo server

   The server watches for changes; no special permissions are required beyond read/write access to the project directory.

5. Verify the generated taxonomy pages

   After the build completes, check the following:

   • Navigate to http://localhost:1313/series/ to see a list of all series terms.
   • Click a term (e.g., "Hugo Tutorials") to land on http://localhost:1313/series/hugo-tutorials/ and confirm that it lists all pages with that series value.
   • Inspect the public/ directory: you should find public/series/index.html and a subfolder public/series/hugo-tutorials/index.html (or similar, depending on URLization).

Expected checks

• The taxonomy list page renders without errors and shows term links.
• Each term page shows the correct set of content pages.
• Links from individual posts to their series term page work and lead to the term listing.

Recovery options

If the taxonomy does not appear as expected:

1. Verify that the front‑matter key exactly matches the taxonomy name defined in the config (case‑sensitive).
2. Check the config for typos; restart hugo server after any change.
3. Remove the generated public/ folder and rebuild with hugo --minify to ensure stale files are not interfering.
4. To revert, delete the taxonomy entry from the config and remove the corresponding front‑matter keys; then rebuild.

Limitations

• Each unique term creates a separate page; on very large sites with many distinct terms this can increase build time.
• Changing the taxonomy name in the config requires updating every content file that uses it; otherwise orphaned terms will be generated.
• Taxonomy terms are URLized automatically (lowercased, spaces to hyphens); ensure links in your content reflect this format if you hard‑code them.