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; datePublished outranks it, and published stands in when neither is set), description (the card / KB excerpt text, with excerpt as its fallback), author (the byline name for an entry that sets no authorName), 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). A member with no usable date still appears — undated entries sort last.

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

Aardvark 0.4.1 release roundup

The 0.4.1 fixes in one read, plus the 0.4.0 release behind them — an islands toolchain that ships with Aardvark, prerendering on by default, and a deploy command.

The Aardvark team

September 1, 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:

• The reader assistant says what actually went wrong — in your language — September 1, 2026
• Windows binaries are back — September 1, 2026
• vark deploy publishes a site from the command line — August 30, 2026
• Aardvark ships the islands JS toolchain — nothing to install — August 30, 2026
• Island prerendering is on by default — August 30, 2026
• The MCP Server Card is written only when MCP is on — August 30, 2026
• The repo browser reads GitLab, and keeps a page-weight budget — August 30, 2026
• Ask AI highlights code without calling out — August 22, 2026
• Maps run on your own site, not a CDN — August 22, 2026
• Ask-AI reader assistant — June 14, 2026
• Build-time accessibility contrast audit — June 14, 2026
• Faster dev-loop rebuilds — June 14, 2026
• Generate the CLI reference from vark --help — June 14, 2026
• Index OpenAPI descriptions for search — June 14, 2026
• Interactive Mantine islands — June 14, 2026
• Multi-language sites — June 14, 2026
• Social unfurl cards (Open Graph) — June 14, 2026
• Standardized code-block Copy & Download buttons — June 14, 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 & hosting — 4 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), and a password-protected member is refused outright — its body is encrypted at build time and must never be re-rendered in the clear on whatever page called the loop. (For the same reason a protected page can only ever be a taxonomy’s listing page, never one of its members.) 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))
%}

The reader assistant says what actually went wrong — in your language — September 1, 2026

Every rejected turn used to report “This conversation is too long”, which was true of none of the four cases that produce it — including a rejected attachment, where the reader was told to start a new chat instead of to drop a file. Failures are classified by their code now, so a reader is told the thing they can act on. A turn rejected that way also restores what was typed, but only if the reader has not already begun a new question.

The panel’s remaining chrome localizes too. Its attachment, install, zoom, fullscreen and clear-conversation controls, and the whole “Copy page” / Markdown / agent-install menu, were never registered for translation, so a localized site rendered them in English without saying it had fallen back. Run a UI-string re-extraction (vark build --translate) to pick up the new strings; until then they fall back to English as before.

See Ask AI.

Windows binaries are back — September 1, 2026

0.4.0 published macOS and Linux builds but no Windows one. The release step that vendors the islands JS toolchain launched npm under its bare name, and Windows resolves a bare command without consulting PATHEXT — so it never found npm.cmd, and the build failed before producing anything. npm is resolved to an absolute path once now, and every call uses it.

macOS and Linux were never affected, and 0.4.0’s binaries for them stand. If you are on Windows, 0.4.1 is the upgrade from 0.3.3.

See Installation.

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: