Pandoc Templates — 문서 변환의 끝판왕을 제대로 길들이는 법

Pandoc, 이름은 들어봤는데 잘 모르겠다면

개발자라면 한 번쯤 "마크다운으로 쓴 문서를 PDF로 깔끔하게 뽑고 싶다" 또는 "이 워드 파일을 마크다운으로 바꾸고 싶다" 같은 욕구를 느껴봤을 거예요. 이런 일을 거의 모든 포맷 사이에서 해주는 도구가 Pandoc이에요. 마크다운, HTML, LaTeX, DOCX, EPUB, PDF, reStructuredText… 정말 다 됩니다. 학계에서는 논문 쓰는 표준 도구로 자리 잡았고, 기술 블로그나 책 쓰는 분들도 많이 써요.

그런데 Pandoc의 진짜 힘은 단순 변환이 아니라 "템플릿" 시스템에 있어요. 최근 공개된 pandoc-templates.org는 이 템플릿들을 한곳에 모아놓은 카탈로그 같은 사이트예요. 이력서, 논문, 슬라이드, 책, 보고서까지 "바로 가져다 쓸 수 있는 디자인 템플릿"을 종류별로 모아뒀어요.

템플릿이 뭐냐면

쉽게 말해서 "틀"이에요. 여러분이 마크다운으로 내용만 쭉 적어놓으면, 템플릿이 "이건 이렇게 생긴 PDF로, 이 글씨체로, 이 여백으로, 이 색상으로 만들어 줄게" 하고 받아주는 거예요. 워드의 "스타일"이나 웹의 CSS와 비슷한 개념인데, 출력 포맷에 따라 다른 언어로 작성돼요.

예를 들어 PDF로 뽑으려면 LaTeX 템플릿이 필요해요. LaTeX는 학술 문서 조판에 쓰이는 언어인데, 처음 보면 코드처럼 생겨서 무섭게 느껴지지만 한 번 잘 만든 템플릿을 가져다 쓰면 그 다음부터는 마크다운만 쓰면 돼요. HTML 출력은 HTML/CSS 템플릿이 필요하고, DOCX 출력은 워드 스타일 파일이 필요해요.

pandoc-templates.org가 의미 있는 이유는, 이 "진입 장벽"을 확 낮춰준다는 점이에요. 예전엔 Pandoc 템플릿을 만들려면 LaTeX 한 권 분량을 공부해야 했거든요. 이젠 그냥 마음에 드는 디자인 골라서 다운받고, 자기 내용만 갈아끼우면 돼요.

실무에서 이렇게 활용해요

가장 흔한 시나리오는 문서 자동화예요. 예를 들어 매주 보고서를 써야 한다고 생각해보세요. 마크다운 파일에 내용만 채우고, pandoc report.md -o report.pdf --template=company.tex 한 줄이면 회사 로고와 폰트가 박힌 PDF가 나와요. 매번 워드에서 표 정렬하느라 30분씩 날리는 일이 사라지는 거예요.

두 번째는 CI/CD에 문서 빌드 끼우기예요. GitHub Actions에 Pandoc 실행 단계를 추가하면, 마크다운으로 쓴 README나 문서가 푸시될 때마다 자동으로 PDF, HTML, EPUB이 빌드되는 파이프라인이 만들어져요. 오픈소스 라이브러리 문서나 사내 위키에 적용하면 효과가 좋아요.

세 번째는 이력서 관리예요. 이게 의외로 인기 있는 활용법인데, 이력서를 마크다운 한 파일로 관리하면 git으로 버전 관리도 되고, 한 번 잘 만들어둔 LaTeX 템플릿으로 항상 깔끔한 PDF를 뽑을 수 있어요. 채용 사이트마다 요구하는 포맷이 달라도 템플릿만 바꿔서 대응할 수 있고요.

비슷한 도구들과 비교해보면

요즘은 Typst라는 새로운 조판 시스템이 LaTeX의 대안으로 떠오르고 있어요. 문법이 훨씬 쉽고 컴파일 속도도 빨라서 "LaTeX 너무 어려워" 하던 사람들이 옮겨가는 중이에요. 하지만 Typst는 아직 생태계가 작고, Pandoc처럼 "수십 가지 포맷 사이를 자유롭게 오가는" 능력은 없어요.

Marp나 Marpit은 마크다운으로 슬라이드를 만드는 도구인데, Pandoc + Beamer 조합과 자주 비교돼요. Marp가 더 가볍고 직관적이라면, Pandoc은 "한 번 익히면 슬라이드, 논문, 책을 다 한 도구로 해결"하는 통합성이 강점이에요.

웹 기반으로는 Quarto라는 도구도 인기예요. R과 Python 진영에서 데이터 분석 보고서 만드는 데 많이 써요. 사실 Quarto 내부도 Pandoc을 엔진으로 쓰고 있어서, "Pandoc을 더 쓰기 편하게 포장한 도구"라고 봐도 돼요.

한국 개발자 입장에서 보면

한국어 처리에서 한 가지 주의할 점이 있어요. LaTeX로 PDF를 뽑을 때 기본 폰트가 한글을 지원 안 해서 글자가 깨질 수 있거든요. 이걸 해결하려면 XeLaTeX이나 LuaLaTeX 엔진을 쓰고, mainfont에 "Noto Sans KD" 같은 한글 폰트를 지정해줘야 해요. pandoc-templates.org에 있는 템플릿들도 한글 적용하려면 이 설정을 추가해야 하는 경우가 많아요.

그리고 사내 기술 블로그나 위키를 운영한다면, Pandoc을 미들웨어처럼 활용하는 걸 추천해요. 작성자는 마크다운으로만 쓰고, 시스템이 알아서 사내 디자인이 적용된 결과물로 변환하게 만들면, 글 쓰는 사람의 부담이 확 줄어들어요. 결과적으로 문서 작성 빈도도 올라가고요.

마무리

한 줄로 정리하면, Pandoc은 "내용"과 "디자인"을 깨끗하게 분리해주는 도구고, pandoc-templates.org는 그중에서도 진입 장벽이 높았던 "디자인" 부분을 손에 잡히는 형태로 제공해줘요. 문서 작업에 시간을 자주 빼앗긴다면 한 번쯤 진지하게 도입해볼 가치가 있어요.

여러분은 문서 작성에 어떤 도구를 쓰세요? 노션이나 컨플루언스로 충분하다고 느끼시나요, 아니면 "내 손에서 출력물까지 통제하고 싶다"는 욕구가 있으세요? 댓글로 워크플로우 공유 부탁드려요.