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:

• 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 10, 2026
• Build-time accessibility contrast audit — June 2, 2026
• Faster dev-loop rebuilds — June 2, 2026
• Generate the CLI reference from vark --help — June 2, 2026
• Index OpenAPI descriptions for search — June 2, 2026
• Interactive Mantine islands — June 2, 2026
• Multi-language sites — June 2, 2026
• Social unfurl cards (Open Graph) — June 2, 2026
• Standardized code-block Copy & Download buttons — June 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))
%}

Ask AI highlights code without calling out — August 22, 2026

Opening the Ask AI panel used to fetch highlight.js from a CDN the first time a reader asked a question. It doesn’t any more: answers are highlighted by the lexer Aardvark already uses for your pages, so the assistant makes no third-party request, needs no extra Content-Security-Policy origin, and still works where that CDN is unreachable.

The colors are unchanged: answers were already painted from your theme’s syntax palette and still are. What has gone is the extra stylesheet that remapped highlight.js’s class names onto that palette, because the built-in lexer emits the same classes your own code blocks use. An answer still stays plain while it streams and is colored in one pass once it finishes — what no longer happens is the repaint when the CDN script arrived late and recolored an answer already on screen.

The trade is breadth. The built-in lexer covers 20 languages — JSON, Bash, Python, JavaScript, TypeScript, Go, PHP, Rust, Ruby, Java, C, C++, SQL, YAML, INI/TOML, CSS, SCSS, XML/HTML, Markdown and Aardvark’s own template syntax, plus the usual aliases. Anything outside that list renders as readable plain text where the CDN’s grammar set would have colored it.

Released in 0.3.3. See Ask AI.

Maps run on your own site, not a CDN — August 22, 2026

{% map %} used to pull MapLibre GL JS from a public CDN at runtime. It now bundles a runtime served from your own site and publishes the map worker as a same-origin asset, so nothing executable in a map comes from a third party. A map keeps working when a CDN is blocked or slow, and it needs no CDN allowance in a Content-Security-Policy.

The runtime is read out of your own node_modules, so a site upgrading from an earlier release has to install mantine-map 0.4.0 — add it to package.json and run your package manager, since it is the installed tree that decides and a listed-but-uninstalled package is not a copy Aardvark can build against. Until that copy is there, the build warns, drops the interactive map and falls back to the accessible list of locations the tag always renders for readers without JavaScript — the build still succeeds, which is what makes a vanished map easy to overlook. Pin the version exactly: a copy that is not 0.4.0 is dropped the same way, since that is the version the map surface is built against. Sites scaffolded by 0.3.3 already carry the pin. On 0.3.3 the install is required; a later release ships the runtime inside Aardvark itself and drops the step.

Three knobs are gone with the CDN they pointed at: map.maplibreVersion, map.maplibreJs and map.maplibreCss no longer do anything, and are ignored without a warning — delete them rather than waiting to be told. If you set a Content-Security-Policy, a map now needs worker-src 'self' and img-src 'self' data: blob:; the basemap’s own style, tile, glyph and sprite origins still belong under connect-src/img-src, since those carry map data rather than code.

The runtime is only shipped by sites that use it: a page tree with no {% map %} emits neither the MapLibre bundle nor the worker.

Released in 0.3.3. See Map.

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: