마크다운은 글쓰기에 훌륭하지만, 문서를 받는 사람은 웹 페이지나 PDF를 기대하는 경우가 많습니다. 다행히 마크다운 변환은 쉽고, 대부분은 복잡한 도구 체인도 필요 없습니다.
아래에서 가장 빠른 방법부터 가장 세밀하게 설정할 수 있는 방법까지 네 가지를 소개하고, 결과물을 전문적으로 보이게 하는 팁도 정리합니다.
한눈에 비교
| 방법 | HTML | 설치 | 추천 용도 | |
|---|---|---|---|---|
| 브라우저 에디터에서 내보내기 | ✅ | ✅ (인쇄) | 없음 | 일상 문서, 빠른 공유 |
| VS Code + 확장 프로그램 | ✅ | ✅ | 에디터 + 확장 프로그램 | 이미 VS Code로 글을 쓰는 사람 |
| Pandoc | ✅ | ✅ | Pandoc (+ PDF 엔진) | 책, 논문, 자동화 파이프라인 |
| 스크립트 (markdown-it, marked) | ✅ | — | Node.js | 맞춤 웹사이트와 빌드 과정 |
1. 브라우저 기반 에디터에서 내보내기
가장 빠른 방법은 바로 내보낼 수 있는 에디터를 쓰는 것입니다. Markdown Preview Editor의 온라인 버전이나 직접 호스팅한 사본에서 문서를 열거나 붙여 넣은 뒤, 상단의 버튼을 사용하세요.
- HTML은 독립 실행형
.html파일 하나를 만듭니다. 스타일, 코드 강조, 수식, 다이어그램, 그리고 문서와 함께 연 이미지가 포함되므로 어느 컴퓨터에서나 제대로 보이며, 그대로 이메일에 첨부하거나 어디에든 올릴 수 있습니다. - 인쇄는 브라우저의 인쇄 대화 상자를 엽니다. 대상을 PDF로 저장으로 선택하면 PDF가 만들어집니다. 도구 모음이나 편집기 없이 렌더링된 문서만 인쇄됩니다.
- 저장은 마크다운 원문을
.md파일로 다운로드합니다.
모든 작업이 브라우저에서 이뤄지므로, 온라인 변환기에 올리고 싶지 않은 문서에도 쓸 수 있습니다.
인쇄 대화 상자로 깔끔한 PDF 만들기
- 한 페이지에 담을 텍스트 양에 따라 여백을 기본 또는 최소로 설정하세요.
- 머리글과 바닥글을 끄면 페이지 가장자리의 날짜와 URL이 사라집니다.
- 코드 블록 배경과 표의 줄무늬를 원한다면 배경 그래픽을 켜세요.
- 인쇄할 때는 밝은 테마를 쓰세요. 잉크를 아끼고 종이에서 읽기도 더 편합니다.
2. VS Code와 확장 프로그램
VS Code에는 마크다운 미리 보기가 내장되어 있지만 내보내기 버튼은 없습니다. Markdown PDF나 Markdown Preview Enhanced 같은 확장 프로그램이 HTML과 PDF 내보내기 명령을 추가해 줍니다. 이미 VS Code를 쓰고 있다면 편리합니다. 결과물 스타일은 확장 프로그램에 따라 다르며, 일부는 처음 사용할 때 헤드리스 브라우저를 다운로드합니다.
3. Pandoc — 만능 변환기
Pandoc은 수십 가지 형식을 서로 변환하며, 책, 학술 논문, 자동화된 문서화의 표준 도구입니다. 설치하고 나면 명령 한 줄로 변환할 수 있습니다.
bash# 마크다운을 완전한 HTML 페이지로
pandoc report.md -o report.html --standalone --metadata title="Report"
# 마크다운을 PDF로 (PDF 엔진 필요, 예: LaTeX 배포판)
pandoc report.md -o report.pdf --pdf-engine=xelatex
# 누군가 꼭 원한다면 마크다운을 Word로
pandoc report.md -o report.docx
--standalone을 빼면 Pandoc은 HTML 조각만 출력합니다. 기존 페이지에 넣을 때 편리합니다. PDF 출력에는 별도의 엔진이 필요합니다. LaTeX 배포판이나 WeasyPrint 같은 HTML 기반 엔진이 그 예입니다. Pandoc의 강점은 세밀한 제어입니다. 템플릿, 인용, 섹션 번호, 상호 참조까지 다룰 수 있습니다.
4. 몇 줄의 JavaScript
마크다운이 내 웹사이트나 빌드 과정의 일부라면 라이브러리가 가장 유연한 선택입니다. markdown-it을 쓰면 이렇습니다.
jsimport MarkdownIt from 'markdown-it';
import { readFileSync, writeFileSync } from 'node:fs';
const md = new MarkdownIt({ linkify: true, typographer: true });
const body = md.render(readFileSync('README.md', 'utf8'));
writeFileSync('README.html', `<!doctype html><meta charset="utf-8"><title>README</title>${body}`);
플러그인으로 각주, 할 일 목록, 수식 등을 추가할 수 있습니다. 출력은 입력만큼만 안전하다는 점을 기억하세요. 다른 사람이 쓴 마크다운이라면 게시하기 전에 HTML을 정제하세요(예: DOMPurify 사용).
더 나은 HTML·PDF 결과물을 위한 팁
명확한 제목 하나로 시작하기
변환기는 파일 이름, 첫 번째 제목 또는 명시적인 메타데이터에서 문서 제목을 가져옵니다. 문서마다 알아보기 쉬운 파일 이름과 # 제목 하나를 붙여 두면, 내보낸 HTML과 PDF를 다운로드 폴더나 브라우저 탭에서 쉽게 찾을 수 있습니다.
이미지는 문서 옆에 두기
images/chart.png 같은 상대 경로를 쓰고 파일을 같은 폴더에 두세요. Markdown Preview Editor에서 폴더 전체를 열면 이미지 경로가 해석되어 HTML 내보내기에 포함됩니다. 미리 보기에서 불러오지 않은 원격 이미지는 포함되지 않습니다.
페이지 나눔 조절하기
마크다운에는 페이지 나눔 문법이 없습니다. 인쇄용 문서라면 큰 섹션을 ## 제목으로 시작하고 표를 짧게 유지하세요. 브라우저는 표의 행이 나뉘지 않게 하지만, 아주 큰 표는 결국 다음 페이지로 넘어갑니다. Pandoc처럼 원시 HTML과 인라인 스타일을 허용하는 도구에서는 <div style="page-break-after: always"></div>를 넣을 수 있습니다.
내보내기 전에 수식과 다이어그램 확인하기
대부분의 도구에서 수식과 다이어그램은 JavaScript 라이브러리로 렌더링됩니다. 먼저 미리 보기에서 확인하세요. 마크다운 수식과 Mermaid 다이어그램 가이드도 참고하세요. Markdown Preview Editor의 HTML 내보내기에서는 이들이 완성된 마크업과 이미지로 저장되므로, 내보낸 파일에 스크립트가 필요 없습니다.
테마는 의도적으로 고르기
어두운 테마의 HTML은 화면에서는 보기 좋지만 종이에는 맞지 않습니다. 독자가 사용할 매체에 맞춰 내보내세요.
자주 묻는 질문
마크다운을 무료로 PDF로 변환하려면 어떻게 하나요?
Markdown Preview Editor 같은 마크다운 뷰어에서 문서를 열고 인쇄를 누른 뒤, 인쇄 대화 상자에서 PDF로 저장을 선택하세요. 자동화나 책 형태의 결과물이 필요하다면 무료 명령줄 도구인 Pandoc을 쓰세요.
아무것도 설치하지 않고 마크다운을 HTML로 변환하려면 어떻게 하나요?
HTML 내보내기를 지원하는 브라우저 기반 에디터를 쓰세요. Markdown Preview Editor는 스타일이 포함된 독립 실행형 HTML 파일을 브라우저에서 바로 만들어 줍니다.
내보낸 HTML에 이미지도 포함되나요?
문서와 함께 연 로컬 이미지는 HTML 파일에 포함되므로 파일 하나로 작동합니다. 원격 서버에 있는 이미지는 포함되지 않습니다.
마크다운을 Word(DOCX)로 변환할 수 있나요?
네, Pandoc으로 가능합니다: pandoc input.md -o output.docx. 또는 HTML로 내보낸 뒤 Word에서 열면 서식이 대부분 유지됩니다.