markusgraf_ch/docs/TAXONOMIES.md

Hugo Taxonomies Guide

Current Status

Taxonomies (categories and tags) are currently disabled in this Hugo site to keep it minimal.

What Are Taxonomies?

Hugo taxonomies are classification systems for your content:

• Categories - Broad groupings (e.g., "Technology", "Personal", "Projects")
• Tags - Specific keywords (e.g., "golang", "web-development", "tutorial")

They're useful for blogs and content-heavy sites where visitors need to filter and find related content.

Why Are They Disabled?

For a minimal personal website without a blog, taxonomies add unnecessary complexity:

• Creates extra pages (/categories/, /tags/) that aren't used
• Requires additional template files
• Generates warning messages during builds

How to Re-enable Taxonomies

When you're ready to add a blog or need content categorization:

Step 1: Enable Taxonomies in Configuration

Edit hugo.toml and remove or comment out this line:

# Remove this line:
disableKinds = ['taxonomy', 'term']

Or comment it out to keep for reference:

# Taxonomies disabled for minimal site - uncomment to enable:
# disableKinds = ['taxonomy', 'term']

Step 2: Create Taxonomy Templates

Create two template files in layouts/_default/:

layouts/_default/taxonomy.html

This template displays all content items for a single category or tag.

{{ define "main" }}
<div class="container">
  <div class="row">
    <div class="col-lg-8 offset-lg-2">
      <header class="mt-5 mb-4">
        <h1 class="display-4">{{ .Title }}</h1>
        <p class="lead text-muted">{{ .Data.Plural }}: {{ len .Pages }} {{ if eq (len .Pages) 1 }}item{{ else }}items{{ end }}</p>
      </header>

      <div class="list-group">
        {{ range .Pages }}
        <a href="{{ .RelPermalink }}" class="list-group-item list-group-item-action">
          <div class="d-flex w-100 justify-content-between">
            <h5 class="mb-1">{{ .Title }}</h5>
            <small class="text-muted">{{ .Date.Format "Jan 2, 2006" }}</small>
          </div>
          {{ if .Description }}
          <p class="mb-1">{{ .Description }}</p>
          {{ end }}
        </a>
        {{ end }}
      </div>
    </div>
  </div>
</div>
{{ end }}

layouts/_default/terms.html

This template lists all available categories or all available tags.

{{ define "main" }}
<div class="container">
  <div class="row">
    <div class="col-lg-8 offset-lg-2">
      <header class="mt-5 mb-4">
        <h1 class="display-4">{{ .Title }}</h1>
        <p class="lead text-muted">Browse all {{ .Data.Plural | lower }}</p>
      </header>

      <div class="row">
        {{ range .Pages }}
        <div class="col-md-6 mb-3">
          <div class="card">
            <div class="card-body">
              <h5 class="card-title">
                <a href="{{ .RelPermalink }}">{{ .Title }}</a>
              </h5>
              <p class="card-text text-muted">{{ len .Pages }} {{ if eq (len .Pages) 1 }}post{{ else }}posts{{ end }}</p>
            </div>
          </div>
        </div>
        {{ end }}
      </div>
    </div>
  </div>
</div>
{{ end }}

Step 3: Add Taxonomies to Content

Add categories and tags to your content front matter:

---
title: "My Blog Post"
date: 2024-10-27
categories:
  - Technology
  - Web Development
tags:
  - hugo
  - golang
  - static-sites
---

Your content here...

Step 4: Optional - Configure Menu Links

Add taxonomy pages to your navigation in hugo.toml:

[menu]
  [[menu.main]]
    name = "Categories"
    url = "/categories/"
    weight = 10
  [[menu.main]]
    name = "Tags"
    url = "/tags/"
    weight = 20

Step 5: Optional - Customize Taxonomy Names

If you want different taxonomy names (e.g., "Topics" instead of "Categories"):

[taxonomies]
  topic = "topics"
  tag = "tags"

Then use in front matter:

---
topics:
  - Web Development
tags:
  - hugo
---

Testing After Re-enabling

After re-enabling and creating templates:

# Build the site
hugo

# Start the server
hugo server -D

# Visit in browser:
# http://localhost:1313/categories/
# http://localhost:1313/tags/
# http://localhost:1313/categories/technology/
# http://localhost:1313/tags/hugo/

You should see:

• No warnings in build output
• Category and tag listing pages
• Individual category/tag pages showing filtered content

Custom Taxonomies

Hugo supports custom taxonomies beyond categories and tags:

[taxonomies]
  category = "categories"
  tag = "tags"
  series = "series"        # For blog post series
  author = "authors"       # For multi-author blogs
  project = "projects"     # For portfolio sites

Use in content:

---
series: ["Getting Started with Hugo"]
authors: ["Markus Graf"]
projects: ["Personal Website"]
---

References

• Hugo Taxonomies Documentation
• Hugo Template Lookup Order
• Bootstrap Components used: Cards, List Groups (see Bootstrap Docs)

See Also

• IMPLEMENTATION_SUMMARY.md - Overview of the Hugo site structure
• hugo.toml - Main configuration file
• layouts/_default/ - Template directory