구성

EditorConfig와 RendererConfig는 모든 커스터마이징의 진입점입니다. 각각 Editor.create() 또는 Renderer.render()에 전달하세요. containerId(및 렌더러의 data)만 필수이며, 나머지 옵션은 모두 안전한 기본값을 가집니다.

EditorConfig

EditorConfig를 Editor.create()의 유일한 인수로 전달하세요. 필수 containerId는 기존 DOM 요소 id와 일치해야 합니다.

옵션	타입	필수	설명
containerId	string	예	에디터를 호스팅할 DOM 요소의 ID. Editor.create()가 호출되기 전에 DOM에 존재해야 합니다.
maxHeight	number	아니오	픽셀 단위의 에디터 최대 높이. 높이 제한 없음은 0(기본값)으로 설정하세요.
minHeight	number	아니오	픽셀 단위의 에디터 최소 높이. 기본값은 300입니다.
onChange	(data: EditorData) => void	아니오	문서가 변경될 때마다 실행되는 콜백. 전체 EditorData 스냅샷을 받습니다.
onReady	() => void	아니오	에디터가 완전히 초기화되어 API 호출을 받을 준비가 되면 실행되는 콜백.
placeholder	string	아니오	에디터가 비어 있을 때 표시되는 플레이스홀더 텍스트. 기본값은 'Start writing...'입니다.
initialData	EditorData	아니오	에디터가 마운트될 때 로드할 미리 채워진 EditorData.
initialView	'edit' \| 'preview' \| 'json'	아니오	초기 뷰 모드. 다음 중 하나: edit, preview, json. 기본값은 'edit'입니다.
allowJsonViewEditing	boolean	아니오	true이면 JSON 뷰가 편집 가능해지고 변경 사항이 문서로 다시 전파됩니다. 기본값은 false입니다.
hasViewSwitcher	boolean	아니오	false이면 작업 표시줄에서 편집, 미리보기, JSON 버튼을 뺍니다. 기본값은 true입니다.
hasDocumentActions	boolean	아니오	false이면 작업 표시줄에서 복사, 다운로드, 지우기 버튼을 뺍니다. hasViewSwitcher도 false이면 작업 표시줄을 그리지 않습니다. 기본값은 true입니다.
onClearRequest	() => Promise<boolean>	아니오	비우기를 누르면 호출됩니다. true로 확정될 때만 페이지를 비우며, 거부되면 페이지를 그대로 둡니다. 없으면 즉시 비웁니다.
margins	BlockMargins	아니오	모든 블록에 적용되는 전역 위아래 여백(픽셀). 블록별 구성이 우선합니다.
styles	EditorStyles	아니오	에디터 크롬(툴바, 다이얼로그, 컨트롤)의 세밀한 CSS 커스터마이징을 위한 EditorStyles 객체.
classNames	EditorClassNames	아니오	에디터 크롬 요소에 CSS 클래스 이름을 연결하는 EditorClassNames 객체.
imageUploader	UploadFunction	아니오	이미지 파일을 업로드하고 공개 URL 문자열을 반환하는 비동기 함수.
audioUploader	UploadFunction	아니오	오디오 파일을 업로드하고 공개 URL 문자열을 반환하는 비동기 함수.
videoUploader	UploadFunction	아니오	비디오 파일을 업로드하고 공개 URL 문자열을 반환하는 비동기 함수.
fileUploader	UploadFunction	아니오	파일 블록 첨부를 스토리지로 옮기는 업로드 함수입니다.
locale	string	아니오	에디터가 편집하는 단일 로케일입니다. 다국어 블록은 이 로케일로 평탄화됩니다.
defaultLocale	string	아니오	블록에 요청한 로케일의 콘텐츠가 없을 때 쓰는 대체 로케일입니다.
onLocaleFallback	(info: { blockId: string; locale: string }) => void	아니오	블록이 다른 로케일로 대체될 때 호출되어 호스트가 표시를 보여줄 수 있습니다.
onInlineRewrite	(selection: string, action: InlineRewriteAction) => Promise<string \| null>	아니오	선택한 텍스트를 AI로 다시 쓰는 함수입니다. 설정하면 툴바에 재작성 버튼이 나타납니다.
inlineRewriteLabels	Partial<Record<InlineRewriteAction, string>>	아니오	재작성 메뉴 동작 레이블을 재정의합니다. 현지화용입니다.
inlineRewriteTooltip	string	아니오	인라인 툴바의 재작성 완드 툴팁을 재정의합니다. 현지화용입니다.
blockToolLabels	Partial<Record<BlockToolType, string>>	아니오	툴박스와 슬래시 메뉴의 블록 도구 레이블을 재정의합니다. 현지화용입니다.
blockToolbarLabels	Partial<Record<BlockToolbarLabel, string>>	아니오	블록 툴바 텍스트(추가, 이동, 삭제 등)와 빈 블록 칸에 표시되는 안내 문구를 재정의합니다. 현지화용입니다.
controlLabels	Partial<Record<ControlLabel, string>>	아니오	작업 표시줄 버튼 이름(편집, 미리보기, JSON, 복사, 다운로드, 지우기)을 재정의합니다. 접근성 이름과 툴팁으로 쓰입니다. 현지화용입니다.
dialogLabels	Partial<Record<DialogLabel, string>>	아니오	링크, 툴팁, 상태 대화상자에 표시되는 문구를 이름별로 지정합니다. 제목, 필드 레이블, 자리 표시자, 상태 스타일, 취소와 적용입니다. 없으면 영어로 표시됩니다.
resolveLink	(url: string) => Promise<Partial<EmbedData>>	아니오	붙여 넣은 임베드의 스냅샷을 서버에서 채웁니다. 제목, Drive 파일, gist 파일 또는 라이브 보기가 불가능한 이유. 실패한 조회는 도구가 응답하지 않은 카드로 그리고 옆에 다시 시도를 둡니다.
onEmbedAction	(action: EmbedAction, blockId: string) => void	아니오	카드 이유 옆의 수정 동작 중 호스트만 수행할 수 있는 것: connectGoogle은 멤버를 Google 계정 연결로 보내고, retry는 편집기가 직접 처리합니다.
disabledEmbedProviders	readonly string[]	아니오	워크스페이스가 끈 임베드 도구의 키 목록(figma, miro, loom, google_drive, github_gist). 해당 링크는 이유를 밝히는 카드로 그려집니다.
pasteEmbeds	'live' \| 'offer' \| 'card'	아니오	지원되는 링크를 붙여 넣을 때의 동작: 라이브로 표시(기본), 표시 여부 묻기, 또는 카드 표시.
embedLabels	Partial<Record<EmbedLabel, string>>	아니오	임베드 블록의 이유 줄, 동작, gist 레이블에 쓰는 번역된 문구. EmbedLabel을 키로 하며, 없으면 영어로 대체됩니다.
resolveIssues	(urls: string[]) => Promise<Record<string, IssueSnapshot>>	아니오	페이지의 이슈 링크에 URL을 키로 하는 스냅샷으로 답합니다. 없으면 칩과 카드는 문서에 저장된 내용을 유지하며 새로 고치지 않습니다.
onIssueAction	(action: IssueAction, tool: string) => void	아니오	이슈 이유 옆의, 호스트만 수행할 수 있는 해결책: 도구를 연결하는 것으로 호스트의 연동 페이지로 이동합니다.
issueCards	'off' \| 'on'	아니오	단독 줄에 붙여 넣은 이슈 링크를 카드로 만들지 여부. 없으면 off. 문장 안의 칩은 항상 칩입니다.
issueChip	{ assignee: boolean; status: boolean }	아니오	구성원의 두 칩 스위치: 상태 필과 담당자. 없으면 둘 다 켜집니다.
issueLabels	Partial<Record<IssueLabel, string>>	아니오	이슈 칩, 카드, 연결된 이슈 표에 쓰는 번역된 문구. IssueLabel을 키로 하며, 없으면 영어로 대체됩니다.
jiraSites	readonly string[]	아니오	워크스페이스의 연결이 도달하는 Jira 사이트 URL로, 사이트 자체 도메인의 링크를 이슈로 인식합니다.
allowedBlockTools	readonly BlockToolType[]	아니오	편집기가 블록 메뉴, 그 검색, 변환 메뉴 및 붙여넣기 시 제공하는 블록 유형입니다. 없으면 등록된 모든 블록이며, 목록 밖의 저장된 블록은 계속 렌더링됩니다.
allowedInlineTools	readonly InlineToolType[]	아니오	인라인 도구 모음이 제공하는 서식 표시입니다. 없으면 등록된 모든 표시입니다.
theme	'auto' \| 'light' \| 'dark'	아니오	색상 구성표. 다음 중 하나: auto(시스템 따름), light, dark. 기본값은 auto입니다.
themeOverrides	{ light?: ThemeTokens; dark?: ThemeTokens }	아니오	모드별 토큰 재정의. 전체 테마를 교체하지 않고 색상을 커스터마이징하려면 light 및/또는 dark 토큰 맵을 제공하세요.

TypeScript

import { Editor } from '@clepit/core';

const editor = Editor.create({
  containerId: 'editor',
  minHeight: 400,
  placeholder: 'Start writing...',
  theme: 'auto',
  onChange: data => console.log(data),
  onReady: () => console.log('Editor ready'),
  imageUploader: async file => {
    const form = new FormData();
    form.append('file', file);
    const res = await fetch('/api/upload', { body: form, method: 'POST' });
    const { url } = await res.json();
    return url;
  },
});

RendererConfig

RendererConfig를 Renderer.render()의 유일한 인수로 전달하세요. containerId와 data 모두 필수입니다.

옵션	타입	필수	설명
containerId	string	예	렌더링된 출력이 주입될 DOM 요소의 ID.
data	EditorData	예	렌더링할 EditorData 문서. 필수.
margins	BlockMargins	아니오	모든 렌더링된 블록에 적용되는 전역 위아래 여백(픽셀).
styles	BlockStyles	아니오	렌더링된 출력의 블록 유형별 CSS 커스터마이징을 위한 BlockStyles 맵.
classNames	BlockClassNames	아니오	렌더링된 출력의 블록 유형별 CSS 클래스 이름을 위한 BlockClassNames 맵.
editorClassNames	EditorClassNames	아니오	인터랙티브 컴포넌트를 렌더링하는 블록에 전달되는 EditorClassNames(예: 문단의 tooltip classNames).
configs	Partial<BlockTypeOutputConfigs>	아니오	블록별 OutputConfig 객체의 부분 맵. 각 항목은 블록 수준 여백과 tooltip 클래스 이름을 설정할 수 있습니다.
theme	'auto' \| 'light' \| 'dark'	아니오	색상 구성표. 다음 중 하나: auto, light, dark.
themeOverrides	{ light?: ThemeTokens; dark?: ThemeTokens }	아니오	렌더링된 출력의 모드별 토큰 재정의.

TypeScript

import { Renderer } from '@clepit/core';
import type { EditorData } from '@clepit/core';

const data: EditorData = await fetch('/api/content/123').then(r => r.json());

Renderer.render({
  containerId: 'output',
  data,
  theme: 'auto',
  margins: { bottom: 16, top: 16 },
});

블록 수준 스타일링

EditorConfig와 RendererConfig 모두 블록 유형을 키로 하는 styles, classNames, configs를 허용합니다. 대상이 지정된 재정의에 사용하세요. 전체 토큰 참조는 Themes 페이지를 참조하세요.

TypeScript

import { Editor, Renderer } from '@clepit/core';
import type { BlockStyles, BlockClassNames, EditorStyles } from '@clepit/core';

const editorStyles: EditorStyles = {
  blockToolbar: { container: { borderRadius: '8px' } },
};

const blockStyles: BlockStyles = {
  header: { h1: { fontFamily: 'Georgia, serif' } },
  paragraph: { lineHeight: '1.75' },
  table: { cell: { padding: '8px 12px' } },
};

const blockClassNames: BlockClassNames = {
  paragraph: 'prose-paragraph',
  header: { h1: 'prose-h1', h2: 'prose-h2' },
  alert: { info: 'alert-info', error: 'alert-error' },
};

Editor.create({
  containerId: 'editor',
  styles: editorStyles,
});

Renderer.render({
  containerId: 'output',
  data,
  styles: blockStyles,
  classNames: blockClassNames,
});