DOCX to Markdown: 문서 시스템 마이그레이션을 위한 형식 가이드

DOCX는 OOXML 사양을 기반으로 저장되며 스타일을 핵심으로 형식을 설명합니다. 동일한 의미 콘텐츠도 여러 시각적 스타일로 표현될 수 있습니다. Markdown은 의미를 핵심으로 하며 간결한 구문으로 콘텐츠 계층 구조를 표시하고 다양한 정적 문서 시스템의 렌더링에 적응합니다.

기술 문서 마이그레이션의 핵심 요구 사항은 DOCX의 시각적 스타일을 Markdown에서 인식할 수 있는 의미 마커로 변환하고, 불필요한 페이지 레이아웃 정보를 제거하며 콘텐츠의 계층 관계를 유지하는 것입니다.

매핑 규칙은 의미 우선 원칙을 따르며 Markdown 사양에 맞는 콘텐츠 마커만 유지하고 Word의 페이지 여백, 행간 등의 레이아웃 정보는 폐기합니다. 변환 도구는 Word의 기본 제공 스타일 레벨을 기반으로 해당 제목 레벨을 매칭하며, 사용자 정의 스타일은 도구의 스타일 인식 규칙에 의존해야 합니다.

순수 형식 변환 도구는 Word 문서에 내장된 이미지만 추출하여 해당 Markdown 이미지 링크 구문을 생성하며, 이미지의 클라우드 스토리지 업로드는 자동으로 완료하지 않습니다. 추출된 이미지는 원본 파일의 해상도와 형식을 유지하며 압축이나 형식 트랜스코딩은 수행되지 않습니다.

문서 마이그레이션 시 사용자는 추출된 이미지를 직접 문서 시스템의 이미지 호스팅에 업로드하고 생성된 로컬 경로를 교체해야 이미지가 정상적으로 표시됩니다.

현재 주류 브라우저 측 DOCX to Markdown 도구는 mammoth.js를 기반으로 개발되었습니다. 이 라이브러리는 OOXML 사양을 준수하는 DOCX 파일만 지원하며 레거시 바이너리 형식 DOC 파일은 지원하지 않습니다.

레거시 DOC 파일은 먼저 Word나 LibreOffice를 통해 DOCX 형식으로 내보낸 후 DOCX to Markdown 변환기로 처리해야 규칙에 맞는 변환 결과를 얻을 수 있습니다.

DOCX to Markdown 변환 및 콘텐츠 수정을 완료한 후 발행 대상에 따라 다른 도구를 조합하여 전달을 완료할 수 있습니다. GitBook 또는 VitePress의 경우 변환된 Markdown을 해당 프로젝트의 콘텐츠 디렉토리에 직접 저장하고 빌드 도구와 협력하여 정적 사이트를 생성할 수 있습니다.

유즈 등의 온라인 문서 시스템의 경우 변환된 Markdown 파일을 직접 가져오면 시스템이 자동으로 구문 렌더링을 완료하고 원본 콘텐츠 계층을 유지합니다. PDF나 새 Word 문서로 내보내야 할 경우 Pandoc을 사용하여 형식 변환을 완료할 수 있으며 매개변수는 현재 공식 발표를 따릅니다.