Frontmatter

Frontmatter is the YAML block at the top of a Markdown file, fenced by ---. zetl reads it, exposes it in templates, and otherwise gets out of the way. It is entirely optional.

What it looks like

---
title: Zettelkasten Method
tags: [note-taking, knowledge-management]
date: 2026-01-14
status: draft
---
# Zettelkasten Method

The Zettelkasten is a slip-box system...

Everything between the two --- fences is parsed as YAML. Everything after is the page body.

What zetl does with it

Three things, all passive:

Parses it once per page, on indexing.
Makes it available in templates as page.frontmatter.<key>. If you’re theming zetl serve or zetl build, you can read anything you’ve written — {{ page.frontmatter.tags }}, {{ page.frontmatter.status }}, anything. See Customising the Look.
Exposes it to hooks via the vault context, so render-pipeline hooks and lifecycle scripts can make decisions based on metadata.

zetl does not require any specific field. No title, no id, no uuid. Your filename is your page name; the graph builds itself from wikilinks.

What the community uses it for

None of these are built-in — they’re conventions that happen to work:

Field	Use
`tags`	A list for topical grouping; read by themes and `zetl check`-style tooling
`date`	Publication or creation date; often used for journal pages
`status`	`draft`, `published`, `archived` — render differently per status
`aliases`	Alternate names for the same page; used by some themes for search
`author`	For multi-author vaults

A minimal page doesn’t need any of this. A page with no frontmatter at all is completely fine:

# Evergreen Notes

A note you tend over time, rather than one you write once and forget.

See Tags and Frontmatter for workflow-level patterns.

Arbitrary keys are welcome

Anything valid YAML is fair game. Nested objects, lists, numbers, booleans — all accessible in templates:

---
project:
  name: zetl
  version: 0.5.0
  contributors: [hugo, ana]
published: false
---

page.frontmatter.project.name is "zetl" in your theme. Use this for whatever structure your vault needs — book bibliographies, task metadata, research parameters — without asking permission.

Reserved fields

A small number of keys have meaning to specific features. The one to know about today:

parser: — picks a non-default Markdown parser (Pandoc, remark) for pages that need it. Only relevant if you’ve set up Plugin Ecosystems. Without a parser: field, zetl uses its built-in CommonMark parser.

More reserved-key documentation lives at Frontmatter Fields. If you never use those features, never think about them.

A worked example: tag-filtered index

Here’s why exposing frontmatter to templates matters. Given a vault of project notes each with:

---
status: active
owner: ana
due: 2026-05-01
---

A custom index.html in .zetl/themes/default/ can filter the page grid:

{% for p in vault.pages if p.frontmatter.status == "active" %}
  <li><a href="/page/{{ p.slug }}/">{{ p.title }}</a> — due {{ p.frontmatter.due }}</li>
{% endfor %}

The vault stays plain Markdown; the presentation reads your metadata. See Customising the Look.

What frontmatter is not

Not required. A vault of files with no YAML headers is a valid zetl vault.
Not validated. zetl doesn’t tell you a field is “wrong” — it doesn’t know what your fields mean. Invalid YAML (bad indentation) is flagged; semantic choices are yours.
Not a schema. If you want a schema, layer one on with Lifecycle Hooks or SPL rules.

Backlinks

Linked Pages

Customising the Look

Both Web Server and Static Site Export accept --theme <name>. A theme is a folder under .zetl/themes/<name>/ containing Minijinja templates, static assets, and an optional theme.toml. You only override what you want — everything you don’t ship falls back to the built-in defaults.

Why themes matter

The default theme is deliberately neutral so it works as a starting point, not an endpoint. You will probably want to change at least the colours, the typography, and the name at the top of the sidebar. Most of that is CSS-only: zetl exposes a versioned set of CSS custom properties so you can restyle the graph widget, the shell, and page typography without touching any HTML.

The bigger reason the theming story is careful: zetl’s graph widget is a single, persistent Sigma.js instance that survives page navigation (no flash, no re-layout). Themes that rewrite base.html have to preserve two DOM markers to keep that property — otherwise the graph re-initialises on every click. The contract below is the bargain that makes “persistent graph across a multi-page site” possible.

Creating a theme

Bundled themes are built into the binary. Export one to the vault to start editing:

zetl theme list                        # what's available
zetl theme export default paper        # copies default to .zetl/themes/paper/

Then point serve or build at it:

zetl serve --theme paper
zetl build --theme paper

What lives where

.zetl/themes/paper/
  theme.toml                  # config for SPA, graph, contract version
  base.html                   # master layout (sidebar, modals, scripts)
  index.html                  # vault landing page
  page.html                   # one page view
  folder.html                 # folder index
  help.html                   # /help page
  static/
    theme.css                 # your CSS
    enhance.js                # extra JS (runs per navigation)
    fonts/

Writing Pages

In a zetl vault, one page is one Markdown file. No databases, no sidecar XML, no magic — if you can write a .md file, you can write a zetl page.

The filename is the title

zetl uses the filename (minus .md) as the page title. Title-case filenames with spaces are the convention:

~/notes/
  Zettelkasten Method.md
  Reading List 2026.md
  Meeting with Priya 2026-04-18.md

When another page writes [[Zettelkasten Method]], zetl resolves the link by matching the filename. Slugification happens at render time — the URL becomes /zettelkasten-method/, but your filesystem stays human-readable. Case doesn’t matter for resolution; [[zettelkasten method]] works too.

There is no restriction on where a file lives. Folders are for your eyes, not zetl’s. See Organising Your Vault.

A minimal page

Every page is CommonMark-compatible Markdown with optional YAML frontmatter at the top:

---
title: Reading List 2026
tags: [reading, journal]
status: open
---

# Reading List 2026

Books I want to read this year, with a running note once I finish each.

- [[Gödel, Escher, Bach]] — started January
- [[The Glass Bead Game]] — queued
- [[Seeing Like a State]] — finished March

## Related

- [[Book Journal]]
- [[Annual Review 2026]]

That’s it. No build step, no registration. Save the file; it’s a page. Run zetl list and you’ll see it.

Markdown flavour

Frontmatter Fields

Frontmatter is YAML at the very top of a page, fenced by --- lines. zetl reads a handful of reserved keys — everything else passes through untouched for templates, hooks, and search. Nothing is required. A page with no frontmatter at all is valid.

---
title: Zettelkasten Method
tags: [pkm, method, luhmann]
date: 2024-06-03
status: draft
---

# Zettelkasten Method

Niklas Luhmann's slip-box system…

Reserved keys

zetl inspects these during indexing and rendering:

Key	Type	Meaning
`title`	string	Display title. Falls back to the filename stem when absent. Does not rename the file or change its wikilink target.
`parser`	string	Force a specific parser for this page. Values: `commonmark` (default) or `pandoc`. See Writing Pages.
`tags`	list of strings	Surfaced in templates and in `zetl search --path`. Drives the tag cloud.
`description`	string	Plain-text `<meta name="description">` / social-preview text. Falls back to the first paragraph.

No key is mandatory. Omit any of them and zetl infers a sensible default.

Parser selection

The parser: key wins over every other selector. Precedence (highest to lowest):

parser: in the page’s frontmatter
First matching [[parse.rule]] glob in .zetl/config.toml
Top-level [parse] default in .zetl/config.toml
commonmark (zetl’s built-in default)

An unknown parser name (e.g. parser: djot when only commonmark is registered) produces a per-page error and the page is skipped — the rest of the build proceeds. Run zetl ecosystem check to see which parsers are available.

Convention-only keys

The following are conventions, not reserved — zetl does not parse them, but templates and hooks consume them by name. Use whichever match your workflow.

Tags and Frontmatter

Tags are how you group pages without forcing them into folders. Frontmatter is how you attach any other structured data — dates, statuses, authors, book ISBNs, whatever your vault needs — that zetl and your templates can both see.

YAML frontmatter basics

Frontmatter is a YAML block at the very top of a page, fenced by ---:

---
title: Seeing Like a State
tags: [book, political-theory, legibility]
author: James C. Scott
year: 1998
status: finished
rating: 5
---

# Seeing Like a State

...

Anything inside the fences is frontmatter; everything after the closing --- is the body. zetl reads frontmatter on every scan and exposes it to templates, search, and hooks. See Frontmatter for the conceptual model and Frontmatter Fields for the reserved-key reference.

Tagging — two syntaxes

zetl recognises tags in two places.

Frontmatter tags. A YAML list under the tags: key:

tags: [rust, cli, reference]

This is the canonical form. Tags here are structured metadata — they’re first-class, they show up in templates, and they don’t clutter your prose.

Inline hashtags. #word tokens inside the body of the page:

What is SPL

Requires --features reason at install time. See Installation.

SPL is Spindle Lisp — a small Lisp-family language for writing rules. zetl extracts SPL from your vault and draws conclusions: “if a project is approved and has an owner, it’s ready to start”. This page is a gentle orientation; see Writing SPL for the syntax reference.

Why a second language at all

Most of your vault is prose — the thing humans are good at reading. But some knowledge is best expressed as a rule, not a paragraph. “Any release candidate must have a green test run and up-to-date docs” is easier to write (and check) as a rule than as a checklist you hope to follow.

SPL lets you write those rules inside your notes, alongside the prose they explain. zetl then reasons over all the SPL in the vault at once — a single combined theory — and tells you what follows.

The shape of SPL

SPL is parenthesised. Facts and rules are S-expressions:

(given docs-updated)
(given tests-pass)

(normally r-ready
  (and docs-updated tests-pass)
  release-candidate)

Reading top to bottom: two facts, then a rule named r-ready that says normally, if both facts hold, conclude release-candidate. Run reasoning and zetl will report +d release-candidate — defeasibly proved.

“Normally” is load-bearing. SPL is a defeasible logic: a conclusion can be drawn by default, and then withdrawn when stronger contrary evidence appears. See What is Defeasible Reasoning for what this means and why it matters for knowledge that isn’t strictly mathematical.

Lifecycle Hooks

Git-style scripts that run at defined points during a zetl operation. Drop an executable into .zetl/hooks/ named after a lifecycle point, and zetl invokes it with structured JSON on stdin and a handful of ZETL_* environment variables.

These are separate from the AST-level Render Pipeline Hooks — lifecycle hooks fire around the build, not inside it. Use them to publish an RSS feed after zetl build, notify a chat room on on-save, or run a schema validator on post-check.

Lifecycle points

Hook	Fires	Can abort?
`pre-build`	Before `zetl build` renders pages	Yes
`post-build`	After `zetl build` completes	No (warning on non-zero)
`post-index`	After `zetl index` completes	No
`post-check`	After `zetl check` collects diagnostics	No
`pre-serve`	Before `zetl serve` binds	Yes
`on-save`	After a page is saved via `zetl serve`	No
`on-agent`	When an agent API request arrives	No
`on-access-request`	When a user requests page access (collab mode)	No

“Can abort” means a non-zero exit cancels the parent operation; every other hook just logs a warning and continues.

What a hook receives

stdin — a JSON object with vault metadata, the page list, the link graph, and hook-specific fields (e.g. saved for on-save). If history is enabled, a history object is included.
environment — ZETL_HOOK (the lifecycle name), ZETL_VAULT_ROOT, ZETL_THEME, ZETL_VERSION, plus hook-specific vars: ZETL_OUT_DIR on build hooks, ZETL_PORT on serve hooks.
working directory — the vault root, regardless of where zetl was invoked from.
timeout — 30 seconds wall-clock. A hook that hangs is killed.

Writing a hook

Create an executable file named exactly after the lifecycle point (no extension):

# .zetl/hooks/post-build
#!/bin/bash
# Generate an RSS feed from pages with a `date:` frontmatter field.
set -euo pipefail

jq -r '
  .pages
  | map(select(.frontmatter.date))
  | sort_by(.frontmatter.date) | reverse | .[0:20]
  | map("<item><title>\(.title)</title><pubDate>\(.frontmatter.date)</pubDate></item>")
  | "<rss><channel>\(join(""))</channel></rss>"
' < /dev/stdin > "$ZETL_OUT_DIR/feed.xml"

Then mark it executable:

chmod +x .zetl/hooks/post-build

Plugin Ecosystems

Rather than rewriting every transform in zetl, reuse the ones that already exist. The plugin-ecosystem adapters let a render-pipeline hook delegate to a Pandoc filter, an mdBook preprocessor, or a remark plugin. zetl handles AST translation in both directions; the hook manifest just names the plugin.

If you already have a Lua filter you wrote for an academic paper, or an mdbook-mermaid you use for a book, you can reach for it from a zetl vault without a rewrite.

Declaring an ecosystem hook

Pick the stage, name the ecosystem, point at the plugin. A Pandoc Lua filter in the transform stage:

# .zetl/hooks/transform.d/smallcaps.py.toml
ecosystem = "pandoc"
lua_filter = "filters/smallcaps.lua"   # OR: exec = "pandoc-smallcaps"

stage = "transform"
mode  = "persistent"
extension_id = "smallcaps"

Each ecosystem has its own required/optional manifest fields:

Ecosystem	Required	Optional
`pandoc`	`exec` or `lua_filter`	`args`
`mdbook`	`exec`	`scope = "page" \| "vault"`
`remark`	`package`	`version`, `options`

Pandoc hooks default to the transform stage; mdBook preprocessors run at pre-parse (they operate on raw Markdown); remark targets the transform stage with the mdast AST type. See each ecosystem’s deep-dive guide in the main repo’s docs/ecosystems/ directory for translation details and per-plugin quirks.

Scaffolding

The authoring CLI seeds the right manifest fields (and, for Pandoc, drops a starter identity Lua filter on disk) when you pass --ecosystem:

zetl hook new transform smallcaps --ecosystem pandoc
zetl hook new pre-parse admonish  --ecosystem mdbook
zetl hook new transform math      --ecosystem remark

The generated hook works out of the box: zetl hook test smallcaps will pass against the seeded fixture. From there you edit the filter, add selectors, and tune the behavioural contract like any other pipeline hook.