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:

---
title: Seeing Like a State
tags: [book, political-theory]
---

# Seeing Like a State

James C. Scott's central move is to define legibility as a prerequisite for
state power. The core definition is worth pinning down:

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

Taylorism extends this into the workplace. See [[Scientific Management]].

Essays/Legibility and Craft.md:

---
title: Legibility and Craft
tags: [essay, draft]
---

# Legibility and Craft

Scott's definition is the one I keep returning to:

![[Seeing Like a State^legibility-def]]

What Taylor did in factories, the state had already been doing to
forests, peasant villages, and names. The parallel isn't incidental.

The essay quotes the book without duplicating the passage. Update the definition in the book note and every essay that embeds it picks up the change on the next zetl build.

For theme authors: `page.transclusion_cards`

If you’re writing a custom theme, the pre-rendered transclusion panel is available as page.transclusion_cards in the template context — a string of HTML ready to drop into your layout with | safe. See Customising the Look for theming, and Frontmatter Fields for the full template variable list.

Backlinks

Linked Pages

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

Customising the Look

Both Web Server and Static Site Export accept --theme <name>. A theme is a folder under .zetl/themes/<name>/ containing Minijinja templates, static assets, and an optional theme.toml. You only override what you want — everything you don’t ship falls back to the built-in defaults.

Why themes matter

The default theme is deliberately neutral so it works as a starting point, not an endpoint. You will probably want to change at least the colours, the typography, and the name at the top of the sidebar. Most of that is CSS-only: zetl exposes a versioned set of CSS custom properties so you can restyle the graph widget, the shell, and page typography without touching any HTML.

The bigger reason the theming story is careful: zetl’s graph widget is a single, persistent Sigma.js instance that survives page navigation (no flash, no re-layout). Themes that rewrite base.html have to preserve two DOM markers to keep that property — otherwise the graph re-initialises on every click. The contract below is the bargain that makes “persistent graph across a multi-page site” possible.

Creating a theme

Bundled themes are built into the binary. Export one to the vault to start editing:

zetl theme list                        # what's available
zetl theme export default paper        # copies default to .zetl/themes/paper/

Then point serve or build at it:

zetl serve --theme paper
zetl build --theme paper

What lives where

.zetl/themes/paper/
  theme.toml                  # config for SPA, graph, contract version
  base.html                   # master layout (sidebar, modals, scripts)
  index.html                  # vault landing page
  page.html                   # one page view
  folder.html                 # folder index
  help.html                   # /help page
  static/
    theme.css                 # your CSS
    enhance.js                # extra JS (runs per navigation)
    fonts/

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:

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:

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.

Frontmatter Fields

Frontmatter is YAML at the very top of a page, fenced by --- lines. zetl reads a handful of reserved keys — everything else passes through untouched for templates, hooks, and search. Nothing is required. A page with no frontmatter at all is valid.

---
title: Zettelkasten Method
tags: [pkm, method, luhmann]
date: 2024-06-03
status: draft
---

# Zettelkasten Method

Niklas Luhmann's slip-box system…

Reserved keys

zetl inspects these during indexing and rendering:

Key	Type	Meaning
`title`	string	Display title. Falls back to the filename stem when absent. Does not rename the file or change its wikilink target.
`parser`	string	Force a specific parser for this page. Values: `commonmark` (default) or `pandoc`. See Writing Pages.
`tags`	list of strings	Surfaced in templates and in `zetl search --path`. Drives the tag cloud.
`description`	string	Plain-text `<meta name="description">` / social-preview text. Falls back to the first paragraph.

No key is mandatory. Omit any of them and zetl infers a sensible default.

Parser selection

The parser: key wins over every other selector. Precedence (highest to lowest):

parser: in the page’s frontmatter
First matching [[parse.rule]] glob in .zetl/config.toml
Top-level [parse] default in .zetl/config.toml
commonmark (zetl’s built-in default)

An unknown parser name (e.g. parser: djot when only commonmark is registered) produces a per-page error and the page is skipped — the rest of the build proceeds. Run zetl ecosystem check to see which parsers are available.

Convention-only keys

The following are conventions, not reserved — zetl does not parse them, but templates and hooks consume them by name. Use whichever match your workflow.

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.