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

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

- 주소: https://copyandrun.com/blog/pandoc-markdown-to-docx/
- 분야: AX
- 발행일: 2026-10-29
- 태그: Pandoc, 마크다운, docx, 문서 변환

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

## 준비물

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

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

## 1. 원본

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

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

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

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

## 2. 변환

<!-- files: convert.sh -->

```bash
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를 찾지 못했다는 메시지가 나오는 것을 확인합니다.](https://copyandrun.com/img/pandoc-markdown-to-docx/01-변환-결과.png)

## 3. 결과 확인

<!-- files: check_docx.py -->

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

```python
import zipfile
x = zipfile.ZipFile("report.docx").read("word/document.xml").decode("utf8")
```

```
# 확인 결과
파일 16개, 표 1개, 문단 14개
추출한 글: 월간 점검 보고서 보안팀 요약 이번 달 점검 결과를 정리합니다. 중요 항목 은 굵게 ...
굵은 글씨 서식: 있음
HTML 안의 표: 1개
```

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

## 4. PDF는 실패했습니다

```bash
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에 넣으려면 한글 글꼴 설정도 필요할 수 있는데 확인하지 않았습니다.

## 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`로 실행하자 두 군데 모두 바뀌었습니다.

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

필터는 변환 과정에서 문서 구조(문단, 단어)를 직접 다루므로 정규식으로 텍스트를 치환하는 것보다 안전합니다. 예를 들어 코드 블록 안의 `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개로 같은 것을 확인합니다.](https://copyandrun.com/img/pandoc-markdown-to-docx/03-옵션-비교.png)

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

```bash
#!/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
```

## 전체 코드

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

![convert.sh 실행 결과에서 11193바이트 docx, 파일 16개와 표 1개와 문단 14개, 굵은 글씨 서식, HTML 표 1개, 마지막에 pdflatex를 찾지 못했다는 메시지가 나오는 것을 확인합니다.](https://copyandrun.com/img/pandoc-markdown-to-docx/02-전체-스크립트-결과.png)

```bash
# 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
```

```python
# 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`

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

# 요약

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

## 점검 항목

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

- 첫째 할 일
- 둘째 할 일

```bash
docker ps
```
````

## 자주 막히는 곳

| 증상 | 원인과 해결 |
|---|---|
| 윈도우에서 `-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 변환 성공, 큰 문서의 변환 시간.
- **읽을 때 주의:** 샘플은 한 쪽짜리 간단한 문서라 복잡한 문서의 결과는 다를 수 있습니다.
