Référence des blocs

Cette page documente chaque type de bloc livré avec l'éditeur. Chaque bloc a une forme JSON, un moteur de rendu et un chemin d'insertion programmatique via editor.blocks.insert.

Tous les blocs partagent la même enveloppe une fois sérialisés : id, type, data et un enregistrement tunes facultatif.

La forme du bloc

Chaque bloc est sérialisé dans la même enveloppe JSON. L'id est attribué par l'éditeur et peut être omis lors de la construction de données par programmation.

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

alert

Encadré de mise en évidence avec 4 variantes.

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

audio

Bloc audio. Consommé via le callback audioUploader sur Editor.create.

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

checklist

Liste de cases à cocher interactive avec un état coché par élément.

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

code

Bloc de code avec coloration syntaxique. 50 langages sont pris en charge, dont typescript, python, rust, go, ruby, swift et kotlin.

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

collapsible

Une section repliable avec un titre et des blocs enfants imbriqués. Les types de blocs enfants inconnus sont conservés tels quels : les documents plus récents survivent aux moteurs de rendu plus anciens.

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

collection

Intègre une vue de collection en direct par son id. Le bloc ne stocke que l'identité de la collection ; le serveur possède la forme et les données.

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

columns

Une mise en page multicolonne de 2 à 4 colonnes, chacune portant sa propre liste de blocs enfants.

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

date

Une date de calendrier, stockée sans fuseau horaire pour que tous les collaborateurs soient d’accord.

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

delimiter

Séparateur visuel entre les sections.

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

doc_card

Une carte de lien riche vers un autre document. Elle stocke l'id de la page référencée et un instantané d'affichage que les hôtes actualisent lors d'un renommage.

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

embed

Un lien intégré. Le bloc stocke l'URL ; le fournisseur et le balisage d'intégration sont dérivés au rendu, les champs d'aperçu servant de carte de repli.

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

file

Une pièce jointe avec un lien de téléchargement, un nom, et une taille et un type de contenu facultatifs.

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

glance

Un panneau récapitulatif d'étiquettes et de valeurs : des lignes de faits lisibles d'un coup d'œil, avec une légende et une variante de fond facultatives.

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

header

Titres de premier niveau et titres de section (h1 à h6). Les outils en ligne fonctionnent à l’intérieur de la charge utile html.

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

image

Bloc image avec légende et texte alt. Consommé via le callback imageUploader sur Editor.create.

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

issues

Un tableau des tickets liés, dérivé au rendu des puces et cartes de tickets de la page (ticket, titre, statut, responsable). Il ne stocke aucune donnée propre.

Ce bloc ne stocke aucun champ ; les lignes sont dérivées des puces et cartes de tickets de la page au rendu.

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

latex

Des mathématiques LaTeX, stockées en source et composées au rendu. Un meilleur moteur plus tard améliore chaque document déjà existant.

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

list

Liste ordonnée ou non ordonnée. Chaque élément est du html.

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

mermaid

Un diagramme Mermaid, stocké en source et dessiné à l’affichage, jamais en image matricielle.

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

openapi

Affiche une référence d'API interactive à partir d'un document OpenAPI 3.x, en ligne ou récupéré depuis une URL, avec sélecteurs de serveur et extraits de code.

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

paragraph

Paragraphe en texte enrichi. Accepte le balisage des outils en ligne tels que bold, italic, code, link, marker et tooltip.

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

quote

Bloc de citation avec une attribution d’auteur facultative.

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

sketch

Un dessin à main levée stocké en traits, jamais en image matricielle : il reste modifiable et s'agrandit proprement.

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

table

Grille de données. La première ligne peut servir d’en-tête ; chaque cellule est du html.

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

toc

Une table des matières dérivée des titres du document au rendu. Elle ne stocke aucune donnée propre.

Ce bloc ne stocke aucun champ ; la liste est dérivée des titres du document au rendu.

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

updates

Un fil d'activité en direct pour un document. Il stocke une identité, jamais un instantané : il continue d'afficher l'activité actuelle.

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

video

Bloc vidéo. Consommé via le callback videoUploader sur Editor.create.

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