korhwp

HWPX (한글 워드 프로세서 표준) 파일을 Markdown 으로 변환하는 작은 Rust CLI. 단일 정적 바이너리, Python·Node.js 불필요.

왜?

HWPX 파일 파싱은 보통 Python (PyHWPX, python-hwp) 이나 TypeScript (kordoc) 같이 무거운 런타임이 필요합니다. korhwp 는 700KB 정적 Rust 바이너리 하나로 동일 작업을 수행합니다.

• Python · Node.js 런타임 불필요
• 외부 API 호출 0
• HWPX = KS X 6101 한국산업표준 (공식 공개 XML 포맷)
• 의존성: zip + quick-xml 만 (순수 Rust)
• Linux · macOS · Windows · Android(Termux) 지원

🚀 Claude Code 로 한 방에 설치

Claude Code 에 아래 문단을 그대로 복사·붙여넣기:

korhwp CLI 를 설치해줘. 저장소는 https://github.com/Hostingglobal-Tech/korhwp 야.

자동으로 아래 순서대로 해줘 (중간에 물어보지 말고):

1. Rust 툴체인(rustup) 이 없으면 설치.
2. cargo install --git https://github.com/Hostingglobal-Tech/korhwp --locked 실행.
3. ~/.cargo/bin 이 PATH 에 없으면 ~/.bashrc (또는 ~/.zshrc) 에 추가.
4. 샘플 HWPX 파일이 있으면 변환 테스트, 없으면 korhwp --help 로 작동 확인.
5. 설치된 바이너리 경로를 알려줘.

수동 설치

cargo install (추천)

cargo install --git https://github.com/Hostingglobal-Tech/korhwp --locked

원라이너 스크립트 (Linux/macOS/Termux)

curl -fsSL https://raw.githubusercontent.com/Hostingglobal-Tech/korhwp/main/install.sh | bash

소스 빌드

git clone https://github.com/Hostingglobal-Tech/korhwp
cd korhwp
cargo build --release
install -m 755 target/release/korhwp ~/.local/bin/

사용

# HWPX → Markdown
korhwp report.hwpx

# 파일로 저장
korhwp report.hwpx -o report.md

# JSON 구조로 출력 (섹션 단위)
korhwp report.hwpx --json

# XML 원본 덤프 (디버그)
korhwp report.hwpx --dump-xml

# 표 생략 (텍스트만)
korhwp report.hwpx --keep-tables false

옵션

Flag	설명	기본
<input>	HWPX 파일 경로 (필수)	—
-o, --out	출력 파일 (기본 stdout)	stdout
--dump-xml	section0.xml 원본 출력 (디버그)	off
--keep-tables	Markdown 표 포함	on
--json	섹션 단위 JSON 출력	off

HWPX 포맷 배경

• HWPX = 한글과컴퓨터가 공개한 ZIP + XML 포맷
• KS X 6101 한국산업표준 등록
• Hancom 홈페이지에서 공식 스펙 PDF 무료 배포
• 이 도구는 Contents/section*.xml 파일을 파싱하여 텍스트와 표를 추출

HWP 5.x (구형 바이너리) 지원?

지원 안 함. HWP 5.x 는 OLE2/CFB 기반 비공개 바이너리 포맷으로 역공학 구현이 필요합니다.

HWP 파일이 필요하시면:

• Hancom Office 또는 온라인 변환기로 HWPX 로 저장 후 이 도구 사용
• 또는 kordoc (TypeScript, HWP 5.x 지원) 사용

보안

• 외부 API 호출 0
• 네트워크 접근 없음
• 파일 읽기 전용, 쓰기는 -o 로 명시한 경로만

라이선스

MIT — LICENSE 참조.

기여

바이너리는 작게, 코드는 지루하게. 한 파일, 한 목적 — HWPX → Markdown.