Compatibility

zetl works with any Markdown vault that uses [[wikilink]] syntax. It never modifies your files.

(given obsidian-compatible)
(given logseq-compatible)
(given foam-compatible)
(given dendron-compatible)

Supported tools

Tool	Status	Notes
Obsidian	Full support	Standard `[[wikilink]]` syntax, aliases, headings, block references
Logseq	Full support	Wikilinks in Markdown mode
Foam	Full support	VS Code extension using `[[wikilinks]]`
Dendron	Full support	VS Code extension with Markdown wikilinks

What zetl reads

zetl parses [[target]], [[target|alias]], [[target#heading]], [[target^block-id]], and ![[embeds]]. It identifies pages by filename (case-insensitive, .md extension stripped). See concepts/Wikilinks for the full grammar.

What zetl ignores

Frontmatter (YAML between --- fences) — parsed but not treated as links
Code blocks — wikilinks inside fenced code are ignored
Comments — HTML comments are skipped

SPL is optional

concepts/Spindle Lisp embedding is entirely optional. Vaults work fine with just wikilinks — SPL adds reasoning capabilities on top. If you don’t use SPL, commands like zetl links, zetl check, and zetl tui work identically.

The `.zetl/` directory

The index and theory cache are stored in .zetl/ at the vault root. This directory is disposable — delete it any time, and zetl index rebuilds it. Add .zetl/ to your .gitignore. See architecture/Cache.

Rationale

Trust — users adopt CLI tools more readily when they can’t cause data loss

Composability — read-only access means zetl works alongside Obsidian, Logseq, Foam, Dendron, or any editor without conflict

Simplicity — no write path means no write bugs, no file locking, no corruption recovery

Disposability — the cache is derived data; losing it costs only a re-index

Syntax

Form

Example

Description

Basic

[[Cache]]

Link to a page

Aliased

[[Cache|caching layer]]

Display text differs from target

Heading

[[Cache#Design tension]]

Link to a specific heading

Block

[[Cache^summary]]

Link to a block ID

Embed

![[Cache]]

Embed the target page inline

Self-heading

[[#Syntax]]

Link to heading in same page

Formal grammar

wikilink = "[[" target ("#" fragment)? ("|" alias)? "]]" embed = "![[" target "]]" target = page-name fragment = heading | "^" block-id heading = text block-id = alphanumeric-with-hyphens alias = text page-name = text (may include "/" for path-qualified links)

Two-tier invalidation

Tier 1 (mtime): If a file’s modification time hasn’t changed, skip it entirely — no I/O beyond the stat call

Tier 2 (content hash): If the mtime changed but the BLAKE3 content hash matches the cached value, skip reprocessing

This handles the common case where git checkout updates mtimes without changing content.

SPL-specific invalidation

For the theory cache, zetl uses the SPL AST hash (not content hash) to determine if re-reasoning is needed. This means:

Prose edits that don’t touch SPL → no theory rebuild

SPL reformatting (comments, whitespace) → no theory rebuild

SPL logical changes (new facts, modified rules) → theory rebuild