Referência de blocos

Esta página documenta cada tipo de bloco que o editor traz. Todo bloco tem uma forma JSON, um renderizador e um caminho de inserção programática via editor.blocks.insert.

Todos os blocos compartilham o mesmo envelope quando serializados: id, type, data e um registro tunes opcional.

A forma do bloco

Cada bloco é serializado no mesmo envelope JSON. O id é atribuído pelo editor e pode ser omitido ao construir dados programaticamente.

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

alert

Caixa de destaque com 4 variantes.

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

audio

Bloco de áudio. Consumido pelo callback audioUploader em Editor.create.

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

checklist

Lista de caixas de seleção interativa com estado marcado por item.

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

code

Bloco de código com realce de sintaxe. São suportadas 50 linguagens, incluindo typescript, python, rust, go, ruby, swift e kotlin.

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

collapsible

Uma seção recolhível com título e blocos filhos aninhados. Tipos de blocos filhos desconhecidos são preservados na íntegra, então documentos mais novos sobrevivem a renderizadores mais antigos.

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

collection

Incorpora uma visão de coleção ao vivo pelo id. O bloco armazena apenas a identidade da coleção; o servidor é dono da forma e dos dados.

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

columns

Um layout de múltiplas colunas, de 2 a 4, cada uma com sua própria lista de blocos filhos.

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

date

Uma data de calendário, armazenada sem fuso horário para que todos os colaboradores concordem com ela.

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

delimiter

Separador visual entre seções.

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

doc_card

Um cartão de link rico para outro documento. Armazena o id da página referenciada e um retrato de exibição que os hosts atualizam ao renomear.

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

embed

Um link incorporado. O bloco armazena a URL; o provedor e a marcação de incorporação são derivados na renderização, com os campos de unfurl como cartão de reserva.

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

file

Um anexo de arquivo com link de download, nome, e tamanho e tipo de conteúdo opcionais.

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

glance

Um painel de resumo de rótulos e valores: linhas de fatos lidas num relance, com legenda e variante de fundo opcionais.

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

header

Títulos de nível superior e de seção (h1 a h6). As ferramentas inline funcionam dentro do payload html.

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

image

Bloco de imagem com legenda e texto alt. Consumido pelo callback imageUploader em Editor.create.

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

issues

Uma tabela das issues ligadas, derivada na renderização das etiquetas e cartões de issues da página (issue, título, estado, responsável). Não armazena dados próprios.

Este bloco não armazena campos; as linhas são derivadas das etiquetas e cartões de issues da página na renderização.

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

latex

Matemática LaTeX, armazenada como fonte e composta na renderização. Um renderizador melhor depois melhora todo documento que já existe.

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

list

Lista ordenada ou não ordenada. Cada item é html.

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

mermaid

Um diagrama Mermaid, armazenado como fonte e desenhado na exibição, nunca como raster.

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

openapi

Renderiza uma referência de API interativa a partir de um documento OpenAPI 3.x, inline ou buscado de uma URL, com seletores de servidor e trechos de código.

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

paragraph

Parágrafo de rich text. Aceita marcação de ferramentas inline como bold, italic, code, link, marker e tooltip.

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

quote

Citação em bloco com atribuição de autor opcional.

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

sketch

Um desenho à mão livre armazenado como traços, nunca raster, então permanece editável e escala com nitidez.

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

table

Grade de dados. A primeira linha pode ser usada como cabeçalho; cada célula é html.

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

toc

Um sumário derivado dos cabeçalhos do documento na renderização. Não armazena dados próprios.

Este bloco não armazena campos; a lista é derivada dos cabeçalhos do documento na renderização.

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

updates

Um feed de atividade ao vivo para um documento. Armazena identidade, nunca um retrato, então continua mostrando a atividade atual.

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

video

Bloco de vídeo. Consumido pelo callback videoUploader em Editor.create.

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