Hugo Taxonomies vs Sections: A Practical Framework

Sep 9, 2026 · 8 min read
a computer screen with a phone and a tablet
Photo by Team Nocoloco on Unsplash

Hugo sections, taxonomies, and page resources can all appear to organize content, but they represent different relationships. Choose a section when content belongs to a hierarchical area, a taxonomy when a classification crosses those areas, and a page resource when a file belongs to one page or page bundle. Start with the relationship you need to express—not the URL you happen to want.

That distinction helps prevent a common modeling problem: using a label as if it were a content area, using a content area as if it were a reusable classification, or placing page-specific assets in a site-wide structure. The choice affects navigation, templates, queries, and the structure maintainers must keep consistent.

Start with the relationship, not the feature name

Ask what the new connection means.

Is this a hierarchy or ownership boundary? Use a section. The content belongs to a recognizable area such as blog, guides, or reference.

Can the same item belong to several shared classifications? Use a taxonomy. A post might be about accessibility, performance, and content modeling regardless of which section contains it. Hugo’s taxonomy documentation describes taxonomies as user-defined groupings that represent logical relationships between content.

Is this a file or supporting asset owned by one page? Use a page resource or page bundle. A diagram, download, image, or data file belongs beside the page that uses it rather than becoming a site-wide category.

These questions are more reliable than starting with a desired navigation label. A navigation label may be a section link, a taxonomy term, or a menu item that points to an ordinary page. The label alone does not determine the content model.

Use sections for hierarchy and content-area boundaries

A section fits when a site needs to answer, “What content area does this belong to?” A blog, documentation area, knowledge base, and changelog may each have different editorial expectations, templates, navigation, or publishing rules. Modeling them as sections makes those boundaries visible in the content structure.

A hypothetical site might begin like this:

content/
├── blog/
│   ├── first-post/
│   │   └── index.md
│   └── second-post/
│       └── index.md
└── guides/
    ├── hugo-content-modeling/
    │   └── index.md
    └── deployment-basics/
        └── index.md

Here, blog and guides express two content areas. They are not merely labels attached to otherwise identical pages. They may need different landing pages, list treatments, navigation, or editorial metadata.

Sections become less comfortable when the same content must be organized along several independent dimensions. A post about Hugo may belong to the blog, a documentation area, a product collection, and an audience group at the same time. Creating nested sections for every combination would turn classification into hierarchy and make the content tree difficult to maintain.

A practical test is ownership: if moving an item to another content area would change its editorial context, a section may be appropriate. If the item should remain in the same area while gaining another shared label, that label probably belongs elsewhere.

The relationship between section structure, _index.md, index.md, bundles, and template resolution is version-sensitive enough to verify against the Hugo documentation for the version being deployed. CloudCannon’s guide to Hugo sections provides additional practical context about sections and page bundles, including the distinction between section and page index files.

Use taxonomies for cross-cutting classification

A taxonomy is useful when a relationship cuts across the site’s hierarchy. Examples include topic, audience, technology, or format. One page can have several terms, and one term can collect pages from different sections.

For the hypothetical site, a shared topic taxonomy might classify both blog posts and guides:

---
title: "Modeling Hugo Content"
topics:
  - Hugo
  - Content modeling
  - Static sites
---

The page still belongs to its original section. The taxonomy adds another way to find it.

This distinction matters because taxonomy pages create naming and presentation decisions. Maintainers need to decide which taxonomies exist, how terms are named, whether singular and plural forms are normalized, which terms deserve landing-page copy, and how taxonomy lists fit into navigation. Hugo provides the grouping mechanism, but it does not decide which groupings are meaningful for a particular site.

Do not create a taxonomy merely because a word appears in a menu. If “Guides” is a stable content area with its own editorial purpose, it is likely a section. If “Hugo” should collect pages from blog posts, reference material, and tutorials, it is more naturally a taxonomy term. A menu can point to either one, but the underlying relationship is different.

Taxonomy scope can also become an implementation question when separate sections need different classification systems. A Stack Overflow discussion about local taxonomies for multiple Hugo sections illustrates that maintainers may need to resolve this through configuration. The discussion demonstrates a practical question, not a general rule about the correct solution.

Use page resources for page-owned files

A page resource answers a narrower question: “Which files belong to this page?” The relationship is ownership, not classification.

A page bundle for an article might look like this:

content/
└── guides/
    └── hugo-content-modeling/
        ├── index.md
        ├── content-tree.svg
        ├── taxonomy-example.yaml
        └── section-notes.txt

The diagram and example file support this specific guide. They do not imply that the guide belongs to a content-tree category or that every page using the same file type should be grouped together.

Page-local assets are useful when an asset should move, be replaced, or be removed with its page. Keeping files near their owner makes that relationship easier to inspect. It also avoids turning an article’s supporting files into unrelated global content.

Page resources are not a substitute for sections or taxonomies. A diagram can belong to a page while the page belongs to the guides section and carries Hugo and content-modeling taxonomy terms. These features can coexist because they describe different relationships:

  • The section identifies the page’s content area.
  • The taxonomy identifies shared classifications.
  • The page resource identifies files owned by that page.

Before relying on a particular resource-discovery method, processing rule, or template behavior, check the Hugo version’s page-bundle and page-resource documentation. The distinction is useful for modeling, but version-specific implementation details should be verified before they become production assumptions.

A decision sequence for new relationships

When a new content relationship appears, work through these questions in order.

1. Does the relationship define where the content belongs?

If yes, begin with a section. Examples include blog, docs, reference, and case-studies when each represents a durable content area with its own context.

If no, do not create a deeper section just to make a label available in navigation.

2. Can the relationship apply across several content areas?

If yes, consider a taxonomy. A shared topic can connect a blog post to a guide without forcing both into the same hierarchy.

If the classification is meaningful only inside one narrow collection, confirm whether a section-specific taxonomy is supported and maintainable in the Hugo version and configuration you use.

3. Is the relationship between a page and its supporting files?

If yes, use page-local resources or a page bundle. The asset should remain discoverable through its owning page rather than becoming a separate content item.

4. What should a reader be able to find?

A section usually answers, “What is this area of the site?” A taxonomy answers, “Which other pages share this characteristic?” A page resource answers, “What files support this page?” If the proposed feature does not produce a useful answer for readers or maintainers, reconsider the relationship.

5. What will templates and navigation need to render?

Each choice creates different presentation work. Sections generally require section landing and listing decisions. Taxonomies require term and taxonomy-list decisions. Page resources require page-level asset handling and, where relevant, resource processing.

Do not choose a feature only because it produces a convenient URL. A URL can often be customized or routed separately from the underlying model. If the model is wrong, a tidy URL can hide an awkward content relationship that later complicates templates and maintenance. After changing the model or templates, a Hugo content preview workflow can help you inspect the rendered result before publication.

When combining features is the accurate model

Real content models often need more than one feature. The hypothetical blog and knowledge base can use:

content/
├── blog/
│   └── choosing-hugo-features/
│       ├── index.md
│       └── comparison-diagram.svg
└── guides/
    └── hugo-content-modeling/
        ├── index.md
        └── content-tree.svg

Both pages can carry shared topic terms such as Hugo and content modeling, while remaining in different sections and owning different diagrams. This is not unnecessary duplication if each relationship answers a different question.

The tradeoff is a larger configuration and template surface. More features mean more names to standardize, more pages to decide whether to expose, and more opportunities for inconsistent content. Combine them when the relationships are genuinely distinct; avoid combining them simply because every feature is available.

A useful review record for each relationship can include:

  • Meaning: What relationship does this represent?
  • Owner: Which page, section, or shared classification owns it?
  • Expected query: How should a maintainer or reader find it?
  • Presentation: Which list, term, section, or page template must support it?
  • Failure mode: What becomes confusing if this relationship is modeled incorrectly?
  • Revisit trigger: What future change would justify restructuring it?

This record is more durable than documenting only the chosen feature. If the site later adds a second documentation area, a new audience dimension, or downloadable assets, the original reasoning helps maintainers determine whether the relationship has changed.

The compact rule

Use a section for hierarchy and content-area ownership. Use a taxonomy for reusable classification that can cross those areas. Use a page resource for files owned by one page. Then check the choice against template needs, navigation, URL expectations, and maintenance scope.

The feature should follow the relationship. When a site needs hierarchy, classification, and page-local assets at the same time, using all three can be more accurate than forcing one feature to represent everything.