Taxonomies and tag pages

Taxonomies are a way to group pages by shared properties. Every Markdown site automatically gets a tag taxonomy at /tags/. You can define additional taxonomies — such as categories, authors, or series types — in site.toml. Each taxonomy generates a listing page and per-value pages automatically, with no code required.

How the built-in tags taxonomy works

Every page with a tags: frontmatter list is automatically indexed. Everlock generates:

/tags/ — a listing of all distinct tag values
/tags/<tag> — a listing of all pages that carry that tag

No configuration needed. Just add tags to your pages:

---
title: Installing Everlock
tags: [guide, setup, linux]
---

Visiting /tags/guide shows all pages tagged guide, sorted by date. Visiting /tags/ shows all tags that exist across the site.

Defining custom taxonomies

Custom taxonomies are defined in site.toml. Each entry maps a URL prefix (singular) to a frontmatter field name:

[taxonomies]
category  = "categories"
author    = "authors"

This tells Everlock:

the field categories: in frontmatter → generates routes under /category/
the field authors: in frontmatter → generates routes under /author/

The key on the left is the URL prefix. The value on the right is the frontmatter field Everlock looks for in each page.

Adding taxonomy fields to pages

Once a taxonomy is defined, add the corresponding field to your pages as a YAML list:

---
title: Deploying with Docker
date: 2026-03-01
tags: [ops, docker]
categories: guides
authors:
  - alice
---

A single-value field is read as a one-item list. A multi-value field assigns the page to multiple taxonomy values:

---
title: Cross-platform setup
categories:
  - guides
  - reference
authors:
  - alice
  - bob
---

What gets generated

For the site.toml example above, Everlock generates:

URL	Content
`/category/`	All distinct values from the `categories` field
`/category/guides`	All pages where `categories` includes `guides`
`/category/reference`	All pages where `categories` includes `reference`
`/author/`	All distinct values from the `authors` field
`/author/alice`	All pages where `authors` includes `alice`
`/author/bob`	All pages where `authors` includes `bob`

These routes are live as soon as you push pages with the corresponding frontmatter. You do not need to create any files for them.

Linking to taxonomy pages

Link to taxonomy pages from your templates like any other URL. In single.html, show a page's category as a link:

{% if page.extra_lists.categories %}
<div class="categories">
  Filed under:
  {% for cat in page.extra_lists.categories %}
  <a href="/category/{{ cat }}">{{ cat }}</a>
  {% endfor %}
</div>
{% endif %}

In list.html or a custom section template, add a category filter link in the navigation:

<nav class="taxonomy-nav">
  <a href="/category/guides">Guides</a>
  <a href="/category/reference">Reference</a>
  <a href="/tags/">All tags</a>
</nav>

Customizing taxonomy listing pages

By default, taxonomy listing pages (both /tags/ and custom taxonomy pages) use list.html. You can create a dedicated template for a specific taxonomy by following the section layout pattern.

Because taxonomy routes are auto-generated and not backed by _index.md files, you customize their look by editing list.html itself or by rendering taxonomy links differently through your CSS.

Practical example: a category-organized docs site

Here is a complete example for a documentation site with two categories: guides and reference.

`site.toml`

title = "My Docs"
base_url = "https://docs.example.com"

[nav]
links = [
  { label = "Home",       url = "/"                  },
  { label = "Guides",     url = "/category/guides"   },
  { label = "Reference",  url = "/category/reference" },
  { label = "Tags",       url = "/tags/"             },
]

[taxonomies]
category = "categories"

Pages with categories

docs/install.md:

---
title: Installation
tags: [setup]
categories: guides
---

# Installation

...

docs/config-reference.md:

---
title: Configuration reference
tags: [configuration]
categories: reference
---

# Configuration reference

...

docs/upgrade.md:

---
title: Upgrading
tags: [setup, ops]
categories:
  - guides
  - reference
---

# Upgrading

...

Visiting /category/guides lists Installation and Upgrading. Visiting /category/reference lists Configuration reference and Upgrading. The overlap page appears in both because it has two values in its categories list.

Show categories on the page in `single.html`

{% if page.extra_lists.categories %}
<div class="page-categories">
  {% for cat in page.extra_lists.categories %}
  <a href="/category/{{ cat }}">{{ cat }}</a>
  {% endfor %}
</div>
{% endif %}

Tags vs. custom taxonomies — when to use each

Use tags for ad-hoc, cross-cutting labels that don't have a fixed vocabulary. Good for: linux, tutorial, security, performance.

Use custom taxonomies for structured classification that you want to navigate as a hierarchy with its own dedicated URL space. Good for: categories, authors, product-areas, release-versions.

A page can use both at the same time. Tags and taxonomies are independent of each other.