Taxonomy

The built-in taxonomy tag — turn tagged member pages into a changelog timeline, a knowledge-base grid, or a blog article list, with tag filtering, per-page tag navigation, and an RSS feed for changelog and article listings. Front-matter schema, options, and live examples.

A built-in tag that renders a listing of member pages — real pages in your content tree that opt into a named taxonomy through front matter — in one of three shapes: a changelog timeline, a knowledge base of categorized questions, or a blog-style article list. Because the members are ordinary pages, every entry has its own URL and its own Markdown body — and, unless it opts out with noindex: true, its own place in search and llms.txt. This site’s changelog entries do opt out: they’re stealthed (nav: false + noindex: true), and the changelog listing folds their body text into its own search record, so it stays findable there. That fold is specific to the changelog type — blog and knowledge-base members are ordinarily their own search landings, so a listing there carries only their teaser; marking such a member noindex: true drops its body from search rather than recovering it through the listing. The listing is assembled at build time from their front matter. This site uses all three: the Changelog tab, the Support knowledge base, and the Blog are each one {% taxonomy %} tag over a folder of member articles. Changelog and article listings also publish an RSS feed (pass feed=false to opt out); knowledge-base listings do not.

Usage

Two halves: member pages declare their membership in front matter, and one listing page renders the tag. A member joins a taxonomy with a taxonomy: entry:

---
title: Faster dev-loop rebuilds
date: 2026-05-28 09:15
taxonomy:
  - name: changes
    tags: [build, performance]
---

and the listing page — the one page marked listing: true — renders all members:

{% taxonomy name="changes" type="changelog" wide %}

The member’s body is the entry’s content — for type="changelog" it renders inline in the timeline exactly as {% changelog %} renders a YAML entry’s description, so a data-file changelog can convert to member articles with an identical rendered result. (Island components in a member body are suppressed in the inline listing view — they render only on the member’s own page.) Relative links in a member body are rebased onto the member’s own URL, so they resolve the same inline as on the article page; on a versioned site, a root-absolute link in an older version’s listing is rewritten to that version’s equivalent page when one exists — the same in-version rule the member’s own page follows — so the inline view never bounces a reader to the latest docs.

Front matter

Member pages

Each entry in a page’s taxonomy: list joins one taxonomy. name is required; everything else is optional:

Several top-level front-matter keys also feed the entry: title (the entry headline), date (YYYY-MM-DD, optionally with a time — 2026-05-28 16:30 — the full timestamp drives the newest-first sort), description (the card / KB excerpt text), version (a changelog release badge beside the date), and image / imageAlt (a blog card cover image and its alt text — omit imageAlt when the cover is decorative).

The listing page

Give exactly one page listing: true for the taxonomy and put the tag in its body. A changelog- or blog-style listing usually wants a wide layout (mode: full or mode: wide) so it can use wide.

Options

A changelog listing

type="changelog" reproduces the {% changelog %} timeline — the same component, fed from member articles instead of a YAML file. This is exactly what the Changelog tab renders (with wide); here, capped to the three most recent entries:

{% taxonomy name="changes" type="changelog" limitEntries=3 toc=false feed=false %}

A knowledge base

type="kb" groups members by tag into categories, with featured: true members surfaced as top questions and each entry’s description as its excerpt. The Support tab is one of these; here, filtered to a single category:

{% taxonomy name="support" type="kb" tagFilter="Included AI" %}

An article list

type="articles" renders blog-style article cards — byline, date, badge, cover image, and the description as the teaser. The Blog tab renders all posts (with wide); here, filtered to one tag:

{% taxonomy name="blog" type="articles" tagFilter="release" feed=false %}

Release

vark 0.9 release roundup

The 0.9 release in one read — a self-generating CLI reference, a faster dev loop, and the best of the 0.8 line.

The aardvark team

May 30, 2026

Traversing a taxonomy yourself

The three listing types are bespoke renderings, but the underlying data is plain and yours to walk: every {% %} block runs real Python, and two injected helpers open the taxonomy up — taxonomy(name) returns the named taxonomy for the current page’s language/version, and member_html(member) renders a member’s actual body content (see below). Loop with print() to emit any markdown (or HTML) you like:

{%
for m in taxonomy("changes").articles:
    print(f"- [{m.title}]({m.url}) — {m.date_display}\n")
%}

which renders the changelog members as a plain list:

• Generate the CLI reference from vark --help — May 28, 2026, 4:30 PM
• Faster dev-loop rebuilds — May 28, 2026, 9:15 AM
• Standardized code-block Copy & Download buttons — May 22, 2026
• Index OpenAPI descriptions for search — May 14, 2026
• Ask-AI reader assistant — May 3, 2026
• Build-time accessibility contrast audit — April 19, 2026
• Social unfurl cards (Open Graph) — April 5, 2026
• Multi-language sites — March 21, 2026
• Interactive Mantine islands — March 2, 2026

The returned object exposes the taxonomy’s whole surface:

An unknown name raises at build time, listing the taxonomies that exist — the same contract as the directive. Combine with featured/by_tag for custom surfaces the built-ins don’t cover (“three most recent posts per tag”, a by-author archive, …). Here’s this site’s real Support taxonomy, grouped by tag:

{%
for tag, members in sorted(taxonomy("support").by_tag.items()):
    print(f"**{tag}** — {len(members)} article(s)\n")
%}

Included AI — 4 article(s) Overflow — 3 article(s) Payments & limits — 8 article(s) Plan changes — 4 article(s) Plans, seats & hosting — 8 article(s)

Member content

Front matter is only the surface — member_html(member) renders a member’s actual body to HTML, so a loop can reproduce the articles themselves, not just link to them. The body renders in the member’s own context (includes and expressions resolve exactly as on the article page), the leading H1 is stripped so your loop prints its own headline, and relative links are rebased onto the member’s URL. Island components are suppressed with a build warning — they render only on the member’s own page, the same contract as the inline changelog view. Calling it from inside a member’s own body is rejected (a member embedding other members could recurse). Here are this site’s two most recent release notes, re-rendered in full:

{%
for m in taxonomy("changes").articles[:2]:
    print(f"\n#### {m.title} — {m.date_display}\n")
    print(member_html(m))
%}

Generate the CLI reference from vark --help — May 28, 2026, 4:30 PM

The CLI reference page is now generated straight from vark --help, so every flag and subcommand stays in lockstep with the code:

• No hand-maintained option tables to drift
• Each subcommand is documented from its own --help

See the CLI reference for the full command list.

Faster dev-loop rebuilds — May 28, 2026, 9:15 AM

vark dev keeps edit-loop rebuilds fast by skipping the build’s heaviest publish phases — Open Graph card rendering and the whole-site PDF — which only matter when you ship. Full vark build output is unchanged. Why aardvark still re-renders every page covers the design thinking.

CSS Selectors

Each listing shape renders its own class-name family — target the article list, the knowledge base, the tag cloud, and the changelog timeline through their prefixes:

.aardvark-articlelist-*   /* article-list layout and cards */
.aardvark-kb-*            /* knowledge-base categories, top questions, entries */
.aardvark-tagcloud-*      /* the tag cloud (listing column or right rail) */
.aardvark-changelog-*     /* the changelog timeline (same parts as {% changelog %}) */

Injecting Attributes

attr={…} forwards raw HTML attributes — id, data-*, ARIA, analytics hooks — onto the rendered listing root: