Show GN: Pandoc 기반 아래아한글 변환기 - md, html, docx를 hwpx로 변환하는 오픈소스 도구를 소개합니다.
(github.com/msjang)출연연 근무 9년차, HWP 문서 작업의 불편함을 해결하고자 개발했습니다.
개발 배경
- 2018년: 파이썬 초보 시절, 정규식 기반 HML/HWPML 변환기 시도 - https://github.com/msjang/md2hml
- 2025년 1월: hwpfy 개발
- 실시간 공동편집 위키 기반 20여명의 주간업무보고 취합
- 위키. → DOCX 내보내기 → 공무원 서식 입힌. DOCX로 변환(hwpfy) → 한글앱에서 열어서 HWPX로 저장 → 원내 상급부서에 HWPX로 공유
- 2025년 12월: pypandoc-hwpx
- 이제는 충분한 내공이 쌓였다 생각하여, 각 잡고 시간을 투자해서 개발했습니다.
개발 방법
- DOCX를 원하는 서식으로 만들고, HWPX로 저장했습니다.
- 생성된 DOCX와 HWPX를 unzip하여 XML을 보고 필요 없는 속성들을 날리고 다듬었습니다. 그리고 워드와 한글 앱에서 잘 열리는지도 확인했습니다.
- md, html, docx, hwpx 포멧을 비교하는 문서를 만들었습니다. - https://github.com/msjang/pypandoc-hwpx/…
- 원래는 위
format_comparison.md를 보고 LLM에게 코딩을 시키려고 했는데, 이미 정답지 HWPX가 있는 상황이라는 걸 깨달았습니다. - Antigravity(Gemini Pro 3)로 여러번 피드백 하면서 만들었습니다. 원하는 형식으로 안나와서 XML을 세세하게 까보면서 피드백을 줬습니다. 포멧 비교 문서를 직접적으로 언급하지는 않았지만, 내용을 숙지한 것이 리뷰하는데 많은 도움이 됬습니다.
추후 할 일
Pypandoc 에서 Python을 걷어내고 하스켈로 코딩해서 Pandoc에 HWPX writer를 기여하고 싶습니다.
원래는 한두달 동안 천천히 만드려 했는데, 어제 https://youtu.be/8cSqPRsM_Yg 뉴스가 나와버려서 급하게 만들었습니다.
멋지네요
그러나 외람되지만 대통령이 원하는 변환 방향은
hwp* -> .md, docs, pdf plain text ... 가 아닐까요? 프로젝트가 역방향 변환도 지원 하는건가요?
hwp나 hwpx를 파상하는 라이브러리는 예로부터 많았습니다. Java 기반으로는 이게 유명합니다.
https://github.com/neolord0/hwplib
https://github.com/neolord0/hwpxlib
python 으로 한컴 win32 api 를 래핑한 것이 있습니다. 초창기 HWP 자동화 강의에 등장하는 녀석이죠. 백엔드에서 윈도우용 HWP 앱을 제어하는거죠.
https://pypi.org/project/pyhwpx/
파이썬으로 별도 프로그램 없이 HWPX를 standalone으로 다루는건 이게 있습니다. 읽거나 치환도 가능하고, 문단이나 표를 추가할 수도 있습니다. https://github.com/airmang/python-hwpx
그런데 생각해보면 저희는 대부분 LLM 앱과 소통합니다. ChatGPT, Claude, Gemini 웹브라우저로 접속해서 채팅하며 소통합니다. OpenWebUI로 로컬 모델 돌려도 웹브라우저로 접속해서 이용합니다. 스마트폰 CharGPT 앱의 음성모드로 소통한 결과도 웹브라우저에서 채팅로그를 확인할 수 있습니다. 그리고 LLM의 output은 복사 버튼을 누른 다음에 메모장에 붙여넣기 해 보면 markdown 인 것을 확인할 수 있습니다.
LLM의 markdown이나 html 이 나오는데 이걸 바로 hwpx로 바꿔서 저장하는 라이브러리가 있나? 없습니다.
GEMINI Pro로 특허 아이디어 생각하다 보면,문서로 만들어 드릴까요라 묻습니다. 그리고 버튼을 누르면 Google Docs 문서로 특허명세서 초안이 만들어져 있습니다. 그냥 마크다운을 컨버팅 해서 문서로 만든 건데 꽤나 볼만 합니다.
대한민국은 싫든 좋든 HWP를 업무추진과 소통의 표준으로 삼았습니다. 그리고 우리의 업무흐름(workflow) 안에서 HWP생성은 어찌 보면 당연한 일입니다.
ChatGPT 음성모드로 회의내용을 다 들은 다음에, ‘요약해서 회의록으로 만들어주고 참가자들에게 메일로 전송해줘‘, ’브레인스토밍 한 내용을 특허명세서 초안으로 만들어줘’ 등등을 할 때 그 출력물은 HWP이어야 한다는 접입니다.
지금까지는 LLM의 결과를 사람이 웹브라우저에서 한글앱으로 복사해와서 서식을 맞추고 장평 자간 등을 열심히 조정하고 조판하는 과정을 거쳤습니다.
GEMINI가 Google Docs를 만들어 주는 시대에, 대한민국 세금을 들인 LLM 모델과 서비스들은 HWPX는 사람의 개입 없이 만들어 줘야 하는 건 아닌가?
제가 업무자동화를 위해 이런 수요를 가지고 있었고, 이를 위해서 만들었습니다.
사족.
HWP 자체는 파싱을 해서 텍스트로 바꾸긴 쉽습니다. 구글이 한국어 문사를 인덱싱 하기 위해 2000년대부터 이미 만들어서 자제적으로 적용하고 있었고, 위에 언급한 오픈소스들로 충분히 가능합니다.
HTML의 h1~h6 에 대응하는 개요단계 1~6 스타일을 입히면 문서의 위계(hierarchy)도 보존하며 문서를 만들 수 있습니다.
다만 HWP는 에디터에 기능이 너무 많고, 사용하는 사람들이 종이 출력물을 잘 보이도록 하는데 집중해서 서식을 적용할 때 개요단계(outline level)를 적용하려는 노력을 하지 않았습니다.
이걸 단적으로 보여주는게, 연구소에서 300쪽짜리 HWP 문서를 PDF로 저장하면, 책갈피 정보가 하나도 생성이 안되어 있다는 점입니다. 그래서 전자문사인데도 스크롤을 해 가며 찾아야 합니다. 엄청 불편합니다. 근데 용량 큰 PDF는 아무리 좋은 컴퓨터도 훑어보기를 위해 빠르게 스크롤하면 엄청 버벅댑니다.
기관평가할 때 이 짓을 할 순 없으니까, 심사위원 숫자대로 수백페이지의 보고서를 수북히 인쇄해서 쌓아놓고 기관평가를 합니다. 그리고 평가 끝나면 바로 버립니다.
해외 보고서는 400쪽짜리 PDF 보고서를 받으면 목차만 16쪽이고 목차에 링크가 달려 있어서 클릭하면 해당 페이지로 이동합니다. 개요 보기를 하면 책갈피가 엄청 새분화되어 잘 되어 있습니다. 이건 도구에서 사람이 의식하지 않아도 손쉽게 입력이 되어 자동으로 생성된 것이라는 걸 의미합니다.
여튼, 다시 돌아와서 현재 대다수가 아래아한글을 사용하는 관습에 의해 만들어진 HWP로부터는 텍스트로 얻을 수 있지만, 문서의 위계정보를 얻기 힘듭니다.
하지만, LLM으로 사람의 개입 없이 HWP를 생성하면 이러한 점을 고려하여 자동으로 만들 수 있습니다.