Markdown을 출판용 포맷으로 변환하기

Markdown은 개발자, 작가, 오픈소스 커뮤니티 사이에서 공통 언어가 되었습니다. 순수 텍스트 문법은 쓰기 쉽고, 버전 관리가 가능하며, 다양한 플랫폼에서 렌더링할 수 있습니다. 하지만 대부분의 독자는 깔끔한 PDF, 반응형 HTML 페이지 또는 EPUB 전자책을 기대합니다. 머리글, 표, 코드 블록, 메타데이터 등을 잃지 않으면서 Markdown을 이러한 하위 포맷으로 변환하는 일은 생각보다 까다로울 수 있습니다. 이 가이드에서는 정확성, 성능, 프라이버시를 균형 있게 맞춘 재현 가능한 워크플로우를 단계별로 살펴봅니다.

소스 자료 이해하기

변환 작업을 시작하기 전에 Markdown 파일을 완성된 문서가 아니라 원본 문서로 취급합니다. 특별히 다뤄야 할 요소들을 파악하세요.

Front‑matter 메타데이터(title, author, date, tags). 많은 정적 사이트 생성기에서는 --- 로 구분된 YAML 형태로 나타납니다. 커버 페이지나 내장 메타데이터가 필요할 수 있으므로 보존해야 합니다.
언어 식별자가 있는 코드 펜스. 기술 서적에서는 구문 강조가 변환 과정에서도 유지돼야 합니다.
표, 각주, 정의 목록. 모든 대상 포맷이 이를 기본적으로 지원하는 것은 아니므로 HTML <table> 혹은 PDF 표 구조로 매핑해야 할 수 있습니다.
상대 경로로 참조된 이미지 및 자산. 변환 파이프라인은 경로를 해결하고 필요에 따라 바이너리 데이터를 내장해야 합니다.
내부 링크(예: [Section](#section))와 문서 간 참조. 단일 PDF나 EPUB을 만들 때는 이들이 작동하는 북마크 또는 하이퍼링크가 되어야 합니다.

이러한 요소들을 초기에 카탈로그화하면 파이프라인 중에 발생할 수 있는 깜짝 놀라움을 피할 수 있습니다.

적절한 변환 엔진 선택하기

Markdown용 변환기는 크게 세 가지 종류가 있습니다.

Pandoc 기반 파이프라인 – Pandoc은 Markdown을 읽고 PDF, HTML, EPUB, DOCX 등 수많은 포맷으로 출력할 수 있는 범용 문서 변환기입니다. 인용, 각주, 사용자 정의 템플릿 처리에 강점이 있습니다.
정적 사이트 생성기(SSG) – Hugo, Jekyll, MkDocs 등은 테마 시스템을 이용해 Markdown을 HTML로 렌더링합니다. 전체 웹사이트가 필요할 때는 이상적이며, 헤드리스 인쇄 도구와도 결합할 수 있습니다.
웹 기반 서비스 – convertise.app 과 같은 플랫폼은 Markdown 파일을 받아 원하는 출력 형식을 반환하는 REST 엔드포인트를 제공합니다. 소프트웨어 설치 없이 일회성 변환에 유용합니다.

반복 가능하고 프라이버시를 최우선으로 하는 워크플로우라면 로컬 Pandoc 설치를 권장합니다. 사용자의 머신에서만 실행되므로 원격 서버에 흔적이 남지 않습니다.

환경 준비하기

Pandoc(최신 안정 버전)과 PDF를 만들 경우 LaTeX 배포판(예: TinyTeX)을 설치합니다.
가상 환경(Python venv 또는 Node nvm)을 설정해 보조 도구들을 격리합니다.
자산 수집 – 참조하는 이미지, PDF, 폰트 파일을 모두 하나의 폴더에 복사합니다. 이렇게 하면 변환기가 경로를 쉽게 해결할 수 있습니다.
메타데이터 파일 만들기 – Markdown에 Front‑matter가 없을 경우 metadata.yaml 파일을 작성해 title, author, date 등 원하는 필드를 넣습니다.

---
title: "Effective Open‑Source Documentation"
author: "Jane Doe"
date: "2026-05-10"
keywords: [markdown, documentation, publishing]
---

이 블록을 모든 소스 파일 앞에 붙이거나 --metadata-file 옵션으로 Pandoc에 넘겨 주세요.

PDF로 변환하기

Step 1: LaTeX 템플릿 선택

Pandoc은 PDF 출력을 위해 내부적으로 LaTeX을 사용합니다. 잘 만든 템플릿은 여백, 헤더/푸터 스타일, 폰트, 코드 블록 렌더링 등을 제어합니다. 공식 eisvogel 템플릿은 다음 이유로 인기가 많습니다.

listings 패키지를 이용한 구문 강조 코드 블록 지원
클릭 가능한 목차 생성
PDF의 XMP 패킷에 메타데이터 삽입(디지털 라이브러리 활용에 유리)

템플릿을 다운로드해 자산 폴더와 같은 위치에 두세요.

Step 2: 적절한 플래그로 Pandoc 실행

pandoc main.md \
  --metadata-file=metadata.yaml \
  --template=eisvogel.tex \
  --toc \
  --highlight-style=pygments \
  --pdf-engine=xelatex \
  -V mainfont="Libre Baskerville" \
  -V monofont="Fira Code" \
  -o output.pdf

주요 옵션 설명

--toc : 자동 목차 생성
-V mainfont, -V monofont : PDF가 원하는 시각적 아이덴티티를 유지하도록 지정
--highlight-style : 코드 펜스의 색상이 일관되게 적용됨

Step 3: 결과 확인

PDF를 열어 다음을 점검합니다.

모든 머리글이 목차에 포함되고 페이지 번호가 정확한가?
코드 블록이 가독성이 좋고 언어별 색상이 유지되는가?
이미지가 외부 링크가 아닌 내부에 삽입되어 비율에 맞게 표시되는가?
메타데이터(작성자, 제목 등)가 문서 속성에 나타나는가(파일 → 속성 → 설명).

누락된 요소가 있으면 템플릿을 수정하거나 Pandoc 필터(pandoc-citeproc 등)를 추가하세요.

HTML로 변환하기

HTML은 대부분의 Markdown 엔진이 기본적으로 내보내는 형식이지만, 출판용으로는 불필요한 클래스가 없는 깔끔한 마크업이 필요합니다.

Step 1: 최소 CSS 프레임워크 선택

가벼운 스타일시트인 Pure.css 혹은 직접 만든 style.css를 사용하면 페이지가 빠르게 로드되면서 표, 인용구, 코드에 대한 기본 스타일을 제공할 수 있습니다. CSS 파일은 생성된 HTML과 동일한 디렉터리에 두세요.

Step 2: Pandoc으로 HTML 생성

pandoc main.md \
  --metadata-file=metadata.yaml \
  --standalone \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o output.html

--standalone : 본문을 전체 HTML 문서 형태로 감쌈
--toc : 네비게이션 사이드바를 삽입하고, CSS로 고정 위치에 스타일링 가능

Step 3: 접근성 강화

<html> 태그에 lang="en"을 추가(언어 설정을 lang=en으로 하면 Pandoc이 자동 삽입)
모든 이미지에 alt 속성이 있는지 확인. Markdown에 누락되었다면 Pandoc 필터나 수동 편집으로 추가
머리글 수준이 계층 구조(h1 → h2 → h3)를 유지하는지 검증

Step 4: 브라우저 테스트

Chrome, Firefox, Edge에서 output.html을 열어 확인합니다.

좁은 뷰포트에서도 코드 블록이 스크롤 가능
목차가 부드럽게 접히는지
Chrome DevTools의 Lighthouse를 사용해 성능·접근성 점수 확인

EPUB(전자책)으로 변환하기

EPUB은 XHTML, CSS, 메타데이터를 묶은 ZIP 아카이브입니다. Pandoc은 복잡한 과정을 추상화해 깔끔한 패키지를 만들어 줍니다.

Step 1: EPUB 메타데이터 세부 조정

--epub-metadata 옵션을 이용해 ID, 출판사, 언어 정보를 삽입합니다. 간단한 epub-metadata.xml 파일을 만들고:

<?xml version="1.0" encoding="UTF-8"?>
<dc:metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:title>Effective Open‑Source Documentation</dc:title>
  <dc:creator>Jane Doe</dc:creator>
  <dc:language>en</dc:language>
  <dc:identifier id="bookid" opf:scheme="ISBN">978-3-16-148410-0</dc:identifier>
  <dc:publisher>Self‑Published</dc:publisher>
</dc:metadata>

Step 2: EPUB 옵션과 함께 Pandoc 실행

pandoc main.md \
  --metadata-file=metadata.yaml \
  --epub-metadata=epub-metadata.xml \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o book.epub

목차는 전자책 네비게이션 파일이 되고, CSS는 다양한 디바이스에서 일관된 스타일을 제공한다.

Step 3: EPUB 검증

오픈소스 검증기 epubcheck를 사용해 깨진 링크, 누락 이미지, 잘못된 XHTML 등을 검사합니다.

java -jar epubcheck.jar book.epub

문제가 발견되면 수정하고, Kindle Direct Publishing 등 플랫폼에 업로드하기 전에 반드시 통과시켜야 합니다.

자산 삽입 및 경로 해결

Markdown은 흔히 ![](images/logo.png) 형태로 이미지를 상대 경로로 참조합니다. 변환 시 특히 PDF와 EPUB에서는 외부 링크 대신 자산을 삽입해야 할 경우가 많습니다.

Pandoc의 --resource-path 옵션으로 자산 검색 경로를 지정합니다.
--extract-media=./media 플래그는 연결된 미디어를 media 폴더에 복사하고 마크업을 그곳을 가리키도록 바꿔 줍니다.
PDF를 만들 때 LaTeX 엔진에 외부 파일 포함을 허용하려면 --pdf-engine-opt=--shell-escape 옵션을 추가합니다.

단일 파일 HTML(예: self‑contained) 출력을 원한다면 pandoc --self-contained 혹은 wget --convert-links 같은 후처리 도구를 활용하세요.

포맷 간 코드 강조 일관성 유지

개발자 중심 문서에서는 구문 강조가 일관되어야 합니다.

Pandoc은 pygments, kate, tango 등 여러 강조 스타일을 지원합니다. PDF와 HTML 모두에서 보기 좋은 스타일을 선택하세요.
PDF에서는 Pandoc이 강조를 LaTeX listings 또는 minted로 변환합니다. minted를 쓰려면 --pdf-engine-opt=-shell-escape와 Python pygments 패키지가 필요합니다.
EPUB에서는 강조가 <span class="hlkwd"> 같은 인라인 CSS span으로 렌더링됩니다. 따라서 CSS 파일에 대응하는 스타일 규칙을 넣어야 합니다.

맞춤 색상표가 필요하면 pygmentize -S <style> -f html -a .code 로 스타일 파일을 만든 뒤 CSS에 포함시키면 됩니다.

Makefile로 워크플로우 자동화하기

각 포맷마다 동일한 명령줄을 반복하면 실수하기 쉽습니다. 간단한 Makefile을 두면 재현성이 확보됩니다.

SOURCES = main.md metadata.yaml
ASSETS  = $(wildcard images/*)

PDF    = output.pdf
HTML   = output.html
EPUB   = book.epub

all: $(PDF) $(HTML) $(EPUB)

$(PDF): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --template=eisvogel.tex \
	  --toc \
	  --highlight-style=pygments \
	  --pdf-engine=xelatex \
	  -V mainfont="Libre Baskerville" \
	  -V monofont="Fira Code" \
	  -o $@

$(HTML): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --standalone \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

$(EPUB): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --epub-metadata=epub-metadata.xml \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

clean:
	rm -f $(PDF) $(HTML) $(EPUB)

make 한 번만 실행하면 세 가지 출력물이 모두 생성되며, 각 포맷이 동일한 소스 파일을 기반한다는 것이 보장됩니다.

언제 cloud 서비스인 convertise.app을 사용할까?

로컬에 LaTeX 환경이 없거나 임시 머신에서 파일을 변환해야 하는 경우 온라인 변환기가 도움이 될 수 있습니다. 데이터가 메모리 내에서만 처리되고 장기 보관되지 않는다면 프라이버시를 어느 정도 유지할 수 있습니다. 일반적인 POST 요청 예시는 다음과 같습니다.

POST https://convertise.app/api/convert
Content-Type: multipart/form-data

--- 
Content-Disposition: form-data; name="file"; filename="main.md"
Content-Type: text/markdown

<Markdown content>
---
Content-Disposition: form-data; name="target"

pdf
---

응답으로 변환된 PDF가 바이너리 스트림 형태로 반환됩니다. 일회성 작업에는 유용하지만, 반복 가능한 출판 파이프라인에서는 로컬 Pandoc 솔루션이 투명성과 감审성을 가장 잘 보장합니다.

포맷 간 충실도 테스트

변환 후 자동화된 검증을 수행합니다.

체크섬 비교 – 소스 Markdown의 SHA‑256 해시를 생성해 출력 파일과 함께 보관합니다. 이를 통해 빌드 간 소스가 변하지 않았음을 증명할 수 있습니다.
링크 검증 – pandoc --filter pandoc-citeproc 로 모든 내부 참조가 해결되는지 확인합니다.
이미지 래스터화 테스트 – PDF와 EPUB을 각각 열어 이미지가 원하는 DPI(인쇄는 보통 300 dpi, 화면은 72 dpi)를 초과로 다운샘플링되지 않았는지 확인합니다.
접근성 감사 – PDF는 pdfaPilot, HTML은 axe‑core 같은 도구로 alt 텍스트 누락이나 머리글 순서 오류를 탐지합니다.
맞춤법 검사 – aspell·hunspell 등을 이용해 생성된 HTML 또는 pdftotext 로 추출한 PDF 텍스트를 검사해 필터가 만든 오타를 잡아냅니다.

이 검증 과정을 CI 파이프라인(GitHub Actions, GitLab CI 등)에 포함하면 커밋마다 검증된 출판용 자산이 자동으로 생성됩니다.

워크플로우 요약

Markdown 소스와 자산을 모은다. 없을 경우 Front‑matter를 추가.
변환 엔진 선택(전체 제어를 위해 Pandoc 권장).
각 타깃 포맷에 맞는 템플릿·CSS 구성.
변환 명령 실행 – PDF는 LaTeX, HTML은 최소 스타일시트, EPUB은 메타데이터 포함.
출력물 검증 – 체크섬, 링크 무결성, 접근성, 시각적 검사.
Makefile·CI로 자동화하여 과정을 반복 가능하게 유지.

이 레시피를 따르면 하나의 Markdown 소스로부터 개발자 가이드, 학술 핸드북, 전자책 등 어떤 형태의 출판물도 일관되게 만들 수 있습니다.

여기에 설명된 모든 기법은 convertise.app과 같은 프라이버시 중심 서비스와도 호환됩니다. 로컬 도구를 사용할 수 없을 때는 선택적인 온‑디맨드 변환 엔드포인트로 활용할 수 있습니다.

마크다운을 출판용 포맷으로 변환하기: 문서와 전자책을 위한 실용 가이드

Markdown을 출판용 포맷으로 변환하기

소스 자료 이해하기

적절한 변환 엔진 선택하기

환경 준비하기

PDF로 변환하기

Step 1: LaTeX 템플릿 선택

Step 2: 적절한 플래그로 Pandoc 실행

Step 3: 결과 확인

HTML로 변환하기

Step 1: 최소 CSS 프레임워크 선택

Step 2: Pandoc으로 HTML 생성

Step 3: 접근성 강화

Step 4: 브라우저 테스트

EPUB(전자책)으로 변환하기

Step 1: EPUB 메타데이터 세부 조정

Step 2: EPUB 옵션과 함께 Pandoc 실행

Step 3: EPUB 검증

자산 삽입 및 경로 해결

포맷 간 코드 강조 일관성 유지

Makefile로 워크플로우 자동화하기

언제 cloud 서비스인 convertise.app을 사용할까?

포맷 간 충실도 테스트

워크플로우 요약

파일 변환이 데이터 중복 제거를 촉진하고 저장 비용을 절감하는 방법

마크다운을 출판용 포맷으로 변환하기: 문서와 전자책을 위한 실용 가이드

Markdown을 출판용 포맷으로 변환하기

소스 자료 이해하기

적절한 변환 엔진 선택하기

환경 준비하기

PDF로 변환하기

Step 1: LaTeX 템플릿 선택

Step 2: 적절한 플래그로 Pandoc 실행

Step 3: 결과 확인

HTML로 변환하기

Step 1: 최소 CSS 프레임워크 선택

Step 2: Pandoc으로 HTML 생성

Step 3: 접근성 강화

Step 4: 브라우저 테스트

EPUB(전자책)으로 변환하기

Step 1: EPUB 메타데이터 세부 조정

Step 2: EPUB 옵션과 함께 Pandoc 실행

Step 3: EPUB 검증

자산 삽입 및 경로 해결

포맷 간 코드 강조 일관성 유지

Makefile로 워크플로우 자동화하기

언제 cloud 서비스인 convertise.app을 사용할까?

포맷 간 충실도 테스트

워크플로우 요약

파일 변환이 데이터 중복 제거를 촉진하고 저장 비용을 절감하는 방법

Step 1: LaTeX 템플릿 선택

Step 2: 적절한 플래그로 Pandoc 실행

Step 3: 결과 확인

Step 1: 최소 CSS 프레임워크 선택

Step 2: Pandoc으로 HTML 생성

Step 3: 접근성 강화

Step 4: 브라우저 테스트

Step 1: EPUB 메타데이터 세부 조정

Step 2: EPUB 옵션과 함께 Pandoc 실행

Step 3: EPUB 검증