확장

Inkio 확장은 두 층으로 나뉩니다.

@inkio/core
- callout
- details/toggle
- table
- keyboard shortcuts
@inkio/advanced
- slash command
- block handle
- mention
- hashtag
- wiki link
- bookmark
- comment

권장 시작점

classic editor가 필요하면 @inkio/simple
notion-like editor가 필요하면 @inkio/editor
low-level 조합이 필요하면 @inkio/core 또는 @inkio/advanced

조합 예시


import { Editor } from '@inkio/core';
import { getDefaultExtensions } from '@inkio/advanced';
import '@inkio/core/minimal.css';
import '@inkio/advanced/style.css';
 
const extensions = getDefaultExtensions({
  hashtagItems: ({ query }) => [{ id: query || 'inkio', label: `#${query || 'inkio'}` }],
});
 
export function Page() {
  return <Editor extensions={extensions} initialContent="<p>Hello Inkio</p>" />;
}

멘션 (Mention)

@ 트리거로 사용자 등을 멘션합니다. mentionItems는 ({ query }) => MentionItem[] 형태의 함수로, 사용자가 @ 뒤에 입력한 query에 맞는 항목을 반환합니다. 동기/비동기 모두 가능합니다.


interface MentionItem {
  id: string;
  label: string;
  [key: string]: unknown;
}


import { Editor } from '@inkio/editor';
 
<Editor
  mentionItems={async ({ query }) => {
    const users = await searchUsers(query);
    return users.map((user) => ({ id: user.id, label: user.name }));
  }}
/>

해시태그도 동일한 패턴이며, # 트리거와 hashtagItems를 사용합니다.


<Editor
  hashtagItems={({ query }) => [
    { id: query || 'inkio', label: `#${query || 'inkio'}` },
  ]}
/>

@inkio/core + @inkio/advanced 직접 조합 시에는 getDefaultExtensions에 동일한 옵션을 전달합니다.


const extensions = getDefaultExtensions({
  mentionItems: async ({ query }) => searchUsers(query),
});

슬래시 커맨드 (Slash Command)

/를 입력하면 명령 메뉴가 열립니다. 기본 명령에는 헤딩, 리스트, 표, 코드 블록, 콜아웃, 토글 리스트, 목차, 이미지 등이 포함됩니다. 두 가지 방식으로 커스터마이즈할 수 있습니다.

transformSlashCommands는 기본 명령 배열을 받아 가공한 뒤 반환합니다. 일부 명령만 추가하거나 제거할 때 적합합니다. 반환된 항목은 이후 query로 필터링됩니다.


import { Editor } from '@inkio/editor';
import type { SlashCommandItem } from '@inkio/advanced';
 
<Editor
  transformSlashCommands={(defaults, { editor }) => {
    const custom: SlashCommandItem = {
      id: 'today',
      label: 'Today',
      description: '오늘 날짜 삽입',
      command: ({ editor, range }) => {
        editor
          .chain()
          .focus()
          .deleteRange(range)
          .insertContent(new Date().toLocaleDateString())
          .run();
      },
    };
    return [custom, ...defaults];
  }}
/>

slashCommands는 기본 명령을 무시하고 명령 목록 전체를 직접 제공합니다. 시그니처는 (query: string) => SlashCommandItem[] | Promise<SlashCommandItem[]>이며, 이 경우 필터링도 직접 처리해야 합니다.


<Editor
  slashCommands={(query) =>
    myCommands.filter((item) =>
      item.label.toLowerCase().includes(query.toLowerCase()),
    )
  }
/>

SlashCommandItem의 isAvailable?: (editor) => boolean으로 특정 명령의 노출 조건을 지정할 수 있습니다.

위키 링크 (Wiki Link)

[[페이지 이름]] 문법으로 인라인 위키 링크를 만듭니다. 닫는 ]]를 입력하는 순간 입력 규칙(input rule)이 발동해 텍스트가 위키 링크 노드로 치환되며, [[...]]가 포함된 텍스트를 붙여넣어도 동일하게 변환됩니다.

@inkio/editor에서는 wikiLink prop으로 켜고 끄며 기본값은 true입니다. 링크 클릭 동작은 onWikiLinkClick 콜백으로 처리합니다. 콜백을 지정하지 않으면 링크는 클릭할 수 없는 텍스트로만 표시됩니다.


import { Editor } from '@inkio/editor';
 
<Editor
  wikiLink
  onWikiLinkClick={(href) => {
    router.push(`/wiki/${encodeURIComponent(href)}`);
  }}
/>

href는 [[...]] 안에 입력한 페이지 이름 문자열입니다. 안전하지 않은 URL은 클릭이 무시됩니다.

북마크 (Bookmark)

URL을 링크 미리보기 카드로 렌더링하는 블록 노드입니다. @inkio/editor에서는 bookmark prop으로 설정하며, false를 전달하면 비활성화됩니다.


bookmark?: false | { onResolveBookmark?: (url: string) => Promise<BookmarkPreview> };

북마크는 setBookmark 커맨드로 삽입합니다.


editor.commands.setBookmark({ url: 'https://example.com' });

onResolveBookmark는 URL을 받아 미리보기 데이터(BookmarkPreview)를 반환합니다. 북마크 노드는 미리보기 데이터가 아직 없을 때 한 번 이 함수를 호출하고, 반환된 값으로 카드를 채웁니다. 지정하지 않으면 북마크는 단순 링크로만 표시됩니다.


interface BookmarkPreview {
  title?: string;
  description?: string;
  image?: string;
  favicon?: string;
}


<Editor
  bookmark={{
    onResolveBookmark: async (url) => {
      const meta = await fetchOpenGraph(url); // 직접 구현하는 메타데이터 조회
      return {
        title: meta.title,
        description: meta.description,
        image: meta.ogImage,
        favicon: meta.favicon,
      };
    },
  }}
/>

onResolveBookmark는 메타데이터를 가져오는 로직만 담당합니다. Open Graph 스크래핑 같은 실제 조회는 직접 구현해야 합니다(보통 서버 측 엔드포인트).

Image editor


import { Editor } from '@inkio/editor';
import { ImageEditorModal } from '@inkio/image-editor';
import '@inkio/image-editor/style.css';
 
export function Page() {
  return (
    <Editor
      onImageUpload={async (file) => URL.createObjectURL(file)}
      imageBlock={{ imageEditor: ImageEditorModal }}
    />
  );
}

자세한 내용은 이미지 에디터 문서를 참고하세요.

TocBlock (인라인 목차)

@inkio/core에 기본 포함됩니다. 문서 안에 Notion 스타일의 인라인 목차 블록을 삽입합니다.

참고: 에디터 외부에 오버레이 미니맵 형태로 표시하려면 <ToC> 컴포넌트를 사용하세요. 컴포넌트 문서 참고

/toc 슬래시 커맨드로 삽입 (@inkio/advanced SlashCommand 필요)
헤딩이 추가/수정/삭제되면 자동으로 업데이트됩니다
항목 클릭 시 해당 헤딩으로 스크롤됩니다
배경/테두리 없는 Notion 스타일 미니멀 디자인 (텍스트 링크만)
헤딩이 없으면 muted 플레이스홀더 표시: “Add headings to see the table of contents.”

비활성화하려면 getExtensions에 tocBlock: false를 전달합니다:


import { getExtensions } from '@inkio/core';
 
const extensions = getExtensions({ tocBlock: false });

CodeBlock (코드 블록)

@inkio/core에 기본 포함되며, lowlight 기반 구문 강조를 제공합니다. 37개의 일반적인 언어를 지원합니다.

에디터 모드: 플로팅 언어 선택기(드롭다운)로 언어 변경
뷰어 모드: 복사 버튼 + 언어 배지 표시
tsx / jsx는 모두 typescript의 별칭으로 처리됩니다

코드 블록을 비활성화하려면 getExtensions에 codeBlock: false를 전달합니다.

커스텀 확장

extensions prop으로 Tiptap 확장을 추가하거나 교체할 수 있습니다.

타입


type ExtensionsInput =
  | Extension[]
  | { items: Extension[]; replace?: boolean };

배열 전달: 기본 확장에 추가합니다. 동일한 이름의 확장이 있으면 교체됩니다.
{ items, replace: true } 전달: 기본 확장을 전부 교체합니다.

예시: 확장 추가


import { Editor } from '@inkio/editor';
import CharacterCount from '@tiptap/extension-character-count';
 
<Editor
  extensions={[CharacterCount.configure({ limit: 1000 })]}
/>

예시: 기본 확장 전체 교체


import { Editor } from '@inkio/editor';
import { Document, Paragraph, Text } from '@tiptap/starter-kit';
 
<Editor
  extensions={{ items: [Document, Paragraph, Text], replace: true }}
/>

기능 토글 (`@inkio/editor` 전용)

@inkio/editor의 Editor 컴포넌트는 주요 확장을 prop으로 켜고 끌 수 있습니다.

Prop	기본값	설명
`blockHandle`	`true`	블록 드래그 핸들
`wikiLink`	`true`	`[[위키링크]]` 문법
`table`	`true`	표
`callout`	`true`	콜아웃 블록
`toggleList`	`true`	토글(접기/펼치기) 리스트


<Editor
  blockHandle={false}
  wikiLink={false}
/>

CSS

@inkio/simple/minimal.css
@inkio/editor/minimal.css
@inkio/advanced/style.css — @inkio/core + @inkio/advanced 직접 조합 시
@inkio/image-editor/style.css

확장