Docunara — Docusaurus 웹 기반 문서 에디터

Context

Certchip 문서 사이트(Docusaurus v3.9.2)에 내장된 웹 기반 문서 에디터이다. 문서는 docs/ 디렉토리의 마크다운 파일로 관리되며, 사이드바는 디렉토리 구조에서 자동 생성된다. 브라우저에서 직접 문서를 작성/수정/관리/빌드할 수 있다. 웹사이트: docunara.com

아키텍처

┌─────────────────────────────────────────────────────────┐
│           /editor 페이지 (React SPA)                     │
│  ┌────────────────────────────────────────────────────┐ │
│  │ DialogProvider & ToastProvider                     │ │
│  │ ┌───────────┬──────────────────┬──────────────────┐│ │
│  │ │ DocTree   │ MarkdownEditor   │ ResourcePanel    ││ │
│  │ │ (왼쪽)    │ (중앙)           │ (오른쪽/모달)    ││ │
│  │ └───────────┴──────────────────┴──────────────────┘│ │
│  └────────────────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────┘
                     │ API (http://localhost:3001)
                     ▼
         ┌─────────────────────────┐
         │  Express v5 API 서버     │
         │  (port 3001)            │
         └────────────┬────────────┘
                      ▼
         ┌─────────────────────────┐
         │  파일시스템              │
         │  docs/        (en)      │
         │  i18n/ko/...  (ko)      │
         └─────────────────────────┘

• 프론트엔드: Docusaurus 페이지(src/pages/editor/)에 React 에디터 UI
• 백엔드: Express v5 API 서버가 파일시스템을 직접 읽기/쓰기 (DB 미사용)
• 개발: Docusaurus() + API 서버() 동시 실행
• 프로덕션: Docusaurus 빌드 후 Express가 정적 파일 + API를 함께 서빙

파일 구조

server/
├── index.ts                 # Express 서버 진입점 (포트 3001)
├── routes/
│   ├── tree.ts              # GET /api/tree — 문서 트리 구조
│   ├── docs.ts              # CRUD /api/docs/* — 문서 CRUD + reorder/duplicate/move
│   └── clone.ts             # POST /api/clone — 다국어 문서 복제
├── middleware/
│   └── auth.ts              # Bearer 토큰 인증 미들웨어
└── tsconfig.json

src/pages/editor/
├── index.tsx                # 에디터 메인 페이지 (3패널 레이아웃)
└── index.module.css

src/components/Editor/
├── DocTree.tsx              # 왼쪽 문서 트리 (드래그 앤 드롭, 컨텍스트 메뉴, 리소스 탐색)
├── MarkdownEditor.tsx       # 마크다운 에디터 (편집 + 미리보기 + 빌드 + Docs View)
├── ResourcePanel.tsx        # 리소스 패널 (이미지/비디오/오디오/PDF 미리보기)
├── EditorDialog.tsx         # 커스텀 모달 다이얼로그 (alert/confirm/prompt)
├── EditorToast.tsx          # 토스트 알림 (success/error/info)
├── CloneDialog.tsx          # 다국어 복제 다이얼로그 (충돌 감지)
└── Editor.module.css        # CSS Modules 스타일 (Infima 변수, 라이트/다크 모드)

src/clientModules/
├── embedMode.ts             # ?embed=true 모드 (Docs View에서 사이드바/네비 숨김)
└── licensesPopup.ts         # 오픈소스 라이선스 팝업

API 엔드포인트

문서 트리

Method	Endpoint	설명
GET	/api/tree?locale=ko	문서 트리 구조 반환 (position 정렬, 리소스 폴더 감지)

문서 CRUD

Method	Endpoint	설명
GET	/api/docs/*path	문서 내용 또는 디렉토리 메타데이터 읽기
POST	/api/docs/*path	새 문서/폴더 생성 (_category_.json 자동 생성)
PUT	/api/docs/*path	문서 내용 또는 카테고리 메타데이터 수정
DELETE	/api/docs/*path	문서/폴더 삭제

문서 관리

Method	Endpoint	설명
PATCH	/api/docs/move	문서 이동/이름 변경 (디렉토리 라벨 자동 업데이트)
PATCH	/api/docs/reorder	순서 일괄 변경 (sidebar_position, category.json position)
POST	/api/docs/duplicate	문서/폴더 복제 (리소스 폴더 포함, 자동 넘버링)

다국어 복제

Method	Endpoint	설명
POST	/api/clone/preview	복제 미리보기 (충돌/신규 파일 분석)
POST	/api/clone	다국어 복제 실행 (`mode: 'all'

리소스 및 빌드

Method	Endpoint	설명
GET	/api/resources/*path	리소스 파일 서빙 (이미지 등)
POST	/api/rebuild	Docusaurus 빌드 트리거 (실시간 진행률 스트리밍)
GET	/api/health	서버 상태 확인

주요 기능

구현 완료

• 문서 CRUD: 생성, 읽기, 수정, 삭제
• 트리 탐색: 폴더/파일 트리, 열기/닫기, 선택
• 컨텍스트 메뉴: 새 문서, 새 폴더, 이름 변경, 라벨 변경, 삭제, 복제, 다국어 복제
• 드래그 앤 드롭: 같은 폴더 내 순서 변경, 다른 폴더로 이동 (순환 방지)
• Duplicate: 문서/폴더 복제 (리소스 폴더 포함, 자동 넘버링)
• 리소스 관리: 문서별 리소스 파일 탐색, 이미지/비디오/오디오/PDF 미리보기
• 마크다운 에디터: 편집/미리보기 분할 뷰 (@uiw/react-md-editor)
• Docs View: iframe 기반 문서 실시간 미리보기 (embed 모드)
• 빌드 통합: 에디터에서 Docusaurus 빌드 실행, 실시간 진행률 표시
• 다국어 지원: 로케일별 문서 편집, 교차 로케일 복제 (충돌 감지)
• 커스텀 다이얼로그: 브라우저 네이티브 대화상자 대신 커스텀 모달
• 토스트 알림: 성공/에러/정보 알림 (3초 자동 소멸)
• 인증: 선택적 Bearer 토큰 인증
• 보안: 경로 탐색(path traversal) 방지

미구현 / 향후 계획

• [ ] 비주얼 에디터 (Plate 기반, GitBook 스타일) — VISUAL_EDITOR_PLAN 참조
• [ ] 리소스 파일 업로드 기능
• [ ] 문서 버전 히스토리
• [ ] 협업 편집 (동시 편집 충돌 해결)
• [x] 데이터베이스 통합 — SQLite 기반 검색 구현 완료 (DB_ENABLED=true)
• [x] 사용자 인증/권한 관리 — JWT + RBAC 구현 완료 (라이센스 필요)
• [x] 검색 기능 — SQLite FTS5 기반 문서 검색 구현 완료

npm scripts

npm run editor         # 프로덕션: 빌드 → Express + 정적 파일 서빙 (다국어 전환 가능)
npm run editor:dev     # 개발: API 서버 + Docusaurus 핫리로드 (영문)
npm run editor:dev:ko  # 개발: API 서버 + Docusaurus 핫리로드 (한국어)
npm run editor:api     # API 서버만 실행 (디버깅용)

주요 의존성

패키지	버전	용도
Docusaurus	v3.9.2	정적 사이트 생성기
React	v19.2.4	UI 프레임워크
TypeScript	v5.6.3	타입 안전성
Express	v5.2.1	API 서버
@uiw/react-md-editor	v4.0.11	마크다운 에디터 컴포넌트
gray-matter	v4.0.3	front matter 파싱
cors	v2.8.6	CORS 미들웨어
concurrently	v9.2.1	개발 서버 동시 실행
tsx	v4.21.0	TypeScript 서버 실행

UI/UX 규칙 (요약)

• 브라우저 네이티브 다이얼로그 금지 → useDialog() 커스텀 모달 사용
• 스팟성 알림 → useToast() 토스트 사용
• 모달 외부 클릭 시 닫히지 않음 (명시적 닫기만 허용)
• 모달 열릴 때 배경 스크롤 방지 (overflow: hidden)
• 모달 내부 스크롤 전파 방지 (overscroll-behavior: contain)
• 갱신 시 내용을 잠깐 비운 후 다시 표시하여 시각적 피드백 제공
• CSS Modules + Infima 변수로 라이트/다크 모드 지원

검증 방법

1. npm run editor:dev로 개발 서버 시작
2. 브라우저에서 http://localhost:3000/editor 접속
3. 왼쪽 트리에서 기존 문서 선택 → 에디터에 로드 확인
4. 문서 수정 → 저장 → 실제 파일 변경 확인
5. 새 문서/폴더 생성 → 파일시스템 확인
6. 문서/폴더 삭제 → 파일 삭제 확인
7. 드래그 앤 드롭으로 순서 변경 → sidebar_position/_category_.json 확인
8. 다른 폴더로 드래그 이동 → 파일 이동 확인
9. 컨텍스트 메뉴에서 Duplicate → 복제 확인
10. 다국어 복제 → 대상 로케일에 문서 생성 확인
11. 빌드 버튼 → Docusaurus 빌드 실행 및 진행률 확인
12. Docs View로 문서 미리보기 확인