Structured Doc Editor

구조를 잃지 않고 기술 문서를 편집하는 WYSIWYG 에디터

설치 · 릴리스 · 이슈 · 기여하기

Structured Doc Editor는 .sdoc와 .tiptap.json 문서를 위한 오픈 소스 편집기입니다. 문서는 사람이 검토하고 Git으로 추적하기 쉬운 JSON으로 저장하면서, 편집할 때는 제목·표·수식·다이어그램·교차 참조를 갖춘 문서 화면을 제공합니다.

동일한 문서 코어와 에디터를 VS Code 확장과 Windows 데스크톱 앱에서 함께 사용합니다.

핵심 기능

빠른 시작

VS Code Marketplace

1. Visual Studio Marketplace에서 확장을 설치합니다.
2. 명령 팔레트에서 Structured Doc: New .sdoc Document를 실행하거나 기존 .sdoc/.tiptap.json 파일을 엽니다.
3. WYSIWYG 에디터에서 문서를 편집하고 Ctrl+S로 저장합니다.

명령줄에서도 설치할 수 있습니다.

code --install-extension swbaek.structured-doc-editor

로컬 VSIX

릴리스 또는 직접 빌드한 .vsix 파일은 명령 팔레트의 Extensions: Install from VSIX...에서 설치할 수 있습니다.

지원 형식

내보내기는 명령 팔레트 또는 에디터 왼쪽의 파일 작업 패널에서 실행합니다. HTML은 이미지만 포함하거나 모든 런타임 자산까지 포함하는 self-contained 출력도 지원합니다.

문서 작성

• 왼쪽 Activity Bar에서 목차, 그림 목록, 표 목록, 문서 설정, 파일 작업을 전환합니다.
• @를 입력해 제목·그림·표·수식에 대한 교차 참조를 삽입합니다.
• 이미지는 클립보드에서 바로 붙여 넣고 캡션·정렬을 지정할 수 있습니다.
• Mermaid는 에디터 안에서 작성하고 미리 볼 수 있습니다. Draw.io 편집에는 Draw.io Integration이 필요합니다.
• Alt+← / Alt+→ 또는 마우스 탐색 버튼으로 이전·다음 커서 위치로 이동합니다.

.sdoc 형식

.sdoc는 버전이 지정된 envelope 안에 문서 메타데이터와 Tiptap JSON 트리를 저장합니다.

{
  "sdoc": "1.0",
  "meta": {
    "title": "시스템 설계서",
    "author": "작성자",
    "version": "1.0"
  },
  "doc": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "첫 문단" }]
      }
    ]
  }
}

저장 형식의 기준은 JSON Schema입니다. 포맷을 변경할 때는 스키마, 타입, 변환기, 예제와 테스트를 함께 갱신합니다.

여러 문서를 한 권으로 관리하기

.sdocbook은 여러 .sdoc 문서의 순서와 책 메타데이터를 관리하고 하나의 HTML/PDF로 내보내는 manifest입니다. VS Code에서 .sdocbook을 열면 문서를 추가·제거·정렬하고 각 장을 개별 편집할 수 있습니다.

Book 화면은 포함 문서를 자동으로 검사합니다. 누락되거나 잘못된 문서, 중복 ID, 깨진 참조가 있으면 진단을 표시하고 불완전한 통합 export를 차단합니다. 열려 있는 .sdoc의 아직 저장하지 않은 변경도 검증과 export에 사용됩니다. 현재 Book 관리 화면과 통합 export는 VS Code 확장에서 지원합니다.

각 장은 병렬로 불러오되 manifest 순서대로 합성되며, 장 링크와 로컬 이미지 경로는 book 경계 안에서 안전하게 다시 계산됩니다. 손상된 장은 다른 장의 미리보기를 지우지 않고 해당 장의 진단으로 표시됩니다.

데이터 안전성

• 저장 전 최신 편집 내용을 flush하고 문서 identity와 revision을 확인해, 이전 문서의 지연 저장이 새 문서에 적용되지 않게 합니다.
• 잘못된 JSON이나 지원하지 않는 미래 버전은 원본 보호를 위해 읽기 전용으로 열립니다.
• 이미지와 Draw.io 파일은 portable 상대 경로만 저장하며, export와 파일 작업은 문서 경계 밖 경로와 symlink 탈출을 거부합니다.
• Command Palette와 편집기 toolbar export는 동일한 변환기와 설정 해석 규칙을 사용합니다.

설정

VS Code 설정에서 Structured Doc Editor를 검색하면 다음 항목을 조정할 수 있습니다.

• 제목 번호·장식·색상
• IEEE, ISO/IEC, Modern, Korean 캡션 스타일과 번호 방식
• 본문·굵게·제목 폰트 굵기
• HTML/PDF 이미지 포함 방식과 출력 경로
• HTML/PDF/슬라이드 테마와 사용자 CSS
• 슬라이드 분할 수준, 타이틀 슬라이드, 전환 효과

문서별 설정은 .sdoc의 meta.settings에 저장되어 다른 환경에서도 동일하게 재현됩니다.

Windows 데스크톱 앱

Tauri 기반 데스크톱 앱은 VS Code 없이 .sdoc 문서를 편집할 수 있도록 동일한 에디터와 문서 코어를 사용합니다. 작업 폴더 탐색, 최근 폴더 복원, 파일 감시, 휴지통 삭제와 실행 취소 같은 네이티브 기능을 제공합니다.

현재 네이티브 앱은 Windows를 대상으로 하며, 소스에서 실행하려면 Node.js, Rust, WebView2가 필요합니다.

npm ci
npm run tauri dev --workspace=sdoc-editor-tauri

개발

요구 사항은 Node.js 22.22.2 이상, npm 10 이상이며 데스크톱 개발에는 Rust 1.90과 WebView2가 추가로 필요합니다.

git clone https://github.com/SWBaek/sdoc-editor.git
cd sdoc-editor
npm ci
npm run check
npm run build:all

저장소 구조와 의존성 방향은 아키텍처 문서, 자세한 작업 규칙은 기여 가이드를 참고하세요.

VS Code Marketplace 설명과 GitHub 프로젝트 소개는 이 루트 README.md를 함께 사용합니다. npm run package가 README를 VSIX의 extension/readme.md로 포함하므로 두 문서를 따로 관리하지 않습니다.

프로젝트 문서

• 제품 비전과 범위
• 아키텍처와 의존성 규칙
• 기여 가이드
• 보안 취약점 신고
• 행동 규칙
• 자산과 라이선스 범위

기여하기

버그 제보와 기능 제안은 GitHub Issues에 남겨 주세요. 코드 기여 전에는 CONTRIBUTING.md의 개발 환경, 아키텍처 경계, 검증 절차와 기여 권리 조건을 확인해 주세요. 보안 취약점은 공개 이슈로 올리지 말고 보안 정책을 따라 신고해 주세요.

라이선스

소스 코드는 기본적으로 MIT License로 배포됩니다. 제3자 의존성과 MIT 범위 밖 자산은 THIRD_PARTY_NOTICES.md와 ASSETS.md를 확인해 주세요.