Right, let’s talk about actually using these taxonomies we’ve so carefully set up. You don’t define a category system just to admire its architectural beauty. You need to populate it. And in the world of static sites, that almost always starts in the front matter.

Think of front matter as the classified section of your content. It’s where you, the author, stick all the metadata—the behind-the-scenes info that tells the system what this thing is and how it should behave. Taxonomies are a huge part of that. You’re essentially slapping labels on your work so the automated sorting machine (Hugo) knows which bins to put it in.

The Absolute Basics: Strings and Lists

This is where most people start, and it’s dead simple. For a taxonomy like categories or tags, you can assign values as a single string or, more commonly, a list of strings (YAML arrays). The list approach is almost always better because it’s explicit and avoids accidental whitespace issues.

---
title: "My Excellent Blog Post"
categories: ["Deep Thoughts", "Technical Musings"]
tags:
  - hugo
  - web-dev
  - existential-dread
---

See that? For categories I used the bracket syntax ["a", "b"], and for tags I used the hyphen list syntax. YAML sees them as identical. Use whichever makes your brain happy. I prefer the hyphen list for longer lists because it’s easier to scan and comment out individual items.

Why Lists Are Your Friend

I just told you to use lists, and you should. Here’s the critical reason why: a single string is interpreted as a list with one item. So whether you write categories: "SomeCategory" or categories: ["SomeCategory"], Hugo will treat it the same internally. But if you start with a string and later need to add a second category, you have to remember to change the syntax to a list. If you forget and just write categories: "Cat1", "Cat2", YAML will throw a fit because that’s invalid. Starting with the list syntax future-proofs your front matter and establishes a consistent pattern. It’s a tiny habit that saves you from a surprisingly annoying class of errors.

Dealing with Special Characters and Case-Sensitivity

Here’s where we hit our first bit of absurdity. You want a category called “C# & .NET 5.0”. Go on, try to put that in your front matter.

# This will cause... problems.
categories: ["C# & .NET 5.0"]

The # is a comment character in YAML. The & has its own special meaning. This will not work as you expect. The solution? Quotation marks. You have to wrap the entire term in quotes to tell YAML, “Hey, treat this whole thing as a single string, and ignore any secret codes inside.”

# This is the way.
categories: ["C# & .NET 5.0"]

The same goes for terms with colons, square brackets, or any other character that YAML might find tasty. When in doubt, quote it. Also, note that taxonomies are case-sensitive by default. tags: ["API"] and tags: ["api"] are two different tags. This is a fantastic way to end up with a fragmented, messy tag cloud. Pick a case style (I’m a lowercase evangelist for this very reason) and stick to it religiously.

The Power (and Peril) of Custom Taxonomies

This is where the magic happens. Remember that series taxonomy we defined in the config.toml? Using it in front matter is identical to categories or tags. You’re not doing anything special.

---
title: "Part 2: How I Built a Thing"
series: ["Building a Thing"]
---

The peril isn’t in the syntax; it’s in your own discipline. The power of custom taxonomies is that they let you create structured, meaningful relationships between your content. The peril is that you’ll get lazy and inconsistent. You’ll create a post with series: "Building-a-thing" and another with series: "Building a Thing". Suddenly, your “Series” page has two separate, lonely posts instead of one coherent series. The machine is dumb. It does exactly what you tell it to. You have to be the intelligent, consistent one. Use a defined list of allowed terms in your project’s style guide or even use Hugo’s taxonomies feature to pre-define them to prevent typos.

Best Practice: Be Consistent, Not Clever

Your future self will thank you for this. Decide on a format for your taxonomy values and do not deviate.

  • Case: Lowercase everything? Title Case? Pick one.
  • Spacing: Are you using hyphens (my-tag) or spaces (my tag)? Spaces are fine, but remember the quoting rule from above.
  • Singular/Plural: Is your tag tutorial or tutorials? Pick one.

This isn’t just pedantry. Inconsistency means your tag pages (/tags/tutorial/ and /tags/tutorials/) will be different, diluting your content and frustrating users. The computer doesn’t care, but your readers will. Use a text expansion tool or a snippet library to make sure you’re always using the approved, canonical form of your taxonomy terms. It feels like busywork until the moment it saves you from a massive, tedious cleanup job. Trust me on this one.