Pandoc 문서 자동화 2026, PDF·HTML 변환 전에 템플릿과 폰트부터 고르는 이유

Pandoc는 Markdown, HTML, DOCX, PDF처럼 서로 다른 문서 형식을 오가는 변환 도구입니다. 개발팀이나 운영팀이 릴리스 노트, API 문서, 제안서, 내부 매뉴얼을 반복해서 만들 때 손작업을 줄이는 데 특히 유용합니다.

다만 명령어 하나로 모든 문서 품질이 해결되는 도구는 아닙니다. 실무에서는 템플릿, 한글 폰트, 이미지 경로, 코드 블록, CI 실행 환경을 먼저 잡아야 PDF와 HTML 결과물이 안정적으로 나옵니다.

처음부터 “문서를 어떤 형식으로 저장할지”보다 “어떤 흐름으로 자동 생성하고 검수할지”를 정하는 편이 실패가 적습니다.

목차

• 1. Pandoc를 쓰기 전에 보는 전체 흐름
• 2. 본문: 변환 도구가 아니라 문서 파이프라인으로 보기
• 3. Markdown·PDF·HTML 중 무엇을 기준으로 둘까
• 4. 템플릿, 폰트, 코드 블록에서 자주 깨지는 지점
• 5. 배포 파이프라인에 넣는 기본 스켈레톤
• 6. 도입 전 체크리스트
• 7. 자주 묻는 질문

1. Pandoc를 쓰기 전에 보는 전체 흐름

Pandoc는 문서 형식을 바꾸는 도구이지만, 실무에서는 단순 변환기보다 문서 제작 파이프라인의 중심에 가깝습니다. README는 Markdown으로 쓰고, 고객 전달본은 PDF로 만들고, 내부 위키에는 HTML로 올리는 식의 흐름이 반복된다면 수동 복사보다 자동 변환이 훨씬 안전합니다.

문제는 변환 자체보다 결과 품질입니다. 한글 폰트가 깨지거나, 표가 페이지 밖으로 밀리거나, 코드 블록 줄바꿈이 어긋나거나, 이미지 상대 경로가 CI 서버에서 사라지는 일이 자주 납니다. 그래서 Pandoc를 도입할 때는 명령어보다 입력 규칙, 템플릿, 검수 기준을 먼저 정해야 합니다.

공식 설치 기준 확인하기 →

2. 본문: 변환 도구가 아니라 문서 파이프라인으로 보기

Pandoc가 잘 맞는 팀은 문서를 반복해서 만드는 팀입니다. 오픈소스 프로젝트, SaaS 제품팀, SI 제안서 작성팀, 교육 콘텐츠 제작팀, 내부 보안 규정 관리팀처럼 같은 내용을 여러 형식으로 배포해야 하는 곳에서 효과가 큽니다.

반대로 한 달에 한 번 짧은 글을 PDF로 바꾸는 정도라면 오피스 도구가 더 편할 수 있습니다. Pandoc의 장점은 “한 번 클릭”이 아니라 “규칙을 정해두면 매번 같은 방식으로 결과물이 나온다”는 점입니다. 문서가 코드처럼 Git에 쌓이고, 변경 이력이 남고, 빌드 과정에서 검수되는 구조를 만들 때 진가가 나옵니다.

상황	Pandoc가 맞는 경우	다른 도구가 나은 경우
개발 문서	Markdown을 PDF, HTML, DOCX로 함께 내보낼 때	웹 문서만 필요하고 검색·버전 관리가 중심일 때
제안서·보고서	반복 양식과 표준 문구가 많을 때	디자이너가 레이아웃을 세밀하게 잡아야 할 때
교육 자료	강의안, 실습서, 웹 자료를 같은 원고에서 만들 때	슬라이드 애니메이션과 시각 효과가 핵심일 때
규정 문서	버전, 승인일, 변경 내역을 남겨야 할 때	부서별 자유 편집이 더 중요한 경우

문서 자동화가 예산이나 개발도구 비용과 연결되는 팀이라면 관련 지원 조건도 함께 볼 만합니다. 단, 도구 구매보다 먼저 현재 문서가 어디서 만들어지고 어디로 배포되는지 흐름을 그려두는 것이 우선입니다.

개발도구 비용 조건 같이 보기 →

3. Markdown·PDF·HTML 중 무엇을 기준으로 둘까

처음부터 PDF를 기준으로 잡으면 편집 결과는 예쁘지만 협업과 자동화가 답답해질 수 있습니다. HTML만 기준으로 잡으면 웹 배포는 쉽지만 고객사 제출용 파일이나 인쇄본에서 품질 차이가 생깁니다. 실무에서는 Markdown을 원본으로 두고 PDF와 HTML을 산출물로 만드는 방식이 가장 관리하기 쉽습니다.

기준 형식	장점	주의할 점
Markdown	Git 관리, 리뷰, 자동 변환에 유리	복잡한 레이아웃 표현은 약함
PDF	제출·인쇄·보존에 안정적	폰트와 페이지 넘김 검수가 필요
HTML	웹 게시, 검색, 내부 위키에 유리	CSS와 이미지 경로를 따로 관리해야 함
DOCX	비개발자 검토와 코멘트에 편함	왕복 편집 시 서식이 흔들릴 수 있음

권장 흐름은 간단합니다. 작성은 Markdown, 검토는 Pull Request 또는 문서 리뷰, 배포는 Pandoc 빌드 산출물로 나누는 방식입니다. 이렇게 하면 문서 수정이 코드 변경처럼 기록되고, 누가 언제 어떤 표현을 바꿨는지도 추적됩니다.

4. 템플릿, 폰트, 코드 블록에서 자주 깨지는 지점

Pandoc 실패의 상당수는 도구 자체 문제가 아니라 주변 조건 문제입니다. 특히 한국어 문서에서는 PDF 엔진, 한글 폰트, 표 너비, 코드 블록, 이미지 경로가 핵심입니다.

한글 PDF는 폰트부터 고정

PDF 변환에서 한글이 네모로 보이면 대부분 폰트 설정 문제입니다. 서버와 로컬 PC의 폰트가 다르면 같은 명령어라도 결과가 달라집니다. 팀에서 쓰는 Noto Sans CJK, 나눔고딕 같은 폰트를 정하고 CI 이미지에도 같은 폰트를 넣어야 합니다.

표와 코드 블록은 짧게 쓰는 규칙이 필요

긴 표, 긴 URL, 한 줄짜리 긴 코드가 들어가면 PDF 페이지가 쉽게 깨집니다. 문서 작성 규칙에서 “표는 열 4개 이하”, “명령어는 줄바꿈 허용”, “긴 설정은 별도 파일로 분리” 같은 기준을 두면 빌드 실패가 줄어듭니다.

이미지 경로는 로컬 기준이 아니라 빌드 기준

내 PC에서는 보이는 이미지가 CI 서버에서는 사라질 수 있습니다. 상대 경로 기준 위치, 대소문자, 파일 확장자, 공백이 들어간 파일명까지 확인해야 합니다. 운영 문서라면 이미지 폴더를 고정하고 파일명을 영문 소문자와 하이픈 중심으로 맞추는 편이 안전합니다.

Pandoc 사용 설명서 확인하기 →

5. 배포 파이프라인에 넣는 기본 스켈레톤

작게 시작하려면 Makefile이나 npm scripts처럼 팀이 익숙한 실행 방식을 하나 정하면 됩니다. 아래는 Markdown 원고 하나에서 PDF와 HTML을 함께 만드는 기본 골격입니다.

SRC=docs/guide.md
DIST=dist
TITLE="Service Operations Manual"

all: pdf html

pdf:
	mkdir -p $(DIST)
	pandoc $(SRC) \
	  --from markdown \
	  --pdf-engine=xelatex \
	  -V mainfont="Noto Sans CJK KR" \
	  -V geometry:margin=25mm \
	  -o $(DIST)/guide.pdf

html:
	mkdir -p $(DIST)
	pandoc $(SRC) \
	  --from markdown \
	  --to html5 \
	  --standalone \
	  --metadata title=$(TITLE) \
	  --css assets/docs.css \
	  -o $(DIST)/guide.html

clean:
	rm -rf $(DIST)

이 정도만 있어도 팀원은 명령어를 외울 필요 없이 make all만 실행하면 됩니다. 이후에는 GitHub Actions, GitLab CI, Jenkins 같은 CI 도구에서 같은 명령을 실행하게 만들면 됩니다. 중요한 것은 문서 빌드가 사람 손이 아니라 저장소 규칙으로 돌아가게 만드는 것입니다.

SaaS 제품 문서처럼 배포 대상이 웹과 PDF로 나뉘는 경우에는 클라우드 전환, 빌드 서버, 권한 관리까지 같이 봐야 합니다. 문서 자동화도 결국 운영 시스템의 일부라서 배포 흐름과 떨어뜨려 생각하면 유지보수가 힘들어집니다.

SaaS 전환 조건 같이 보기 →

6. 도입 전 체크리스트

• 원본 문서 형식을 Markdown으로 둘지, DOCX를 유지할지 먼저 정한다.
• PDF, HTML, DOCX 중 실제 배포에 필요한 산출물만 남긴다.
• 한글 폰트와 PDF 엔진을 로컬·서버에서 동일하게 맞춘다.
• 표, 이미지, 코드 블록 작성 규칙을 문서 작성자에게 공유한다.
• 이미지 파일명과 상대 경로가 CI 환경에서도 깨지지 않는지 확인한다.
• 템플릿, CSS, 로고, 머리말·꼬리말을 저장소에서 함께 관리한다.
• 빌드 결과물을 사람이 내려받기 전에 자동으로 생성·검수하는 절차를 둔다.
• 최종 파일명에 버전, 날짜, 제품명을 넣는 규칙을 고정한다.

Pandoc는 문서 작성 습관을 대신 고쳐주지 않습니다. 하지만 입력 규칙과 빌드 흐름을 잡아두면 매번 사람이 서식을 맞추는 시간을 크게 줄일 수 있습니다. 특히 개발 문서, 정책 문서, 고객 전달 자료가 계속 바뀌는 조직이라면 작은 자동화부터 시작해볼 만합니다.

7. 자주 묻는 질문

Q1. Pandoc는 개발자만 써야 하나요?

개발자가 세팅하면 가장 편하지만, 실제 사용자는 기획자나 운영자여도 됩니다. 작성 규칙과 실행 명령을 단순하게 만들어두면 비개발자도 Markdown만 수정하고 결과물은 자동으로 받을 수 있습니다.

Q2. PDF 변환이 자꾸 깨지면 어디부터 봐야 하나요?

먼저 PDF 엔진과 한글 폰트부터 확인하는 것이 좋습니다. 그다음 표 너비, 긴 코드 줄, 이미지 경로, 특수문자 순서로 점검하면 원인을 찾기 쉽습니다.

Q3. Notion이나 Google Docs를 쓰면 Pandoc가 필요 없나요?

공동 편집만 필요하면 기존 협업 도구가 더 편할 수 있습니다. 하지만 같은 문서를 여러 형식으로 반복 배포하고, 변경 이력과 자동 빌드를 중요하게 본다면 Pandoc 방식이 더 안정적입니다.

Q4. 처음 도입할 때 가장 작은 시작점은 무엇인가요?

README 하나를 PDF와 HTML로 동시에 만드는 것부터 시작하면 됩니다. 그 과정에서 폰트, 이미지, 코드 블록, 파일명 규칙을 정리한 뒤 팀 문서 전체로 넓히는 편이 안전합니다.