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

zetl parses CommonMark plus a small set of widely-supported extensions: fenced code blocks, tables, footnotes, strikethrough, task lists. Wikilinks ([[...]] and ![[...]]) and block anchors (^id) are zetl-specific — see Wikilinks and Headings and Blocks.

If you have been using Obsidian or another wikilink editor, your existing Markdown will almost certainly parse without changes. See Migrating from Obsidian.

zetl doesn’t impose a method

You don’t have to run a Zettelkasten. You don’t have to run Johnny Decimal. You don’t have to write atomic notes, daily notes, MOCs, or any other thing. A vault of long-form essays works. A vault of one-line bookmarks works. A vault that mixes research notes, a reading journal, and project plans works.

The only rule zetl cares about: pages are files, links are [[links]]. Everything else is your call.

Writing workflows

A few idioms that tend to work well:

Situation	What to do
New thought, not sure where it belongs	Create `Inbox Note 2026-04-18.md` at the vault root, link later
Long-form draft	Keep it in one file until a section starts getting linked to — then extract
Reference material	One page per concept; link liberally from narrative pages
Journal	`Journal/2026-04-18.md` per day; links to whatever you were thinking about

Previewing what you wrote

Three ways to see the rendered page:

zetl view "Reading List 2026"   # two-pane terminal view
zetl serve                      # local web server
zetl build                      # write dist/ as static HTML

See Terminal Viewer, Web Server, and Static Site Export.

Backlinks

Linked Pages

Wikilinks

A wikilink is how you point from one note to another by name. zetl parses five shapes of wikilink from your Markdown. This page is the syntax reference; for workflow advice see Linking Pages.

The five shapes

Shape	Example	Purpose
Plain	`[[Zettelkasten Method]]`	Link to a page; display text is the target name
Aliased	`[[Zettelkasten Method\|the slip-box method]]`	Link with custom display text
Heading	`[[Zettelkasten Method#Origins]]`	Link to a specific heading on a page
Block	`[[Zettelkasten Method^b3a9f1]]`	Link to a specific content-addressable block
Embed	`![[Zettelkasten Method]]`	Transclude the target’s content inline (see Embeds and Transclusion)

All five can be combined with a heading or block anchor on the target side: ![[Zettelkasten Method#Origins]] embeds a single section.

How resolution works

When you write [[Some Page]], zetl does not look up a URL or an ID. It looks for a file named Some Page.md in your vault. Specifically:

By filename, not by the # H1 inside the file. The name in brackets must match the file stem.
Case-insensitive. [[some page]], [[SOME PAGE]], and [[Some Page]] all resolve to Some Page.md.
Across subfolders. zetl searches the whole vault tree; you don’t write [[projects/zetl]], just [[zetl]].
Slugified for the web output — Some Page.md becomes /page/some-page/ in zetl serve and zetl build. You never need to think about slugs when writing; that’s what the resolver is for.

If two files share a name across folders, the first match wins and the other is reported as ambiguous by zetl check. Rename one.

Dead links are fine (until they’re not)

A wikilink to a page that does not yet exist is a dead link. zetl does not crash, does not refuse to render, and does not auto-create the file. It records the edge and surfaces it in:

zetl check --dead-links

Many people use this as a to-do list: write what you wish existed, then fill in the targets later. See Finding Orphans and Dead Links.

Your First Vault

A vault is just a folder of .md files. This page walks you through creating one from scratch — three linked notes, an index, a health check, and a web UI — so you have a feel for vault hygiene before you pour a decade of notes in.

Make the folder

mkdir ~/notes
cd ~/notes

That’s the whole setup. No config files, no database, no init command. zetl treats any folder containing Markdown as a vault.

Create three linked notes

Open your editor and create three files. The content matters less than the wikilinks — we want to see the graph form.

Projects.md:

---
tags: [hub, projects]
---
# Projects

Active work this quarter. My overarching goals for the year live
in [[2026 Goals]]. Day-to-day progress notes accumulate in
[[Daily Journal]].

## Current

- Rewriting the customer onboarding flow
- Writing a long-form piece about [[2026 Goals#writing]]

2026 Goals.md:

---
tags: [planning, goals]
year: 2026
---
# 2026 Goals

Three things I want to get done this year. Progress lives
in [[Daily Journal]], and specific projects are tracked
in [[Projects]].

## Writing

Publish a monthly essay. See [[Projects]] for the current draft.

## Health

Run three times a week.

## Learning

Read one book a month, notes in the journal.

Daily Journal.md:

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:

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

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:

Static Site Export

zetl build turns your vault into a folder of plain HTML, CSS, and JavaScript. No runtime, no database, no server process — every page is a file you can upload to any static host. The output looks the same as Web Server minus the editor.

Why build a static site

A static site is the right deliverable when:

You want to publish research notes, a personal wiki, or project docs to the public internet.
You want a vault readable from any browser with zero operational overhead.
You want something to hand to collaborators, reviewers, or your future self that doesn’t depend on the zetl binary being installed.
You want archival: HTML works the same way in 2040 as it does in 2026.

Because nothing on the published site writes back, the edit button is absent and the save/delete endpoints aren’t emitted. Everything else — wikilinks, backlinks, transclusion panels with SVG bridges, the graph widget, full-text search, per-page history (if built with --features history) — lands in the output as static HTML and JSON.

Running it

zetl build                             # writes ./dist/
zetl -d ~/notes build
zetl build --out-dir site              # custom output directory
zetl build --theme paper               # pick a theme
zetl build --site-url https://vault.example    # absolute URLs for social cards

Preview the result locally with any static file server:

python3 -m http.server -d dist 8080

Then open http://localhost:8080/.

Output structure

Web Server

zetl serve starts a local web server that renders your vault as a browsable site. You get rendered Markdown, working wikilinks, a live backlink panel, a persistent graph mini-map, and an in-browser editor. It’s the fastest way to actually read — and edit — a vault of more than a handful of notes.

Why run a server

A static export (Static Site Export) shows your vault as it was when you last built it. A terminal viewer (Terminal Viewer) shows one note at a time. zetl serve is what you want between those: a live view of the vault right now, with:

Rendered pages — Markdown, wikilinks, embeds, and code blocks, rendered through Minijinja templates with YAML frontmatter in scope.
Backlinks panel — every page that points here, updated on every save.
Transclusion panel — forward-link excerpts as cards in the right rail, connected to anchors in the main text by SVG bridges (the same Xanadu idea as the terminal viewer).
Live search — full-text search across the vault from a modal.
CodeMirror editor — click Edit, change the note, hit Save. The index rebuilds on save; no reload dance. A delete button is a click away.
Persistent graph mini-map — a Sigma.js WebGL graph of your vault, docked bottom-right, that survives page navigation (no flash, no re-layout).
History strip — when zetl was built with --features history, every page shows when it last changed and links to its timeline. See Page History.

Running it

zetl serve                            # http://localhost:3000
zetl -d ~/notes serve
zetl serve --port 8080
zetl serve --theme paper

Open http://localhost:3000/ to land on the vault index. Wikilinks in rendered pages are clickable. Ctrl-P (or whatever the active theme binds) opens the search modal.

Flags that matter

Flag	Default	Purpose
`-p, --port <PORT>`	`3000`	TCP port.
`--theme <THEME>`	`default`	Theme from `.zetl/themes/<name>/`. See Customising the Look.
`--public <DIR>`	—	Files in this directory override generated pages (good for `robots.txt`, custom error pages).
`--collab`	off	Switches to multi-user mode with passkeys and CRDT sync. See Running a Team Server.
`--safe-mode`	off	Skip every hook except ones declared in the theme.
`--at <TIME-EXPR>`	—	Serve a past snapshot. See Time Travel.
`--exclude <PATTERN>`	—	Gitignore-syntax exclusion, repeatable.

Single-user vs collab

Out of the box, zetl serve is single-user and trusts whoever reaches the port. There’s no login, no accounts; editing works immediately. This is the right mode when the server is on your laptop or behind a VPN.

With --collab, zetl turns into a multi-user server: WebAuthn passkey login, real-time CRDT editing over WebSockets, access control, invitations. That whole stack — bootstrapping an owner, inviting collaborators, deterministic server keys — lives in Running a Team Server.

Terminal Viewer

zetl view is a Xanadu-inspired two-pane reader for reading linked notes without leaving the terminal. It exists because most of the time you don’t want a browser — you want to sit with one note, glance at what it points to, and jump onwards when something catches your eye.

Why two panes

When you read a note in a normal editor, forward-links are just names — [[Zettelkasten Method]] tells you nothing about what Zettelkasten Method actually says. Ted Nelson’s original vision for Xanadu put the cited text right next to the citing text, bridged by a visible connector. zetl view does exactly that in a TTY:

Main pane (left) — the note you asked for, rendered as Markdown. Every wikilink is annotated with a numbered anchor glyph [1], [2], [3] in reading order.
Context column (right) — a stack of context cards, one per forward link. Each card shows the first few lines of the linked note, coloured to match its anchor.
Bridge column (middle) — coloured connectors from each [N] anchor to its card, so your eye can follow the citation at a glance.

In terminals narrower than 60 columns the layout collapses to single-pane and context cards become inline footnotes. You lose the bridges but keep the anchors.

Opening a page

zetl view "Zettelkasten Method"      # by page name
zetl view                            # interactive page picker
zetl view "Project Notes" --context-lines 10
zetl view "Project Notes" --main-width 65

With no argument, zetl view launches an interactive picker of every page in the vault — type to filter, Enter to open.

Flags

Flag	Default	Purpose
`--context-lines <N>`	`5`	Lines shown per context card. Range 1–20.
`--main-width <pct>`	`58`	Percent of terminal columns for the main pane. Range 30–80.
`--at <TIME-EXPR>`	—	Read a past snapshot (see Time Travel).
`-d, --dir <DIR>`	`.`	Vault root.

Keybindings

Key	Action
`j` / `k`	Scroll down / up (or cycle anchors in focus mode)
`Ctrl-d` / `Ctrl-u`	Half-page down / up
`g` / `G`	Jump to top / bottom of the note
`Tab`	Toggle between scroll mode and focus mode
`Enter`	Navigate to the focused link
`[` / `]`	Session history: back / forward
`/`	Open the page picker
`?`	Toggle the keybindings overlay
`q`	Quit

Focus mode is what makes the navigation fast. Hit Tab, then j/k steps from one anchor to the next (not one line at a time); the bridge column highlights the selected anchor’s connector; Enter opens that page. [ returns to where you came from, so you can explore breadth-first through a chain of notes and back-track without losing your place.

Migrating from Obsidian

There is no migration. Point zetl at your Obsidian vault and it works. The two tools read the same Markdown, the same wikilink syntax, and the same YAML frontmatter — your notes are the source of truth for both.

The short version

zetl -d ~/Documents/ObsidianVault index
zetl -d ~/Documents/ObsidianVault serve

Open your vault in Obsidian at the same time. Both read your .md files. Neither locks anything. zetl never writes to your notes — only to a disposable cache under .zetl/.

Syntax compatibility

Every wikilink shape Obsidian uses, zetl parses the same way:

Syntax	Meaning
`[[Zettelkasten Method]]`	Standard link.
`[[Zettelkasten Method\|the method]]`	Aliased display text.
`[[Zettelkasten Method#History]]`	Link to a specific heading.
`[[Zettelkasten Method^abc123]]`	Link to a block by ID.
`![[Book Notes]]`	Embed (transclude) the whole page.
`![[Book Notes#Ch 3]]`	Embed a section.

See Wikilinks for the zetl-specific details (resolution rules, ambiguity handling).

Frontmatter

zetl parses YAML frontmatter the same way Obsidian does. Existing tags, aliases, publish, and anything else you rely on will surface in page.frontmatter.* for templates, and tags flow into Tags and Frontmatter queries. Custom keys — status, project, deadline — are preserved verbatim and available in templates and hooks.

A frontmatter block Obsidian wrote this morning:

---
tags: [research, reading]
aliases: [Adler, How to Read]
status: in-progress
---

Headings and Blocks

A plain wikilink takes a reader to a page. On a long page, that’s a coarse target — you may have wanted to point at one section, or one sentence. zetl supports both.

Heading links

Use # to point at a heading within a page:

See [[Annual Review 2026#Priorities]] for the three-item list.
The argument is developed in [[Seeing Like a State#Legibility]].

Matching rules:

Case-insensitive. #Priorities, #priorities, and #PRIORITIES all match ## Priorities.
Slugified. Spaces and punctuation are normalised, so #getting started matches ## Getting Started.
Any heading level. # in the link matches ##, ###, and so on — the link just names the heading text.

If multiple headings on a page share the same text, the first one wins. That’s rare in practice; rename one of them if it bites you.

Block ids

When you want to point at something finer than a heading — a definition, a quoted passage, a data row — use a block id. Append ^some-id to the end of the block, then link with [[Page^some-id]]:

The central definition in the book:

> State simplifications are static typifications that abstract
> away from local knowledge in the service of administrative
> control.
> ^legibility-def

From another page:

Scott's definition of legibility — [[Seeing Like a State^legibility-def]] —
maps cleanly onto what Taylor was doing in factories.

Block ids can live on any paragraph, blockquote, list item, code block, or table. Convention: