공문서 다루기 — hwp·hwpx

이 장에서 배우는 것 .hwp·.hwpx를 읽어 자료로 쓰는 법, 마크다운에서 공문서를 만드는 법, 그리고 빈 서식을 자동으로 채우는 법.

앞 장에 없던 확장자

문서를 자료로 바꾸기에서 다룬 것은 네 가지였습니다 — pdf · docx · xlsx · pptx. 국내 실무에서 가장 자주 마주치는 확장자가 거기 없습니다.

관공서 공고문, 지원사업 신청서, 사내 기안문, 회의록 서식. 이것들이 .hwp나 .hwpx로 옵니다. 그리고 대부분의 자동화가 여기서 멈춥니다 — 한컴오피스가 깔린 윈도우 PC가 있어야 한다고 알려져 있기 때문입니다.

그렇지 않습니다.

먼저 — 두 확장자는 다른 포맷입니다

이 장에서 가장 자주 사고가 나는 지점입니다.

	`.hwp`	`.hwpx`
정체	바이너리 (HWP 5.x)	ZIP + XML
읽기	됩니다	됩니다
쓰기·수정	안 됩니다	됩니다

읽는 것은 양쪽 다 되지만, 만들고 고치는 것은 .hwpx뿐입니다. 아래 나오는 생성·채우기·편집의 산출물은 전부 .hwpx입니다. 한글에서 .hwp로 다시 저장하는 것은 사람이 마지막에 하면 됩니다.

도구 — kordoc

npm 패키지 하나입니다. 설치하지 않고 부릅니다.

bash

npx -y kordoc@^4 <명령> ...

Node.js 18+ 만 있으면 됩니다. 한컴오피스도, 윈도우도, COM 자동화도 필요 없습니다. macOS·리눅스 서버에서 그대로 돕니다.
첫 호출만 내려받느라 느리고 이후는 캐시됩니다.
@^4로 메이저 버전을 고정합니다. 앞 장의 yt-dlp와 반대 방향인데, 상대가 플랫폼이 아니라 문서 포맷 규격이라 자주 바뀌지 않기 때문입니다.

1. 읽기 — 무엇이든 마크다운으로

bash

npx -y kordoc@^4 사업계획서.hwp -o 사업계획서.md

문서를 자료로 바꾸기의 텍스트 사본이 여기서도 그대로 성립합니다. 원본 옆에 마크다운을 나란히 두면 검색이 걸립니다.

하고 싶은 것	붙일 것
폴더 통째로	`-d ./변환결과/`
특정 쪽만	`-p 1-3` 또는 `-p 1,3,5`
구조화된 JSON	`--format json`

hwp 계열뿐 아니라 PDF·DOCX·XLS/XLSX도 같은 명령으로 읽힙니다. 관공서에서 받은 파일 묶음이 확장자별로 섞여 있을 때 유용합니다.

표는 GFM이 아니라 HTML <table>로 나옵니다. 공문서의 병합·중첩 표는 파이프표로 표현이 안 되기 때문입니다. 셀 병합이 살아 있다는 뜻이니 그대로 쓰면 됩니다. 수식은 LaTeX( $...$ )로 나옵니다.

스캔본 구분

PDF는 텍스트층 품질을 함께 계산해 알려줍니다. needsOcr 신호가 뜨면 스캔본 이라 글자가 아니라 그림입니다. kordoc은 OCR을 내장하지 않으므로 여기서 멈추고 다른 경로를 찾아야 합니다. 표가 깨져 보이는 PDF는 대개 이 경우입니다.

2. 만들기 — 마크다운에서 공문서로

bash

npx -y kordoc@^4 초안.md -o 보고서.hwpx --preset 보고서

프리셋이 일곱 개 있습니다 — 기안문 · 보고서 · 계획서 · 통지 · 회의록 · 개조식 · 보도자료.

여기서 자동으로 되는 것이 공문서 작성의 실제 번거로움 대부분입니다.

마크다운에 쓴 것	문서에서
`1.` / 들여쓴 `-`	공문서 항목부호 8단계 (1. → 가. → 1) → 가) → …)
—	함초롬바탕·공식 여백 등 표준 서식
GFM 파이프표	표
`$$...$$`	한글 네이티브 수식
```chart 펜스	한글 네이티브 차트 (막대·선·원·도넛 등)

항목부호 단계와 내어쓰기는 손으로 맞추면 오래 걸리고 자주 틀리는 부분입니다. 마크다운으로 내용만 쓰고 서식은 맡기는 것이 이 명령의 요점입니다.

본문 옵션은 --font gothic(맑은 고딕) · --pt <크기> · --line-spacing <퍼센트>가 있고, 공문서 서식을 끄고 범용 변환만 하려면 --plain입니다.

3. 서식 채우기 — 빈칸이 있는 신청서

가장 반복이 심한 일입니다. 같은 신청서를 스무 번 채우는 자리입니다.

순서가 중요합니다. 무엇을 채울 수 있는지부터 봅니다.

bash

npx -y kordoc@^4 fill 신청서.hwpx --dry-run

라벨 목록이 나옵니다. 그걸 보고 값을 JSON으로 만들어 넣습니다.

bash

npx -y kordoc@^4 fill 신청서.hwpx -j 값.json -o 결과.hwpx

값은 반드시 -j 파일로 넘기세요. -f 'k=v,...'도 되지만 값이 셸 히스토리와 프로세스 목록에 남습니다. 신청서에 들어가는 값이 무엇인지 생각하면 이유가 분명합니다.
원본 글꼴·크기·정렬은 100% 유지됩니다. 채운 티가 나지 않습니다.
여러 줄은 JSON 문자열 안의 \n으로 씁니다.

같은 라벨이 여러 곳에 있으면 기본 동작은 "전부 채우기"입니다. 반복 양식을 위한 동작인데, 서식에 따라 엉뚱한 칸까지 채워질 수 있습니다. 처음 쓰는 서식은 --dry-run으로 라벨이 몇 번 나오는지 먼저 확인하세요.

도장

bash

npx -y kordoc@^4 seal 신청서.hwpx --image 도장.png --anchor "(인)" -o 날인본.hwpx

"(인)" 같은 앵커 문구를 찾아 이미지를 글 앞 부유로 얹습니다. 표나 페이지가 커지지 않는다는 뜻입니다 — 날인하고 나서 서식이 한 장 밀리는 사고를 막습니다. 투명 배경 PNG를 쓰세요.

4. 고치기 — 원본 서식을 유지한 채

받은 문서의 내용만 바꿔야 할 때입니다.

bash

npx -y kordoc@^4 원본.hwpx -o 편집.md          # ① 마크다운으로# ② 편집.md 에서 내용을 고칩니다npx -y kordoc@^4 patch 원본.hwpx 편집.md -o 수정본.hwpx   # ③ 되돌려 넣기

②에서 내용만 고치세요. 문단을 옮기거나 지우는 구조 변경은 최소로 합니다. 글꼴·표·개체·조판은 원본 것이 그대로 유지되고 텍스트만 제자리에 반영됩니다.

전달 전에 — 검증과 미리보기

생성하거나 고친 파일은 확인하고 넘깁니다.

bash

npx -y kordoc@^4 validate 결과.hwpx                    # 구조 검사npx -y kordoc@^4 render 결과.hwpx --reflow -o 미리보기.svg   # 눈으로 확인

validate는 ZIP 구조·필수 파트·XML 형식을 봅니다. 한컴독스 업로드가 거부되는 사유를 미리 걸러내는 자리입니다. render는 조판을 SVG로 그립니다 — kordoc이 만든 파일은 조판 캐시가 없으므로 --reflow를 붙여야 합니다.

두 문서를 비교해 신구대조표를 만드는 것도 됩니다. 조문·문단 단위 diff를 돌려줍니다.

HyperTeams에서 돌리기

정해진 변환이면 판단이 없으니 terminal입니다. 사례 — 콘텐츠 공장의 수집 칸과 같은 자리입니다.

text

매주 월 08:00  ·  kind: terminalnpx -y kordoc@^4 ./공고/*.hwp -d ./공고-md/

반대로 무엇을 채울지 판단해야 하면 task입니다.

text

1. terminal — 받은 서식을 --dry-run 으로 라벨 추출2. task     — 사내 자료에서 값을 찾아 값.json 작성3. terminal — fill 로 채우고 validate4. 사람     — 확인하고 제출

4번이 사람인 이유는 가드레일과 같습니다. 제출은 되돌릴 수 없습니다.

Connect에서 쓸 때

kordoc은 MCP 서버로도 붙습니다. 워크스페이스 멤버가 대화 중에 hwp를 다루게 하려면 이쪽입니다.

bash

npx -y kordoc@^4 setup

대화형 마법사가 클라이언트에 등록해 줍니다. 워크스페이스 쪽 연결은 MCP 서버 연결하기와 도구 설정을 보세요. 도구가 열한 개 늘어나므로 도구가 많아질 때의 주의가 그대로 적용됩니다.

조심할 것

개인정보가 담긴 서식입니다

신청서·인사 서식에는 주민등록번호·계좌·연락처가 들어갑니다.

text

□ 값 파일(값.json)을 저장소에 커밋하고 있지 않나□ 채운 결과 파일이 공유 폴더에 남아 있지 않나□ 대화 기록에 값이 그대로 남지 않았나

문서를 자료로 바꾸기의 마지막 경고가 여기서 더 강해집니다. 작업 폴더가 곧 활동 범위이고, 시스템을 Connect에 등록했다면 멤버도 닿습니다.

원본을 덮어쓰지 마세요

-o로 항상 새 파일에 씁니다. 채우기·패치·날인 모두 마찬가지입니다. 원본 서식은 다시 받기 번거로운 경우가 많습니다.

암호·DRM 문서는 열리지 않습니다

기관에서 배포한 DRM 문서나 암호가 걸린 파일은 파싱되지 않습니다. 우회 대상이 아니라 다른 경로를 찾아야 하는 신호입니다.

숫자와 표는 확인하세요

앞 장과 같습니다. 금액·날짜·수량이 걸린 판단이라면 원본을 확인하세요. 조심할 것의 "숫자는 반드시 확인"이 공문서에서 특히 그렇습니다.

확인

1. .hwp 파일의 내용을 고쳐서 다시 내보낼 수 있습니까?

답

읽을 수는 있지만 그 포맷으로 다시 쓸 수는 없습니다. 생성·채우기·편집의 산출물은 전부 .hwpx입니다. .hwp로 필요하면 마지막에 한글에서 다시 저장합니다.

2. 서식을 채울 때 값을 -f가 아니라 -j 파일로 넘기는 이유는?

답

셸 히스토리와 프로세스 목록에 값이 남기 때문입니다. 신청서에 들어가는 값은 주민등록번호·계좌 같은 개인정보인 경우가 많습니다.

3. 만든 hwpx를 사람에게 넘기기 전에 무엇을 합니까?

답

validate로 구조를 검사합니다. ZIP 구조·필수 파트·XML 형식을 미리 봐서 한컴독스 업로드가 거부되는 사유를 걸러냅니다. 조판이 걱정되면 render --reflow로 눈으로도 확인합니다.

확장하기 파트가 끝났습니다. 막히는 것이 있으면 → 문제 해결 · 가이드 목차