yQuant
#rust#markdown#hwpx#wasm

Markdown ↔ HWPX 양방향 변환

md2hwpx는 마크다운과 한글 워드프로세서 문서 형식인 HWPX 사이의 양방향 변환을 지원하는 Rust 기반 도구입니다. 마크다운을 HWPX 보고서로 컴파일하는 compile 모듈과, 반대로 HWPX를 마크다운으로 역변환하는 parse 모듈이 하나의 프로젝트에 통합되어 있습니다.

#저장소 정보

#개발 배경

보고서나 공문서 작업에서는 여전히 한글(HWP/HWPX) 형식이 널리 쓰이지만, 초안 작성이나 버전 관리, AI 도구와의 연동에는 마크다운이 훨씬 편리합니다. 매번 마크다운으로 초안을 쓴 뒤 한글 프로그램에 옮겨 서식을 다시 잡는 과정은 번거롭고 실수도 잦습니다. md2hwpx는 이 변환 과정을 자동화해, 마크다운으로 쓴 문서를 정해진 템플릿에 맞춰 HWPX로 곧바로 출력하고, 반대로 기존 HWPX 문서를 마크다운으로 뽑아내 재활용할 수 있도록 만들어졌습니다.

#주요 기능

  • md2hwpx (compile): 마크다운 소스와 HWPX 템플릿을 입력받아 서식이 적용된 HWPX 문서를 생성
  • hwpx2md (parse): 기존 HWPX 문서를 마크다운으로 역변환
  • 방언 토큰(Dialect Tokens): 표준 마크다운으로 표현하기 어려운 문서 요소를 지원하기 위한 확장 문법
    • ===: 강조 블록
    • [[박스]], [[붙임]], [[외부제목]]: 문서 구조를 지정하는 명령어
  • 웹 애플리케이션: 서버 전송 없이 브라우저에서 Wasm으로 완전히 로컬 실행되는 변환기 제공

#아키텍처

Rust로 작성된 코어는 세 모듈로 나뉩니다.

  1. compile (src/compile/): 마크다운과 템플릿을 조합해 HWPX를 생성하는 컴파일러
  2. parse (src/parse/): HWPX를 마크다운으로 되돌리는 파서
  3. shared (src/shared/): XML DOM 처리, 글리프, 방언 토큰 정의, 오류 처리, ZIP 읽기 등 공용 로직

웹 애플리케이션은 Vite + Svelte 5 + Tailwind 4로 만든 2페이지 SPA이며, wasm-pack으로 빌드한 Rust 코어를 그대로 브라우저에서 호출합니다.

  • /hwpx/compile: 마크다운 → HWPX 변환 페이지
  • /hwpx/parse: HWPX → 마크다운 변환 페이지

두 페이지는 헤더의 워드마크를 클릭해 전환하며, 전환 시에도 입력 상태가 유지됩니다.

#사용 방법

#CLI

# 마크다운 + 템플릿 → HWPX
./target/release/md2hwpx source.txt template.hwpx compiled.hwpx

# 템플릿 변형 지정
./target/release/md2hwpx 보고서.md --variant title=external

# HWPX → 마크다운
./target/release/hwpx2md sample.hwpx sample.md

두 명령 모두 변환 결과를 JSON 형식의 Report로 stdout에 출력하며, 종료 코드로 성공(0)·경고(1)·오류(2)를 구분합니다. -h/--help, -v 옵션도 지원합니다.

#웹 애플리케이션

설치 없이 xcv.kr/hwpx에서 바로 사용할 수 있습니다. 모든 변환이 Wasm으로 브라우저 안에서 실행되므로 문서 내용이 서버로 전송되지 않습니다.

로컬 개발 환경 실행:

cd web
npm ci
npm run dev  # http://localhost:8292

Share this post