Copy & Run

Pandoc으로 마크다운을 Word와 HTML로 바꾸기: 한글 문서 변환 확인

마크다운 보고서를 pandoc/core 이미지로 docx와 html로 변환하고, docx를 압축 해제해 제목, 표, 굵은 글씨가 들어갔는지 확인합니다. PDF 변환은 LaTeX가 없어 실패한 결과 그대로 기록합니다.

실습 노트 · 2026-10-29 발행 · 6분 · 2026-10 확인

보고서를 마크다운으로 쓰고, 제출할 때만 Word로 바꾸고 싶을 때가 있습니다. Pandoc은 문서 형식 사이를 변환해 주는 오픈소스 도구입니다. 이 글에서는 한글 마크다운 문서를 docx와 html로 바꾸고, 결과 파일을 열어 내용이 들어갔는지 확인합니다.

준비물

항목 확인한 값
Docker 29.5.3 (Windows 11)
Pandoc 3.11 (pandoc/core:latest 이미지)

Pandoc을 설치하지 않고 컨테이너로 실행했습니다.

1. 원본

report.md는 제목 두 줄(%로 시작), 제목 2단계, 굵은 글씨, 2열 표, 목록, 코드 블록으로 만들었습니다.

% 월간 점검 보고서
% 보안팀

# 요약
이번 달 점검 결과를 정리합니다. **중요 항목**은 굵게 표시했습니다.

| 항목 | 결과 |
|---|---|
| 패치 | 완료 |
| 백업 | 확인 필요 |
이 단계의 파일 내려받기:report.md

2. 변환

MSYS_NO_PATHCONV=1 docker run --rm -v "<폴더>:/data" pandoc/core:latest report.md -o report.docx
docker run --rm -v "<폴더>:/data" pandoc/core:latest report.md -s -o report.html

둘 다 성공했고 report.docx는 11,193바이트였습니다. HTML에는 -s(독립 문서)를 붙여야 <html> 전체가 만들어집니다.

pandoc/core 이미지로 report.md를 report.docx로 바꾼 뒤 파일 크기 11193바이트가 보이고, report.pdf 변환은 pdflatex를 찾지 못했다는 메시지가 나오는 것을 확인합니다.
pandoc/core 이미지로 report.md를 report.docx로 바꾼 뒤 파일 크기 11193바이트가 보이고, report.pdf 변환은 pdflatex를 찾지 못했다는 메시지가 나오는 것을 확인합니다.

이 단계의 파일 내려받기:convert.shreport.md

3. 결과 확인

docx는 압축 파일이라 파이썬으로 열어 안을 봤습니다.

import zipfile
x = zipfile.ZipFile("report.docx").read("word/document.xml").decode("utf8")
# 확인 결과
파일 16개, 표 1개, 문단 14개
추출한 글: 월간 점검 보고서 보안팀 요약 이번 달 점검 결과를 정리합니다. 중요 항목 은 굵게 ...
굵은 글씨 서식: 있음
HTML 안의 표: 1개

한글이 깨지지 않았고 표는 Word 표 한 개로 들어갔으며 굵은 글씨 서식도 있었습니다. 다만 Word 프로그램에서 열어 모양을 눈으로 보지는 않았고, 파일 안의 구조만 확인했습니다.

이 단계의 파일 내려받기:check_docx.py

4. PDF는 실패했습니다

docker run --rm -v "<폴더>:/data" pandoc/core:latest report.md -o report.pdf
'pdflatex' not found. Please select a different --pdf-engine or install 'pdflatex'

pandoc/core 이미지에는 PDF를 만드는 LaTeX가 없습니다. 다른 PDF 엔진을 지정하거나 LaTeX가 포함된 이미지를 써야 하는데, 이 글에서는 시도하지 않았습니다. 한글을 PDF에 넣으려면 한글 글꼴 설정도 필요할 수 있는데 확인하지 않았습니다.

이 단계의 파일 내려받기:report.md

5. 쓰는 방법

목적 방법
회사 양식 적용 --reference-doc=양식.docx로 글꼴과 여백을 가져올 수 있습니다. 이 글에서는 해 보지 않았습니다
반복 변환 변환 명령을 스크립트나 CI에 넣어 문서 저장소에서 자동 생성합니다
여러 파일 합치기 파일을 여러 개 나열하면 하나로 합쳐집니다. 이 글에서는 확인하지 않았습니다

더 해 보기: 목차, 메타데이터, 단일 HTML, 글꼴, Lua 필터, 되돌려 변환

변환이 되는 것은 확인했으므로, 이어서 실제 문서를 만들 때 필요한 옵션을 같은 report.md(제목 두 개와 표 한 개가 든 짧은 보고서)로 확인했습니다(pandoc_more.sh). 결과 파일은 docx가 zip 묶음이라는 점을 이용해 파이썬으로 안을 열어 확인했습니다.

목차와 장 번호

--toc --number-sections를 붙여 변환한 파일과 붙이지 않은 파일의 document.xml을 비교했습니다.

파일 문서 XML 크기 목차 필드 표 제목
plain.docx 3,481바이트 0개 1개 2개
toc.docx 4,210바이트 1개 1개 2개

옵션을 붙이면 목차 필드가 하나 생겼습니다. 이 목차는 완성된 목차가 아니라 "워드에서 열면 채워 넣는 자리"입니다. 워드에서 처음 열면 필드를 갱신할지 묻고, 갱신해야 쪽 번호가 있는 목차가 나옵니다. 이 글에서는 워드에서 열어 보지 않았습니다.

메타데이터(YAML 머리말)

원고 맨 위에 title, author, date를 적으면 본문 바로 위에 문서의 제목, 저자, 날짜로 들어갑니다.

항목 결과
문서에 들어간 글 월간 보고서, 김민수, 2026-10-29, 개요, 본문입니다.
문단 스타일 Title, Author, Date, Heading1, FirstParagraph

메타데이터가 별도 스타일(Title, Author, Date)을 받으므로 워드에서 이 스타일을 바꾸면 모든 문서의 표지 모양이 한꺼번에 바뀝니다. 아래 글꼴 바꾸기가 이 원리를 씁니다.

단일 HTML 파일

-s --embed-resources --css style.css로 변환하면 CSS가 HTML 안에 들어간 하나의 파일이 만들어집니다. 만들어진 파일은 4,271바이트였고, color:#c33(내 CSS의 내용)이 포함되어 있었으며 style.css를 가리키는 외부 링크는 없었습니다. 메일에 첨부하거나 내부 문서 서버에 올릴 때 파일 하나만 옮기면 되는 방식입니다. 이 보고서에는 그림이 없어서, 그림이 많을 때 파일이 얼마나 커지는지는 확인하지 않았습니다.

글꼴 바꾸기: 참조 문서

회사 문서 양식(글꼴, 제목 모양)에 맞추려면 참조 문서를 줍니다. 기본 참조 문서를 pandoc -o ref.docx --print-default-data-file reference.docx로 꺼내서 고친 뒤 --reference-doc으로 지정합니다. 처음에는 styles.xml에서 글꼴 이름을 찾았지만 0곳이었습니다. 이 참조 문서의 글꼴은 스타일에 적혀 있지 않고 테마(word/theme/theme1.xml)에 들어 있었습니다.

파일 테마의 글꼴
기본으로 만든 plain.docx Aptos 2곳, Malgun Gothic 0곳
테마를 고친 참조 문서로 만든 styled.docx Malgun Gothic 4곳, Aptos 0곳

기본 테마 글꼴은 Aptos와 Aptos Display였고, 이것을 Malgun Gothic으로 바꾸고 동아시아 글꼴 칸도 같은 이름으로 채웠더니 결과 문서의 테마가 바뀌었습니다. 실제로 워드에서 한글이 맑은 고딕으로 보이는지는 확인하지 않았습니다. 참조 문서는 워드에서 직접 열어 스타일을 고쳐 저장하는 방법이 더 쉽습니다. 이 글에서는 자동화하려고 압축을 열어 고쳤습니다.

Lua 필터

본문을 처리하는 작은 프로그램(필터)을 끼워 넣을 수 있습니다. "TODO"를 "[할 일]"로 바꾸는 필터를 만들어 --lua-filter todo.lua로 실행하자 두 군데 모두 바뀌었습니다.

[할 일] 항목을 정리한다. [할 일] 는 두 번 나온다.

필터는 변환 과정에서 문서 구조(문단, 단어)를 직접 다루므로 정규식으로 텍스트를 치환하는 것보다 안전합니다. 예를 들어 코드 블록 안의 TODO는 Str(일반 글자)이 아니라 Code 요소여서 이 필터에는 걸리지 않습니다. 이 동작은 이 글에서 확인하지 않았습니다. 필터는 내 PC에서 임의의 코드를 실행하는 것이므로 출처를 모르는 필터는 쓰지 않습니다.

되돌려 변환

plain.docx를 다시 마크다운(-t gfm)으로 바꿔 원본과 비교했습니다. 제목은 2개 모두 원본과 같았고, 글자 수는 원본 168글자에서 172글자로 조금 늘었습니다. 워드 문서를 마크다운으로 가져오는 일도 되지만, 표 모양이나 코드의 줄 바꿈은 달라질 수 있어서 가져온 뒤에 눈으로 확인합니다. 이 글에서는 차이가 난 4글자가 어디인지는 확인하지 않았습니다.

pandoc_more.sh 실행 결과에서 목차 옵션으로 목차 필드가 0개에서 1개가 되고, 메타데이터가 Title, Author, Date 스타일이 되며, 단일 HTML에 CSS가 들어가고, 테마 글꼴이 Aptos에서 Malgun Gothic으로 바뀌며, Lua 필터가 TODO를 바꾸고, 되돌린 제목이 2개로 같은 것을 확인합니다.
pandoc_more.sh 실행 결과에서 목차 옵션으로 목차 필드가 0개에서 1개가 되고, 메타데이터가 Title, Author, Date 스타일이 되며, 단일 HTML에 CSS가 들어가고, 테마 글꼴이 Aptos에서 Malgun Gothic으로 바뀌며, Lua 필터가 TODO를 바꾸고, 되돌린 제목이 2개로 같은 것을 확인합니다.

pandoc_more.sh는 아래와 같습니다. report.md와 같은 폴더에서 실행하며 만든 임시 파일은 끝에서 지웁니다.

#!/usr/bin/env bash
# Pandoc 심화: 목차와 번호, 메타데이터, 단일 HTML 파일, 참조 문서로 글꼴 바꾸기, Lua 필터, 되돌려 변환.
# 준비: Docker, 파이썬. Pandoc 은 컨테이너(pandoc/core)로 실행한다. 같은 폴더에 report.md 가 있어야 한다.
# 실행(Git Bash): bash pandoc_more.sh   (약 1분)
set -u
export MSYS_NO_PATHCONV=1
export PYTHONWARNINGS=ignore
HERE="$(pwd -W 2>/dev/null || pwd)"
P="docker run --rm -v $HERE:/data pandoc/core:latest"
mkdir -p out

echo "## 1. 목차(--toc)와 장 번호(--number-sections)"
$P report.md -o out/plain.docx
$P report.md --toc --number-sections -o out/toc.docx
python -X utf8 - <<'PY'
import re, zipfile
def info(f):
    x = zipfile.ZipFile(f).read("word/document.xml").decode("utf-8")
    return len(x), x.count('TOC ' + chr(92) + 'o'), len(re.findall(r'<w:tbl>', x)), len(re.findall(r'w:pStyle w:val="Heading\d"', x))
for f in ("out/plain.docx", "out/toc.docx"):
    n, toc, tbl, head = info(f)
    print(f"  {f:<16} 문서 XML {n:>6}바이트, 목차 필드 {toc}개, 표 {tbl}개, 제목 {head}개")
PY

echo "## 2. 메타데이터(YAML 머리말)가 어디로 가나"
printf -- '---\ntitle: 월간 보고서\nauthor: 김민수\ndate: 2026-10-29\n---\n\n# 개요\n\n본문입니다.\n' > meta.md
$P meta.md -o out/meta.docx
python -X utf8 - <<'PY'
import re, zipfile
z = zipfile.ZipFile("out/meta.docx")
x = z.read("word/document.xml").decode("utf-8")
texts = re.findall(r'<w:t[^>]*>([^<]*)</w:t>', x)
styles = re.findall(r'w:pStyle w:val="([A-Za-z0-9]+)"', x)
print("  문서의 글:", texts[:5])
print("  문단 스타일:", styles[:5])
PY

echo "## 3. 단일 HTML 파일(--embed-resources --standalone)과 CSS"
printf 'body{font-family:sans-serif;color:#223}h1{color:#c33}\n' > style.css
$P report.md -s --embed-resources --css style.css -o out/report.html 2>&1 | tail -1
python -X utf8 - <<'PY'
x = open("out/report.html", encoding="utf-8").read()
print(f"  크기 {len(x.encode())}바이트, CSS 포함 {'color:#c33' in x}, 외부 링크 없음 {'href=\"style.css\"' not in x}")
PY

echo "## 4. 참조 문서(reference.docx)로 글꼴 바꾸기"
$P -o ref.docx --print-default-data-file reference.docx 2>/dev/null
python -X utf8 - <<'PY'
import re, zipfile
src = zipfile.ZipFile("ref.docx")
out = zipfile.ZipFile("out/my-ref.docx", "w", zipfile.ZIP_DEFLATED)
for item in src.infolist():
    data = src.read(item.filename)
    if item.filename == "word/theme/theme1.xml":      # 글꼴은 스타일이 아니라 테마에 들어 있다
        t = data.decode("utf-8")
        print("  기본 테마 글꼴:", sorted(set(re.findall(r'<a:latin typeface="([^"]+)"', t))))
        t = re.sub(r'(<a:latin typeface=")[^"]*(")', r'Malgun Gothic', t)
        t = t.replace('<a:ea typeface=""', '<a:ea typeface="Malgun Gothic"')
        data = t.encode("utf-8")
    out.writestr(item, data)
out.close()
PY
$P report.md --reference-doc out/my-ref.docx -o out/styled.docx
python -X utf8 - <<'PY'
import zipfile
for f in ("out/plain.docx", "out/styled.docx"):
    t = zipfile.ZipFile(f).read("word/theme/theme1.xml").decode("utf-8")
    print(f"  {f:<16} Malgun Gothic {t.count('Malgun Gothic')}곳, Aptos {t.count('Aptos')}곳")
PY

echo "## 5. Lua 필터: 본문의 TODO 를 [할 일] 로 바꾸기"
cat > todo.lua <<'LUA'
function Str(el)
  if el.text == "TODO" then return pandoc.Str("[할 일]") end
end
LUA
printf '# 목록\n\nTODO 항목을 정리한다. TODO 는 두 번 나온다.\n' > todo.md
$P todo.md --lua-filter todo.lua -t plain | sed 's/^/  /'

echo "## 6. 되돌려 변환: docx 를 다시 마크다운으로"
$P out/plain.docx -t gfm -o out/back.md
python -X utf8 - <<'PY'
import re
a = open("report.md", encoding="utf-8").read()
b = open("out/back.md", encoding="utf-8").read()
ha = re.findall(r'^#+ .*', a, re.M); hb = re.findall(r'^#+ .*', b, re.M)
print(f"  원본 제목 {len(ha)}개, 되돌린 제목 {len(hb)}개, 같은 제목 {len(set(h.lstrip('# ').strip() for h in ha) & set(h.lstrip('# ').strip() for h in hb))}개")
print(f"  원본 {len(a)}글자, 되돌린 {len(b)}글자 (표와 코드가 어떻게 바뀌는지는 두 파일을 비교해 본다)")
PY
rm -rf out meta.md style.css ref.docx todo.lua todo.md
이 단계의 파일 내려받기:pandoc_more.shreport.md

전체 코드

아래 파일 세 개(report.md, convert.sh, check_docx.py)를 같은 폴더에 저장하고 bash convert.sh로 실행하면 변환, 내부 확인, PDF 실패 재현까지 한 번에 나옵니다.

convert.sh 실행 결과에서 11193바이트 docx, 파일 16개와 표 1개와 문단 14개, 굵은 글씨 서식, HTML 표 1개, 마지막에 pdflatex를 찾지 못했다는 메시지가 나오는 것을 확인합니다.
convert.sh 실행 결과에서 11193바이트 docx, 파일 16개와 표 1개와 문단 14개, 굵은 글씨 서식, HTML 표 1개, 마지막에 pdflatex를 찾지 못했다는 메시지가 나오는 것을 확인합니다.

# convert.sh
#!/usr/bin/env bash
# report.md 를 Pandoc(컨테이너)으로 docx 와 html 로 바꾸고, docx 안을 확인하고, PDF 실패를 재현한다.
# 준비: Docker, 파이썬, 같은 폴더의 report.md 와 check_docx.py
# 실행: bash convert.sh
set -u
export MSYS_NO_PATHCONV=1                 # Git Bash 의 경로 변환을 끈다
HERE="$(pwd -W 2>/dev/null || pwd)"
PANDOC="docker run --rm -v $HERE:/data pandoc/core:latest"

echo "## 1. docx 와 html 변환"
$PANDOC report.md -o report.docx && ls -l report.docx | awk '{print $5, "bytes", $9}'
$PANDOC report.md -s -o report.html && echo "report.html 만들어짐"

echo "## 2. docx 안 확인"
python -X utf8 check_docx.py

echo "## 3. PDF 변환(LaTeX 가 없는 이미지라 실패하는 것이 정상)"
$PANDOC report.md -o report.pdf 2>&1 | head -2
# check_docx.py
"""report.docx 는 압축 파일이다. 안의 word/document.xml 을 열어 표, 문단, 굵은 글씨, 글자를 확인한다."""
import re
import zipfile

z = zipfile.ZipFile("report.docx")
x = z.read("word/document.xml").decode("utf8")
text = re.sub(r"\s+", " ", re.sub(r"<[^>]+>", " ", x)).strip()

print("압축 안 파일 수:", len(z.namelist()))
print("표:", x.count("<w:tbl>"), "| 문단:", x.count("<w:p>") + x.count("<w:p "))
print("굵은 글씨 서식:", "있음" if "<w:b" in x else "없음")
print("추출한 글:", text[:80])
html = open("report.html", encoding="utf8").read()
print("HTML 안의 표:", html.count("<table"))

report.md

% 월간 점검 보고서
% 보안팀

# 요약

이번 달 점검 결과를 정리합니다. **중요 항목**은 굵게 표시했습니다.

## 점검 항목

| 항목 | 결과 |
|---|---|
| 패치 | 완료 |
| 백업 | 확인 필요 |

- 첫째 할 일
- 둘째 할 일

```bash
docker ps
```
이 단계의 파일 내려받기:check_docx.pyconvert.shreport.md

자주 막히는 곳

증상 원인과 해결
윈도우에서 -v 경로가 틀렸다고 나옵니다 Git Bash는 경로를 바꿔 버립니다. MSYS_NO_PATHCONV=1을 앞에 붙입니다
표가 표로 변환되지 않습니다 표 위에 빈 줄이 있는지, 구분선 `
PDF 변환 오류 위 4번과 같습니다. PDF 엔진이 없는 환경입니다

확인 범위

  • 해 본 것: 29일에 pandoc_more.sh로 목차와 번호, 메타데이터, 단일 HTML, 테마 글꼴 바꾸기, Lua 필터, 되돌려 변환을 확인했습니다. 앞의 확인 내용은 다음과 같습니다. 2026-10-29, Windows 11 · Docker 29.5.3 · Pandoc 3.11로 샘플 보고서를 docx와 html로 변환하고 docx 내부를 확인했으며 PDF 실패를 재현했습니다.
  • 해 보지 않은 것: 워드에서 목차 갱신과 글꼴 표시 확인, 그림이 든 문서의 HTML 크기, 코드 블록 안의 글자에 필터가 걸리는지, Word에서 열어 본 모양, 회사 양식 적용, 이미지 삽입, PDF 변환 성공, 큰 문서의 변환 시간.
  • 읽을 때 주의: 샘플은 한 쪽짜리 간단한 문서라 복잡한 문서의 결과는 다를 수 있습니다.
이 단계의 파일 내려받기:pandoc_more.sh

이 글의 다음 단계

이 내용을 팀 교육으로 진행하고 싶으신가요?

인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.

교육 문의하기

교육 진행 순서와 자주 묻는 질문 보기

팀이나 교육 담당자에게 이 글 제안하기

메일로 보내실 수도 있습니다: fankh111@gmail.com

같은 카테고리의 글