@newtil/editor
v0.10.20
Published
Framework-agnostic Markdown ↔ HTML bidirectional editor (Web Component)
Maintainers
lectureteamReadme
@newtil/editor
마크다운 ↔ HTML 양방향 편집기 웹 컴포넌트. <newtil-editor> 태그 하나로 React · Vue · Vanilla 어디서든 쓴다.
ProseMirror 위에서 WYSIWYG 로 편집하고 저장은 마크다운(CommonMark + GFM 표)으로 한다. Shadow DOM 이라 페이지 CSS 와 서로 새지 않고, 스타일은 자동 주입된다. React/Vue 래퍼를 같이 제공하며, 색은 newtil 디자인 토큰(CSS 변수)으로 넘긴다. 캡처 위에 화살표·상자·글자를 그리는 그림판은 @newtil/drawing 이 맡고 편집기는 열고·넣고·고치는 접착부만 가진다. 뉴렉처의 노트·게시판이 쓰고 있다.
설치
npm install @newtil/editorReact/Vue 는 peerDependency(선택). 각각 @newtil/editor/react, @newtil/editor/vue 로 가져온다.
빠른 시작
Vanilla
import "@newtil/editor"; // <newtil-editor> 등록 + 스타일 자동 주입
const editor = document.querySelector("newtil-editor"); // <newtil-editor toolbar></newtil-editor>
editor.value = "# 제목\n\n본문"; // 마크다운 넣기
editor.addEventListener("change", (e) => save(e.detail.markdown)); // e.detail.html 도 있다React
import "@newtil/editor"; // 래퍼보다 먼저 — Custom Element 등록
import { NewtilEditor } from "@newtil/editor/react";
const [md, setMd] = useState("");
<NewtilEditor value={md} onChange={(d) => setMd(d.markdown)} toolbar />Next.js 처럼 서버에서 그리는 환경에서는 next/dynamic 의 ssr: false 로 불러온다(Custom Element 는 브라우저에서만 등록된다).
Vue 3
import "@newtil/editor"; // 래퍼보다 먼저 — Custom Element 등록
import { NewtilEditor } from "@newtil/editor/vue";
const content = ref("");
<NewtilEditor v-model="content" toolbar />문서
- 가이드·API 사이트: https://newlecture-corp.github.io/newtil-editor/
- 라이브 데모: 문서 첫 화면과 시작하기 에서 설치 없이 편집기를 직접 써볼 수 있습니다
- API 레퍼런스 — 속성 · 프로퍼티 · 이벤트 · 문자열 표 · CSS 변수
- 그림판 연동 —
onDrawingSave/onDrawingLoad - 선택 범위 동작 —
selectionActions: 고른 글을 호스트 함수(번역·맞춤법·AI 엔드포인트 등)로 넘겨 결과로 바꿔 넣는 확장점 - CHANGELOG
주요 기능
- 툴바 · 플로팅 툴바 · 슬래시 메뉴(
/): 제목, 굵게·기울임·밑줄·인라인 코드·링크·글자 색, 목록, 인용, 코드 블록, 표, 구분선, 정렬·테두리, 이미지·그림판·영상·오디오·코드 임베드 - 표: GFM 파이프 표(열 정렬 포함). Tab/Shift+Tab 으로 셀 이동, 마지막 셀 Tab 은 새 행. 표 안에서만 행·열 추가/삭제·머리글·표 삭제 버튼
- 코드 블록: "
java " 또는 "java"+Enter 로 언어가 잡히고 블록 오른쪽 위에서 바꾼다. 편집 중에도 구문 색(highlight.js, 20종). Shift+Enter / Ctrl+Enter 로 빠져나온다 - 이미지: 툴바·
/이미지·붙여넣기·끌어놓기 모두onImageUpload훅을 탄다(없으면 data URL). 고르면 손잡이로 폭 조절, 정렬·테두리 - 그림판: 툴바·
/그림판. 캡처 위에 화살표·상자·글자를 그려 이미지로 넣고, 문서 속 그림을 두 번 클릭해 도형째 다시 고친다(onDrawingSave/onDrawingLoad) - 선택 범위 동작: 호스트가
selectionActions로 동작을 등록하면 말풍선 툴바·슬래시 메뉴에 버튼이 붙는다. 편집기는 고른 블록(과 문서 전체)을 마크다운으로 넘기고 돌아온 마크다운으로 바꿔 넣을 뿐이라 번역·맞춤법·AI 어느 것이든 같은 통로를 탄다. 등록이 없으면 버튼도 없다 - 영상·임베드: MP4, YouTube · Vimeo · Loom · Dailymotion · Wistia · 네이버TV · 카카오TV · Spotify · SoundCloud · CodePen. 이미지와 같은 손잡이로 폭 조절
- 마크다운 붙여넣기: 붙여 넣은 글이 마크다운처럼 보이면 마크다운으로 해석한다. Shift 붙여넣기는 글자 그대로
- 마크다운 모드: 툴바 오른쪽 끝 버튼(
mode="source"). 전환하는 순간에만 한 번 변환한다 - 빈 문단 정책: 마크다운에 빈 문단이 없으므로 편집기도 만들지 않는다. 빈 문단 Enter 는 안내 말풍선(
empty-line-hint), 문단 간격은 CSS 의 몫 - 한국어·영어 문자열:
lang속성(→ 조상lang→<html lang>).messages로 일부만 덮어쓴다 - 블록 드래그: 왼쪽 여섯 점 핸들(모바일은 길게 누르기). 640px 이하에서는 핸들을 숨기고 툴바를 화면 위에 붙인다
- 테마:
<html data-theme>를 호스트로 동기화해 다크 모드를 따른다. 편집 영역이.n-prose라 보기 화면과 같은 모습
newtil 패밀리
| 패키지 | 한 줄 | 문서 |
|---|---|---|
| @newtil/design-tokens | CSS 변수(토큰) — 색·간격·글꼴·모서리·그림자·층. 모든 패키지의 바닥 | https://newlecture-corp.github.io/newtil-design-tokens/ |
| @newtil/css | 실제 CSS 속성명 기반 유틸리티 클래스 + JIT | https://newlecture-corp.github.io/newtil-css/ |
| @newtil/components | n- 접두사 기본 컴포넌트 — prose·table·layout·resize-handle | https://newlecture-corp.github.io/newtil-components/ |
| @newtil/materials | Material Design 3 구현 m3- 컴포넌트 | https://newlecture-corp.github.io/newtil-materials/ |
| @newtil/editor | 마크다운↔HTML 양방향 편집기 웹 컴포넌트(React/Vue 래퍼) — 이 패키지 | https://newlecture-corp.github.io/newtil-editor/ |
| @newtil/drawing | 캡처 위에 화살표·상자·글자를 그리는 그림판(PNG+JSON) | https://newlecture-corp.github.io/newtil-drawing/ |
편집기는 design-tokens(토큰), components(.n-prose 등), drawing(그림판)을 의존성으로 가지며 스타일은 빌드 때 한 번 묶어 Shadow DOM 에 넣는다.
개발
npm install
npm run dev # Vite 데모 (prebuild: 스타일 번들 생성)
npm run build # dist/
npm run typecheck
npm run test:e2e # Playwright 브라우저 회귀 검사 (처음 한 번: npx playwright install chromium)
npm run docs:dev # VitePress 문서 (docs:build / docs:preview)버그를 고칠 때는 tests/e2e/editor.e2e.mjs 에 시나리오를 한 줄 더한다. 버전은 수정·정정이면 끝자리, 새 기능이면 가운데 자리를 올린다.
라이선스
MIT © Newlecture