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.

Key	Convention
`date`	Publication / last-edited date. Any ISO-8601 string. Themes often sort by this.
`status`	`draft`, `published`, `archived`. Hooks read it for publish-gating.
`author`	Override for multi-author vaults.
`aliases`	Alternate titles — surfaced in some themes; not currently resolved by the wikilink matcher.

Anything you invent is fair game — add project_code: Q2-2026, mood: 🔥, reading_time: 8m. Templates see it via page.frontmatter.<key>.

Template variables

Every HTML render receives a page object. The fields writers care about:

Variable	Source
`page.title`	`title:` frontmatter, or the filename stem if absent.
`page.slug`	URL-safe page path, relative to vault root.
`page.frontmatter`	The entire parsed YAML as a JSON object. Access nested keys as `page.frontmatter.date`, `page.frontmatter.tags[0]`, etc.
`page.description`	Either the frontmatter `description:` or the first paragraph.
`page.content_html`	Rendered HTML body.
`page.content_raw`	Original Markdown source.
`page.backlinks`	List of inbound links.
`page.outlinks`	List of outbound links (with `is_dead` flag).
`page.breadcrumbs`	Directory path components.
`page.history`	Snapshot timeline. `null` when history is unavailable.

page.frontmatter is the raw parsed document — any key you put in the YAML appears here verbatim. This is how templates pick up your custom fields without any template changes.

{% if page.frontmatter.status == "draft" %}
  <aside class="draft-banner">Draft — not for circulation.</aside>
{% endif %}

{% for tag in page.frontmatter.tags %}
  <a class="tag" href="/tags/{{ tag }}">#{{ tag }}</a>
{% endfor %}

Interaction with wikilinks

Frontmatter title: changes display, not addressing. A page at notes/zettelkasten.md is linked as [[zettelkasten]] or [[Zettelkasten]] regardless of whether its frontmatter declares title: The Zettelkasten Method. The rendered heading and the entry in every other page’s backlinks will show the title-cased frontmatter value.

If you want [[The Zettelkasten Method]] to resolve, rename the file.

Interaction with search

zetl search reads both the body and the serialised frontmatter text. A query for status: draft matches draft pages. tags: values are searchable by their string.

Interaction with SPL

Frontmatter keys are ground-truth facts for SPL reasoning under --features reason. A rule can test @page.frontmatter.status == "published" (subject to the SPL syntax — see Writing SPL).

Backlinks

Linked Pages

Configuration

Every knob zetl exposes: environment variables, ignore files, theme.toml, and the .zetl/ state directory. Nothing here is required — zetl runs on a bare directory of Markdown with zero configuration. Read this page when you want to change defaults.

Environment variables

zetl-specific variables are prefixed ZETL_. The binary also honours NO_COLOR (a de-facto standard).

Read by the CLI

Variable	Equivalent flag	Purpose
`ZETL_DIR`	`-d, --dir`	Default vault root.
`ZETL_FORMAT`	`-f, --format`	`json`, `table`, or `auto`.
`ZETL_NO_CACHE`	`--no-cache`	Force full rescan.
`NO_COLOR`	`--no-color`	Disable ANSI colour.
`ZETL_HOSTNAME`	`--hostname` (on `serve --collab`)	WebAuthn relying-party hostname.
`ZETL_SERVER_KEY_SEED`	`--server-key-seed` (on `serve --collab`, `derive-ssh-key`)	BIP39 mnemonic for deterministic key derivation in ephemeral deployments.
`ZETL_CAP_SITE_URL`	`--site-url` (on `cap invite`)	Canonical site URL for capability-URL rendering.
`ZETL_CAP_PAIR_PHRASE`	`--phrase` (on `cap pair`)	Pinned SPAKE2 phrase; test-harness hook.

Pass any of these once in your shell profile and skip the corresponding flag forever.

Exported to hooks

Every hook zetl launches inherits these:

Variable	Value
`ZETL_HOOK`	Hook name (e.g. `post-build`, `callouts`).
`ZETL_VAULT_ROOT`	Absolute path to the vault.
`ZETL_THEME`	Active theme name. Empty string if no theme.
`ZETL_VERSION`	zetl binary version (e.g. `0.5.0`).
`ZETL_AST_SCHEMA_VERSION`	AST schema version (SemVer, e.g. `1.0.0`). Independent of `ZETL_VERSION`.
`ZETL_MODE`	`build` or `serve`.
`ZETL_OUT_DIR`	Build output directory. Empty string under `serve`.
`ZETL_VERBOSE`	`true` / `false`.
`ZETL_HOOK_PATH`	Absolute path to the hook executable. Render-pipeline only.
`ZETL_EXTENSION_ID`	Hook extension id (filename stem, minus `\d+-` ordering prefix). Render-pipeline only.
`ZETL_HOOK_DEPTH`	Nesting depth; zetl increments on every child invocation to detect runaway recursion.
`ZETL_AT`	Time expression passed via `--at`. Set only when time-travel is active.

Pin your hook against ZETL_AST_SCHEMA_VERSION, not ZETL_VERSION — the AST schema changes far less often. See Render Pipeline Hooks.

Persistent-mode hooks also receive both versions in their JSON init message, alongside a capability probe. See tools/zetl-ast-reference.md in the source tree for the wire protocol.

Ignore files

zetl layers five sources of file-exclusion. Later layers override earlier ones except for level 1 (which is absolute).

CLI Overview

Every zetl subcommand at a glance, with the flags writers actually use. This page is the reference — the linked how-to pages give the narrative.

Run zetl <cmd> --help for the authoritative flag list for any command. This guide tracks zetl v0.5.0.

Global flags

Every subcommand honours these, wherever they make sense.

Flag	Env var	Purpose
`-d, --dir <DIR>`	`ZETL_DIR`	Vault root. Default: `.` (current directory).
`-f, --format <FORMAT>`	`ZETL_FORMAT`	`json` / `table` / `auto`. Auto picks table for a TTY, JSON for a pipe.
`--json`	—	Shorthand for `-f json`.
`--no-cache`	`ZETL_NO_CACHE`	Ignore the cached index; force a full rescan.
`--no-color`	`NO_COLOR`	Disable ANSI colour.
`-q, --quiet`	—	Suppress non-essential output.
`-v, --verbose`	—	Increase verbosity. Repeatable (`-vv`).
`--no-input`	—	Disable interactive prompts; fail if input is needed.
`--at <TIME-EXPR>`	—	Query the vault at a historical point. Requires `--features history`. See Time Travel.
`-V, --version`	—	Print zetl version.

Subcommand summary

Command	Description	Feature flag
`index`	Build or refresh the link index	—
`list`	List every page in the vault	—
`stats`	Summary counts and most-linked pages	—
`links`	Forward links from a page	—
`backlinks`	Backlinks to a page	—
`check`	Dead links, orphans, syntax, SPL diagnostics	—
`search`	Full-text search (BM25, optional semantic)	`semantic` for `--semantic`/`--hybrid`
`similar`	SimHash title matches	—
`path`	Shortest link path between two pages	—
`export`	Dump the full link graph	—
`blocks`	List or resolve Merkle blocks	—
`view`	Two-pane terminal reader	—
`serve`	Local web server	—
`build`	Static-site HTML export	—
`watch`	Stream vault changes as NDJSON	—
`diff`	Graph diff against a git ref or snapshot	—
`theme`	List / install / remove / export themes	—
`hook`	Author, test, and inspect hooks	—
`ecosystem`	Probe Pandoc / mdBook / remark runtimes	`ecosystems-v1`
`ast`	Inspect or diff zetl-ext AST	—
`agent`	Run an agent-lifecycle hook	—
`invite`	Multi-user invitation token	collab (built-in)
`agent-token`	Derive a headless API token	collab
`derive-ssh-key`	Derive an SSH ed25519 key from a mnemonic	collab
`cap`	Capability-URL static sharing operations	—
`reason`	SPL queries over the vault	`reason`
`mcp`	Start an MCP server	`mcp`
`delegate`	Issue a delegate JWT	`mcp`
`completions`	Emit a shell completion script	—
`man`	Emit a roff(7) man page	—

zetl index

Scan the vault and write the cached link index to .zetl/index.json. Incremental by default; --no-cache forces a full rescan.

Key flags: --exclude <PATTERN> (repeatable gitignore syntax), --include-hidden (walk .claude/, .obsidian/, etc.).

zetl index
zetl -d ~/notes index --exclude 'drafts/**'

zetl list

Enumerate every page zetl can see. Useful in pipes.

Organising Your Vault

zetl is indifferent to how your vault is laid out. Pages resolve by filename, not path, so you can reorganise at any time without breaking links.

No required structure

A handful of layouts people actually use:

Flat. Every page in the vault root. Works surprisingly well up to a few hundred pages. The link graph provides the structure; the filesystem is just a blob.

~/notes/
  Annual Review 2026.md
  Reading List 2026.md
  Scientific Management.md
  Seeing Like a State.md
  Zettelkasten Method.md

Topic-based. Top-level folders by subject.

~/notes/
  Books/
    Seeing Like a State.md
  Essays/
    Legibility and Craft.md
  Journal/
    2026-04-18.md
  Reference/
    SPL Cheatsheet.md

Johnny Decimal. Numbered categories. Good when the topics are stable and you value predictable paths.

~/notes/
  10 Work/
    11 Projects/
    12 Meetings/
  20 Reading/
    21 Books/
    22 Papers/
  30 Personal/

Zettelkasten-style. Timestamped slip-boxes, no folders, atomic notes linked into trails. Works, but not required — zetl is not a Zettelkasten tool, just a link-graph tool.

~/notes/
  202604181423 Legibility as precondition.md
  202604181431 Taylor and Scott in parallel.md

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:

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

Writing SPL

Spindle Lisp (SPL) is the small language zetl reads when you ask it to reason over your vault. This page walks through the syntax by example — no formal grammar, just enough to start writing useful theories.

Requires --features reason at install. See Installation.

Where SPL goes

SPL lives in two places:

Fenced code blocks inside any Markdown file, tagged spl.
Standalone .spl files anywhere in the vault.

# Q2 Release

We're tracking the release of the next minor version here.

```spl
(given core-features-done)
(given docs-drafted)
```

zetl merges every spl block and every .spl file across the vault into one combined theory before reasoning. A fact stated on one page can feed a rule defined on another. This is the point — rules and facts can live next to the prose that motivated them.

Facts

A fact is something you assert to be true. Use (given ...):

(given project-approved)
(given has-owner)
(given budget-signed-off)