Custom Taxonomies

What it is

Every site has two built-in taxonomies for blog posts: Category (hierarchical — a category can have sub-categories) and Tags (flat). Beyond those two, you can define your own custom taxonomies — a "Region," a "Product Line," anything specific to your content — and choose which content types each one applies to: the blog, one or more of the content types you've defined (see Content Types), or several at once.

A taxonomy is a category of organization; its individual values (e.g. "Recipes" within Category, or "vegan" within Tags) are called terms. Assigning a term to an article or entry is what lets you later find "everything tagged vegan" or "everything in the Recipes category."

Managing taxonomies

1. 1

   Open Taxonomies

   In the site editor, go to Workspace → Taxonomies. Category and Tags are already there — every site starts with them.

2. 2

   Create a custom taxonomy

   Give it a name and a slug, choose whether it's hierarchical (terms can have a parent, like Category) or flat (like Tags), and pick which content types it's assignable to — the blog and/or any content type you've defined; at least one is required. You don't need to pre-create its terms — the next step handles that.

3. 3

   Assign terms from the entry editor

   Open any blog post or content-type entry and use its Category/Tags (or your custom taxonomy's) field — a searchable picker, not free text. Search existing terms or type a new one to create it on the spot; there's no separate "add this term first" step.

Hierarchical vs. flat

A hierarchical taxonomy (like the built-in Category) lets a term have a parent — "Desserts" under "Recipes," for example — so you can browse or filter at either level. A flat taxonomy (like Tags) has no parent/child relationship; every term stands on its own.

Every term gets its own page

Once a term has at least one published entry, your published site automatically gets an indexable archive page for it — listing every entry that carries it, at yoursite.com/tags/vegan or yoursite.com/category/recipes. You don't create these pages yourself; they're generated straight from your terms, and they update automatically as entries are published, unpublished, or re-tagged.

A term with no published entries yet doesn't get a page at all — an empty archive would just be a thin, low-value page for search engines, so nothing is published for it until it has real content.

Anywhere you render terms on a page yourself (e.g. a tag cloud built from a repeating terms block), each rendered term automatically links to its archive page too.

SEO for a term's archive page

Every term archive comes with a search-friendly title, a meta description generated from the term's own description (or a plain "N posts in X" summary if it doesn't have one), and a canonical URL — no setup required. Two overrides are available if you want more control, currently via the manage_taxonomies MCP tool's updateTerm action rather than the dashboard UI:

• seoMetaDescription — replaces the auto-generated meta description for that term's archive page specifically.
• seoNoindex — excludes the archive from your sitemap and marks it noindex for search engines, while still keeping the page itself live and linkable. Useful for a low-value or purely organizational term (e.g. a catch-all "uncategorized") you don't want competing for search visibility with your real content.

Customizing an archive page's layout

Every taxonomy's archive pages start with a plain, generic list — title, excerpt, cover image, date. You can replace that with a real, custom layout: one template per taxonomy, shared by every one of its terms (all of yoursite.com/tags/* uses the same layout, not one per tag). This is currently available via the manage_templates MCP tool only — there's no dashboard UI for it yet.

A template has two kinds of placeholder, kept strictly separate. Outside the entry list, term-level placeholders describe the term itself: {{name}}, {{description}}, {{count}}, {{path}}, and {{taxonomyName}}. The entry list itself is a single container marked data-zg-archive-entries — its one child element is the "card" that gets repeated once per published entry, and inside that card the same-looking placeholders mean the entry's own fields instead: {{title}}, {{excerpt}}, {{path}}, {{publishedAt}}, and {{coverImageUrl}}. Which meaning applies is purely a matter of whether the placeholder sits inside or outside that one container — a {{path}} outside it is the archive page's own URL, the same placeholder inside a card is that specific entry's URL instead.

There's no saved-variant or per-locale variant support for an archive template yet (unlike content-type detail-page templates, which have both) — exactly one template per taxonomy. Deleting it reverts that taxonomy's archive pages to the default generic list.

Choose which content types it applies to

A taxonomy is only assignable to the content types you've explicitly checked for it — the blog, one specific content type, or several at once. Check multiple to share one vocabulary (e.g. one "Region" taxonomy used by both blog posts and a Testimonials content type) instead of redefining it per type; a content type you haven't checked simply won't offer that taxonomy in its entry editor. You can widen or narrow this any time from the taxonomy's settings — including for Category and Tags themselves.

• A content type created after a taxonomy already exists isn't automatically included — add it explicitly if you want that taxonomy there too.
• An entry can have terms from as many taxonomies as apply to its content type — Category, Tags, and any custom ones, all independently.