Taxonomies

A taxonomy groups pages by a shared frontmatter list: tags, categories, a series. Declare one and the build generates the index pages for it.

content {
  taxonomies {
    tags { listing { template "list.typ" } }
  }
}

Any page with tags: ("rust", "cli") in its frontmatter is now grouped automatically, and A listing { } block writes:

URL	Holds
`/tags/`	Every term, each with its page count as the entry’s `note`.
`/tags/rust/`	Every page tagged `rust`, ordered by title.

Both are ordinary templated pages rendered through the template you bound, so they inherit the site layout. They receive the same structured listing data a collection index does.

Keys

A taxonomy is a block named by its id, and what it generates is the listing { } block inside it, spelled the way a collection’s paginate { } is.

Key	Type	Default	Does
`key`	str	the taxonomy’s id	The frontmatter field its terms are read from.
`listing`	block	absent	Generate a page per term, and an index of the terms. Its presence turns them on.
`sort`	`order` \| `date` \| `title`	`title`	What a term’s members are ordered by.
`reverse`	bool	`#false`	Reverse that order.

Inside listing { }:

Key	Type	Default	Does
`template`	str	none	The layout those listings render through.
`size`	int	none	Members per term page. Without it, every member sits on one.
`prefix`	str	`page`	The path segment before a term page’s number.

sort and reverse are the collection keys, read by the same comparator, so a term page and a collection index listing the same posts cannot come in two orders. The default differs on purpose: a term spans collections, and order is a number each collection assigns for itself.

A dated blog usually wants newest first:

content {
  taxonomies {
    tags { sort "date"; reverse #true; listing }
  }
}

Reading a different key

A taxonomy reads the frontmatter key that matches its own name. Point it elsewhere with key to group the same content more than one way, or to name the taxonomy independently of the field:

content {
  taxonomies {
    tags { listing { template "list.typ" } }
    topics { key "categories"; listing { template "list.typ" } }
  }
}

Paginating a term

A term listing holds every page under it, which on a blog with three years of Rust posts is one page listing four hundred. size chunks it by the same rule a collection index is chunked by, so page 2 is named the same way in both:

content {
  taxonomies {
    tags { listing { size 20 } }
  }
}

/tags/rust/ keeps the first twenty, /tags/rust/page/2/ takes the next, and each carries page.frontmatter.nav like any other paginated listing. prefix renames the page segment, or empties it for /tags/rust/2/.

Terms and slugs

Terms are the strings you write, unchanged, in listings and titles: a term page is titled Tags: rust. The URL segment is the slugged form, lowercased with runs of non-alphanumerics collapsed to -.

WARN

Two terms that slug to the same segment (C++ and C-- both give c) are a build error naming both, not a silent overwrite. A term with no letters or digits at all has no slug and errors the same way.

On a multi-language site terms are grouped per language, so a French and an English rust tag are separate /fr/tags/rust/ and /tags/rust/ pages, never a merged one. See multiple languages.

A term can also carry its own feed, with generate { feed { terms #true } }; see feeds and sitemap.

Terms can be more than words. Point a taxonomy at a registry and each term is a person, a series, an organization the build knows other things about: see authors and other entities.