Pandoc
Pandoc
Mkdocs 중 문서 중 Markdown으로 된 문서를 쉽게 DOCX / PPTX 혹은 다양한 포맷으로 변경가능한 Tool이며,
아래의 설명과 같이 다양한 기능을 제공을 해준다.
NOTE
Markdown을 쉽게 변경을 가능하지만, Mermaid 나 UML 미지원
Pandoc를 이용하여 문서를 만들고자 하면 각 Mermaid 나 UML는 우선 SVG or PNG 그림파일로 변경
Install pandoc
현재 Window에서만 사용을 주로해서 아래와 같이 Window에서 쉽게 설치
Windows
- Install pandoc in Windows
winget install --id JohnMacFarlane.Pandoc -e
- Check pandoc
pandoc --version
NOTE
Markdown to Docx/PPTx 변경" 쉽게 Docx 와 PPTx 변경
DOCX/PPTX 은 XML 기반이므로 가능하지만, 뒤에 X가 빠지면 안됨
아래 TEST 를 위해서 --- 추가함
Markdown
Markdown To DOCX
> NOTE
>
> 가능하면, ">" 기반으로 경고문을 작성
>
> NOTE
>
> A. !!! tips/success/note "" 대신 전부 > 변경
>
> "<br/>"
> " --- " : HTML 괜찮으나, --- 로 문서의 질이 떨어짐
>
아래 TEST 를 위해서 --- 추가함
모든 Markdown이 되는 것이 아니며, Mkdocs 와 좀 많이 다르다.
일부 HTML을 허용하나, 모두 허용하는 것은 아니다.
-
Image 사이즈 강제 조절
 {width=10cm height=6cm} {width=50% height=50%} -
TEST Table 미 조절
| 구분 | A | B |
|---|---|---|
| 1| A.1 | A.1 |
| 2 | A.2 | A.1 |
| 3 | A.1 | A.1 |
| 4 | A.1 | A.1 |
| 5 | A.1 | A.1 |
- TEST Table 정렬
| 구분 | A | B |
|:---:|:---|---:|
| 1 | A.1 | A.1 |
| 2 | A.2 | A.1 |
| 3 | A.1 | A.1 |
- TEST Table 사이즈 조절
아래 Lua Filter로도 가능
+------+----------------+------------------------+ | 구분 | A | B | +======+================+========================+ | 1 | A.1 | A.1 | +------+----------------+------------------------+ | 2 | A.2 | A.1 | +------+----------------+------------------------+ | 3 | A.1 | A.1 | +------+----------------+------------------------+ | 4 | A.1 | A.1 | +------+----------------+------------------------+ | 5 | A.1 | A.1 | +------+----------------+------------------------+
Markdown To PPTX
- Example
--- 로 쉽게 각 Slide 구분--- title: "Pandoc PPTx" author: "TEST 이정훈" date: "2026-10-19" toc-title: "목차" --- # Slide 1: 프로젝트 소개 Pandoc - 개발 목적 - 시스템 개요 --- # Slide 2: 시스템 아키텍처 - Pandoc - PPTX --- # Slide 3: 개발 일정 | 단계 | 작업 | |---|---| | 1 | System Driver 개발 | | 2 | Application 개발 | | 3 | 통합 테스트 |
Make Reference
Reference docx 와 pptx 파일생성 방법이지만, 솔직히 Reference 파일은 필요 없을 듯하다.
왜냐하면, 본인 스타일 이나, 회사 문서 서식기반으로 한다음 Reference 파일을 수정해 나가는 것이 빠르다
- Reference docx/pptx file
pandoc -o reference.docx --print-default-data-file reference.docx
pandoc -o reference.pptx --print-default-data-file reference.pptx
- Reference File
- 상위 파일을 만든 후, 각 폰트를 변경하고 본인 스타일로 수정
- docx 와 pptx 가능한 이유는 XML기반

DOCX File Edit
상위 reference 기반으로 각 Docx 파일의 Style을 수정
머리글/바닥글

- 자동 페이지
삽입 → 페이지 번호 → 페이지 아래쪽/위쪽 → “X/Y 형식
Page { PAGE } of { NUMPAGES } { PAGE } / { NUMPAGES }
Modify Reference
Reference 파일을 한번에 완성하기는 힘들면, 아래와 같이 반복 진행하며, 상위처럼 Reference 파일 만들기 보다
기존에 본인이 사용하는 것을 Reference 파일을 이용하는 게 더 빠름
가능하다면, 기존파일을 아무거나 사용하고 싶은 것을 가져와서 Reference하는 게 더 좋음
- STEP.1 : Convert to DOCX 파일 생성 (reference 이용)
- STEP.2 : 상위 Output의 tool_pandoc.docx 파일을 수정
- Ctrl+Alt+Shift+S : 스타일 수정 나옴 (각 스타일 서식구조를 변경)
- 각 원하는 서식에서 우측버튼 -> 스타일 -> 원하는 스타일 선택 -> 스타일 적용
Modify Style
Pandoc에서 사용하는 스타일 서식을 본인 스타일의 서식으로 변경
- docx 파일 스타일 수정
- 스타일에서 각 pandoc의 스타일 이름 찾기
- e.g. 제목2, 제목3, Compact, Source Code, Table
- 스타일 적용 수정으로 모든 포맷 교정
- 스타일에서 각 pandoc의 스타일 이름 찾기
-
스타일 수정 -> TOC 제목
- 스타일 이름: TOC 제목
- 서식 : 한글 -> 모든언어

-
스타일 수정->Source Code
- 스타일 이름: Source Code
- 서식 : 한글 -> 모든언어

Modify Style-Font
Pandoc에서 사용하는 스타일 서식을 본인 스타일의 서식으로 변경
중요사항
아래의 스타일에서 폰트가 겹치면 안됨
- 스타일 수정->제목 2
아래와 같이 폰트가 겹치는 경우가 발생
- 글꼴 -> 원하는 글꼴 설정
- 폰트 충돌 없음
- 글꼴 -> 원하는 글꼴 설정
- TOC 문제
- 제목 1 하이퍼링크
- 제목 2 하이퍼링크
상위를 수정을 했다고 해서, TOC의 하이퍼링크도 개별로 적용해서 해야한다.
Modify Matrix
- 테이블디자인 -> 표스타일

아래에서 최종 표스타일 수정
- 스타일 수정-Table-표전체
- 스타일이름: Table : 이 이름을 찾아서 매번 스타일 서식을 변경하는 것이 목적
- 스타일기준: 외부에 이미 설정된 스타일을 가져오는 것으로 수정중이라면 변경하지 않는 것이 좋음
- 서식 : 한글 -> 모든언어


- 스타일 수정-Table-머리글행
- 스타일이름: Table
- 서식 적용대상: 표전체 -> 머리글행
- 서식 : 한글 -> 모든언어
| TEST | TEST | TEST |
|---|---|---|
| TEST | TEST | TEST |
| TEST | TEST | TEST |
| TEST | TEST | TEST |
| TEST | TEST | TEST |
Modify TOC
-
목차-> 사용자지정목차
- 우측 목차1 ~ 8 의 크기 및 폰트 수정
- 수준표시 와 표시방법
-
목차 1 -> 단락
단락을 선택하여 각 간격 조절
- TOC 제목
Table of Contents 수정
- 하이퍼링크
각 항목은 각 제목의 하이퍼 링크로 되어있어, 각 제목의 폰트를 그대로 적용되어진다. 같은 하이퍼 링크지만, 각 제목 1,2에 따라 다 확인- 제목 1 -> 하이퍼 링크
- 제목 2 -> 하이퍼 링크
- 목차업데이트
각 폰트 변경을 재확인을 해야함. 즉 1개의 제목 1 스타일 수정을 했다고, 전체 제목 1의 스타일 변경되지 않는다.
PPTX File Edit
상위 reference 기반으로 각 Docx 파일의 Style을 수정
보기 -> 슬라이드 마스터

- 슬라이드 노트 마스터
생략
| 구분 | 슬라이드 마스터 | 슬라이드 노트 마스터 |
|---|---|---|
| 목적 | 발표 화면 디자인 | 발표자 노트 인쇄 |
| 제목·본문 | 글꼴·크기·위치 | 노트 서식 |
| 머리글 | 기본 지원 없음 | 지원 |
| 바닥글 | 슬라이드 하단 | 노트 페이지 하단 |
| 번호 | 슬라이드 번호 | 노트 페이지 번호 |
| 로고·배경 | 슬라이드 전체 | 노트 페이지 |
| Pandoc | reference.pptx 적용 | 일반적으로 불필요 |
| 설정 | 보기 → 슬라이드 마스터 | 보기 → 노트 마스터 |
Style 수정
- 글꼴 수정
각 구조 변경 및 각 Size 변경

Check DOCX/PPTX
- DOCX/PPTX 의 구성
zip으로 되어있으며, 이를 풀면 XML 기반으로 쉽게 확인가능
tar -tf .\reference.docx | Select-Object -First 10
tar -tf .\reference.docx
[Content_Types].xml
_rels/.rels
docProps/app.xml
docProps/core.xml
docProps/custom.xml
word/document.xml
word/fontTable.xml
word/footnotes.xml
word/comments.xml
word/numbering.xml
Check XML
XML기반으로 세부분석
- styles.xml 내용확인
tar -xf .\reference.docx -O word/styles.xml
- 압축풀기
압축을 풀면 다양한 XML과 Directory가 나옴tar -xf .\reference.docx
Pandoc Build
Convert to PPTX
- Convert markdown to pptx
간단히 변경가능하지만, 사용의미가 없음
pandoc .\docs\index.md ` --slide-level=2 ` --resource-path=".;.\docs" ` -o .\output\index.pptx
- Convert markdown to pptx
Reference 이용
pandoc .\docs\index.md ` --slide-level=2 ` --reference-doc=.\docx\reference.pptx ` --resource-path=".;.\docs" ` -o .\output\index.pptx
- Convert markdown to pptx
Referencepandoc .\docs\test_pptx.md ` --standalone ` --toc ` --toc-depth=1 ` --slide-level=0 ` --reference-doc=.\docx\reference.pptx ` --resource-path=".;.\docs" ` -o .\docx\output\test_pptx.pptx
- task.json
{ "label": "Pandoc: test_ppt.md to PPTX", "type": "shell", "command": "pandoc", "args": [ ".\\docx\\test_ppt.md", "--standalone", "--toc", "--toc-depth=1", "--slide-level=0", "--reference-doc=.\\docx\\reference\\reference.pptx", "--resource-path=.\\docx", "-o",`` ".\\docx\\output\\test_ppt.pptx" ] },
Convert to DOCX
- Convert markdown to docx
pandoc ` .\docs\index.md ` --toc ` --number-sections ` --reference-doc=.\docx\reference.docx ` --resource-path=".;.\docs" ` -o .\output\index.docx
- Convert markdown to docx
pandoc ` .\docs\tool_pandoc.md ` --toc ` --number-sections ` --reference-doc=.\docx\tool_pandoc.docx ` --resource-path=".;.\docs" ` -o .\output\tool_pandoc.docx
- task.json
{ "label": "Pandoc: tool_pandoc.md (Lua filter) to DOCX", "type": "shell", "command": "pandoc", "args": [ ".\\docs\\tool_pandoc.md", "--toc", "--metadata-file=.\\docx\\lua\\signature.yaml", "--lua-filter=.\\docx\\lua\\signature.lua", "--lua-filter=.\\docx\\lua\\information.lua", "--lua-filter=.\\docx\\lua\\test_result.lua", "--lua-filter=.\\docx\\lua\\table-width.lua", "--number-sections", "--reference-doc=.\\docx\\reference\\reference.docx", "--resource-path=.\\docs", "-o",`` ".\\docx\\output\\tool_pandoc_lua.docx" ] },
Mermaid Build
Node.js가 설치되어있다면, npx가 존재
- Pandoc
Pandoc is not support mermaid
Pandoc는 Mermaid가 미지원하므로, 이를 SVG를 변경 후 진행
All Pandoc need Converting
npx --help
- Check package.json
주석을 사용하면 안됨
Convert Mermaid to SVG
- Convert Markdown(mmd) to svg
npx -p @mermaid-js/mermaid-cli mmdc `
-i .\docx\mmd\test.md `
-o .\docx\imgs\test.svg `
-b transparent
npx -p @mermaid-js/mermaid-cli mmdc `
-i .\docx\mmd\test_general.md `
-o .\docx\imgs\test_general.svg `
-b transparent
npx -p @mermaid-js/mermaid-cli mmdc `
-i .\docx\mmd\test_handdrawn.md `
-o .\docx\imgs\test_handdrawn.svg `
-b transparent
Lua Filter
- Check Pandoc Version and Lua Filter Engine
pandoc --version pandoc 3.10 Features: +server +lua Scripting engine: Lua 5.4 User data directory: C:\Users\LeeJeongHun\AppData\Roaming\pandoc Copyright (C) 2006-2025 John MacFarlane. Web: https://pandoc.org This is free software; see the source for copying conditions. There is no warranty, not even for merchantability or fitness for a particular purpose.
- Markdown
아래와 같이 Lua Filter 와 인식자/구분자 정하고, 그에 맞게 Lua filter Script 작성
꼭 ::: 필요는 없으며 각 부분을 정하고 하면 됨
아니면, 인식자/구분자 없이 무조건적으로 넣는 것을 해도 될 듯하다.
가급적 Markdown에서 사용하는 인식자/구분자 중복을 피하는 것 이 좋은 것 같다.
DOCX
아래의 예제는 DOCX 기준이나 HTML 기준으로 작성할 수 있다.
HTML
Lua Filter Script을 보면 div 기반으로 사용하므로, DOCX가 아니라면,
HTML 로 한다면, CSS까지 나중에 고려 해도 될 듯하다.
Lua Filter Script-A
- TEST Lua Filter-1
::: {.signature} :::
상위 구분자 와 Lua Filter and Metadata
- lua/signature.yaml // Metafile 에서 각 데이타 정보 추출
- lua/signature.lua // 상위 Metafile 정보 기반으로 적용
즉 yaml 정보파일 (Metafile은 YAML로 이용) 과 정보 image path 이용
yaml 내의 이미지 위치 PATH는 반드시 Project 기반 이유는 Task에서 실행하기 때문에
- docx/tool_pandoc_lua.docx
pandoc result // pandoc 실행 결과
Lua Filter Script-B
- TEST Lua Filter-2
아래 소스 위치를 --resource-path 찾지 못하고, Project Root 에서 찾음
::: {.information source=".gitignore" title="Git Ignore"} :::
상위 구분자 와 information.lua
간단히 lua filter만 이용하여 외부파일 읽기
.gitignore 파일의 위치 PATH는 반드시 Project 기반 이유는 Task에서 실행하기 때문에
- docx/tool_pandoc_lua.docx
pandoc result // pandoc 실행 결과
Lua Filter Script-C
- TEST Lua Filter-3
::: {.test-result source="docx/lua/test_result.json"} :::
상위 구분자 와 test_result.lua
- test_result.json
- test_result.lua
Json 파일을 읽어서, lua filter로 처리하여, Table 생성
json 파일의 위치 PATH는 반드시 Project 기반 이유는 Task에서 실행하기 때문에
- docx/tool_pandoc_lua.docx
pandoc result // pandoc 실행 결과 (test_result.lua/test_result.json)

Lua Filter Script-D
table-width.lua 이용하여 각 width를 세부적으로 조절 이 방법 말고 별도로
- TEST Table Size Lua Filter로 조절
::: {.table-width widths="10,45,45"}
| 구분 | A | B |
|---|---|---|
| 1 | A.1 | A.1 |
| 2 | A.2 | A.1 |
| 3 | A.1 | A.1 |
| 4 | A.1 | A.1 |
| 5 | A.1 | A.1 |
:::
- TEST Table 사이즈 조절
이 방법으로 도 사이즈 조절 가능 하지만 좀 불편
+------+----------------+------------------------+ | 구분 | A | B | +++==============+ | 1 | A.1 | A.1 | +------+----------------+------------------------+ | 2 | A.2 | A.1 | +------+----------------+------------------------+ | 3 | A.1 | A.1 | +------+----------------+------------------------+ | 4 | A.1 | A.1 | +------+----------------+------------------------+ | 5 | A.1 | A.1 | +------+----------------+------------------------+
Pandoc Args
- VS Code Task
Pandoc args에 아래와 같이 각 Lua filter 적용
".\\docs\\tool_pandoc.md",
"--toc",
"--number-sections",
"--metadata-file=.\\docx\\lua\\signature.yaml", //signature.lua meta data
"--lua-filter=.\\docx\\lua\\signature.lua",
"--lua-filter=.\\docx\\lua\\information.lua",
"--lua-filter=.\\docx\\lua\\test_result.lua",
"--lua-filter=.\\docx\\lua\\table-width.lua",
"--reference-doc=.\\docx\\reference\\reference.docx",
"--resource-path=.\\docs",
"-o",``
".\\docx\\tool_pandoc.docx"