Taxonomies

A taxonomy is a set of terms that entries relate to. Tidewater’s blog has two: the authors who write posts, and the topics posts are about.

After reading this guide, you will know:

• How to declare a taxonomy, and give each term and the taxonomy itself a page.
• How an entry relates to terms.
• How to list a term’s entries in a view.

1. Declaring a taxonomy

The theme Tidewater started from already declares authors and topics. Topics look like this:

# site/themes/tidewater/schema/taxonomies/topics.yml
schema: 1
title: Topics
route: /topics/{slug}
index_route: /topics
template: topics/show
index_template: topics/index
blueprints: [topic]
sort: title:asc
api: true

• route gives each term a page: Cash flow lives at /topics/cash-flow.
• index_route gives the taxonomy a page listing its terms, at /topics.
• blueprints are the fields a term has, exactly as for entries — an author has a bio and a website.

Generate a new one with bin/rails nibble:generate:taxonomy industries. Use it to sort Tidewater’s customer stories: Agencies, Consultancies, Studios.

2. Relating entries to terms

A terms field on the entry’s blueprint is the relationship:

- handle: authors
  field: { type: terms, taxonomies: [authors], max_items: 1, listable: true }
- handle: topics
  field: { type: terms, taxonomies: [topics], listable: true }

Editors pick from the terms that exist; the field stores references, so renaming a term renames it everywhere. Listing it (listable: true) adds a column and a filter to the collection’s listing in the control panel.

Alternatively, name taxonomies on the collection and every entry gets a picker in its sidebar without the blueprint declaring a field:

# site/schema/collections/posts.yml
taxonomies: [topics]

3. Showing a term’s entries

A term’s page is rendered by its template. Its query sidecar asks for the entries that carry it:

# site/themes/tidewater/views/topics/show.yml
params: [page]
posts:
  from: entries:posts
  where:
    topics: $term
  paginate: { per_page: 12 }

$term is the term being rendered — on its own it means the term’s ID — as $entry is the entry. See Queries.

4. Every key

Key	Notes
title, blueprints	required
route, index_route	the term page and the taxonomy page
template, index_template, layout	view names
sort	e.g. title:asc
sitemap, api, localizable, search	as for collections
icon	shown in the control panel’s sidebar