Hugo Taxonomies and Custom Front Matter Integration

Direct Answer

Hugo lowercases taxonomy terms by default during aggregation, so Foo and foo map to the same term. There is no configuration flag to enforce case-insensitivity; the behavior is built into the taxonomy engine and may vary by Hugo version. To guarantee consistent URLs and avoid duplicate archive pages, standardize all front-matter taxonomy values to lowercase before committing content.

Build time scales roughly linearly with the number of content files. On modest hardware, expect approximately 1 second per 1,000 files for taxonomy processing alone. A site with 10,000 files typically adds ~10 seconds to the total build.

Why This Matters

When front-matter arrays contain the same logical term with different casing (e.g., ["Design", "design", "DESIGN"]), Hugo's default lowercasing merges them into a single taxonomy term design. However, if a future Hugo release changes this normalization or if you disable it inadvertently, each casing variant generates its own archive page under /taxonomies/Design/, /taxonomies/design/, and /taxonomies/DESIGN/. This inflates site size, confuses navigation, and breaks canonical URL expectations.

Recommended Configuration

1. Define taxonomies in hugo.toml (or config.yaml):

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

2. Enforce lowercase in front matter — either by author discipline, a pre-commit hook, or a content linter. Example front matter:

   +++
   title = "Post Title"
   topics = ["performance", "scaling", "hugo"]
   +++

3. Verify aggregation after each build:

   hugo --verbose 2>&1 | grep -i taxonomy
   ls public/topics/

   Confirm each term appears once regardless of input casing.

Build-Time Scaling Notes

• Taxonomy term registration is O(N) where N = total term occurrences across all files.
• Each unique term creates one archive template execution. Thousands of unique terms increase template rendering time proportionally.
• Extremely long term names (over 200 characters) or dozens of simultaneous taxonomies can add measurable overhead.
• Mitigation: keep term names short, limit the number of custom taxonomies, and consider disabling taxonomy page generation for rarely used groupings with disableKinds = ["taxonomy", "term"] in config.

One Diagnostic Detail Needed

What Hugo version are you running? The default lowercasing behavior was made explicit in v0.120+; earlier versions relied on Go's map iteration order which could produce inconsistent casing in generated URLs. Run hugo version and share the output if you observe unexpected duplicate archive pages despite lowercase front matter.