블록 참조

이 페이지는 에디터가 제공하는 모든 블록 유형을 기록합니다. 모든 블록에는 JSON 형태, 렌더러, editor.blocks.insert를 통한 프로그래밍 방식 삽입 경로가 있습니다.

모든 블록은 직렬화될 때 동일한 엔벨로프를 공유합니다: id, type, data 및 선택적 tunes 레코드.

블록의 형태

모든 블록은 동일한 JSON 엔벨로프로 직렬화됩니다. id는 에디터가 할당하며 데이터를 프로그래밍 방식으로 구성할 때 생략할 수 있습니다.

JSON

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

alert

4가지 변형이 있는 강조 콜아웃 박스.

필드	타입	필수	설명
html	string	예	알림 메시지의 HTML 콘텐츠. 인라인 도구 마크업이 지원됩니다.
variant	'error' \| 'info' \| 'success' \| 'warning'	예	알림의 시각적 스타일. 다음 중 하나: error, info, success, warning.

JSON

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

audio

오디오 블록. Editor.create의 audioUploader 콜백을 통해 처리됩니다.

필드	타입	필수	설명
url	string	예	임베드할 오디오 파일의 URL.
caption	string	아니요	플레이어 아래에 표시되는 일반 텍스트 캡션.
alt	string	아니요	오디오 요소의 접근 가능한 레이블.
alignment	'center' \| 'left' \| 'right'	아니요	플레이어의 수평 정렬. 다음 중 하나: center, left, right.

JSON

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

checklist

항목별 체크 상태를 가진 대화형 체크박스 목록.

필드	타입	필수	설명
items	ChecklistItem[]	예	체크리스트 항목의 배열, 각각 text와 checked 상태를 가집니다.
items[].text	string	예	항목 레이블의 HTML 콘텐츠.
items[].checked	boolean	예	체크박스가 체크되어 있는지 여부.

JSON

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

code

구문 강조가 적용된 코드 블록. typescript, python, rust, go, ruby, swift, kotlin을 포함해 50개 언어를 지원합니다.

필드	타입	필수	설명
code	string	예	표시할 원시 코드 문자열.
language	CodeLanguage	아니요	구문 강조 언어. 기본값은 typescript입니다.
theme	CodeTheme	아니요	에디터 색상 테마. 기본값은 github-dark입니다.
showCopy	boolean	아니요	렌더링된 출력에 복사 버튼을 표시합니다.
syncKey	string	아니요	키를 공유하는 블록은 언어를 함께 전환합니다.
variants	CodeVariant[]	아니요	비어 있지 않으면 변형의 탭 스트립을 렌더링하며, 권위 있는 소스가 됩니다.

JSON

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

collapsible

제목과 중첩된 자식 블록이 있는 접을 수 있는 섹션입니다. 알 수 없는 자식 블록 유형은 그대로 보존되므로 최신 문서가 이전 렌더러에서도 살아남습니다.

필드	타입	필수	설명
html	string	예	인라인 HTML 형식의 섹션 제목입니다.
open	boolean	아니요	섹션을 펼친 상태로 렌더링할지 여부입니다.
children	Block[]	아니요	중첩된 자식 블록입니다.

JSON

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

collection

id로 실시간 컬렉션 뷰를 삽입합니다. 블록은 컬렉션의 신원만 저장하며, 형태와 데이터는 서버가 소유합니다.

필드	타입	필수	설명
collectionId	string	예	삽입된 컬렉션의 id입니다. 저장되는 유일한 값입니다.

JSON

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

columns

2개에서 4개의 열로 구성된 다단 레이아웃이며, 각 열은 자체 자식 블록 목록을 가집니다.

필드	타입	필수	설명
columns	Block[][]	예	각 열은 자식 블록의 목록입니다. 2개에서 4개의 열입니다.

JSON

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

date

달력 날짜입니다. 시간대 없이 저장되므로 모든 공동 작업자가 같은 날짜를 보게 됩니다.

필드	타입	필수	설명
date	string	예	yyyy-MM-dd 형식의 ISO 날짜이며 시간대가 없습니다.

JSON

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

delimiter

섹션 사이의 시각적 구분선.

필드	타입	필수	설명
variant	'line' \| 'stars'	예	구분선의 시각적 스타일. 다음 중 하나: line, stars.

JSON

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

doc_card

다른 문서를 가리키는 리치 링크 카드입니다. 참조된 페이지 id와 표시 스냅숏을 저장하며, 이름이 바뀌면 호스트가 스냅숏을 새로 고칩니다.

필드	타입	필수	설명
pageId	string	예	참조된 페이지의 id로, 카드의 신원입니다.
title	string	예	페이지 제목의 표시 스냅숏입니다.
icon	string	아니요	카드에 표시되는 선택적 아이콘입니다.
description	string	아니요	제목 아래에 표시되는 선택적 설명입니다.

JSON

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

embed

삽입된 링크입니다. 블록은 URL을 저장하며, 제공자와 삽입 마크업은 렌더링 시점에 도출됩니다. 언펄 필드는 대체 카드로 쓰입니다.

필드	타입	필수	설명
url	string	예	삽입된 링크입니다. 제공자와 삽입 마크업은 렌더링 시점에 이 값에서 도출됩니다.
title	string	아니요	링크 카드를 위한 언펄 스냅숏입니다.
description	string	아니요	링크 카드를 위한 언펄 설명입니다.
imageUrl	string	아니요	링크 카드를 위한 언펄 미리보기 이미지입니다.
display	'card'	아니요	라이브 보기가 있어도 링크 카드를 표시하는 "card".
file	object	아니요	붙여 넣은 사람의 Google 계정에서 가져온 Drive 파일의 이름, 유형, 아이콘.
gist	object	아니요	붙여 넣은 시점의 gist 파일. GitHub 자체 보기를 불러올 수 없는 곳에서는 코드로 그립니다.
reason	string	아니요	라이브 보기가 표시되지 않는 이유: connect_google, no_access, provider_unreachable 또는 switched_off.
issue	object	아니요	카드로 표시되는 이슈 링크: 마지막으로 읽은 스냅샷(tool, key, title, stateName, category, assigneeName, updatedAt, reason).

JSON

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

file

다운로드 링크, 이름, 선택적 크기와 콘텐츠 유형을 갖춘 파일 첨부입니다.

필드	타입	필수	설명
url	string	예	파일이 제공되는 위치입니다.
name	string	예	첨부에 표시되는 파일 이름입니다.
size	number	아니요	바이트 단위의 파일 크기입니다.
contentType	string	아니요	파일의 MIME 유형입니다.

JSON

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

glance

레이블과 값의 요약 패널입니다. 한눈에 읽히는 사실 행으로, 선택적 캡션과 배경 변형을 지원합니다.

필드	타입	필수	설명
rows	GlanceRow[]	예	표시할 사실입니다. 각 행은 레이블과 인라인 HTML 값으로 이루어집니다.
caption	string	아니요	행 위에 표시되는 선택적 캡션입니다.
variant	'plain' \| 'error' \| 'info' \| 'success' \| 'warning'	아니요	배경 변형입니다. plain은 스타일이 없고, 나머지는 알림 팔레트와 일치합니다.

JSON

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

header

최상위 및 섹션 제목(h1부터 h6까지). 인라인 도구는 html 페이로드 안에서 작동합니다.

필드	타입	필수	설명
html	string	예	제목의 HTML 콘텐츠. 인라인 도구 마크업이 지원됩니다.
level	'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'	아니요	제목 레벨. 다음 중 하나: h1, h2, h3, h4, h5, h6. 기본값은 h1입니다.

JSON

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

image

캡션과 alt 텍스트가 있는 이미지 블록. Editor.create의 imageUploader 콜백을 통해 처리됩니다.

필드	타입	필수	설명
url	string	예	임베드할 이미지의 URL.
caption	string	아니요	이미지 아래에 표시되는 일반 텍스트 캡션.
alt	string	아니요	이미지 요소의 alt 텍스트.
alignment	'center' \| 'left' \| 'right'	아니요	이미지의 수평 정렬. 다음 중 하나: center, left, right.

JSON

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

issues

페이지의 이슈 칩과 카드에서 렌더링 시점에 도출되는 연결된 이슈 표(이슈, 제목, 상태, 담당자)입니다. 자체 데이터를 저장하지 않습니다.

이 블록은 필드를 저장하지 않습니다. 행은 렌더링 시점에 페이지의 이슈 칩과 카드에서 도출됩니다.

JSON

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

latex

LaTeX 수식입니다. 소스로 저장되고 렌더링 시점에 조판됩니다. 나중에 더 나은 렌더러가 나오면 이미 존재하는 모든 문서가 개선됩니다.

필드	타입	필수	설명
source	string	예	LaTeX 소스입니다. 소스로 저장되며, 렌더링된 출력으로는 저장되지 않습니다.

JSON

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

list

순서가 있거나 없는 목록. 각 항목은 html입니다.

필드	타입	필수	설명
type	'ordered' \| 'unordered'	예	목록 유형. 다음 중 하나: ordered, unordered.
items	string[]	예	HTML 문자열의 배열, 각 목록 항목당 하나.

JSON

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

mermaid

Mermaid 다이어그램입니다. 소스로 저장되고 표시 시점에 그려지며, 래스터로는 저장되지 않습니다.

필드	타입	필수	설명
source	string	예	Mermaid 소스입니다. 소스로 저장되며, 그려진 출력으로는 저장되지 않습니다.

JSON

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

openapi

OpenAPI 3.x 문서에서 인터랙티브 API 레퍼런스를 렌더링합니다. 인라인이거나 URL에서 가져오며, 서버 선택기와 코드 스니펫을 제공합니다.

필드	타입	필수	설명
spec	object	아니요	인라인 OpenAPI 3.x 문서입니다. 둘 다 설정되면 url보다 우선합니다.
url	string	아니요	렌더링 시점에 OpenAPI 문서를 가져올 위치입니다.
include	OpenApiFilter	아니요	어떤 작업을 렌더링할지 거르는 필터입니다.
exclude	OpenApiFilter	아니요	어떤 작업을 숨길지 거르는 필터입니다.
defaultServer	string	아니요	레퍼런스가 기본으로 선택하는 서버입니다.
snippetLanguages	CodeLanguage[]	아니요	요청 스니펫에 제공되는 언어입니다.

JSON

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

paragraph

서식 있는 텍스트 단락. bold, italic, code, link, marker, tooltip 같은 인라인 도구 마크업을 허용합니다.

필드	타입	필수	설명
html	string	예	단락의 HTML 콘텐츠. 인라인 도구 마크업이 지원됩니다.

JSON

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

quote

선택적 작성자 표기가 있는 인용 블록.

필드	타입	필수	설명
html	string	예	인용문 본문의 HTML 콘텐츠. 인라인 도구 마크업이 지원됩니다.
author	string	아니요	인용문 아래에 표시되는 일반 텍스트 또는 HTML 출처.

JSON

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

sketch

스트로크로 저장되는 자유 곡선 드로잉입니다. 래스터가 아니므로 계속 편집할 수 있고 깔끔하게 확대됩니다.

필드	타입	필수	설명
strokes	SketchStroke[]	예	스트로크로 표현된 드로잉입니다. 각 스트로크는 선택적 색상과 너비를 가진 점의 목록입니다.

JSON

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

table

데이터 그리드. 첫 번째 행을 헤더로 사용할 수 있습니다. 각 셀은 html입니다.

필드	타입	필수	설명
data	string[][]	예	HTML 셀 문자열의 2차원 배열. 첫 번째 행이 헤더 행입니다.
caption	string	아니요	테이블 아래에 표시되는 일반 텍스트 또는 HTML 캡션.
showDownload	boolean	아니요	렌더링된 출력에 다운로드 버튼을 표시합니다.

JSON

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

updates

문서의 실시간 활동 피드입니다. 스냅숏이 아니라 신원을 저장하므로 계속 현재 활동을 보여줍니다.

필드	타입	필수	설명
pageId	string	아니요	어느 문서의 활동을 보여줄지 정합니다. 없으면 블록이 있는 문서를 뜻합니다.

JSON

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

video

비디오 블록. Editor.create의 videoUploader 콜백을 통해 처리됩니다.

필드	타입	필수	설명
url	string	예	비디오 파일의 URL 또는 YouTube/Vimeo 임베드 링크.
caption	string	아니요	플레이어 아래에 표시되는 일반 텍스트 캡션.
alt	string	아니요	비디오 요소의 접근 가능한 레이블.
alignment	'center' \| 'left' \| 'right'	아니요	플레이어의 수평 정렬. 다음 중 하나: center, left, right.

JSON

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

참조

패키지

블록 참조

블록의 형태

alert

audio

checklist

code

collapsible

collection

columns

date

delimiter

doc_card

embed

file

glance

header

image

issues

latex

list

mermaid

openapi

paragraph

quote

sketch

table

toc

updates

video