Markdown에서 HWPX로
HwpForge는 Markdown을 HWPX로 변환하는 완전한 파이프라인을 제공합니다. LLM이 Markdown을 생성하면 HwpForge가 이를 한글 문서로 자동 변환합니다.
MD → Core → HWPX 파이프라인
Markdown 문자열
|
v (MdDecoder::decode)
Document<Draft> + StyleRegistry
|
v (doc.validate())
Document<Validated>
|
v (HwpxEncoder::encode)
HWPX 바이트 → .hwpx 파일
각 단계는 독립적이므로, 중간 Core DOM을 직접 조작하거나 검사할 수 있습니다.
MdDecoder::decode() 사용법
#![allow(unused)] fn main() { use hwpforge::md::{MdDecoder, MdDocument}; let markdown = r#" --- title: 사업 제안서 author: 홍길동 date: 2026-03-06 --- 개요 본 제안서는 신규 사업 기회를 설명합니다. # 배경 시장 분석에 따르면 성장 가능성이 높습니다. "#; let MdDocument { document, style_registry, .. } = MdDecoder::decode_with_default(markdown).unwrap(); println!("섹션 수: {}", document.sections().len()); }
MdDocument에는 document: Document<Draft>, style_registry: StyleRegistry, warnings: Vec<MdWarning>이 포함됩니다. warnings에는 대상이 빈 이미지(![x]())처럼 문서에 넣지 않은 것이 남습니다. 필드가 늘 수 있으므로 구조 분해에는 ..을 붙입니다.
YAML Frontmatter
Markdown 파일 상단에 --- 블록으로 문서 메타데이터를 지정합니다.
---
title: 문서 제목 # Metadata.title
author: 작성자 이름 # Metadata.author
date: 2026-03-06 # Metadata.created (ISO 8601)
template: government # 파싱되지만 스타일 선택에는 쓰이지 않습니다 (inert)
metadata: # 아래 하위 필드를 담는 중첩 맵
subject: 신규 사업 제안 # Metadata.subject
keywords: # Metadata.keywords (YAML 배열)
- 사업
- 제안
modified: 2026-03-10 # Metadata.modified (ISO 8601)
---
최상위 필드:
| 필드 | Metadata 필드 | 설명 |
|---|---|---|
title | title | 문서 제목 |
author | author | 작성자 |
date | created | 작성일 (ISO 8601) |
template | (없음) | 파싱되지만 스타일 선택에는 쓰이지 않습니다(inert) |
metadata | (중첩 맵) | 아래 하위 필드를 담는 컨테이너 |
metadata: 아래의 하위 필드:
| 하위 필드 | Metadata 필드 | 설명 |
|---|---|---|
subject | subject | 주제/설명 |
keywords | keywords | 검색 키워드 (YAML 배열) |
modified | modified | 수정일 (ISO 8601) |
format | (없음) | 값이 lossless 이면 lossless 출력 표식이라 디코드가 거부합니다 |
subject/keywords/modified는 반드시 metadata: 아래에 중첩해야 합니다 — 최상위에 쓰면 조용히 무시됩니다(Frontmatter 구조체가 이 키들을 최상위 필드로 갖지 않고, 모르는 키를 에러로 거부하지도 않기 때문입니다).
Frontmatter 없이도 디코딩이 가능하며, 메타데이터 필드는 빈 값으로 처리됩니다.
디코딩 후 메타데이터 확인
#![allow(unused)] fn main() { use hwpforge::md::{MdDecoder, MdDocument}; let markdown = "---\ntitle: 보고서\nauthor: 홍길동\ndate: 2026-03-06\n---\n\n# 본문\n"; let MdDocument { document, .. } = MdDecoder::decode_with_default(markdown).unwrap(); let meta = document.metadata(); assert_eq!(meta.title.as_deref(), Some("보고서")); assert_eq!(meta.author.as_deref(), Some("홍길동")); assert_eq!(meta.created.as_deref(), Some("2026-03-06")); }
전체 메타데이터 필드와 프로그래밍 설정 방법은 메타데이터 가이드를 참고하세요.
섹션 마커
<!-- hwpforge:section --> 주석으로 HWPX 섹션을 분리합니다. 한 Markdown 파일에서 여러 섹션(페이지 설정이 다른 구역)을 만들 때 유용합니다.
# 1장 개요
첫 번째 섹션 내용.
<!-- hwpforge:section -->
# 2장 본론
두 번째 섹션 — 다른 페이지 설정 가능.
각주 (Footnote) / 미주 (Endnote)
GFM 각주 문법으로 각주와 미주를 표현합니다.
본문에 각주를 답니다.[^1] 미주도 답니다.[^e1]
[^1]: 각주 본문입니다.
[^e1]: 미주 본문입니다.
[^라벨]: 각주 — 관례적으로 숫자를 씁니다([^1]), 하지만 규칙 자체는 아래 미주 형태(e[0-9]+)가 아니면 어떤 라벨도 각주로 인정됩니다(예:[^note]도 유효한 각주 라벨입니다).[^eN](e+ 숫자 1개 이상): 미주 — HwpForge dialect의 예약 네임스페이스입니다. 각주 의도로[^e1]을 써도 미주로 정규화됩니다 (lossy 변환입니다).- 정의는 여러 문단으로 이어갈 수 있습니다. 첫 문단 다음에 빈 줄을 두고, 이어지는 문단의 모든 줄을 4-space 들여씁니다.
[^1]: 첫 번째 문단.
두 번째 문단 (4-space 들여쓰기).
hwpforge to-md(기본 styled 모드)로 HWPX → Markdown 역방향 변환할 때도 각주는 [^N], 미주는 [^eN]으로 방출되어 왕복이 보존됩니다. lossy 모드는 대신 (footnote: ...)/(endnote: ...) 형태의 인라인 텍스트로 펼쳐서 출력하므로 이 왕복 규약의 대상이 아닙니다.
표 (Table)
GFM 표 문법을 지원합니다.
| 항목 | 값 |
| ---- | ------ |
| 이름 | 홍길동 |
| 부서 | 기획팀 |
표 셀 안에는 링크, 이미지, 각주/미주 참조 등 인라인 요소도 담을 수 있습니다. 셀 안의 <br> 는 셀 문단을 나눕니다.
Markdown 안의 HTML
디코더는 to-md 의 styled·lossy 보기가 쓰는 HTML 만 읽습니다(읽기 보기가 쓰는 HTML 의 목록은 아래 “읽기 보기(styled·lossy)가 escape 하는 것과 쓰는 HTML” 절). 그 밖의 HTML, 대문자 태그, 표에 없는 속성은 MD_DECODE_FAILED 오류입니다.
아래 표의 태그 이름은 문법 개요입니다. 실제 입력은 보기가 쓰는 모양 그대로여야 합니다. 태그 이름은 소문자로 쓰고, 속성 값은 큰따옴표로 감싸며, <br> 는 닫지 않고, <img> 는 /> 로 끝냅니다. 예: <a href="https://example.com">링크</a>, <img src="images/a.png" alt="a"/>, <td colspan="2">칸</td>.
| HTML | 읽는 방식 |
|---|---|
<strong>·<em>·<del>·<u>·<sup>·<sub> | 글자 모양(굵게·기울임·취소선·밑줄·위첨자·아래첨자). 열고 닫는 순서가 맞아야 하고, 문단·셀 안에서 닫혀야 합니다. 위첨자와 아래첨자를 함께 쓰면 오류입니다 |
<a href>·<img src alt> | Markdown 링크·그림과 같습니다(같은 URL 규칙, 같은 그림 파일 규칙) |
<br> | 본문·각주에서는 줄바꿈, 표 셀에서는 셀 문단 경계, 링크 안에서는 링크 글의 줄바꿈 |
<table>·<tbody>·<tr>·<td colspan rowspan> | 표. <table><tbody> 안에 <tr> 행과 <td> 셀이 오는 순서를 지켜야 합니다. 셀 안에는 글·서식·링크·그림·<br>·주석과 표(32단계까지)가 옵니다. span 은 1–65535 입니다. 행과 셀은 쓴 그대로 읽고, 표가 맞는지는 문서 검증이 판정합니다 |
<!-- hwpforge:section --> | 구역 경계(본문에서만) |
<!-- chart -->·<!-- memo: … --> | 읽지 않고 건너뜁니다. 주석마다 경고 CONTENT_LOST(MdWarning::ContentLost)가 하나씩 나옵니다 |
각주·미주 정의 안에서는 서식, <br>, chart·memo 주석만 읽습니다. 링크·그림·표는 같은 자리의 Markdown 링크·그림·표처럼 오류이고, 구역 표지도 오류입니다. chart·memo 주석을 건너뛰어 정의에 글이 남지 않아도 오류가 아닙니다. 각주는 남은 문단 그대로(빈 서식 문단도 그대로, 문단이 없으면 빈 문단 하나) 남고 CONTENT_LOST 가 나옵니다.
HTML 표 안의 글은 HTML 글로 한 번만 읽습니다. **굵게** 같은 Markdown 은 셀 안에서 글자 그대로 남습니다. 예외는 각주·미주 참조 하나입니다. styled 보기는 셀 글의 [ 를 [ 로 쓰므로, 셀 안의 날 [^1] 은 보기가 쓴 참조이고 문서 끝 정의와 이어집니다. [^1] 은 글자 [^1] 입니다.
이미지

- 지원 포맷: PNG, JPEG, GIF, BMP, WMF, EMF (SVG는 지원하지 않습니다) — 확장자가 아니라 실제 바이트를 스니핑해 포맷을 확인합니다.
- 경로(상대·절대 모두)는 정규화한 뒤 Markdown 파일이 있는 디렉터리 하위에 있는지 검사합니다.
../로 그 디렉터리를 벗어나는 경로는 거부되지만, 그 디렉터리 안을 가리키는 절대 경로는 허용됩니다 — 거부되는 것은 “절대 경로“가 아니라 “벗어나는 경로“입니다. data:URI(base64)도 지원합니다 — 네트워크 접근 없이 로컬에서 바로 디코드됩니다. 기준 디렉터리가 없는 인라인 텍스트/stdin 입력에서는data:URI만 임베드할 수 있습니다.http(s)원격 URL은 네트워크 접근을 금지하는 정책상 거부됩니다.- 실패한 참조(파일 없음·경로 탈출·원격 URL·미지 포맷 등)는 경고와 함께 이미지 run이 드롭됩니다 — 결과 문서에 깨진 참조가 남지 않습니다.
- 파일 크기 상한은 50MB입니다.
구분선과 섹션 구분자
Markdown의 ---(frontmatter 블록 밖에서 단독으로 쓴 thematic break)는 리터럴 "---" 문단으로 변환됩니다 — 페이지나 섹션을 나누는 구분자가 아닙니다. HWPX 섹션(다른 페이지 설정 구역)을 나누려면 반드시 <!-- hwpforge:section --> 주석을 사용하세요 (앞의 섹션 마커 참고).
H1-H6 → 개요 1-6 자동 매핑
Markdown 헤딩은 한글의 개요 스타일로 자동 변환됩니다.
| Markdown | 한글 스타일 |
|---|---|
# H1 | 개요 1 (style ID 2) |
## H2 | 개요 2 (style ID 3) |
### H3 | 개요 3 (style ID 4) |
#### H4 | 개요 4 (style ID 5) |
##### H5 | 개요 5 (style ID 6) |
###### H6 | 개요 6 (style ID 7) |
| 일반 문단 | 본문 (style ID 0) |
목록 → 한컴 글머리표·번호 문단
Markdown 목록은 한컴의 글머리표·번호·체크 문단으로 바뀝니다. 표지(-, 1., [x])는 글자로 남지 않고 문단 모양의 목록 설정이 됩니다. 한컴에서 문단을 고치면 기호와 번호가 그 설정대로 따라옵니다.
| Markdown | 한컴 문단(기본 템플릿) |
|---|---|
- 항목 | 글머리표 문단. 수준 0·1·2 의 기호는 •·◦·▪, 그 뒤 수준은 이 셋을 되풀이 |
1. 항목 | 번호 문단. 수준 0–5 는 1.·가.·1)·가)·(1)·(가), 수준 6·7 은 원문자 숫자·한글, 수준 8·9 는 1. |
- [ ] 할 일·- [x] 끝난 일 | 체크 문단(☐·☑). 번호 목록 안의 체크 항목(1. [x] …)도 체크 문단 |
- 수준: 중첩 깊이가 수준입니다(0부터). 수준마다 왼쪽 여백이 20pt 씩 깊어지고, 첫 줄 내어쓰기는 없습니다(한컴이 둘째 줄을 기호 뒤 글이 시작하는 자리에 맞춥니다). 9 보다 깊은 목록은 수준 9 로 쓰고
LIST_LEVEL_CLAMPED를 냅니다. - 번호 형식과 Markdown: 번호 형식은 한컴에서 보이는 모양입니다. HWPX 를 Markdown 으로 다시 쓰면 번호 형식과 상관없이
1.표지로 나오고, 나란히 놓인 두 번호 목록을 가를 때만1)을 씁니다. - 항목 안의 블록: 항목의 둘째 문단, 항목 안의 표·코드 블록은 그 항목의 이어지는 문단(기호 없음, 왼쪽 여백은 항목 여백에 기호 폭 20pt 를 더한 값)입니다. 한컴에서 기호 폭은 번호 값과 상관없이 글자 크기의 2배로 고정해 쓰므로, 기본 글자 크기 10pt 에서는 항목 글과 이어지는 문단이 같은 자리에서 시작합니다. 글자 크기가 다르면 항목 글과 어긋날 수 있습니다. 기호 폭 고정은 그 수준의 숫자·한글·원문자 번호 하나에 ASCII 문자만 붙고 글자 크기의 2배 안에 드는 번호 형식에만 적용하고, 그 밖의 형식은 번호 값을 따릅니다. 표는 항목 글이 시작하는 자리에서 시작하고, 본문 표처럼 오른쪽 여백에서 끝나도록 열 폭을 그만큼 줄입니다. 항목 여백이 쪽 폭을 다 차지해 남는 폭이 없으면 열마다 최대 40mm 로 써서 오른쪽 여백을 넘을 수 있습니다. Markdown 표는 본문과 항목 안 모두 다음 줄과 붙어 보이지 않도록 아래에 10pt 를 비웁니다. 코드는 공백·탭·빈 줄을 그대로 두고, 마지막 줄 끝의 줄바꿈 하나만 뺍니다. 그래서 빈 줄 하나뿐인 코드 블록은 빈 코드 블록과 같은 문단이 됩니다. 글이 없는 항목(
-만 있는 줄, 표나 하위 목록으로 시작하는 항목)도 기호만 있는 빈 문단으로 남습니다. - 항목 안의 제목·구분선: 항목 밖의 제목·
---문단이 됩니다(항목 머리는 남음). 문단마다LIST_SEMANTICS_LOST를 냅니다. - 번호 목록마다 다시 시작: 번호 목록 하나(같은
Start(List)의 항목들)마다 번호 정의를 하나씩 씁니다. 본문 뒤의 두 번째1.목록, 같은 부모 아래 나란히 놓인 두 하위 목록(1.다음1))은 각각 1 부터 다시 셉니다. 한컴도 번호를 다시 시작할 때 새 번호 정의를 만듭니다. 한 문서는 번호 정의를 1024 번까지 복제합니다. 첫 번호 목록은 템플릿의 번호 정의가 Markdown 처럼 시작하면(번호 정의의 시작 0, 모든 수준의 시작 1. 기본 템플릿이 그렇습니다) 그 정의를 그대로 쓰므로, 1025 번째 목록까지 각자 셉니다. 그렇지 않은 템플릿은 첫 목록부터 복제하므로 1024 번째 목록까지입니다. 그 뒤의 목록은 템플릿의 번호 정의를 함께 써서 번호가 이어질 수 있고,NUMBERING_PRESENTATION_LOST를 한 번 냅니다. - 시작 번호: 1 이 아닌 수로 시작하는 목록(
3. 항목)은 1 부터 쓰고LIST_START_NORMALIZED를 냅니다(한컴이 시작 번호를 어느 값으로 보이는지 아직 확인하지 않았습니다). 체크 항목만 있는 목록은 번호를 쓰지 않으므로 경고가 없습니다. - 상위 수준 번호를 쓰는 서식: 템플릿의 번호 서식이 더 얕은 수준의 번호를 가리키면(
^1.^2), 하위 목록은 자기 번호 정의 안의 그 수준을 세므로 바깥 목록의 번호가 보이지 않습니다. 그 정의에NUMBERING_PRESENTATION_LOST를 한 번 냅니다. 자기 수준만 쓰는 서식((^2))은 그대로 됩니다. - 목록 정의가 없는 템플릿: 템플릿에 그 종류의 목록 역할이 없으면(스타일 템플릿) 그 항목은 목록이 아닌 문단으로 글과 순서만 남고, 종류마다
LIST_DEFINITION_MISSING을 한 번 냅니다.
반대로 HWPX 를 Markdown 으로 읽을 때(styled·lossy)는 한컴의 글머리표·번호·체크 문단을 -, 1., - [x] 항목으로 씁니다. 번호는 늘 1. 로 시작합니다(한컴이 계산한 번호를 다시 세지 않습니다). 나란히 놓인 서로 다른 번호 정의의 목록은 1. 와 1) 를 번갈아 써서 따로 읽히게 합니다. 항목의 코드 문단에 한컴에서 표·그림·컨트롤을 넣으면 그 문단은 코드 블록으로 쓸 수 없어 항목의 일반 이어지는 문단으로 쓰고, 코드의 공백 보존은 적용되지 않습니다. 한컴 문서에서 같은 번호 정의가 다른 블록 뒤에서 이어지면 Markdown 은 다시 1 부터 쓰므로 NUMBERING_PRESENTATION_LOST 를 냅니다. 표 칸·글상자·각주·캡션 안의 목록 문단은 그 보기가 글로 쓰므로 목록 의미가 빠지고, 문단마다 LIST_SEMANTICS_LOST 를 냅니다. lossy 보기가 원본 목록을 읽으려면 원본 스타일이 필요합니다. CLI 의 to-md, Python 의 to_md, MCP 의 hwpforge_to_md(styled 만)는 늘 원본 스타일로 읽습니다. Rust 에서 lossy 로 읽을 때는 MdEncoder::encode_lossy_with_styles 가 그 경로이고, 스타일을 받지 않는 encode_lossy 는 목록을 알지 못합니다.
lossy 보기는 본문 글자 1. 항목 을 escape 하지 않습니다(아래 “읽기 보기가 escape 하는 것” 절). 그래서 lossy Markdown 을 다시 convert 하면 그런 본문 문단이 번호 문단이 됩니다. 시작 번호가 1 이 아니면 LIST_START_NORMALIZED 가 그 사실을 알립니다.
MdEncoder — Core → Markdown
반대 방향(HWPX → Markdown) 변환도 지원합니다. 두 가지 모드가 있습니다.
#![allow(unused)] fn main() { use hwpforge::md::MdEncoder; use hwpforge::hwpx::HwpxDecoder; let result = HwpxDecoder::decode_file("document.hwpx").unwrap(); let validated = result.document.validate().unwrap(); // Lossy 모드: 읽기 좋은 GFM (표, 이미지 등 일부 정보 손실) let gfm = MdEncoder::encode_lossy(&validated).unwrap(); // Lossless 모드: YAML frontmatter + HTML-like 마크업 (보존 범위 확인용 기계 보기) let lossless = MdEncoder::encode_lossless(&validated).unwrap(); }
| 모드 | 특징 | 용도 |
|---|---|---|
encode_lossy | 읽기 좋은 GFM | 사람이 읽는 문서 미리보기 |
encode_lossless | 아래 보존 범위 안에서 보존, 못 담으면 거부 | 보존 범위 확인(기계용 보기) |
Markdown으로 HWPX를 재생성할 때 원본 패키지의 서명·암호화 상태는 승계되지 않습니다.
Lossless 출력은 Markdown 변환의 입력이 아닙니다. 프론트매터에 늘 metadata.format: lossless 를 담고, 일반 Markdown 디코드(CLI·MCP 의 convert, Python convert_md, Rust MdDecoder::decode)는 이 표식을 보면 MD_DECODE_FAILED(Rust 는 MdError::UnsupportedStructure)로 거부합니다. 문서를 고쳐 다시 HWPX 로 만들려면 JSON 왕복(to-json → 편집 → from-json)을 사용하세요. JSON 은 이미지를 담지 않으므로, from-json --base 로 기준 HWPX 의 이미지를 물려받습니다.
전체 파이프라인 예제 (MD string → HWPX file)
use hwpforge::md::{MdDecoder, MdDocument}; use hwpforge::hwpx::{HwpxEncoder, HwpxStyleStore}; fn markdown_to_hwpx(markdown: &str, output_path: &str) { // 1. Markdown 파싱 → Core DOM let MdDocument { document, .. } = MdDecoder::decode_with_default(markdown).unwrap(); // 2. 문서 검증 let validated = document.validate().unwrap(); // 3. 한컴 기본 스타일 적용 후 HWPX 인코딩 let style_store = HwpxStyleStore::with_default_fonts("함초롬바탕"); let image_store = Default::default(); let bytes = HwpxEncoder::encode(&validated, &style_store, &image_store).unwrap(); // 4. 파일 저장 std::fs::write(output_path, &bytes).unwrap(); println!("저장 완료: {output_path}"); } fn main() { let md = r#" --- title: AI 활용 정책 제안서 author: 정책팀 date: 2026-03-06 --- 제안 배경 인공지능 기술의 급속한 발전에 대응하여 정책 수립이 필요합니다. # 현황 분석 국내외 AI 활용 사례를 분석하였습니다. # 정책 방향 단계적 도입과 윤리적 기준 마련을 제안합니다. "#; markdown_to_hwpx(md, "proposal.hwpx"); }
HWPX → Markdown 변환 (RAG/LLM 활용)
HWPX 문서를 Markdown으로 변환하면 LLM이나 RAG(Retrieval-Augmented Generation) 시스템에서 직접 활용할 수 있습니다.
의존성 설정
Cargo.toml에 md 기능을 활성화합니다:
[dependencies]
hwpforge = { version = "0.20", features = ["md"] }
Lossy vs Lossless 모드 선택
| 기준 | Lossy (encode_lossy) | Lossless (encode_lossless) |
|---|---|---|
| 출력 형식 | 표준 GFM Markdown | YAML frontmatter + HTML 마크업 |
| 가독성 | 높음 (사람/LLM 모두) | 낮음 (기계 파싱용) |
| 정보 손실 | 스타일/레이아웃 일부 손실 | 보존 범위 안에서 보존 |
| RAG 추천 | 추천 — 청크 분할에 적합 | 쓰지 않음 |
| LLM 추천 | 추천 — 토큰 효율적 | 보존 범위 확인 시(편집은 JSON 왕복) |
Lossless 모드는 그림·도형·묶음의 개체 틀(원래 크기와 크기 고정)을 data-original-width-unit·data-original-height-unit·data-size-protect 속성으로, 표의 크기 고정을 data-size-protect 로 담고, Rust MdDecoder::decode_lossless 가 이를 되읽습니다(표에는 원래 크기가 없습니다). 이 속성들은 이전 버전의 디코더가 무시하므로, 이전 버전으로 되읽으면 개체 틀은 기본값이 됩니다.
Lossless 보존 범위
Lossless 모드는 표 칸·행의 제목 속성(아래 문법)과 아래 “보존하는 것“을 Rust MdDecoder::decode_lossless 가 그대로 되읽을 수 있게 쓰고, “거부하는 것“이 있으면 일부를 버리는 대신 문서 전체를 거부합니다(ENCODE_FAILED, Rust 는 MdError::UnsupportedStructure). 두 목록 밖의 값은 모두 거부 없이 빠집니다.
| 구분 | 내용 |
|---|---|
| 보존하는 것 | 구역의 쪽 크기·여백, 문단·run 구조와 글자, 문단 모양·글자 모양 번호(para_shape_id·char_shape_id — 문단 스타일 style_ref 는 아님), 표의 행·칸(병합·너비·배경·줄 나눔 방식)·행 높이·표 너비·크기 고정·칸 크기 고정·셀 영역, 표 캡션의 글자·위치(측)·전체 폭 여부·저장된 너비, 링크(글자 링크와 그림 링크), 각주 본문, 그림·도형의 개체 틀(원래 크기·크기 고정), 그림(본문·묶음 안 모두: 배치와 위치·바깥 여백, 크기, 자르기, 이미지 크기, 링크, 개체 번호, 그림 형식 이름 원문)과 본문 그림의 캡션(위치·간격·너비·전체 폭 여부·저장된 너비와 문단), 도형(글상자·선·타원·다각형·사각형·호·곡선·연결선, 본문·묶음 안 모두: 정의점, 크기, 배치와 위치·바깥 여백, 선 색·두께·종류, 채우기(단색·그러데이션·무늬·없음), 회전·뒤집기·화살표·문단 첫 글자 장식·둥근 모서리, 글자의 세로 정렬, 글상자 안쪽 여백, 안의 문단), 묶음 개체와 중첩 묶음 |
| 빠지는 것(예) | 문단의 쪽·단 나눔·개요 수준·style_ref·줄 배치 캐시, 탭 정보, 칸 여백·칸 세로 정렬, 표 캡션의 간격·너비와 글자가 아닌 내용, 구역의 단·쪽 번호 등 쪽 설정 밖의 값, 머리말·꼬리말·바탕쪽과 그 안의 개체, 각주·미주 번호 |
| 거부하는 것 | 묶음 안의 수식·차트·글맵시, 도형의 캡션, 그림 채우기, 예약 비트가 켜진 도형 색·칸 배경색, 문단 없는 글상자·점 세 개 미만 다각형(어디에 있든), 32 겹을 넘는 중첩, 회전값 NaN·무한대, 묶음 안 그림의 캡션, 표 캡션 안의 그림·묶음·도형, 그림 캡션과 도형 글 안의 내용이 빈 문단·표·칸·각주, 그 밖에 이 형식이 표현하지 못하는 컨트롤 |
| 쓰지만 되읽지 못하는 것 | <endnote>·<dutmal>·<compose> — 이 요소가 든 Markdown 은 decode_lossless 가 오류를 냅니다 |
| 되읽기 | Rust API MdDecoder::decode_lossless 만 읽습니다. CLI·MCP 의 convert·Python convert_md 는 프론트매터의 metadata.format: lossless 표식을 보고 MD_DECODE_FAILED 로 거부합니다 |
<group>·<img>·<caption> 과 도형 요소(<textbox>·<line>·<ellipse>·<polygon>·<rect>·<arc>·<curve>·<connectline>)는 정해진 속성만 받습니다 — 모르는 속성이나 같은 속성이 두 번 나오면 디코드가 실패합니다. 속성 값 안의 제어 문자(탭·줄바꿈 등)는 	 같은 문자 참조로 써서 그대로 되읽습니다.
표의 제목 속성은 <td data-header="true|false">와 <tr data-is-header="true|false">로 보존합니다. 값은 소문자 true 또는 false만 허용하며 잘못된 값·중복 속성은 오류입니다.
td의data-header="true"·"false"는 칸의 명시값(Some)입니다. 생략하면None으로 행 값을 상속합니다. 명시적false를 생략하면 의미가 바뀔 수 있습니다.tr의data-is-header는 옛 문서·생성 코드의 상속 기준이자 파생된 제목행 편의값입니다. 생략은false이고 출력도false를 생략합니다. 모든 칸의 실효값이 참인 비어 있지 않은 선두 연속 행만 제목행입니다. 빈 물리 행은 rowspan으로 덮여 있어도 이 블록을 끝냅니다.- 검증 시 칸 실효값에서 행 값을 정규화합니다. 행 값이 바뀌면 그 행의
None칸은 이전 실효값의 명시값으로 고정합니다. 따라서encode_lossless→decode_lossless는 검증된 문서의None/Some을 보존하며, 검증 전의 모순된 행 플래그를 그대로 보존하는 계약은 아닙니다. - 두 속성을 모르는 이전 lossless 독자는 속성을 무시하므로 칸·행 제목 정보가 사라집니다. 일반 Markdown 독자는 HTML 사용자 정의 속성을 화면에 표시하지 않습니다. styled·lossy는 기존처럼 첫 물리 행을 GFM 머리 행으로 쓰며 칸별 제목값을 보존하지 않습니다.
- PDF는 공용 제목행 규칙과 표의
repeat_header가 참일 때만 선두 블록을 반복합니다. 혼합 행의 일부 제목칸·비선두 제목칸은 보존되지만 반복 대상으로 승격되지 않습니다. 제목행 경계를 가로지르는 rowspan은 PDF에서 거부합니다. 혼합 제목칸의 한컴 반복 배치와 같다는 보장은 없습니다.
컨테이너(표·묶음·그림·캡션·도형·각주)는 32 겹까지 중첩할 수 있습니다. 더 깊은 문서는 인코드가, 더 깊은 Markdown 은 디코드가 오류로 거부합니다.
필드 경계는 본문 run 사이의 <field-start>·<field-end/>로 보존합니다. 시작·끝 ID, 종류, 이름, 플래그의 원문 문자열, 파라미터의 종류·순서·이름·값·공백 속성은 정확히 되읽습니다. 주석 문단은 시작 요소의 <field-annotation> 안에 담으며, 그 안의 문단·표에는 위의 투영 범위가 적용됩니다. None과 빈 주석 목록, 파라미터 그룹 이름 없음과 빈 이름은 구별합니다. 원문에 끝이 없는 시작은 data-unclosed="true"로 명시합니다(생략 또는 false는 일반 범위이며, 다른 표기는 거부합니다). 끝 경계를 만들지 않으며, Core 검증은 이를 경고로 허용합니다. 표시 없이 짝이 깨지거나 미종결 표시와 끝 경계가 함께 있으면 오류입니다. 미종결 범위의 시작부터 해당 독립 흐름 끝까지는 편집할 수 없습니다. 기존 접힌 Control::Field·Control::Memo에는 별도의 lossless 문법이 없습니다. lossy·styled는 경계를 표시하지 않고 일반 본문을 씁니다.
| 요소 | 허용 속성 | 부모·자식·빈 형식 |
|---|---|---|
<field-start> | data-char-shape, data-id, data-kind, data-name, data-editable, data-dirty, data-z-order, data-field-id, data-meta-tag 필수; data-parameter-name, data-unclosed 선택 | 부모 p. field-param 0개 이상 다음 field-annotation 0–1개. 자식 없으면 /> 또는 명시적 닫기 |
<field-end/> | data-char-shape, data-begin-id, data-field-id 필수 | 부모 p. 빈 요소만 허용 |
<field-param/> | data-kind(String·Integer·Boolean), data-name, data-value 필수. data-xml-space는 String에만 필수, 나머지에는 금지 | 부모 field-start. 빈 요소만 허용. 숫자·불리언 값도 원문 문자열로 운반 |
<field-annotation> | 없음 | 부모 field-start. p 0개 이상. />도 허용 |
이 네 요소는 모르는 속성·중복 속성·잘못된 부모·자식·중복 주석을 거부합니다. 속성은 공통 escape_attr 규칙을 따릅니다. field-start는 깊이 한도에서 한 겹이며, 파라미터·주석 래퍼는 추가 깊이로 세지 않습니다. 복구 표시 없이 짝이 깨진 범위는 Core 검증에서 거부하므로 lossless 인코드 입력으로 사용할 수 없습니다. 표 캡션처럼 경계를 버리는 경로도 인코드가 거부합니다.
버전·도구 사이의 호환
이 형식은 보존 범위를 확인하는 기계용 보기이고, 되읽는 것은 Rust MdDecoder::decode_lossless 뿐입니다. 일반 Markdown 미리보기나 HTML 렌더러에서는 구조가 다르게 보일 수 있습니다.
| 이 버전이 쓴 것 | 이전 버전(v0.16.10) 디코더 | 일반 HTML 렌더러 |
|---|---|---|
캡션 없는 <img … />(배치·개체 번호·자르기 등 속성이 늘어남) | 읽지만 새 속성은 무시해 그 값을 잃음 | 그림으로 보임 |
캡션 있는 <img …><caption>…</caption></img> | 오류 | <img> 는 자식을 가질 수 없어 캡션이 그림 밖으로 나옴. 표 칸 안이면 <caption> 이 칸을 닫아 바깥 표의 캡션으로 옮겨질 수 있음 |
<group>·<rect>·<arc>·<curve>·<connectline>, 그리고 <line>·<ellipse>·<polygon> | 오류(<line>·<ellipse>·<polygon> 은 이전 버전이 쓰기는 했으나 읽지 못하던 태그) | 모르는 요소로 다룸 |
<textbox> 의 새 속성(스타일·배치·세로 정렬·안쪽 여백) | 읽지만 새 속성은 무시해 그 값을 잃음 | — |
<td data-line-wrap> | 무시해 기본 줄 나눔이 됨 | — |
<field-start>·<field-end/>·<field-param/>·<field-annotation> | 오류(필드 문법 도입 전 디코더는 모르는 태그를 거부) | 모르는 요소로 다루며 주석 글자가 본문에 보일 수 있음 |
<field-start data-unclosed="true"> | 필드 문법 도입 전에는 모르는 태그 오류; 미종결 속성 도입 전에는 허용 목록 밖 속성 오류 | 속성을 무시하고 본문 글자를 표시 |
속성 값의 	 같은 문자 참조 | 원래 글자로 읽음 | 원래 글자로 읽음 |
반대 방향으로, 이전 버전이 쓴 lossless Markdown 은 이 버전이 읽을 수 있는 범위에서 그대로 읽습니다 — 이전 출력의 속성은 모두 새 디코더가 받는 속성 목록에 들어 있습니다. 다만 <endnote>·<dutmal>·<compose> 는 여전히 읽지 못하고, 컨테이너가 32 겹을 넘게 중첩된 파일은 새 깊이 한도로 이제 오류가 납니다.
묶음 개체는 lossy·styled 모두 자식을 본문과 같은 방식으로 그 자리에 그립니다(그림은 링크, 글상자는 그 글). lossy 는 글상자·도형·각주 글자 안의 그림과 묶음을 그리지 않습니다(그 글은 평문). styled 는 쓴 그림 링크마다 그 그림 파일을 images 에 함께 내며, 메모(<!-- memo: … -->) 안의 그림은 링크 글자만 씁니다. 병합 칸(HTML 표) 안의 글상자 글은 HTML 서식(<strong> 등)으로 씁니다. 각주 안이나 메모 안의 각주는 (주: …) 로 본문에 넣습니다. 중첩 깊이는 보기마다 세는 법이 다릅니다. lossless 와 lossy 는 문서 구조의 깊이를 lossless 디코더와 같은 방식으로 셉니다 — 표·그림(캡션은 한 겹 더)·묶음·도형·각주·메모가 한 겹씩이고, 32 겹을 넘으면 오류를 냅니다. styled 는 그리면서 들어가는 깊이를 셉니다 — 표·캡션·도형 글·각주·메모만 한 겹씩이고 묶음과 그림 자체는 세지 않으므로, 같은 문서라도 lossless·lossy 가 거부하는 깊이를 styled 는 그릴 수 있습니다(예: 묶음 → 글상자 17번 반복은 구조 깊이 34 라 lossy 는 거부, styled 는 글상자 17 겹이라 그림). styled 는 32 겹을 넘는 자리에 오류 대신 (중첩 깊이 초과로 생략) 을 씁니다. lossy 는 표 안의 표가 8 단계를 넘으면 그 자리에 (중첩 표 생략) 을 씁니다. 생략한 자리는 경고로 알립니다 — Rust 는 MdOutput::warnings·encode_lossy_with_report 의 MdWarning::ContainerTooDeep, CLI·MCP·Python 은 경고 코드 CONTAINER_TOO_DEEP. styled 는 수식을 $…$ LaTeX 로 쓰되 Markdown 글에서는 <·> 를 \lt·\gt 로 바꾸고, LaTeX 에 $·]( 가 있거나 \ 로 끝나면 수식 스크립트를 일반 글자로 쓴 뒤 MdWarning::EquationAsText(경고 코드 EQUATION_AS_TEXT)로 알립니다.
styled 의 글자 서식과 문단 스타일
styled 는 글자의 굵게·기울임·취소선·밑줄·위 첨자·아래 첨자를 그 문단 스타일의 기본 글자 모양과 비교해, 스타일이 이미 주는 서식은 강조로 쓰지 않습니다. 굵은 개요 스타일의 제목은 # **제목** 이 아니라 # 제목 으로 씁니다. 비교는 글자 모양 번호가 아니라 이 여섯 속성의 값으로 합니다(글꼴·크기·색은 보지 않습니다). 스타일이 주지 않는 서식만 씁니다. 굵은 제목 안의 기울임은 # *제목* 입니다.
다음 경우에는 전처럼 글자의 서식을 그대로 씁니다.
- 문단에 스타일이 없거나, 스타일의 기본 글자 모양을 알 수 없을 때. Rust 에서 직접 만든
StyleLookup은style_char_shape를 구현해야 이 비교가 적용됩니다(기본 구현은None). - 문단 안에 스타일 서식을 끈 글자가 있을 때(굵은 스타일 문단의 굵지 않은 글자). Markdown 에는 강조를 끄는 표기가 없으므로, 그 문단은 글자끼리의 대비를 지키도록 절대 서식으로 씁니다.
이 출력은 외형을 보존하는 계약이 아닙니다. 문단 스타일 자체는 Markdown 에 남지 않으므로, convert 하면 스타일이 주던 서식은 쓰는 템플릿의 것이 됩니다. 예를 들어 한컴의 굵지 않은 개요 스타일에 굵은 글자로 쓴 제목은 # **제목** 으로 나옵니다. 이것을 기본 템플릿(굵은 제목)으로 convert 한 뒤 다시 읽으면 # 제목 입니다. 같은 템플릿으로 만든 문서는 두 번째 읽기부터 결과가 같습니다. 스타일과 같은 서식을 원문에서 일부러 표시했는지(# **제목**)는 문서에 남지 않으므로 구별하지 않습니다. 코드 글꼴 문단을 코드 블록으로 쓰는 판정은 이 비교와 따로입니다.
읽기 보기(styled·lossy)가 escape 하는 것과 쓰는 HTML
문서 글자는 그 글자가 놓이는 자리(Markdown 글, GFM 표 칸, HTML 칸, 코드)에 맞게 한 번만 escape 해서 씁니다. 두 보기 모두 다음은 같습니다.
- 줄 끝: Core 문자열을 Markdown으로 쓸 때 CRLF 쌍, 단독 CR, 단독 LF 는 각각 LF 하나로 정규화합니다. HWPX 본문을 읽을 때는 날 문자·문자 참조·CDATA의 CR과 LF를 각각 LF 하나로 읽습니다. 실제
to-md의 styled·lossy 출력에서 본문 문단의a\r\nb는a\n\nb가 되며, Markdown 글에서는 빈 줄로 문단을 나눕니다. styled 제목은 한 줄이라 줄 끝이 공백이 됩니다. GFM 칸과 HTML 칸에서는 각 줄 끝을<br>로 씁니다. Core·patch·fill 값으로 직접 준 CRLF는 한 글 조각 안에서 줄바꿈 하나로 쓰는 기존 계약을 유지합니다. - 링크: 주소가
http://·https://·mailto:(대소문자 무관)이거나 비어 있고, 공백·제어 문자가 없을 때만 링크로 씁니다. 상대 경로,#앵커, 그 밖의 스킴은 표시 글자만 씁니다. 이전 버전은 이런 링크도 썼으므로 동작이 바뀐 부분입니다. - 링크 주소·그림 경로: 다시 읽었을 때 원래 값과 같도록 씁니다.
\·(·)·<·>, 그리고 엔티티 앞의&는 앞에\를 붙입니다. 공백이 있으면<…>형식으로 씁니다. 줄 끝은 주소 안에 둘 수 없어서%0A·%0D로 씁니다. 링크 글자와 그림 대체 글자 안의 줄 끝은 공백으로 씁니다. - 코드: 코드 블록과 코드 스팬의 울타리는 내용에 있는 가장 긴 백틱 연속보다 깁니다. 그래서 내용이 울타리를 닫지 못합니다.
styled 는 글자에 Markdown escape 를 적용합니다. *·_·`·[·]·~·\·# 앞에 \ 를 붙이고, <·> 는 <·>, 엔티티 앞의 & 는 \& 로 씁니다. 서식 태그(<u> 등) 안의 글자도 같은 방식으로 escape 합니다. Markdown 렌더러는 인라인 HTML 태그 안의 Markdown 도 해석하기 때문입니다. HTML 칸의 글자는 HTML escape 합니다.
수식은 $…$ LaTeX 로 씁니다. 이때 보장하는 범위는 실행 가능한 HTML 과 검사하지 않은 링크를 만들지 않는 것까지입니다. <·> 는 \lt·\gt 로 바꿉니다. LaTeX 에 $·]( 가 있거나 \ 로 끝나면 수식 스크립트를 글자로 쓰고 EQUATION_AS_TEXT 로 알립니다. $ 안의 다른 Markdown(*x* 등)은 수식 렌더러가 먼저 읽는다고 보고 글자로 바꾸지 않습니다. 중첩이 너무 깊어 변환하지 못한 수식도 글자로 쓰지만, 이 경우에는 경고를 내지 않습니다.
lossy 는 문서 글자를 거의 그대로 씁니다. CommonMark 가 글자가 아닌 마크업으로 읽는 자리에만 앞에 \ 를 붙입니다. 판정은 문단 전체를 한 번에, 인코더가 만든 마크업(링크·그림·표)까지 문맥으로 넣어서 합니다. 그래서 여러 run 에 걸친 시퀀스([a] 다음 run 의 (…)), 링크 양옆의 원문이 함께 만드는 태그(<img title=' · 링크 · ' onerror=…>), 원문과 마크업이 맞닿아 생기는 문법(원문 ! 바로 뒤의 링크, 원문 끝의 \ 바로 뒤의 링크)도 잡습니다.
| escape 하는 것 | 예 |
|---|---|
raw HTML 을 여는 < — 완전한 여는 태그(이름, 속성, >·/>), 닫는 태그, 주석, <?, 선언, CDATA, HTML 블록을 여는 태그 이름(div·table·script 등 뒤에 공백·>·줄 끝) | <b>, </b>, <The Pulse>, <!-- -->, <div 가 |
자동 링크를 여는 < | <https://…>, <a@b> |
엔티티·문자 참조를 여는 & | &, < |
인라인 링크·그림 이름을 닫는 ](뒤에 () | [현재단계](기관) |
링크 참조 정의를 여는 [ — 줄 머리, 인용문 >·목록 표지 뒤 포함, 라벨이 여러 줄이어도 | [a]: …, > [a]: …, - [a]: … |
마크업 앞의 백틱(코드 스팬이 링크를 삼키지 않게), 줄 머리의 코드 울타리(```·~~~ 세 개 이상) | — |
링크 글자·그림 대체 글자의 \·[·]·` | — |
위에 해당하지 않는 글자는 그대로 둡니다. 예를 들어 <붙임>, <표 1>, <AI가 바꾼 것>, a < b, [참고], AT&T, *강조*, # 제목, 1. 항목 은 그대로 씁니다. 그래서 *·_·#·-·숫자 목록은 Markdown 서식으로 보일 수 있습니다. lossy 는 읽기 위한 보기라서 이 차이는 받아들였습니다. escape 하는 글자 바로 앞에 원래 있던 역슬래시는 두 배로 써서 글자로 남깁니다.
마지막으로 두 보기 모두 완성된 Markdown 을 다시 파싱해 검사합니다. 인코더가 쓰지 않는 마크업 — 아래 목록 밖의 HTML, 인코더가 만들지 않은 링크·그림, 링크 참조 정의 — 이 나오면, 그 최상위 문단을 모든 구두점을 escape 한 평문으로 다시 쓰고 MdWarning::MarkupWrittenAsText(경고 코드 MARKUP_WRITTEN_AS_TEXT)로 알립니다. 문단 하나로는 문제가 없는데 문단끼리 작용해 생긴 경우(다른 문단의 참조 정의 등)에는 모든 문단을 평문으로 씁니다. 위 규칙들이 제대로 동작하면 이 경고는 나오지 않습니다. 측정 코퍼스(한컴 HWPX·HWP5)에서도 0 건입니다.
두 보기가 직접 쓰는 HTML 은 아래 것뿐입니다. 이 밖의 HTML 은 문서 글자에서 생기지 않습니다(src/encoder/markup_safety_tests.rs 가 공격 문자열을 모든 자리에 넣고 출력을 파싱해 확인합니다).
| HTML | 쓰는 곳 |
|---|---|
<br> | 표 칸 안 줄바꿈(GFM 칸·HTML 칸), HTML 칸 캡션 |
<table>·<tbody>·<tr>·<td colspan rowspan> | styled 병합 칸·표 안 표 |
<strong>·<em>·<del>·<u>·<sup>·<sub> | styled 서식 |
<a href>·<img src alt> | styled HTML 칸 링크·그림(속성은 HTML escape, 줄 끝은 문자 참조) |
<!-- hwpforge:section -->·<!-- chart -->·<!-- memo: … --> | 구역 경계·차트 자리·메모(메모 본문은 한 줄, 줄바꿈은 공백, - 는 \-) |
styled 의 결과 MdOutput 에는 markdown·images·warnings 세 필드가 있습니다. #[non_exhaustive] 구조체라서 크레이트 밖에서는 구조체 리터럴로 만들 수 없고, MdEncoder::encode_styled 로만 만듭니다. 필드를 읽거나 let MdOutput { markdown, images, .. } = out; 처럼 .. 를 넣어 분해합니다.
RAG 시스템에서는 encode_lossy를 권장합니다. 표준 GFM으로 출력되어 청크 분할기(text splitter)와 호환성이 높고, 불필요한 마크업이 없어 토큰을 절약합니다.
완전한 HWPX → Markdown 예제 (에러 처리 포함)
use hwpforge::hwpx::HwpxDecoder; use hwpforge::md::MdEncoder; use std::path::Path; fn hwpx_to_markdown(input_path: &str) -> Result<String, Box<dyn std::error::Error>> { // 1. 파일 존재 여부 확인 let path = Path::new(input_path); if !path.exists() { return Err(format!("파일을 찾을 수 없습니다: {}", input_path).into()); } // 2. HWPX 디코딩 let result = HwpxDecoder::decode_file(input_path) .map_err(|e| format!("HWPX 디코딩 실패: {e}"))?; // 3. 메타데이터 확인 (선택) let meta = result.document.metadata(); if let Some(title) = &meta.title { eprintln!("문서 제목: {}", title); } // 4. Draft → Validated 상태 전이 let validated = result.document.validate() .map_err(|e| format!("문서 검증 실패: {e}"))?; // 5. Markdown 변환 (RAG용 lossy 모드) let markdown = MdEncoder::encode_lossy(&validated) .map_err(|e| format!("Markdown 인코딩 실패: {e}"))?; Ok(markdown) } fn main() { match hwpx_to_markdown("document.hwpx") { Ok(md) => { std::fs::write("output.md", &md).expect("파일 저장 실패"); println!("변환 완료: {} bytes", md.len()); } Err(e) => eprintln!("오류: {e}"), } }
대량 파일 변환
여러 HWPX 파일을 Markdown으로 일괄 변환합니다:
#![allow(unused)] fn main() { use hwpforge::hwpx::HwpxDecoder; use hwpforge::md::MdEncoder; use std::path::Path; fn batch_convert(input_dir: &str, output_dir: &str) -> Result<usize, Box<dyn std::error::Error>> { std::fs::create_dir_all(output_dir)?; let mut count = 0; for entry in std::fs::read_dir(input_dir)? { let entry = entry?; let path = entry.path(); if path.extension().is_some_and(|ext| ext == "hwpx") { let result = HwpxDecoder::decode_file(&path)?; let validated = result.document.validate()?; let markdown = MdEncoder::encode_lossy(&validated)?; let out_name = path.file_stem().unwrap().to_string_lossy(); let out_path = Path::new(output_dir).join(format!("{}.md", out_name)); std::fs::write(&out_path, &markdown)?; eprintln!("변환: {} → {}", path.display(), out_path.display()); count += 1; } } Ok(count) } }
CLI로 변환
# Markdown → HWPX
hwpforge convert report.md -o report.hwpx
# HWPX → Markdown
hwpforge to-md report.hwpx -o report.md
# 변환 모드 선택 (기본값: styled)
hwpforge to-md report.hwpx -o report.md --mode lossy
hwpforge to-md report.hwpx -o report.md --mode lossless
# HWPX 구조 확인 후 JSON으로 추출 (Markdown 변환 대안)
hwpforge inspect document.hwpx --json
hwpforge to-json document.hwpx -o document.json
참고: CLI의
convert명령은 Markdown → HWPX 방향만 지원합니다. HWPX → Markdown 변환은hwpforge to-md명령(모드styled/lossy/lossless) 또는 Rust API(MdEncoder)를 사용하세요.lossless출력은convert입력으로 쓸 수 없으므로, 왕복 편집에는to-json/from-json을 사용하세요.