Zettel

A portable JSON-based rich text AST to enable interoperability between apps, rich text editors, and other tools - basically Markdown but as an AST spec.

Zettel is German for "a scrap of paper that anything can be written on."

Zettel is the outcome of analyzing numerous rich text ASTs and editors. No common AST exists to express rich text. Zettel aims to become this shared spec for rich text, just like Markdown is for plain text.

🧩 Why Zettel?

One rich text document format. Many editors. Zero reinventing the wheel.

• 📦 Portable — serialize anywhere, validate everywhere
• 🔧 Extensible — just define new type nodes
• 🧘 Flexible — unknown nodes won’t break your app
• 📐 Structured — shared schema, unique keys, typed marks

Problems of existing solutions (and how Zettel solves them)

| Problem | Zettel Fix | | ---------------------------------------------------------------------------------------------- | ------------------------------------ | | Markdown & HTML are unsuited | Explicit JSON nodes | | Every app builds its own AST | Shared spec with extensibility | | Editor-tied formats like Slate/Lexical can't be shared | Editor-agnostic, storage-first model | | Other spec's don't define common nodes | zettel_* node spec with guarantees |

🚚 Interoperability Principles

| Principle | Practice | Why it matters | | ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------- | | 1. Single wrapper | Root node: { type: "zettel_doc", content: [...] } | Recognizable file type, room for metadata | | 2. Universal keys | Every node/mark has a unique zettel_key | Enables merging, diffing, comments, anchoring | | 3. Flat block array | Top-level content is always an array | Easy to stream, diff, or patch | | 4. Namespaced types | Built-ins use zettel_*; everything else is vendor space | Tools can skip unknowns, preserve them round-trip | | 5. Graceful fallback | Unknown blocks are ignored; unknown marks are stripped but text remains | Always renders, even with unknown content | | 6. JSON Schema validation | Canonical spec with runtime validation + TS types | Fail fast, validate early, ensure compatibility |

🔄 What graceful fallback looks like

| Original JSON | Viewer knows it? | Render result | | -------------------------------------------------------------------------- | ----------------- | ------------------------------ | | { "type": "custom_video_viewer", "src": "…" } | ✅ Yes | Inline video player | | same | ❌ No | <div>Unsupported block</div> | | { "type": "zettel_span", text: "@Max", marks: [{type: "acme_mention"}] } | ✅ Custom editor | @Max (styled mention) | | same | ❌ Generic editor | @Max (plain text) |

✅ Text is never lost. Unknown nodes are preserved and round-tripped safely.

🧠 Core Design

Zettel is designed for easy parsing, transformation, and interoperability.

• Flat block list — no nested trees
• Editor-agnostic — serialize anywhere, render everywhere
• Typed nodes — built-in types use the zettel_ prefix
• Every node has a unique key — great for diffs, comments, and syncing

🧾 Node rules (spec)

Every node MUST contain:

• type (string) – a namespaced identifier (e.g. "zettel_text_block", "acme_widget")
• zettel_key (string) – a unique key within the document

All other Zettel-reserved properties start with the zettel_* prefix. This ensures future compatibility and avoids naming collisions.

🧱 Built-in Nodes

zettel_text_block

{
  type: "zettel_text_block",
  zettel_key: "id",
  style: "zettel_normal", // or zettel_h1, zettel_quote, etc.
  children: [ZettelSpan]
}

zettel_span

{
  type: "zettel_span",
  zettel_key: "id",
  text: "Hello",
  marks: [ZettelMark]
}

Mark examples

{ type: "zettel_bold",   zettel_key: "m1" }
{ type: "zettel_italic", zettel_key: "m2" }
{ type: "zettel_link",   zettel_key: "m3", href: "https://…" }

✨ Examples

Basic text block

{
	"type": "zettel_doc",
	"content": [
		{
			"type": "zettel_text_block",
			"zettel_key": "x1",
			"style": "zettel_normal",
			"children": [
				{
					"type": "zettel_span",
					"zettel_key": "s1",
					"text": "Hello, world!",
					"marks": []
				}
			]
		}
	]
}

Rich marks

{
	"type": "zettel_span",
	"zettel_key": "s2",
	"text": "link",
	"marks": [{ "type": "zettel_link", "zettel_key": "m1", "href": "https://example.com" }]
}

Custom marks

{
	"type": "zettel_span",
	"zettel_key": "s3",
	"text": "@alice",
	"marks": [{ "type": "custom_mention", "zettel_key": "mention1", "id": "alice" }]
}

🔧 Extending Zettel

You can define custom marks or blocks.

Custom mark example

{
  type: "emoji_mark",
  zettel_key: "m4",
  emoji: "🚩"
}

Use it in a span

{
  type: "zettel_span",
  zettel_key: "s1",
  text: "important",
  marks: [{ type: "emoji_mark", zettel_key: "m4", emoji: "🚩" }]
}

Custom block example

{
  type: "code_block",
  zettel_key: "cb1",
  code: "console.log()",
  language: "js"
}

Generic editors will skip unknown blocks, but text remains readable and round-trappable.

🔁 Blocks vs. Styles for Diffing

Zettel models textual blocks with a single type (zettel_text_block) and separates their presentation using a style field. This separation makes diffs cleaner and identities stable.

• Stable identity: the block keeps the same zettel_key even when the style changes (e.g., normal → quote → heading).
• Smaller change sets: style flips are a single modification, not a delete+add+reorder at the document level.
• Simpler merging: downstream tools can treat style changes as non-structural updates to the same block.

Example: paragraph → blockquote

Before

{
	"type": "zettel_text_block",
	"zettel_key": "b1",
	"style": "zettel_normal",
	"children": [{ "type": "zettel_span", "zettel_key": "s1", "text": "Hello" }]
}

After (style change only)

{
	"type": "zettel_text_block",
	"zettel_key": "b1",
	"style": "zettel_quote",
	"children": [{ "type": "zettel_span", "zettel_key": "s1", "text": "Hello" }]
}

Contrast: ASTs that use different node types for paragraph vs. blockquote typically require a deletion (paragraph), an insertion (blockquote), and a document order update — creating noisier diffs and losing block identity. Zettel keeps the block identity intact by expressing presentation as style.