Block Reference

This page documents every block type the editor ships. Every block has a JSON shape, a renderer, and a programmatic insert path via editor.blocks.insert.

All blocks share the same envelope when serialised: id, type, data, and an optional tunes record.

The block shape

Every block serialises to the same JSON envelope. The id is assigned by the editor and can be omitted when constructing data programmatically.

{
  "id": "abc123",
  "type": "paragraph",
  "data": { "html": "Hello <b>world</b>" },
  "tunes": {}
}

alert

Highlighted call-out box with 4 variants.

{
  "type": "alert",
  "data": { "html": "Your session will expire in 5 minutes.", "variant": "warning" }
}

audio

Audio block. Consumed via the audioUploader callback on Editor.create.

{
  "type": "audio",
  "data": { "url": "/media/podcast.mp3", "caption": "Episode 12", "alignment": "center" }
}

checklist

Interactive checkbox list with per-item checked state.

{
  "type": "checklist",
  "data": {
    "items": [
      { "text": "Install the package", "checked": true },
      { "text": "Mount the editor", "checked": false }
    ]
  }
}

code

Syntax-highlighted code block. 50 languages are supported, including typescript, python, rust, go, ruby, swift and kotlin.

{
  "type": "code",
  "data": { "code": "const x = 42;", "language": "typescript", "theme": "github-dark", "showCopy": true }
}

collapsible

A collapsible section with a title and nested child blocks. Unknown child block types are preserved verbatim, so newer documents survive older renderers.

{
  "type": "collapsible",
  "data": {
    "html": "Details",
    "open": true,
    "children": [{ "type": "paragraph", "data": { "html": "Hidden until opened." } }]
  }
}

collection

Embeds a live collection view by id. The block stores only the collection identity; the server owns the shape and the data.

{
  "type": "collection",
  "data": { "collectionId": "c-42" }
}

columns

A multi-column layout of 2 to 4 columns, each holding its own list of child blocks.

{
  "type": "columns",
  "data": {
    "columns": [
      [{ "type": "paragraph", "data": { "html": "Left" } }],
      [{ "type": "paragraph", "data": { "html": "Right" } }]
    ]
  }
}

date

A calendar date, stored timezone-free so every collaborator agrees on it.

{
  "type": "date",
  "data": { "date": "2026-08-31" }
}

delimiter

Visual separator between sections.

{
  "type": "delimiter",
  "data": { "variant": "line" }
}

doc_card

A rich link card for another document. It stores the referenced page id plus a display snapshot that hosts refresh on rename.

{
  "type": "doc_card",
  "data": { "pageId": "p-7", "title": "Release notes", "icon": "📄" }
}

embed

An embedded link. The block stores the URL; the provider and embed markup are derived at render time, with unfurl fields as the fallback card.

{
  "type": "embed",
  "data": { "url": "https://www.youtube.com/watch?v=abc123" }
}

file

A file attachment with a download link, a name, and optional size and content type.

{
  "type": "file",
  "data": { "url": "/files/notes.pdf", "name": "notes.pdf", "size": 2048, "contentType": "application/pdf" }
}

glance

A label and value summary panel: rows of facts read at a glance, with an optional caption and background variant.

{
  "type": "glance",
  "data": {
    "caption": "Facts",
    "rows": [{ "label": "Version", "html": "<b>1.0</b>" }],
    "variant": "plain"
  }
}

header

Top-level and section headings (h1 to h6). Inline tools work inside the html payload.

{
  "type": "header",
  "data": { "html": "Getting started", "level": "h2" }
}

image

Image block with caption and alt text. Consumed via the imageUploader callback on Editor.create.

{
  "type": "image",
  "data": { "url": "/img/hero.jpg", "caption": "Hero image", "alt": "A hero", "alignment": "center" }
}

latex

LaTeX math, stored as source and typeset at render time. A better renderer later improves every document that already exists.

{
  "type": "latex",
  "data": { "source": "\\frac{a}{b}" }
}

list

Ordered or unordered list. Each item is html.

{
  "type": "list",
  "data": { "type": "unordered", "items": ["First item", "Second item"] }
}

mermaid

A Mermaid diagram, stored as source and drawn at display time, never as a raster.

{
  "type": "mermaid",
  "data": { "source": "flowchart TD\n  A --> B" }
}

openapi

Renders an interactive API reference from an OpenAPI 3.x document, inline or fetched from a URL, with server pickers and code snippets.

{
  "type": "openapi",
  "data": { "url": "/api/openapi.json", "defaultServer": "https://api.example.com" }
}

paragraph

Rich-text paragraph. Accepts inline tool markup such as bold, italic, code, link, marker, and tooltip.

{
  "type": "paragraph",
  "data": { "html": "This is a <b>paragraph</b> with inline markup." }
}

quote

Blockquote with an optional author attribution.

{
  "type": "quote",
  "data": { "html": "The best way to predict the future is to invent it.", "author": "Alan Kay" }
}

sketch

A freehand drawing stored as strokes, never a raster, so it stays editable and scales cleanly.

{
  "type": "sketch",
  "data": { "strokes": [{ "points": [0, 0, 10, 10], "color": "#ff0000", "width": 3 }] }
}

table

Data grid. First row can be used as a header; each cell is html.

{
  "type": "table",
  "data": {
    "data": [["Name", "Type"], ["html", "string"], ["variant", "AlertVariant"]],
    "caption": "AlertData fields",
    "showDownload": false
  }
}

toc

A table of contents derived from the document headers at render time. It stores no data of its own.

This block stores no fields; the list is derived from the document headers at render time.

{
  "type": "toc",
  "data": {}
}

updates

A live activity feed for a document. It stores identity, never a snapshot, so it keeps showing current activity.

{
  "type": "updates",
  "data": { "pageId": "p-7" }
}

video

Video block. Consumed via the videoUploader callback on Editor.create.

{
  "type": "video",
  "data": { "url": "/media/demo.mp4", "caption": "Product demo", "alignment": "center" }
}