마크다운을 PDF로 변환

어떤 마크다운이, 무엇이 되는가

마크다운은 하나의 명세가 아니라 한 가족입니다. 제목, 강조, 목록, 링크, 이미지, 인용 블록, 코드 블록 같은 공통 핵심은 어디서나 같지만, 그 밖은 구현마다 다릅니다. 여기서는 널리 합의된 확장 세트를 지원합니다. 표, 구문 강조가 적용되는 펜스 코드 블록, 작업 목록, 취소선, 각주, 프런트 매터입니다. 거의 모든 사람이 쓰는 범위를 포괄하며, 그 경계는 부딪혀서 알게 되기보다 미리 알아 두는 편이 좋습니다.

제목은 단지 큰 글씨가 아니라 실제 PDF 구조가 됩니다. 개요 수준을 가지므로 PDF에 탐색할 수 있는 책갈피 사이드바가 생깁니다. 링크는 작동하는 링크 주석이 됩니다. 코드 블록은 하이라이트와 함께 고정폭 글꼴로 조판되는데, 읽기 편한 문서와 회색 글자 벽의 차이가 바로 여기서 납니다. 마크다운 파일에는 종이에 대한 정보가 없으므로, 페이지 크기와 여백은 물려받지 않고 읽기 좋게 정해집니다.

이미지는 접근할 수 있어야 하며, 가장 흔히 실망하는 부분이 여기입니다. 마크다운 파일은 그림을 담지 않고 참조만 하므로, 상대 경로는 이미지를 파일과 함께 끌어다 놓아야만 찾을 수 있고, 웹 주소는 그 서버가 다른 사이트의 가져오기를 허용해야만 찾을 수 있습니다. 찾을 수 없는 그림은 조용히 빈 자리로 두지 않고 PDF에 표시되므로, 빠진 도표를 문서를 보낸 뒤가 아니라 바로 알아챌 수 있습니다.

두 가지는 일부러 렌더링하지 않고 코드로 보여 드립니다. LaTeX 표기법의 수식과 Mermaid 다이어그램은 각각 전용 렌더러가 필요하며, 잘못 렌더링하는 것은 원본을 보여 주는 것보다 나쁩니다. 잘못 렌더링된 수식은 아무도 알아챌 수 없는 방식으로 틀리기 때문입니다. 마크다운 안의 HTML은 간단한 인라인 서식에만 적용되고 레이아웃에는 적용되지 않습니다. 페이지로 나뉘는 문서에 임의의 마크업 블록이 들어갈 자리는 없기 때문입니다.

다른 작업이 필요할 때

이 작업을 위한 본격적인 도구는 Pandoc이며 무료입니다. pandoc doc.md -o doc.pdf --pdf-engine=xelatex는 LaTeX로 조판해 제대로 된 하이픈 처리, 외톨이 줄 제어, 진짜 목차를 갖춘 정말 아름다운 결과물을 만들고, 템플릿을 쓰면 디자인의 모든 부분을 제어할 수 있습니다. 여기서 부족한 바로 그 부분인 LaTeX 수식도 올바르게 렌더링합니다. 대가는 TeX 배포판을 설치해야 한다는 것인데, 용량이 작지 않습니다.

일회성 문서가 아니라 기술 문서라면 정적 사이트 생성기나 mdBook이 PDF보다 나은 결과물을 만듭니다. 검색할 수 있고, 링크를 걸 수 있고, 휴대폰에서도 읽을 수 있습니다. 문서를 인쇄하거나 첨부하거나 보관해야 할 때 PDF로 변환하세요. 그리고 어느 쪽이든 마크다운을 원본으로 유지하세요. 편집하고 비교(diff)할 수 있는 것은 그 버전이기 때문입니다.