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:

---
tags: [journal]
---
# Daily Journal

## 2026-04-20

Started sketching the onboarding rewrite from [[Projects]].
Reminder: the writing goal in [[2026 Goals#writing]] is
behind — only one essay shipped so far.

## 2026-04-19

Read two chapters. Need to backfill notes on those tomorrow.

Three files. Six wikilinks between them. One of them ([[2026 Goals#writing]]) points at a specific heading.

Build the index

zetl index

If your terminal shows a table like:

Metric              Value
Pages               3
Links               6
Unique targets      3
Dead links          0
Orphans             0

…then zetl parsed everything correctly. The .zetl/ cache now holds the graph, the search index, and (if built with --features history) a snapshot.

Check vault health

zetl check

With three internally-consistent files, you should see No issues found (or an empty diagnostics block in JSON mode). Typical things check catches as a vault grows:

Dead links — [[Some Page]] where no file Some Page.md exists.
Orphan pages — notes nothing links to and that link to nothing.
Syntax errors — malformed wikilinks, broken frontmatter.

Run zetl check --dead-links or zetl check --orphans to isolate one category. See Finding Orphans and Dead Links for the full workflow.

Query the graph

Who points at Projects?

zetl backlinks "Projects"

Answer: both 2026 Goals and Daily Journal do. What does 2026 Goals link out to?

zetl links "2026 Goals"

Answer: Daily Journal and Projects. Two hops:

zetl path "Daily Journal" "Projects"

zetl finds the shortest path through your link graph — in this three-note case, one hop, but the same command scales to hundred-hop traversals in a large vault.

Read it in the browser

zetl serve
# Serving on http://localhost:3000

You get a three-column layout: sidebar with all three pages, rendered Markdown in the middle, backlinks and transclusion cards on the right. Click [[2026 Goals]] in Projects.md and the page navigates without reload — the graph widget in the corner updates its highlighted node.

Edits in the browser save straight back to ~/notes/*.md. Your text editor sees the update immediately. zetl re-indexes in the background.

Wikilink syntax cheat-sheet

Everything you just used, plus a few extras you’ll want:

Form	Meaning
`[[Projects]]`	Link to the page `Projects.md`.
`[[Projects\|current work]]`	Same link, displayed as “current work”.
`[[2026 Goals#Writing]]`	Link to the Writing heading in `2026 Goals.md`.
`[[Projects^abc123]]`	Link to the block with ID `abc123`.
`![[Daily Journal]]`	Embed (transclude) the target’s content.

See Wikilinks for every variant and Linking Pages for the day-to-day workflow.

What just happened

You made a folder, wrote three Markdown files, and pointed zetl at it. That’s a vault. Add 397 more files and you have a Zettelkasten. zetl never wrote to any of your notes; everything it needed to remember lives in ~/notes/.zetl/ and can be deleted without losing a word.

Writing Pages — titles, Markdown flavours, frontmatter conventions.
Linking Pages — aliases, heading links, block references, day-to-day practice.
The Link Graph — how zetl thinks about your notes.
Finding Orphans and Dead Links — keeping the vault healthy as it grows.

Backlinks

Linked Pages

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

Finding Orphans and Dead Links

zetl check is the vault-health command. It reports three kinds of problem — dead links, orphan pages, and syntax errors — and optionally a fourth, SPL diagnostics, if you use the reasoning layer. Run it before a big refactor, before a publish, and in CI.

zetl check

Exits non-zero if anything at error level is found. That makes it a drop-in CI step.

The two main health signals

Dead links

A dead link is a [[wikilink]] that points at a page that does not exist. You typed [[Zettelkasten Methog]] and meant [[Zettelkasten Method]]; or you deleted a page without updating the notes that cited it.

zetl check --dead-links

Two ways to fix each one:

Create the page. If the link represents a real idea that deserves a page, the dead link is a prompt: go write the note. This is the positive use of dead links — they are a TODO list generated by your past self.
Rename or delete the link. If the target was a typo, fix the typo. If the idea no longer deserves a page, remove the link or replace it with plain prose.

The zetl similar "Zettelkasten Methog" command (see Similar Pages) pairs naturally with dead-link review: for each dead link, check whether you meant an existing page.

Orphans

The Link Graph

zetl thinks about your vault as a directed graph: pages are nodes, wikilinks are edges. Every command you will run — backlinks, path, orphans, export, the graph widget in zetl serve — is a query over this graph. Understanding the model makes the rest of zetl obvious.

What a node is

A node is one page: one .md file in your vault. The node’s identity is its filename (minus .md, case-normalised). The node’s content is what’s between the frontmatter and the end of file. That’s it — no IDs, no database keys.

What an edge is

Every [[wikilink]] you write is an edge from the current page to the target. Edges are directed: A.md writing [[B]] creates an edge A → B, not B → A. Backlinks are the inverse — the set of pages that link at you.

The graph distinguishes:

Plain edges — [[Page]], [[Page|alias]]
Heading edges — [[Page#heading]]
Block edges — [[Page^b3a9f1]], which target a specific block
Embed edges — ![[Page]], same edge, different rendering

All four contribute to forward-links and backlinks. An aliased link is still an edge to Page, not to alias.

Dead links and orphans

Two graph concepts show up often enough to name:

A dead link is an edge whose target has no matching file. The edge exists in the graph; the node on the far end is empty. zetl check --dead-links lists them.
An orphan is a node with no inbound edges — nothing links to it. An orphan may still have outbound links. zetl check --orphans lists them.

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

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.