Taxonomy Configuration

Taxonomies provide a powerful method for organizing and categorizing content in Hugo. The Sans theme supports Hugo’s flexible taxonomy system, allowing you to use default taxonomies or create custom classifications for your content.

Understanding Taxonomies

Taxonomies are classification systems that enable content grouping and relationship building. Hugo automatically handles taxonomy generation and page creation once configured.

Default Taxonomies

The theme includes three pre-configured taxonomies commonly used in content management:

**Table:** Default Taxonomy Types
Taxonomy	Singular	Plural	Use Case
Tags	tag	tags	Keyword-based content classification
Categories	category	categories	Broad content grouping
Authors	author	authors	Content attribution and authorship tracking

Configuration

Basic Setup

Taxonomies are configured in the hugo.toml file. Navigate to the [taxonomies] section and specify your desired taxonomies:

1
2
3
4
[taxonomies]
  tag = "tags"
  category = "categories"
  author = "authors"

Configuration Syntax

**Table:** Taxonomy Configuration Syntax
Component	Description	Example
Singular Form	Left side of assignment	tag, category, author
Plural Form	Right side of assignment	tags, categories, authors
Format	singular = "plural"	tag = "tags"

Important: The singular form defines the taxonomy identifier used in front matter, while the plural form determines the URL structure and list page naming.

Custom Taxonomies

Creating Custom Taxonomies

The process of creating custom taxonomies follows the same logic as that of default taxonomies.

Syntax Pattern

1
2
[taxonomies]
  singular = "plural"

Custom Taxonomy Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[taxonomies]
  # Default taxonomies
  tag = "tags"
  category = "categories"
  author = "authors"
  
  # Custom taxonomies
  series = "series"
  topic = "topics"
  project = "projects"
  location = "locations"
  difficulty = "difficulties"

Using Taxonomies in Content

Front Matter Configuration

Once taxonomies are defined in hugo.toml, assign them to individual content files through front matter:

1
2
3
4
5
6
7
8
9
+++
title = "Understanding Taxonomies"
date = 2024-01-15
tags = ["hugo", "documentation", "taxonomies"]
categories = ["tutorials"]
authors = ["John Doe", "Jane Smith"]
series = ["Hugo Basics"]
topics = ["content-organization"]
+++

Multiple Values

Taxonomies accept multiple values, enabling comprehensive content classification:

1
2
3
tags = ["web-development", "hugo", "static-sites", "jamstack"]
categories = ["tutorials", "technical"]
authors = ["Author One", "Author Two"]

Single Value Taxonomies

For taxonomies requiring only one value per post:

1
2
difficulty = ["beginner"]
format = ["video"]

Taxonomy Page Generation

Hugo automatically generates several page types for each configured taxonomy:

**Table:** Auto-Generated Taxonomy Pages
Page Type	URL Pattern	Description
Taxonomy List	/tags/	Lists all available tags
Taxonomy Terms	/tags/hugo/	Shows all posts tagged with 'hugo'
Taxonomy RSS	/tags/index.xml	RSS feed for taxonomy
Taxonomy Terms RSS	/tags/hugo/index.xml	RSS feed for specific term

URL Structure Examples

With the configuration tag = "tags" and series = "series":

1
2
3
4
5
6
/tags/                    # All tags
/tags/hugo/              # Posts with tag "hugo"
/categories/             # All categories
/categories/tutorials/   # Posts in category "tutorials"
/series/                 # All series
/series/hugo-basics/     # Posts in series "hugo-basics"

Display Configuration

Taxonomy Visibility

Control taxonomy display in various contexts through the [posts] and [sections] configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[posts]
  showTags = true
  showCategories = true
  showAuthors = true
  showTagCloud = false
  showCategoryCloud = false
  showAuthorCloud = false

[sections]
  showTags = false
  showCategories = false
  showAuthors = false

Advanced Configuration

Taxonomy Weight and Ordering

Control taxonomy display order through front matter weights:

1
2
3
4
5
6
+++
title = "Advanced Hugo"
categories = ["tutorials"]
tags = ["hugo", "advanced"]
tags_weight = 10  # Higher weight = appears first
+++

Preserving Taxonomy Case

By default, Hugo lowercases taxonomy values. To preserve case:

1
2
3
4
[taxonomies]
  tag = "tags"

preserveTaxonomyNames = true

Taxonomy Rename Process

To rename a taxonomy:

Update hugo.toml configuration
Update all content front matter
Rebuild site to regenerate pages
Implement 301 redirects for old URLs
Update internal links and references