kimminsung/doc2md

Files

minsung 6f365018f5 docs: Initial project scaffold with AI agent guide

- AGENT_GUIDE.md: AI 에이전트 사용 스펙 (CLI, JSON 출력, 페이지 타입 정의)
- CLAUDE.md: 프로젝트 개요 및 개발 원칙

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-20 08:52:00 +09:00

1.4 KiB

Raw Blame History

doc2md

바이너리 문서(PDF/HWP/HWPX/HML/HTML)를 Markdown으로 변환하는 도구. AI 에이전트(Claude Code)가 ParaWiki ingest-raw에서 호출한다.

필수 읽기

사용법은 AGENT_GUIDE.md 를 먼저 읽어라.

프로젝트 구조

doc2md/
├── convert.py          # 통합 CLI 진입점 (에이전트가 직접 호출)
├── converters/
│   ├── pdf.py          # PDF → MD (페이지별 분류 + 라우팅)
│   ├── hwp.py          # HWP → MD (COM + pyhwp fallback)
│   ├── hwpx.py         # HWPX → MD (ZIP+XML 파싱)
│   ├── hml.py          # HML → MD (XML 파싱)
│   └── html.py         # HTML → MD (html2text)
├── AGENT_GUIDE.md      # AI 에이전트 사용 가이드 (핵심 문서)
└── requirements.txt

핵심 원칙

비대화형: 절대 사용자 입력 대기하지 않음
JSON 출력: --json 플래그 시 파싱 가능한 JSON만 stdout 출력
멱등성: 이미 변환된 파일은 건너뜀 (기본 동작)
다이어그램 플래그: PDF에 다이어그램 페이지 존재 시 has_diagrams: true 반환

개발 시 주의사항

convert.py CLI 인터페이스는 AGENT_GUIDE.md 스펙과 항상 일치해야 함
JSON 출력 구조 변경 시 AGENT_GUIDE.md 동시 업데이트 필수
converters/ 각 파일은 단독 임포트 가능해야 함 (순환 의존 금지)