마크다운 워드 변환: 명령줄 Pandoc 가이드

명령줄에서 마크다운을 워드로 변환하고 싶다면 답은 pandoc이고, 전체 작업은 한 줄이면 끝납니다:

pandoc report.md -f gfm -o report.docx

이 명령 하나로 대부분의 문서가 해결됩니다. 하지만 한 줄짜리 튜토리얼이 알려주지 않는 것은 "어디서부터 안 되는가"입니다. 게다가 pandoc의 한계에 대해 떠도는 정보 중 일부는 그냥 낡은 이야기입니다. Pandoc 3.7로 직접 테스트해 보니 예상 밖의 결과가 몇 가지 있었습니다. 표, 작업 목록(task list), LaTeX 수식, Mermaid 다이어그램을 가득 채운 테스트 문서를 pandoc 3.7.0.2로 변환한 뒤, 생성된 .docx의 압축을 풀어 내용물을 직접 확인했습니다.

이 가이드에서는 설치, 알아둘 만한 명령, DOCX 스타일 지정, 일괄 변환, 그리고 그 테스트를 바탕으로 pandoc이 어디서 무너지고 언제 온라인 변환기가 더 나은 선택인지에 대한 솔직한 지도를 차례로 살펴봅니다.

👉 테스트 결과로 건너뛰기 | 명령줄 vs 온라인 비교로 건너뛰기

Pandoc 설치

Pandoc은 단일 바이너리이며 모든 주요 플랫폼용 설치 프로그램이 제공됩니다:

• macOS: brew install pandoc
• Windows: winget install --id JohnMacFarlane.Pandoc (또는 MSI 설치 프로그램)
• Debian/Ubuntu: sudo apt install pandoc

오래된 시스템 패키지를 믿기 전에 한 가지 주의할 점이 있습니다. 배포판 저장소는 몇 년씩 뒤처진 pandoc 버전을 배포하는 경우가 많습니다. Ubuntu LTS는 오랫동안 2.x를 제공해 왔지만 현재 릴리스 라인은 3.x입니다. 아래에서 보게 되겠지만, 버전의 나이는 무엇이 깨끗하게 변환되는지를 좌우합니다. pandoc --version으로 내 버전을 확인하세요.

기본 변환 명령 이해하기

최소한의 명령으로도 동작하지만, 실제 프로젝트에서는 다음 플래그들이 대부분의 일을 해냅니다:

pandoc report.md -f gfm -o report.docx --toc

왜 pandoc의 기본 마크다운 방언 대신 -f gfm을 쓸까요? 오늘날 대부분의 사람이 쓰는 마크다운 — GitHub README, ChatGPT와 Claude의 출력, Notion 내보내기 — 이 GFM이기 때문입니다. pandoc의 기본 방언은 더 학술적입니다. 각주와 인용을 지원하지만 몇몇 구문을 다르게 해석합니다. 소스가 AI 어시스턴트나 개발자 도구에서 왔다면 gfm이 더 안전한 리더입니다.

수식 관련 참고: GFM 리더에서도 최신 pandoc에서는 $...$와 $$...$$ 수식이 그냥 동작합니다. 수식은 그림이 아니라 워드 네이티브 수식이 됩니다. 이 부분은 아래에서 자세히 다룹니다. 웹에서 가장 잘못 알려진 pandoc 동작이기 때문입니다.

reference-doc으로 출력 스타일 지정하기

pandoc이 생성한 DOCX를 워드에서 열면 스타일이 밋밋합니다. 문서를 회사 템플릿에 맞춰야 한다면 플래그로는 해결할 수 없습니다 — **참조 문서(reference document)**를 사용합니다.

워크플로는 세 단계입니다:

1. 출발점으로 pandoc의 기본 템플릿을 생성합니다:

   pandoc -o custom-reference.docx --print-default-data-file reference.docx
   

2. custom-reference.docx를 워드에서 열고 스타일 — 제목 1, 표준, 표, 코드 블록 — 을 편집합니다. 이 파일의 본문 내용은 무시되며, 스타일과 페이지 설정만 넘어갑니다.

3. 템플릿을 적용해 변환합니다:

   pandoc report.md -f gfm --reference-doc=custom-reference.docx -o report.docx
   

어떤 스타일 이름이 반영되는지는 pandoc 매뉴얼에 문서화되어 있습니다. 이해를 돕는 멘탈 모델은 이렇습니다: 문서 하나하나를 꾸미는 것이 아니라, 조직의 워드 스타일을 pandoc에 한 번 가르쳐 놓고 이후 모든 변환에서 재사용하는 것입니다.

여러 파일 일괄 변환

여기가 명령줄이 어떤 웹 도구보다 진짜로 앞서는 지점입니다. 폴더 전체를 변환하려면:

Bash (macOS/Linux):

for f in docs/*.md; do
  pandoc "$f" -f gfm -o "${f%.md}.docx"
done

PowerShell (Windows):

Get-ChildItem docs -Filter *.md | ForEach-Object {
  pandoc $_.FullName -f gfm -o ($_.FullName -replace '\.md$', '.docx')
}

그리고 pandoc은 의존성이 하나뿐이라 CI에도 별다른 절차 없이 들어갑니다. 푸시할 때마다 문서의 워드 사본을 다시 생성하는 GitHub Actions 단계는 다음과 같습니다:

- uses: pandoc/actions/setup@v1
- run: |
    for f in docs/*.md; do
      pandoc "$f" -f gfm --reference-doc=brand.docx -o "out/$(basename "${f%.md}").docx"
    done

팀들은 이 패턴으로 컴플라이언스 검토나 고객 납품용으로 마크다운 위키의 워드 미러를 유지합니다. 같은 파일 묶음을 세 번 이상 변환한다면 이 스크립트는 즉시 본전을 뽑습니다.

Pandoc의 실제 한계 (3.7 테스트)

제가 실행한 테스트는 이렇습니다. 표, 작업 목록, 인라인 수식($E = mc^2$), 여러 줄 디스플레이 수식, Mermaid 순서도, GFM 알림(alert) 블록을 담은 마크다운 파일 하나. 이를 pandoc 3.7.0.2로 변환한 뒤 .docx의 압축을 풀고 word/document.xml을 직접 읽었습니다. 발견한 것은 세 가지입니다.

수식은 알려진 것보다 잘 동작합니다

문서 XML에는 <m:oMath> 블록이 두 개 — 수식마다 하나씩 — 들어 있었습니다. 이것이 OMML, 즉 워드의 네이티브 수식 형식입니다. 두 수식 모두 워드 수식 편집기에서 완전히 편집 가능하고, 인쇄 품질로 렌더링되며, 다른 Office 문서로 복사·붙여넣기해도 살아남습니다.

이는 오래된 튜토리얼(그리고 최근까지 저희 가이드 중 하나)에서 여전히 볼 수 있는 주장 — 복잡한 LaTeX가 이미지로 래스터화된다는 것 — 과 모순됩니다. 최신 pandoc에서는 그렇지 않습니다. 표준 LaTeX 수식 — 분수, 합기호, 그리스 문자, 아래 첨자 — 은 별도 설정 없이 네이티브 수식으로 변환됩니다.

솔직한 경계선은 이렇습니다: pandoc이 처리하는 것은 표준 LaTeX 수식 구문이지, 임의의 LaTeX가 아닙니다. 사용자 정의 \newcommand 매크로, TikZ 그림, 패키지 의존 환경은 넘어오지 못합니다. 그리고 배포판이 pandoc 2.x를 제공했다면 동작이 다릅니다 — 도구를 탓하기 전에 pandoc --version부터 확인하세요.

진짜 걸림돌은 Mermaid입니다

Mermaid 순서도는 다이어그램이 되지 않았습니다. 원본 flowchart LR 소스가 코드 블록 스타일의 고정폭 텍스트 그대로 넘어왔습니다. 문서 XML에는 그리기 개체(drawing object)가 하나도 없습니다.

이 문제는 5년 전보다 지금이 더 중요합니다. AI 어시스턴트들이 Mermaid를 즐겨 쓰기 때문입니다. ChatGPT나 Claude에 아키텍처 개요를 요청하면 응답에 mermaid 코드 블록이 포함될 가능성이 큽니다. 그 대화를 pandoc으로 변환하면 워드 문서에 지우다 만 소스 코드처럼 보이는 것이 남습니다. 그것이 여러분의 워크플로라면, ChatGPT 출력을 워드로 내보내는 가이드에서 AI 특유의 세부 사항을 다루고 있습니다.

CLI에서의 해결책은 있습니다: 변환 중에 다이어그램을 렌더링해 주는 pandoc 필터인 mermaid-filter입니다. 동작은 하지만 설치 비용을 솔직하게 따져보세요. Puppeteer를 통해 헤드리스 Chromium을 끌어오는 npm 패키지이고, pandoc 호출은 pandoc -F mermaid-filter ...가 됩니다. 매일 다이어그램을 변환하는 문서 파이프라인이라면 그 설치 비용은 충분히 상쇄됩니다. 오늘 오후까지 내야 하는 보고서 한 편을 위해서라면 돌아가는 길입니다.

가장자리에서의 작은 손실들

같은 테스트에서 나온 조용한 발견 두 가지. GFM 알림 블록(> [!NOTE])은 텍스트는 유지되지만 색상 콜아웃 서식을 잃습니다 — 워드에서는 평범한 인용 블록으로 보입니다. 그리고 작업 목록 항목은 워드 체크박스 컨트롤이 아니라 일반 목록 텍스트로 들어옵니다. 둘 다 문서를 망가뜨리지는 않지만, 작성자가 의도적으로 선택했을 서식을 평탄화합니다. 변환이 다른 방식으로 어긋난다면 흔한 마크다운 변환 문제에 자주 발생하는 실패 유형을 정리해 두었습니다.

명령줄 vs 온라인 변환기, 언제 무엇을 쓸까

그 테스트를 거친 뒤 제가 실제로 쓸 만한 판단 기준은 이렇습니다:

두 경로 모두 정당합니다. 반복되는 파이프라인이라면 pandoc은 제 몫을 합니다. "5분 안에 .docx가 필요하다"는 일회성 상황 — 특히 Mermaid가 끼어 있다면 — 에는 무료 온라인 마크다운 워드 변환기로 아무것도 설치하지 않고 수식과 렌더링된 다이어그램이 모두 살아 있는 깔끔한 문서를 얻을 수 있습니다.

자주 묻는 질문

Q: 아무것도 설치하지 않고 마크다운을 워드로 변환할 수 있나요?
A: 명령줄에서는 불가능합니다 — pandoc은 설치가 필요합니다. 소프트웨어 설치가 선택지에 없다면 브라우저 기반 변환기가 현실적인 경로입니다. 변환은 서버 측에서 이루어지고 완성된 .docx를 내려받으면 됩니다.

Q: pandoc은 LaTeX 수식을 진짜 워드 수식으로 변환하나요?
A: 네. pandoc 3.7.0.2 테스트에서 인라인 수식과 디스플레이 수식 모두 네이티브 OMML 수식이 되었고, 워드 수식 편집기에서 편집할 수 있었습니다. 예외는 아주 오래된 pandoc 버전과 사용자 정의 LaTeX 매크로입니다.

Q: 왜 Mermaid 다이어그램이 워드에서 코드로 보이나요?
A: pandoc은 mermaid 코드 블록을 문자 그대로의 코드로 취급하며 다이어그램을 렌더링하지 않습니다. mermaid-filter를 파이프라인에 추가하거나(Node.js 필요), Mermaid 렌더링이 내장된 변환기를 사용하세요.

Q: 회사의 글꼴과 제목 스타일을 유지하려면 어떻게 하나요?
A: --reference-doc=template.docx를 사용하세요. 템플릿의 스타일을 워드에서 한 번만 편집하면 pandoc이 모든 변환에 적용합니다. 템플릿의 본문 내용은 무시되고 스타일만 넘어갑니다.

Q: -f markdown과 -f gfm의 차이는 무엇인가요?
A: markdown은 pandoc 고유의 확장 방언(각주, 인용)입니다. gfm은 GitHub, ChatGPT를 비롯한 대부분의 현대 도구가 생성하는 것 — 표, 작업 목록, 취소선 — 과 일치합니다. AI가 생성했거나 개발자가 작성한 마크다운이라면 gfm이 돌발 상황이 적습니다.

Q: pandoc으로 워드를 다시 마크다운으로 변환할 수 있나요?
A: 네 — 인수를 뒤집으면 됩니다: pandoc report.docx -o report.md. 왕복 변환에서는 워드 고유 서식(텍스트 상자, 메모) 일부가 손실되므로, 무손실 사이클이 아니라 콘텐츠 이전으로 생각하세요.

관련 자료

• 마크다운 워드 변환 완전 가이드: 명령줄 너머의 전체 변환 옵션 지형도
• ChatGPT를 워드로: AI 생성 문서를 위한 마크다운 워크플로
• 마크다운을 PDF로: 결과물이 PDF여야 할 때
• 흔한 마크다운 변환 문제: 깨진 표, 인코딩 문제, 서식 어긋남 해결법

마무리

"명령줄에서 마크다운을 워드로 변환"이라는 질문에 대한 정답은 여전히 pandoc입니다. 파일 하나에는 명령 한 줄, 폴더에는 짧은 스크립트, 회사 스타일에는 --reference-doc. 테스트 결과 수식 지원은 알려진 평판보다 좋았습니다: 표준 LaTeX는 진짜 편집 가능한 워드 수식이 됩니다.

진짜 공백은 시각 요소입니다. Node 기반 필터 체인을 덧붙이지 않는 한 Mermaid 다이어그램은 소스 코드로 도착합니다. 그러니 워크플로에 따라 고르세요. 텍스트 위주 문서를 다루는 반복 파이프라인이라면 pandoc으로 스크립트를 짜고, 다이어그램과 마감이 걸린 단건 문서라면 브라우저에서 변환해 수식과 순서도를 그대로 지키세요.

참고 자료

• Pandoc User's Guide — 공식 매뉴얼: 리더, 라이터, --reference-doc, 수식 처리
• Installing pandoc — 모든 플랫폼용 공식 설치 프로그램
• mermaid-filter — Mermaid 다이어그램을 렌더링하는 커뮤니티 pandoc 필터
• pandoc/actions — CI에서 pandoc을 쓰기 위한 공식 GitHub Actions