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

…just works in zetl with no changes.

Hidden folders and `.obsidian/`

By default zetl skips dotdirs — .obsidian/, .trash/, .git/, and friends — during vault scans. Your Obsidian config, plugins, and workspace state are invisible to zetl, which is almost always what you want.

If you need zetl to walk those folders (for example, to publish .obsidian/ docs as part of a static site), pass --include-hidden:

zetl --include-hidden index
zetl --include-hidden build

.git/, .zetl/, and node_modules/ remain excluded regardless — they’re hardcoded in the scanner and not overridable.

See Organising Your Vault for the full layered exclusion model and .zetlignore.

Obsidian feature → zetl equivalent

Obsidian	zetl
Backlinks pane	`zetl backlinks "Page"` (CLI) or the right-rail backlinks in `zetl serve`.
Graph view	The Sigma-based graph widget in `zetl serve` / `zetl build`, plus `/_graph` full-screen. See The Link Graph.
Quick switcher	`zetl view` opens a page picker; `zetl search` for content.
Search	`zetl search "query"` (full-text), `zetl search --regex`, `zetl similar` for fuzzy page-name matching.
Tags (`#tag`)	Parsed from YAML `tags: [...]`. Query via `page.frontmatter.tags` in templates. See Tags and Frontmatter.
Embeds (`![[...]]`)	Same syntax; rendered inline in `zetl serve` / `zetl build`. See Embeds and Transclusion.
Canvas (`.canvas`)	Not supported. Canvas files are skipped.
Daily Notes plugin	Not supported as a plugin. Build daily files by hand or with a `pre-build` lifecycle hook.
Templater / Dataview	Not supported. The render-pipeline hooks (see Render Pipeline Hooks) are the zetl equivalent for transforming content mid-build.
Publish / Obsidian Sync	`zetl build` writes static HTML; Capability URLs share live views without a server.

What doesn’t port over

The parts of your Obsidian setup that live in .obsidian/ — plugins, workspace layout, hotkeys, themes, community plugin settings — don’t map into zetl, because zetl isn’t a GUI editor. Your notes port perfectly; your Obsidian environment does not.

Canvas files (.canvas) are skipped. The JSON format isn’t parsed.
Templater / QuickAdd / Dataview / Excalidraw — these are Obsidian-specific extensions that run inside the Obsidian app. For zetl, the nearest equivalent is Lifecycle Hooks (shell scripts at pre/post-build) or Render Pipeline Hooks (AST-level transforms during zetl build).
Daily Notes as a built-in feature doesn’t exist. Either create daily files manually or script them in a hook.
Plugins in general. zetl’s extension model is render hooks + ecosystem adapters (Pandoc, mdBook, remark). See Plugin Ecosystems.

Running both at once

This is the comfortable path while you try zetl. Open your vault in Obsidian as usual; run zetl serve from the same directory in another terminal. Both processes read the same .md files on disk.

Save a note in Obsidian → zetl’s serve watcher picks up the change and re-indexes.
Save a note in zetl serve’s browser editor → the file on disk updates; Obsidian’s file-watcher reloads.

The only coordination point is .zetl/, which is zetl’s private cache. Obsidian ignores it. Add .zetl/ to your .gitignore if you version-control the vault.

Read-only guarantee

zetl never modifies your .md files during index, check, view, or build. serve writes only when you edit and save through its browser UI. If that still feels too close, run your whole session in a read-only copy:

cp -r ~/Documents/ObsidianVault /tmp/vault-copy
zetl -d /tmp/vault-copy index
zetl -d /tmp/vault-copy serve

Backlinks

Linked Pages

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

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:

Quick Start

Sixty seconds from install to first result. This page uses the demo-vault/ bundled with the zetl repo — a self-referential knowledge base about zetl itself. Run each command; what you see should match what’s described.

Install zetl

macOS / Linux:

curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

Windows: download zetl-windows-x86_64.zip, extract zetl.exe, and add it to your PATH.

The installer puts zetl in ~/.local/bin, generates the man page, and wires up shell completions. Full details, feature flags, and source-build instructions: Installation.

Get the demo vault

Clone the zetl repo to get demo-vault/:

git clone https://codeberg.org/anuna/zetl && cd zetl
ls demo-vault/
# architecture/  concepts/  decisions/  features/  theories/  Demo Script.md ...

Build the index

zetl -d ./demo-vault index

What is zetl

zetl is a command-line tool that reads a folder of Markdown notes, understands the [[wikilinks]] between them, and lets you query, search, and reason over the resulting graph. Your notes stay on your laptop, in the filesystem, in plain .md files. zetl just reads them.

What it does

Point zetl at a folder of notes and it will:

Parse wikilinks — every [[Zettelkasten Method]], [[Book Notes|my reading list]], [[Daily Journal#2026-04-20]], and ![[Project Brief]] embed.
Build a link graph — who points at whom, how many hops between two pages, which pages have no inbound links.
Answer questions — forward links, backlinks (including multi-hop), shortest path between two pages, orphaned notes, dead links, pages with similar names.
Search content — full-text and regex across the vault, with frontmatter and code-block awareness.
Render the vault — as a terminal viewer (zetl view), a local web server (zetl serve), or a static HTML site (zetl build).
Reason over SPL — optional defeasible-logic layer that reads spl code blocks from your notes and draws conclusions with full provenance. See What is SPL.

A concrete example. You have ~/notes/ with 400 Markdown files. You run:

cd ~/notes
zetl index
zetl backlinks "Zettelkasten Method" --depth 2
zetl check --dead-links

zetl tells you which notes cite Zettelkasten Method directly, which cite those, and flags every [[broken link]] in the vault. No database. No daemon. The cache lives in ~/notes/.zetl/ and is disposable.

Who it’s for

Solo knowledge workers and small teams who:

Already keep notes in plain Markdown and don’t want to migrate.
Use [[wikilinks]] (Obsidian, Logseq, Foam, Dendron, or hand-written — all work).
Want command-line answers about their graph, not just a GUI.
Care about local-first tools that treat your files as source of truth.

With --collab, small teams can co-edit the same vault over WebSocket with passkey auth and real-time CRDT sync. See Running a Team Server.

Plugin Ecosystems

Rather than rewriting every transform in zetl, reuse the ones that already exist. The plugin-ecosystem adapters let a render-pipeline hook delegate to a Pandoc filter, an mdBook preprocessor, or a remark plugin. zetl handles AST translation in both directions; the hook manifest just names the plugin.

If you already have a Lua filter you wrote for an academic paper, or an mdbook-mermaid you use for a book, you can reach for it from a zetl vault without a rewrite.

Declaring an ecosystem hook

Pick the stage, name the ecosystem, point at the plugin. A Pandoc Lua filter in the transform stage:

# .zetl/hooks/transform.d/smallcaps.py.toml
ecosystem = "pandoc"
lua_filter = "filters/smallcaps.lua"   # OR: exec = "pandoc-smallcaps"

stage = "transform"
mode  = "persistent"
extension_id = "smallcaps"

Each ecosystem has its own required/optional manifest fields:

Ecosystem	Required	Optional
`pandoc`	`exec` or `lua_filter`	`args`
`mdbook`	`exec`	`scope = "page" \| "vault"`
`remark`	`package`	`version`, `options`

Pandoc hooks default to the transform stage; mdBook preprocessors run at pre-parse (they operate on raw Markdown); remark targets the transform stage with the mdast AST type. See each ecosystem’s deep-dive guide in the main repo’s docs/ecosystems/ directory for translation details and per-plugin quirks.

Scaffolding

The authoring CLI seeds the right manifest fields (and, for Pandoc, drops a starter identity Lua filter on disk) when you pass --ecosystem:

zetl hook new transform smallcaps --ecosystem pandoc
zetl hook new pre-parse admonish  --ecosystem mdbook
zetl hook new transform math      --ecosystem remark

The generated hook works out of the box: zetl hook test smallcaps will pass against the seeded fixture. From there you edit the filter, add selectors, and tune the behavioural contract like any other pipeline hook.

Render Pipeline Hooks

Transform a page mid-build by mutating a typed AST rather than its serialised form. Unlike the around-the-build Lifecycle Hooks, render-pipeline hooks run on every matching page as it moves through the renderer — callouts, custom blocks, link rewrites, banner injection, citation expansion, anything that needs to touch structure.

Hooks live under .zetl/hooks/<stage>.d/ (or .zetl/themes/<name>/hooks/<stage>.d/ for theme-bundled ones) and stay resident for the duration of a build via a JSON-lines protocol over stdin/stdout. No per-page subprocess spawn, no shell fork on every paragraph.

The three stages

Stage	Payload at the boundary	Typical use
`pre-parse`	raw Markdown string	Frontmatter rewrites, include/import expansion, prelude injection
`transform`	typed AST (`zetl-ast` schema v1)	Callouts, custom blocks, link-graph mutations, ecosystem plugins
`post-render`	HTML fragment string	Banner injection, post-processing, accessibility fixes

Stages run in that order, once per page. A pre-parse hook sees what the author wrote; a transform hook sees the parsed tree; a post-render hook sees the nearly-final HTML.

A hook is two files

Scaffold one with the authoring CLI — it writes the skeleton, a sidecar manifest, and a seeded fixture so zetl hook test passes immediately:

zetl hook new transform callouts                # Python (default)
zetl hook new pre-parse prelude --lang sh       # shell
zetl hook new post-render banner --lang js      # JavaScript

Resulting layout:

.zetl/hooks/transform.d/
  callouts.py            # persistent-mode skeleton (executable)
  callouts.py.toml       # sidecar manifest — composition reads <name>.<ext>.toml
tests/hook-fixtures/callouts/
  input.md
  expected.json          # golden output, seeded so `hook test` passes

The sidecar TOML manifest is where all the interesting configuration lives:

# .zetl/hooks/transform.d/callouts.py.toml
stage = "transform"
mode  = "persistent"
extension_id = "callouts"

[selector]
glob = "**/*.md"
frontmatter = "layout == 'note' && !draft"
content = "re:^> \\[!"          # pages containing callout syntax

[contract]
preserves = ["Wikilink", "Embed"]   # these node types must survive untouched
idempotent = true                    # running twice = running once
may_restructure = false              # pre-parse only; denied at transform
expansion_bound = 2.0                # output ≤ 2× input size

[timeouts]
run_ms = 200

Lifecycle Hooks

Git-style scripts that run at defined points during a zetl operation. Drop an executable into .zetl/hooks/ named after a lifecycle point, and zetl invokes it with structured JSON on stdin and a handful of ZETL_* environment variables.

These are separate from the AST-level Render Pipeline Hooks — lifecycle hooks fire around the build, not inside it. Use them to publish an RSS feed after zetl build, notify a chat room on on-save, or run a schema validator on post-check.

Lifecycle points

Hook	Fires	Can abort?
`pre-build`	Before `zetl build` renders pages	Yes
`post-build`	After `zetl build` completes	No (warning on non-zero)
`post-index`	After `zetl index` completes	No
`post-check`	After `zetl check` collects diagnostics	No
`pre-serve`	Before `zetl serve` binds	Yes
`on-save`	After a page is saved via `zetl serve`	No
`on-agent`	When an agent API request arrives	No
`on-access-request`	When a user requests page access (collab mode)	No

“Can abort” means a non-zero exit cancels the parent operation; every other hook just logs a warning and continues.

What a hook receives

stdin — a JSON object with vault metadata, the page list, the link graph, and hook-specific fields (e.g. saved for on-save). If history is enabled, a history object is included.
environment — ZETL_HOOK (the lifecycle name), ZETL_VAULT_ROOT, ZETL_THEME, ZETL_VERSION, plus hook-specific vars: ZETL_OUT_DIR on build hooks, ZETL_PORT on serve hooks.
working directory — the vault root, regardless of where zetl was invoked from.
timeout — 30 seconds wall-clock. A hook that hangs is killed.

Writing a hook

Create an executable file named exactly after the lifecycle point (no extension):

# .zetl/hooks/post-build
#!/bin/bash
# Generate an RSS feed from pages with a `date:` frontmatter field.
set -euo pipefail

jq -r '
  .pages
  | map(select(.frontmatter.date))
  | sort_by(.frontmatter.date) | reverse | .[0:20]
  | map("<item><title>\(.title)</title><pubDate>\(.frontmatter.date)</pubDate></item>")
  | "<rss><channel>\(join(""))</channel></rss>"
' < /dev/stdin > "$ZETL_OUT_DIR/feed.xml"

Then mark it executable:

chmod +x .zetl/hooks/post-build

Capability URLs

Capability mode is zetl’s answer to: “I want to share my wiki with a dozen friends, read-only, without running a server, but I don’t want the whole internet reading it.” The output is a plain static site — hostable on any CDN, any S3 bucket, any sftp’d directory — where access is gated by a secret in the URL fragment. No accounts, no server-side auth, nothing to rotate but the URLs themselves.

If you want multi-user editing, you want Running a Team Server. Capability mode is for publishing.

The idea in one paragraph

Each page is encrypted at build time with a cohort-specific key. Invite URLs look like https://wiki.example.com/welcome.html#k=<base64-secret>. The #fragment — by design of the HTTP spec — is never sent to the server. The reader’s browser, executing a small JavaScript shim, pulls the key out of the fragment, decrypts the page locally, and verifies a vault-level Ed25519 signature so nobody can serve them a forged page. Revocation is per-cohort: you rotate the cohort’s salt and re-deploy, old URLs stop decrypting.

Formal spec: see docs/capability-mode.md in the zetl repo.

Setting up a capability site

1. Generate the keys

zetl cap genkey

This prints two secrets to stdout, exactly once:

ZETL_CAP_SECRET — the 48-byte content-encryption secret.
ZETL_CAP_SIGNING_KEY — the Ed25519 vault-signing private key.

Capture them somewhere safe (a secret store, a password manager, a sealed envelope). You’ll need ZETL_CAP_SECRET on every build and ZETL_CAP_SIGNING_KEY whenever you rotate the signing key.

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:

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:

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.