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.

Neither is an error. A dead link can be a stub you intend to fill in. An orphan can be a brand-new note waiting for its first backlink, or an index page whose incoming links are all from the sidebar. See Finding Orphans and Dead Links for when to care.

Backlinks are the graph’s secret

The real reason wikilink graphs are useful is the backlink view. Your outbound links capture what you were thinking about when you wrote the page. The inbound links capture what the rest of your vault thinks of it — often including connections you forgot you made. Every page in zetl serve has a backlinks pane for exactly this reason. See Backlinks.

Traversal

Because it’s a graph, you can ask graph-shaped questions:

Multi-hop backlinks. zetl backlinks "Rust" --depth 2 walks two steps inward.
Shortest path. zetl path "Note A" "Note B" finds the chain that connects two ideas, if one exists.
Following forward links. zetl links "Some Page" is the outbound side. See Following Links.
Full export. zetl export dumps the whole graph as JSON for external tools.

Incremental rebuild

The graph is not recomputed from scratch on every command. zetl index walks the vault once, and uses a two-tier cache keyed on mtime + content hash:

If the file’s mtime matches the cache, assume unchanged — skip.
If the mtime changed, hash the content and compare. If the hash matches (mtime-only touch), skip parsing.
Otherwise, reparse the file, update its outbound edges, and invalidate downstream inverses.

The result: reindexing a vault after editing three files takes about as long as parsing three files, not the whole tree. The cache lives in .zetl/ and is safe to delete.

Staying out of your way

zetl never modifies a page to “fix” the graph. A renamed target stays a dead link until you rename its incoming references too. zetl check tells you what changed; the edit is yours. See Local-first.

Backlinks

Linked Pages

Searching

zetl search scans your vault for a string and prints the matches, with context. It is deliberately small: a fast text finder for when you remember a phrase but not which note it lives in.

zetl search "attention is all you need"

No regex engine, no query DSL. If you want regex, pipe the raw index through rg. What zetl gives you instead is graph-aware narrowing.

The two flags you will actually use

Flag	What it does
`--near "Zettelkasten Method"`	Only match pages within `--depth` hops of that page
`--case-sensitive`	Exact case, no folding

--near is the one most people miss. A keyword search over 4,000 notes gives you noise; a search restricted to “notes that cite Zettelkasten Method or one link away” gives you signal.

# Every note mentioning "CRDT" anywhere in the vault
zetl search "CRDT"

# Every note about CRDTs within two hops of my reading list
zetl search "CRDT" --near "2026 Research Plan" --depth 2

Other useful flags:

--path "journal/**" — glob filter on file paths.
--context 120 — widen the snippet from the default 40 characters.
--limit 200 — default is 50; raise for grep-replace workflows.

See CLI Overview for the full list.

JSON when piped

When stdout is a pipe or redirect, zetl search auto-switches to JSON. This is the contract that lets you chain searches into scripts:

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.

Following Links

Three commands walk the forward-link graph: zetl links for a page’s neighbours, zetl path for the shortest route between two pages, and zetl export for dumping the whole graph as JSON. Together they turn your vault into a navigable graph you can query from the shell.

`zetl links` — forward neighbours

zetl links "Zettelkasten Method"

Prints every page that Zettelkasten Method links to. This is the complement of Backlinks: forward links are what this page cites; backlinks are what cites it.

Walk further with --depth:

# Direct forward links
zetl links "2026 Research Plan"

# Two hops: pages linked from pages linked from the plan
zetl links "2026 Research Plan" --depth 2

Useful flags:

Flag	Use
`--depth N`	Multi-hop forward traversal
`--context 80`	Show surrounding prose of each link
`--fuzzy`	Tolerate typos in the source page name

See CLI Overview for the rest.

`zetl path` — shortest route between two pages

zetl path "CRDT" "Zettelkasten Method"

CRDT
-> Collaborative Editing
-> Knowledge Management
-> Zettelkasten Method

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

Backlinks

zetl backlinks "Page" lists every page that links to Page. It is the quiet workhorse of a wikilink system — more useful, over time, than the links you write yourself.

zetl backlinks "Zettelkasten Method"

Output: the file path, the line of the match, and (with --context N) a snippet of the surrounding prose.

Why backlinks matter

Forward links are a claim you made at the time of writing. A backlink is every claim anyone ever made that referred back to this idea — including you, six months later, with more context. That asymmetry is the whole research payoff:

You read a paper and start a note on it. A year later the note has eight backlinks: three from project docs, two from meeting minutes, one from a book review. You did not plan any of that. The graph assembled it.
You are revisiting an old concept page. Instead of re-reading it in isolation, you walk its backlinks — every context in which you once found it relevant. That is a research tool disguised as a list.

Forward links (see Following Links) answer what does this page talk about? Backlinks answer what talks about this page? The second question is almost always more interesting for notes older than a few weeks.

Multi-hop with `--depth`

By default zetl backlinks returns direct, one-hop references. --depth N walks the reverse graph:

# Direct backlinks only
zetl backlinks "Zettelkasten Method"

# Every page that reaches "Zettelkasten Method" in up to 3 reverse hops
zetl backlinks "Zettelkasten Method" --depth 3

Depth 2–3 is where the transitive structure gets interesting: you find the notes that cite notes that cite this concept. Depth 5+ tends to return most of your vault — the graph is small-world.

Local-first

zetl is local-first. That phrase is doing real work — not “runs locally” and not “offline-capable”, but a specific design stance about whose computer owns your notes. This page is the philosophy; every other design choice in zetl follows from it.

The principles

Your files are the source of truth. Not a database, not a cloud tenant, not a proprietary binary format. A zetl vault is a directory of plain .md files. Whatever any zetl command says about your vault, the Markdown on disk is the authority. If zetl and the files disagree, the files win.

zetl never modifies your Markdown. Indexing, reasoning, rendering, validation — none of these rewrite your notes. Wikilinks stay wikilinks; frontmatter stays whatever YAML you wrote. The only bytes zetl writes are under .zetl/ (its cache) and, optionally, an output directory from zetl build.

Everything in .zetl/ is disposable. Link index, block hashes, snapshot history, reasoning theory — all of it is cache, derived from your files. Delete .zetl/ and zetl index rebuilds it. Commit your vault without it; share vaults across machines by syncing the .md files alone.

Works offline. zetl is a single binary that reads from and writes to your local filesystem. No network is required for any core operation — indexing, searching, viewing, building, reasoning. A machine in airplane mode has the full feature set.

Data outlives the tool. If zetl disappears tomorrow, or if you decide it’s not for you, your vault is still a folder of Markdown files. Open them in any text editor, any other wikilink tool, any static site generator. You did not sign up for a migration problem.

Why this matters for knowledge work

A second brain is only useful if you trust it to still be there in ten years. Most knowledge tools violate at least one of the above: they own the format, they own the storage, they own the sync layer, or they break when offline. The cost compounds — every note you write increases your exposure to someone else’s product decisions.

Local-first flips the dependency. You own the files. Tools like zetl read them and give you views — a graph, a search index, a rendered site, a reasoning layer — without taking ownership. When a better tool comes along, your vault is already portable to it.

What local-first does not mean

Blocks

zetl breaks every page into blocks — headings, paragraphs, code fences, lists, tables, blockquotes, and SPL fragments — and gives each block a stable hash. This turns a page into a small Merkle tree of content, which is what makes [[Page^block-id]] links work, what makes the incremental cache fast, and what will later make sync possible.

What a block is

A block is the smallest unit of page content zetl tracks. Parsing a page yields a sequence of typed blocks:

Type	Example
`heading`	`## Origins`
`paragraph`	Regular prose, one logical paragraph per block
`code`	A fenced ``` code block (any language)
`spl`	A fenced ```spl block (only with `--features reason`)
`list`	A top-level list; nested items stay inside
`table`	A pipe or grid table
`blockquote`	A `> …` quoted section
`frontmatter`	The YAML header, if present

List what’s in a page:

zetl blocks "Zettelkasten Method"
zetl blocks "Zettelkasten Method" --type heading

Why content-addressable

Every block’s content is hashed with BLAKE3, and the whole page is a Merkle tree with block hashes as leaves. “Content-addressable” means the hash identifies the content, not a location. This has three consequences that matter to you.

1. Block links survive file moves

[[Some Page^b3a9f1]] links to the block whose hash starts with b3a9f1. Rename Some Page.md to Renamed Page.md and the hash doesn’t change — the block is the same content. zetl can still resolve the link. It keeps pointers to what you said, not to where it lived.

Resolve a hash back to its source:

zetl blocks --resolve b3a9f1

The Link Graph

What a node is

What an edge is

Dead links and orphans

Backlinks are the graph’s secret

Traversal

Incremental rebuild

Staying out of your way

Related

Backlinks