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.

Examples from a real note

# Research on Note-Taking

I've been reading about [[Zettelkasten Method]] — especially the idea of
[[Zettelkasten Method#atomic notes|atomic notes]]. One concrete claim from
[[Luhmann's Workflow^b3a9f1]] is worth pulling in verbatim:

![[Luhmann's Workflow^b3a9f1]]

See also [[Evergreen Notes]] and [[Andy Matuschak]].

This note has five outbound edges, one of which is an embed. If Evergreen Notes.md doesn’t exist yet, the link stays in place; zetl check will nag you politely.

What wikilinks are not

Not standard Markdown. [[...]] is an extension. zetl, Obsidian, Logseq, and a few others understand it; vanilla CommonMark does not. If you need to publish with a tool that doesn’t, zetl build turns wikilinks into regular <a href> links for you.
Not case-sensitive. Good: no one remembers capitalisation. If you prefer strict matching, name your files consistently.
Not paths. [[Some Page]] is not a file path. Do not write [[./notes/Some Page.md]] — it won’t work, and you do not need to.

Backlinks

Linked Pages

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

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:

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.

Embeds and Transclusion

An embed pulls another page’s content into the current page. A plain wikilink just points. An embed quotes — at full resolution, live, without duplicating the source.

The three embed forms

![[Zettelkasten Method]]              # the whole page
![[Zettelkasten Method#History]]       # one section (by heading)
![[Seeing Like a State^legibility-def]] # one block (by block id)

The leading ! is what turns a link into an embed. Everything else mirrors the plain wikilink forms — see Wikilinks.

How embeds render

When you run zetl serve or zetl build, embeds render as transclusion cards in a right-rail panel alongside the main content. The surrounding prose keeps flowing; the embedded material appears next to the paragraph that references it, in its own framed card showing the source page, the quoted region, and a link back to the original.

In the terminal viewer (zetl view), embeds render in the two-pane layout, with the source content expanded where the ![[...]] appears — see Terminal Viewer.

When to embed, when to link

Situation	Use
You’re pointing at related material	plain link `[[...]]`
You want the reader to see the quoted passage without leaving	embed `![[...]]`
You need a definition, claim, or diagram from elsewhere	embed a block `![[Page^id]]`
You’re writing a meta-page (index, reading list, MOC)	mostly links
You’re writing an essay that quotes your own notes	embeds for quoted material

A good heuristic: embed when you’d otherwise be tempted to copy-paste. Embeds stay in sync if the source changes; copies rot.

A worked example

Book Journal/Seeing Like a State.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: