Configure taxonomies

Configure taxonomies.

The default configuration defines two taxonomies, categories and tags.

taxonomies:
  category: categories
  tag: tags

[taxonomies]
  category = 'categories'
  tag = 'tags'

{
   "taxonomies": {
      "category": "categories",
      "tag": "tags"
   }
}

When creating a taxonomy:

Use the singular form for the key (e.g., category).
Use the plural form for the value (e.g., categories).

Then use the value as the key in front matter:

---
categories:
- vegetarian
- gluten-free
tags:
- appetizer
- main course
title: Example
---

+++
categories = ['vegetarian', 'gluten-free']
tags = ['appetizer', 'main course']
title = 'Example'
+++

{
   "categories": [
      "vegetarian",
      "gluten-free"
   ],
   "tags": [
      "appetizer",
      "main course"
   ],
   "title": "Example"
}

If you do not expect to assign more than one term from a given taxonomy to a content page, you may use the singular form for both key and value:

taxonomies:
  author: author

[taxonomies]
  author = 'author'

{
   "taxonomies": {
      "author": "author"
   }
}

Then in front matter:

---
author:
- Robert Smith
title: Example
---

+++
author = ['Robert Smith']
title = 'Example'
+++

{
   "author": [
      "Robert Smith"
   ],
   "title": "Example"
}

The example above illustrates that even with a single term, the value is still provided as an array.

You must explicitly define the default taxonomies to maintain them when adding a new one:

taxonomies:
  author: author
  category: categories
  tag: tags

[taxonomies]
  author = 'author'
  category = 'categories'
  tag = 'tags'

{
   "taxonomies": {
      "author": "author",
      "category": "categories",
      "tag": "tags"
   }
}

To disable the taxonomy system, use the disableKinds setting in the root of your site configuration to disable the taxonomy and term page kinds.

disableKinds:
- categories
- tags

disableKinds = ['categories', 'tags']

{
   "disableKinds": [
      "categories",
      "tags"
   ]
}

See the taxonomies section for more information.

Last updated: March 5, 2025 : content: Consolidate configuration documentation (b6cae5cbc)

Improve this page