DOCX 파일을 열어 문단 텍스트를 순서대로 꺼낸 뒤 Markdown 기호를 붙이면 변환기가 완성될 것처럼 보입니다. 실제 문서를 다루기 시작하면 이 접근은 빠르게 한계에 도달합니다.
DOCX는 하나의 XML 파일이 아니라 여러 XML과 관계 파일, 이미지, 스타일, 번호 체계가 ZIP 안에서 연결된 패키지입니다. 화면에 보이는 한 문단도 다음 정보의 조합일 수 있습니다.
- 문서 본문의 paragraph와 run
- styles.xml의 스타일 상속
- numbering.xml의 목록 정의
- relationships의 링크와 이미지
- footnotes, endnotes, comments의 별도 정의
- 표의 병합 정보
- 변경 추적의 삽입과 삭제
- 필드 코드와 북마크
따라서 DOCX를 Markdown으로 바꾸는 일은 태그 치환이 아니라 분산된 문서 의미를 복원해 다른 표현으로 직렬화하는 일입니다.
undocx는 이 문제를 parser와 renderer 사이에 DocumentAst를 두는 방식으로 해결합니다.
전체 변환 흐름
flowchart LR A[DOCX ZIP/XML] --> B[rs-docx Parser] B --> C[DocxExtractor] C --> D[DocumentAst] C <--> E[ConversionContext<br/>번호·스타일·관계·참조 상태] D --> F[Reference Validation] F --> G[MarkdownRenderer] G --> H[Markdown]
기본 흐름은 다음과 같습니다.
- 경로, bytes 또는
Read + Seek입력에서 DOCX 문서를 읽습니다. - 이미지 처리 정책과 변환 옵션을 준비합니다.
DocxExtractor가 DOCX 요소를 block 기반DocumentAst로 변환합니다.- 각주, 댓글, 이미지와 내부 참조의 무결성을 검사합니다.
Renderer가 AST를 Markdown으로 직렬화합니다.
이 구조에서 중요한 것은 parser가 곧바로 Markdown 문자열을 만들지 않는다는 점입니다.
왜 AST가 필요한가
XML 노드를 읽는 코드와 Markdown을 출력하는 코드를 직접 연결하면 처음에는 빠르게 구현할 수 있습니다. 하지만 기능이 늘수록 두 책임이 뒤엉킵니다.
예를 들어 표 셀 안의 목록을 처리한다고 가정해보겠습니다.
- XML parser는 셀과 문단의 구조를 알아야 합니다.
- 목록 resolver는 현재 numbering definition과 level을 알아야 합니다.
- Markdown renderer는 중첩 깊이에 맞는 들여쓰기를 결정해야 합니다.
- 이미지와 각주가 있다면 별도 reference도 만들어야 합니다.
이 모든 결정을 한 함수에서 처리하면 parser 변경이 출력 포맷 전체에 영향을 줍니다. 테스트도 최종 문자열 비교에 의존하게 됩니다.
AST 경계는 문제를 세 단계로 나눕니다.
- Parsing: DOCX 패키지와 XML을 읽는다.
- Semantic extraction: 문서 요소를 단락, 목록, 표, 이미지, note 같은 의미 구조로 바꾼다.
- Rendering: 의미 구조를 Markdown 문법으로 표현한다.
이 분리의 효과는 큽니다.
- parser 변경이 renderer에 직접 전파되는 범위를 줄입니다.
- Markdown 외의 출력 형식을 추가할 수 있습니다.
- extractor와 renderer를 각각 테스트할 수 있습니다.
- 렌더링 전에 공통 reference validation을 수행할 수 있습니다.
- 도메인 규칙이 문자열 조립 코드에 숨지 않습니다.
문서 변환에는 전역 상태가 필요하다
문서의 각 노드는 독립적이지 않습니다. 현재 노드만 봐서는 올바른 출력을 만들 수 없는 경우가 많습니다.
목록의 연속성
DOCX 목록은 화면에 1., 2., 3.으로 보여도 각 문단에 숫자 문자열이 직접 저장되지 않을 수 있습니다. numbering ID, abstract definition, level, restart 규칙을 함께 해석해야 합니다.
중첩 목록에서는 현재 level뿐 아니라 상위 level의 상태도 필요합니다.
이미지 관계
본문 XML에는 이미지 파일명이 아니라 relationship ID가 들어갑니다. 변환기는 해당 ID를 실제 media 파일과 연결하고, inline·directory 저장·skip 중 선택한 정책에 따라 출력해야 합니다.
같은 이미지가 여러 번 참조되거나 파일명이 충돌하는 경우도 처리해야 합니다.
각주와 댓글
본문에는 reference만 있고 실제 내용은 별도 XML에 존재합니다. 출력할 때는 정의를 한 번만 만들고, 깨진 reference와 중복 ID를 탐지해야 합니다.
스타일 상속
문단과 run의 실제 스타일은 직접 지정된 속성뿐 아니라 문서 기본값과 상위 스타일을 통해 결정됩니다. 굵게, 제목, 정렬 같은 결과를 얻으려면 inheritance를 해석해야 합니다.
표 병합
colspan, rowspan, 다중 문단 셀, 중첩 표는 단순한 행·열 순회로 표현하기 어렵습니다. Markdown 표가 표현할 수 없는 구조는 HTML fallback이나 명시적 손실 정책도 필요합니다.
이 상태를 ConversionContext와 전문 resolver가 관리하면 개별 converter는 “현재 요소를 어떤 AST 노드로 만들 것인가”에 집중할 수 있습니다.
문자열이 아니라 의미를 먼저 보존한다
문서 변환의 목표를 “원본과 같은 문자열”로 두면 판단이 모호해집니다. DOCX와 Markdown은 표현 능력이 다르기 때문입니다.
더 나은 기준은 다음 우선순위입니다.
- 문서의 논리적 순서
- 제목, 단락, 목록, 표 같은 구조
- 링크, 이미지, 각주와 댓글의 참조 관계
- 강조, 삭제, 삽입 같은 의미 있는 서식
- 정렬과 공백 같은 시각적 표현
- 표현할 수 없는 기능의 명시적 fallback
예를 들어 underline은 표준 Markdown 문법이 없으므로 HTML <u>를 사용할지, 의미를 포기할지 정책으로 결정해야 합니다. 표 병합도 GFM 표만으로 표현할 수 없다면 HTML을 허용하거나 구조 손실을 문서화해야 합니다.
좋은 변환기는 모든 서식을 억지로 보존하는 도구가 아니라, 무엇을 보존하고 무엇을 손실할지 계약이 명확한 도구입니다.
API를 세 층으로 나눈 이유
대부분의 사용자는 설정 없이 파일 하나를 변환하고 싶어합니다. RAG 파이프라인에서는 이미지 제외나 엄격한 참조 검사가 필요할 수 있습니다. 라이브러리 사용자는 extractor나 renderer 자체를 교체하고 싶을 수도 있습니다.
따라서 API를 세 층으로 나눌 수 있습니다.
- 간단한 함수
- 파일 경로 변환
- bytes 변환
- reader 변환
- Builder
- 이미지 처리
- 공백 보존
- HTML 사용
- reference validation
- Custom pipeline
AstExtractor교체Renderer교체- 계측이나 다른 출력 포맷 주입
간단한 사용법을 위해 확장성을 포기하거나, 확장성을 위해 모든 사용자에게 generic과 trait을 노출할 필요가 없습니다. 입구를 여러 층으로 만들면 기본 사용성과 고급 확장을 함께 유지할 수 있습니다.
테스트는 출력 문자열 하나로 끝나지 않는다
문서 변환기는 edge case가 매우 많습니다. 몇 개의 예제 파일이 성공한다고 품질을 보장할 수 없습니다.
undocx에서는 테스트 책임을 계층별로 나눕니다.
| 테스트 | 확인하는 것 |
|---|---|
| Unit test | 번호, 단락, 스타일, 표, 이미지 같은 국소 규칙 |
| Golden snapshot | 대표 문서의 전체 Markdown 출력 안정성 |
| Regression test | 과거에 발견된 버그가 다시 발생하지 않는지 |
| Parser feature test | DOCX XML 기능별 해석 경계 |
| Randomized invariant | 생성된 참조와 정의가 항상 일관적인지 |
| Doctest | 공개 API 예제가 실제로 컴파일되는지 |
특히 randomized invariant는 특정 문자열을 기대하기보다 다음과 같은 불변식을 검사하는 데 유용합니다.
- 모든 note reference에는 정확히 하나의 정의가 있다.
- 정의되지 않은 이미지 relationship이 출력되지 않는다.
- 같은 ID의 정의가 중복 생성되지 않는다.
- renderer가 처리할 수 없는 AST 상태가 조용히 유실되지 않는다.
Golden test는 결과의 변화를 잘 잡지만, 변화가 옳은지까지 판단하지는 않습니다. snapshot 변경을 검토할 때 의미 손실 여부를 함께 봐야 합니다.
벤치마크 수치는 계약이 아니다
문서 변환 프로젝트에서는 처리 속도를 비교하기 쉽습니다. 하지만 한 corpus와 한 장비에서 얻은 평균 시간은 모든 문서에 적용되는 보편적 성능이 아닙니다.
벤치마크를 해석할 때 최소한 다음을 함께 봐야 합니다.
- 문서 수와 크기
- 이미지와 표의 비중
- warm-up과 반복 횟수
- subprocess 시작 비용 포함 여부
- 출력 기능의 동등성
- CPU와 스토리지 환경
- 평균뿐 아니라 p95와 최악값
속도는 중요하지만 정확히 보존하지 못한 기능을 생략해서 빨라진 것이라면 같은 작업을 비교한 것이 아닙니다. 성능 주장은 재현 가능한 스크립트와 corpus 경계를 함께 공개해야 합니다.
코드보다 릴리스 메타데이터가 먼저 어긋날 수 있다
오픈소스 프로젝트를 점검하면서 기능 코드와 별개로 발견한 문제는 릴리스 정보의 드리프트였습니다.
2026년 7월 24일 기준 공개 저장소에는 다음 차이가 있습니다.
- Rust crate의
Cargo.toml은0.5.2 - Python의
pyproject.toml은0.4.0 - README의 Cargo 설치 예시는
undocx = "0.4" - 실제 Rust 최소 버전은
1.83
코어 테스트가 모두 통과해도 사용자는 README와 패키지 metadata를 먼저 접합니다. 이 정보가 다르면 어떤 버전이 최신인지, Python과 Rust 릴리스가 함께 움직이는지, 어떤 toolchain이 필요한지 판단하기 어렵습니다.
해결 방법은 버전과 MSRV를 여러 파일에서 사람이 각각 수정하지 않는 것입니다.
- 하나의 release manifest를 정본으로 둡니다.
- release script가 Cargo, Python, README, changelog를 갱신합니다.
- CI가 파일 간 버전 일치를 검사합니다.
- tag 생성 전 package dry-run과 문서 예제를 검증합니다.
변환 정확성의 SSOT가 AST와 테스트라면, 배포 정확성의 SSOT는 release metadata입니다.
일반화할 수 있는 설계 원칙
DOCX 변환기에서 얻은 교훈은 다른 변환 시스템에도 적용됩니다.
- 입력 포맷의 문법과 출력 포맷의 문법을 직접 결합하지 않는다.
- 중간 표현은 문자열이 아니라 보존하려는 의미를 담는다.
- 문서 범위 상태를 명시적인 context로 관리한다.
- 표현 불가능한 기능에는 fallback과 손실 정책을 둔다.
- 간단한 API와 확장 API의 입구를 분리한다.
- 예제 테스트, 회귀 테스트, invariant를 함께 사용한다.
- 성능 수치의 corpus와 기능 경계를 공개한다.
- 코드뿐 아니라 버전, 문서, 패키지 metadata도 하나의 계약으로 검증한다.
결론
DOCX를 Markdown으로 바꾸는 일은 XML을 순회하며 기호를 붙이는 작업이 아닙니다.
- 분산된 문서 관계를 복원하고
- 문서 전체의 상태를 추적하고
- 의미 구조를 AST로 분리하고
- 출력 포맷의 한계에 맞춰 손실 정책을 적용하고
- 여러 층의 테스트로 참조와 구조를 검증하는 작업입니다.
parser와 renderer 사이에 올바른 의미 경계를 만들면 새로운 DOCX 기능이나 출력 형식이 추가되어도 시스템 전체를 다시 작성하지 않아도 됩니다.