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

None of these is “right.” Pick whatever matches how your brain looks things up when you’re not thinking about tooling.

Pragmatic advice: start flat

If you’re starting a new vault, put everything in the root. When you pass around 100 pages and finding files in your editor gets annoying, group the obvious clusters into folders. You’ll know which ones — they’re the folders you wish existed.

Rename and move freely

Because links resolve by filename, moving Seeing Like a State.md from ~/notes/ to ~/notes/Books/ doesn’t break a single [[Seeing Like a State]] reference. After the move:

zetl index     # refresh the cached graph
zetl check     # confirm no dead links

Renaming is a little more work — see Linking Pages for the rename workflow.

`.zetlignore` — excluding drafts and private files

zetl scans the entire vault root by default. Put files and folders you want zetl to ignore into a .zetlignore file using gitignore syntax:

# ~/notes/.zetlignore
drafts/
private/
*.tmp
scratch.md

Patterns match the vault root. Subdirectory .zetlignore files are not honoured — keep it all in one file at the top.

zetl already excludes .git/, .zetl/, node_modules/, and dotdirs like .obsidian/ by default. Run zetl build --include-hidden to include them anyway, or zetl build --exclude 'pattern/' for a one-off exclusion that doesn’t touch .zetlignore.

Tags vs folders

Both are fine. They answer different questions.

Folders answer	Tags answer
“Where does this file live?”	“What is this file about?”
One per page	Many per page
Exclusive	Overlapping
Filesystem-native	Metadata-native

A meeting note might live in Meetings/2026-04-18.md (one place) and carry tags: [project-x, priya] (two dimensions). Folders scale for filesystem browsing; tags scale for cross-cutting queries. See Tags and Frontmatter.

Naming conventions

Three patterns pull their weight:

Titles. Zettelkasten Method.md, not zettelkasten-method.md. Human filenames. zetl slugifies at render.
Dates. 2026-04-18 (ISO 8601) sorts right and never confuses month order. Use it in journal/meeting filenames.
Uniqueness. Two pages with the same title on the graph is ambiguous. Disambiguate in the filename: Meeting with Priya 2026-04-18.md, Scientific Management (book).md.

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).

Linking Pages

Links are how your vault stops being a folder of files and starts being a graph. This page covers the everyday workflow of linking — the full syntax reference lives in Wikilinks.

Link as you write

The honest workflow: while drafting a note, when you reach a concept that deserves its own page, just wrap it in double brackets.

The book makes the case that [[Scientific Management]] hollowed out
craft knowledge in a way that [[Seeing Like a State]] would later
describe as legibility.

Two things happen:

If Scientific Management.md already exists, the link resolves — clicking it in zetl view or zetl serve navigates to the page.
If it doesn’t exist, zetl flags it as a dead link but otherwise leaves you alone. The link is a promise, not an error.

Dead links are surfaced by zetl check --dead-links:

$ zetl check --dead-links
Scientific Management — referenced from: Taylorism and its Discontents.md:7

You can create the target page any time. Run zetl index (or let zetl serve re-scan) and the link goes live.

Creating the target page later

This is the rhythm most writers settle into:

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

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:

Vaults

A vault is any directory that contains Markdown files. That is the whole definition. zetl does not own your notes, does not require a config file, and does not need to import anything — point it at a folder and it starts working.

What’s in a vault

A vault is a tree of .md files. Folders are just folders; there is no hidden database beside your notes. The only thing zetl adds is a .zetl/ directory at the vault root, used for caching:

~/notes/
  Zettelkasten Method.md
  projects/
    zetl.md
    daily/
      2026-04-15.md
  .zetl/           <- zetl's cache; safe to delete
    index.json
    blocks/
    theory/        <- only with --features reason
    jj/            <- only with --features history

Everything in .zetl/ is disposable. Delete it and the next zetl index rebuilds it from your files. This matters: your vault is your Markdown, not zetl’s cache. See Local-first.

How zetl walks a vault

When you run zetl index, zetl walks the tree using a layered ignore stack. From lowest to highest precedence:

Layer	Rule
1	Hardcoded: `.git/`, `.zetl/`, `node_modules/` are never scanned
2	Dotdirs like `.obsidian/`, `.vscode/`, `.claude/` are skipped by default (`--include-hidden` disables)
3	`.gitignore` patterns, if present
4	`.zetlignore` at the vault root (gitignore syntax; `!pattern` re-includes)
5	`--exclude PATTERN` CLI flag (repeatable, highest priority)

This means a zetl vault coexists cleanly with a git repo, a node project, an Obsidian workspace, or a Logseq graph. You do not need to rearrange files.

Pointing zetl at a vault

Two ways, and they are equivalent:

# Explicit
zetl -d ~/notes index

# Or set the env var once per shell
export ZETL_DIR=~/notes
zetl index
zetl links "Zettelkasten Method"