Block-Referenz

Diese Seite dokumentiert jeden Blocktyp, den der Editor mitbringt. Jeder Block hat eine JSON-Form, einen Renderer und einen programmatischen Einfügepfad über editor.blocks.insert.

Alle Blöcke teilen beim Serialisieren dieselbe Hülle: id, type, data und einen optionalen tunes-Datensatz.

Die Blockstruktur

Jeder Block wird in dieselbe JSON-Hülle serialisiert. Die id wird vom Editor zugewiesen und kann beim programmgesteuerten Aufbau von Daten weggelassen werden.

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

alert

Hervorgehobene Hinweisbox mit 4 Varianten.

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

audio

Audioblock. Wird über den audioUploader-Callback bei Editor.create verarbeitet.

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

checklist

Interaktive Checkbox-Liste mit Markierungsstatus pro Element.

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

code

Codeblock mit Syntaxhervorhebung. 50 Sprachen werden unterstützt, darunter typescript, python, rust, go, ruby, swift und kotlin.

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

collapsible

Ein einklappbarer Abschnitt mit Titel und verschachtelten Kindblöcken. Unbekannte Kindblocktypen bleiben unverändert erhalten, sodass neuere Dokumente ältere Renderer überleben.

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

collection

Bettet eine Live-Sammlungsansicht per id ein. Der Block speichert nur die Identität der Sammlung; Form und Daten gehören dem Server.

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

columns

Ein mehrspaltiges Layout mit 2 bis 4 Spalten, von denen jede ihre eigene Liste von Kindblöcken hält.

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

date

Ein Kalenderdatum, ohne Zeitzone gespeichert, damit sich alle Mitwirkenden darauf einigen.

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

delimiter

Visueller Trenner zwischen Abschnitten.

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

doc_card

Eine reichhaltige Linkkarte für ein anderes Dokument. Sie speichert die id der referenzierten Seite und einen Anzeige-Schnappschuss, den Hosts bei einer Umbenennung aktualisieren.

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

embed

Ein eingebetteter Link. Der Block speichert die URL; Anbieter und Einbettungs-Markup werden beim Rendern abgeleitet, die Unfurl-Felder dienen als Ausweichkarte.

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

file

Ein Dateianhang mit Download-Link, Namen sowie optionaler Größe und optionalem Inhaltstyp.

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

glance

Ein Zusammenfassungspanel aus Beschriftungen und Werten: Faktenzeilen auf einen Blick, mit optionaler Beschriftung und Hintergrundvariante.

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

header

Überschriften der obersten Ebene und Abschnittsüberschriften (h1 bis h6). Inline-Tools funktionieren innerhalb der html-Nutzlast.

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

image

Bildblock mit Beschriftung und Alt-Text. Wird über den imageUploader-Callback bei Editor.create verarbeitet.

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

issues

Eine Tabelle der verknüpften Issues, beim Rendern aus den Issue-Chips und -Karten der Seite abgeleitet (Issue, Titel, Status, Zuständige). Sie speichert keine eigenen Daten.

Dieser Block speichert keine Felder; die Zeilen werden beim Rendern aus den Issue-Chips und -Karten der Seite abgeleitet.

{
  "type": "issues",
  "data": {}
}

latex

LaTeX-Mathematik, als Quelltext gespeichert und beim Rendern gesetzt. Ein besserer Renderer verbessert später jedes bereits existierende Dokument.

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

list

Geordnete oder ungeordnete Liste. Jedes Element ist html.

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

mermaid

Ein Mermaid-Diagramm, als Quelltext gespeichert und bei der Anzeige gezeichnet, nie als Rasterbild.

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

openapi

Rendert eine interaktive API-Referenz aus einem OpenAPI-3.x-Dokument, inline oder von einer URL geholt, mit Serverauswahl und Code-Schnipseln.

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

paragraph

Rich-Text-Absatz. Akzeptiert Inline-Tool-Markup wie bold, italic, code, link, marker und tooltip.

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

quote

Blockzitat mit optionaler Autorenangabe.

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

sketch

Eine Freihandzeichnung, als Striche gespeichert, nie als Rasterbild: Sie bleibt bearbeitbar und skaliert sauber.

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

table

Datenraster. Die erste Zeile kann als Kopfzeile verwendet werden; jede Zelle ist html.

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

toc

Ein Inhaltsverzeichnis, das beim Rendern aus den Überschriften des Dokuments abgeleitet wird. Es speichert keine eigenen Daten.

Dieser Block speichert keine Felder; die Liste wird beim Rendern aus den Überschriften des Dokuments abgeleitet.

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

updates

Ein Live-Aktivitätsfeed für ein Dokument. Er speichert Identität, nie einen Schnappschuss, und zeigt so weiterhin die aktuelle Aktivität.

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

video

Videoblock. Wird über den videoUploader-Callback bei Editor.create verarbeitet.

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