HWP·HWPX는 RAG 파이프라인에도, LLM 입력에도, 버전 관리에도 바로 쓸 수 없습니다. 기존 변환 도구는 표와 이미지 위치를 잃거나 한컴 설치를 요구하고, 개발자는 매번 같은 파싱 코드를 다시 짭니다. hwp2md는 그 문을 여는 열쇠입니다.
예시: 공고문의 개요 수준 제목은 # 기호가 붙은 Markdown 제목이 되고, 표는 파이프 표, 그림은 문서명_images 폴더의 이미지 링크가 됩니다.
터미널 한 줄, 브라우저 미리보기, 파이썬 코드. 어느 쪽으로 변환해도 같은 Markdown이 나옵니다.
아직 PyPI 배포 전입니다. 소스에서 pip install '.[web]'으로 설치하세요. Python 3.11 이상.
서식 재현 대신 구조를 지킵니다. 제목 계층·표·이미지가 다음 도구에서 바로 쓰이도록.
바이너리 HWP 5.0(OLE), XML 기반 HWPX(zip), 단일 XML인 HWPML 2.x를 모두 읽습니다. 확장자가 아니라 파일 내용으로 판별해, HWPX에 .hwp 확장자가 붙은 파일도 그대로 변환합니다. 복사·인쇄를 막은 배포용 문서도 공개된 방식으로 풀어 본문을 꺼냅니다.
OLE → hwp5 · zip → hwpx · xml → hwpml
문단 모양의 개요 1~6수준을 #~######으로 옮깁니다. 7수준 이상은 ######로 묶어 구조를 버리지 않습니다.
# · ## · ### … ######
첫 행을 헤더로 쓰고, 셀 안 줄바꿈은 <br>, 파이프는 \|로 이스케이프합니다. 병합으로 덮인 칸은 빈 칸으로 남겨 열 정렬을 지킵니다.
| 구분 | 내용 |
본문·표 칸·글상자 안 그림을 img_001.png처럼 순서대로 꺼내 제자리에 링크합니다. 같은 그림을 다시 쓰면 파일은 하나, 링크는 여러 개입니다. 글상자·도형 안 글과 표·그림 캡션도 본문 단락으로 옮깁니다.
각주·미주는 [^1] 참조와 문서 끝 정의로, 하이퍼링크는 [글자](주소)로(http·https·mailto만), 수식은 LaTeX $…$로, 번호·글머리표 목록은 - 와 1. 목록으로 옮깁니다(가.·① 같은 번호는 글자로 앞에 붙입니다). 번호는 한글 화면과 다를 수 있는 근사값이고, 수식을 바꾸지 못하면 원래 수식 문자열을 코드로 남깁니다.
[^1] · [링크](https://…) · $\frac{a}{b}$ · - 목록
웹 미리보기에서 렌더링 결과와 원문을 나란히 확인하고, 원문만 복사하거나 .md와 이미지 폴더를 한 압축 파일로 받습니다.
demo.md + demo_images/
"브라우저 안에서만 처리"를 켜면 같은 파이썬 코드가 브라우저 안에서 돌고, 문서 파일은 페이지 밖으로 나가지 않습니다.
server · browser
문서를 다음 도구로 넘겨야 하는 사람들의 실제 요구에서 출발했습니다.
개요 수준이 Markdown 제목이 되어 제목 단위로 자르기 좋습니다. 머리말·꼬리말·쪽 번호는 본문에 섞지 않아 청크에 잡음이 들어가지 않습니다.
## 1. 사업 개요
…
## 2. 추진 절차
…
### 2.1 심사 기준표는 첫 행이 헤더인 GFM 표가 됩니다. 셀 안 여러 줄은 <br>로 이어져 행·열 수가 그대로 남습니다.
| 구분 | 내용 |
|---|---|
| 지원 규모 | 총 10억 원 |
| 지원 기간 | 2026. 3. ~ 12. |순수 파이썬 3.11 이상, 기본 의존성은 olefile과 lxml 두 개입니다. 웹 미리보기용 의존성은 [web] extra에만 있습니다.
$ pip install .
$ hwp2md 공고문.hwp -o out/
✓ 공고문.hwp → out/공고문.md웹 미리보기는 내 컴퓨터에서 실행하는 hwp2md serve입니다. 두 가지 처리 방식의 차이를 직접 확인하세요.
파일은 같은 컴퓨터에서 실행 중인 hwp2md serve 프로세스로 전달되어 메모리 안에서만 변환됩니다. 임시 파일을 만들지 않고, 결과를 돌려준 뒤 남는 사본이 없습니다.
인터넷 연결이 필요 없습니다. 기본 주소는 localhost:8770이며 인증이 없으니 외부에 공개하지 마세요.
같은 변환 코드가 브라우저 안의 Pyodide(WebAssembly 파이썬)에서 실행됩니다. 문서 파일은 페이지 밖으로 나가지 않고, 결과도 서버 모드와 같습니다.
처음 켤 때 Python 실행 환경과 lxml을 CDN에서, 변환 코드를 hwp2md serve에서 받습니다. 첫 준비에 약 1분이 걸리고 인터넷 연결이 필요합니다.
지금 꺼내지 못하는 것을 먼저 밝힙니다. 변환할 때 빠진 요소는 화면과 CLI가 종류별 개수로 알려 줍니다. 변환하지 못하는 요소 전체 목록과 이유는 저장소의 docs/extraction-limits.md 에 있습니다.
--table html)은 예정입니다.부분