마크다운 변환 사용법 가이드

이 도구는 마크다운을 실시간 미리보기로 그린 뒤, 그 화면을 그대로 캡처해 PDF로 내보냅니다. 이 가이드에서는 사용 순서와 지원 문법뿐 아니라, PDF가 왜 이미지로 만들어지는지·페이지가 어디서 어떻게 나뉘는지·Mermaid와 수식 렌더링이 어디까지 지원되는지를 구현 기준으로 설명합니다.

사용 목적

이 도구는 README, 팀 기획 문서, 회의록처럼 마크다운으로 작성한 글을 다른 사람에게 공유하거나 인쇄해야 할 때 사용합니다. 개발자가 아닌 동료에게 넘길 핸드오프 문서를 PDF로 만들어, 마크다운 렌더러가 없는 환경에서도 작성한 그대로의 모습으로 보이게 하는 것이 목적입니다.

사용 순서

왼쪽 입력창에 마크다운을 붙여넣거나 작성합니다.
오른쪽 미리보기에서 렌더 결과를 확인합니다.
상단 툴바의 다운로드 버튼으로 PDF를 내보냅니다.

지원 문법

제목, 순서/무순서 목록, 체크박스
굵게·기울임·인라인 코드·링크 등 인라인 서식
인용문(blockquote), 표
Mermaid 다이어그램 — 보안 수준을 strict로 고정해 렌더하며, 문법 오류가 있는 다이어그램만 오류 표시로 대체되고 나머지 문서는 정상 변환됩니다(아래 “Mermaid·수식 렌더링 한계” 참고).
LaTeX 수식 — 인라인 $...$·$...$, 블록 $$...$$·\[...\](미리보기·PDF 모두 지원). MathJax(v3, KaTeX 아님) 기반이며, 기본 패키지 6종만 등록되어 있어 mhchem·physics 등 확장 패키지 명령은 지원되지 않습니다(자세한 범위는 아래 참고).

PDF 페이지가 이미지로 만들어지는 이유

PDF의 각 페이지는 브라우저가 그린 화면을 캡처한 이미지 한 장입니다. 이 도구는 jsPDF의 자체 HTML 레이아웃 엔진(doc.html())을 쓰지 않습니다 — 커닝 붕괴, 인라인 이미지 배치, 박스 정렬이 깨지는 문제 때문에 폐기됐고, 대신 미리보기와 같은 스타일(CSS)로 화면 밖에 다시 렌더한 마크업을 캡처해 페이지 이미지로 싣는 방식을 씁니다. 실제로 호출되는 jsPDF API도 새 문서 생성·페이지 추가·이미지 삽입·출력 뿐이고, 텍스트를 직접 그려 넣는 API(doc.text())는 쓰이지 않습니다. 그래서 각 페이지가 이미지로만 추가되어, 선택·검색 가능한 텍스트 레이어가 없습니다.

캡처용 컨테이너는 화면 밖(위치 고정, 폭 794px, 안쪽 여백 24px, 배경 흰색)에 렌더됩니다. PDF가 화면 테마와 무관하게 항상 라이트 테마로 고정되는 것도 이 캡처 방식 때문입니다 — SVG의 foreignObject 안에서는 페이지의 CSS 변수나 폰트가 적용되지 않으므로, 라이트 테마 색상 값과 시스템 폰트를 캡처 컨테이너에 직접 값으로 넣어 둡니다. 페이지 나눔 계산에 쓰이는 실측(DOM 높이 측정)과 실제 캡처가 같은 폰트·색상 값을 쓰는 것도, 두 렌더의 줄바꿈이 어긋나지 않게 하기 위해서입니다.

컨테이너 전체 DOM은 한 번만 SVG로 직렬화해 이미지 하나로 불러온 뒤, 페이지마다 그 이미지에서 필요한 구간만 잘라(source-rect 슬라이스) 개별 캔버스에 그립니다. 문서 전체 높이만큼 큰 캔버스를 새로 만들지 않기 때문에, 브라우저 캔버스 크기 한계(Chrome·Firefox는 약 32,767px, iOS는 약 4,096px로 알려져 있습니다)에 부딪히지 않고 긴 문서도 페이지 단위로 안정적으로 캡처됩니다. 각 페이지 캔버스는 2배 해상도로 그려진 뒤 JPEG(품질 0.92)로 인코딩되어 PDF에 삽입됩니다.

이 때문에 완성된 PDF에서는 뷰어의 찾기 기능으로 본문을 검색하거나 드래그해 선택·복사할 수 없고, 스크린리더가 읽는 접근성 태그 구조도 없습니다. 텍스트를 검색·복사·편집해야 한다면 변환 결과 대신 마크다운 원문(.md)을 함께 전달하세요. 다만 Mermaid 다이어그램과 LaTeX 수식은 다른 이미지 형식으로 다시 변환하는 과정 없이 원래 그려진 SVG 그대로 이 페이지 캡처 안에 담깁니다.

페이지는 어디서, 어떻게 나뉘나요

한 페이지에 실제로 담기는 높이(usable height)는 A4 인쇄 가능 영역의 98%입니다. 나머지 2%는 계획 단계(px 계산)와 실측 단계(브라우저가 실제로 그린 좌표) 사이의 반올림 오차를 흡수하는 여유값입니다.

제목(헤딩) 바로 아래에서 페이지가 넘어가는 경우가 있는데, 이는 의도된 동작입니다. 헤딩 높이에 최소 45px(약 2줄 분량의 본문)를 더한 값이 남은 공간보다 크면 헤딩을 통째로 다음 페이지로 넘겨서, “제목만 페이지 맨 아래 혼자 남고 본문 시작 부분은 다음 페이지로 넘어가는” 상황(고아 헤딩)을 막습니다.

한 페이지를 넘는 표와 코드 블록은 각각 행·줄 단위로 나뉩니다. 표를 나눈 경우 분할된 조각마다 원래 헤더 행이 그대로 복제되어 반복되므로, 페이지를 넘겨도 어떤 열인지 다시 확인할 필요가 없습니다. 다만 어떤 경우든 행·줄 하나를 중간에서 자르지는 않습니다 — 한 행(또는 한 줄)이 페이지보다 커도 그 자리에서 강제로 배치될 뿐 잘리지 않습니다.

한 페이지를 넘는 이미지는 페이지 높이에 맞게 축소되고, 축소된 이미지가 페이지를 가득 채운 것으로 간주해 다음 내용은 새 페이지에서 시작합니다. 표·코드가 아닌 그 외 거대한 블록(긴 문단 등)은 줄 단위로 여러 페이지에 걸쳐 흘러가되 중간에서 잘리지 않습니다.

Mermaid·수식 렌더링 한계

Mermaid는 보안 수준을 strict로 고정하고(텍스트 안 태그를 인코딩하고 클릭 기능을 비활성화), 라벨을 HTML이 아니라 순수 SVG 텍스트로 그립니다 — foreignObject로 HTML 라벨을 그리면 캡처 캔버스가 오염되거나 태그가 제대로 닫히지 않는 문제가 있기 때문입니다. 다이어그램은 블록마다 따로 렌더링을 시도하므로, 한 다이어그램에 문법 오류가 있어도 나머지 문서 변환에는 영향이 없습니다 — 오류가 난 자리에는 오류 메시지와 원본 코드가 그대로 표시되고, 코드를 고치면 다시 렌더링을 시도합니다.

수식은 MathJax(v3)로 렌더됩니다. KaTeX가 아닙니다. TeX 소스를 SVG로 그리는 방식이라 미리보기와 PDF 캡처 경로에서 동일하게 동작합니다. 다만 MathJax의 전체 패키지 세트가 아니라 실용적인 기본 6종 (base, ams, newcommand, noundefined, textmacros, noerrors)만 등록되어 있어, mhchem(화학식)· physics·bussproofs 같은 확장 패키지의 명령은 지원되지 않습니다.

지원되지 않는 명령이나 잘못된 LaTeX 문법을 만나도 변환이 멈추지는 않습니다. 미등록 명령은 빨간 “미정의” 표시로, 문법 오류는 빨간 글씨·연한 핑크 배경의 오류 표시로 렌더되며, 오류 표시 안에는 일반적인 오류 메시지 대신 원본 수식 소스가 그대로 보여 무엇이 잘못됐는지 바로 확인할 수 있습니다.

옵션 선택 기준

PDF는 인쇄나 고정된 레이아웃 공유(외부 발표 자료, 계약 문서 등)에 적합합니다. 브라우저가 그린 화면을 그대로 캡처하므로 뷰어 프로그램과 무관하게 항상 같은 모양으로 보입니다.
편집 가능한 사본이 필요하다면 변환 결과 대신 마크다운 원문(.md)을 함께 전달하는 것이 안전합니다. PDF는 텍스트를 그리는 API 없이 이미지로만 만들어져 선택·검색 가능한 텍스트 레이어가 없고, 그 안에서 직접 고칠 수도 없기 때문입니다.
미리보기는 최종 출력 전에 렌더링 결과(표, 다이어그램, 수식 포함)를 확인하는 용도이므로, 내보내기 전에 반드시 확인하는 것이 좋습니다. 미리보기는 브라우저에 실시간으로 그린 DOM이고 PDF는 같은 마크업을 화면 밖에서 다시 렌더해 캡처한 이미지인데, 둘 다 같은 스타일(CSS)을 공유하므로 미리보기에서 확인한 모습이 PDF에도 거의 그대로 이어집니다.

실패·주의 케이스

문서가 매우 길면(수십 페이지 분량) 미리보기 렌더링과 PDF 생성에 시간이 더 걸릴 수 있으니, 분량이 큰 문서는 섹션 단위로 나눠 작업하는 것을 권장합니다.
코드 블록 한 줄이 너무 길면 PDF 페이지 폭을 넘어갈 수 있습니다. 긴 코드는 줄바꿈하거나 핵심 부분만 포함해야 읽기 좋습니다.
정리하면 이 도구가 포기하는 것은 세 가지입니다 — PDF의 텍스트 검색·선택·복사(래스터 캡처 방식), MathJax 확장 패키지 명령(mhchem·physics 등 미지원), Mermaid의 HTML 라벨·클릭 기능(strict 보안 수준). 대신 얻는 것은 브라우저가 그린 모습 그대로의 레이아웃입니다.

예시 시나리오

Mermaid가 포함된 README → PDF 핸드오프: 마크다운을 작성하고 미리보기에서 다이어그램을 확인한 뒤 PDF로 내보내면, 같은 다이어그램이 SVG로 캡처되어 외부 파트너에게 고정된 형태로 전달할 수 있습니다.
표가 많은 회의록 → 인쇄 배포: 회의록을 마크다운으로 정리해 PDF로 내보내면, 표가 페이지 경계를 넘어가도 헤더 행이 자동으로 반복되므로 참석자에게 종이 문서나 고정된 파일 형태로 배포할 수 있습니다.

팁

미리보기와 PDF는 같은 스타일(CSS)을 공유하므로 출력 모습이 미리보기와 거의 같습니다 — 다만 같은 CSS를 써도 픽셀 단위까지 동일하다고 보장되지는 않습니다. 미리보기는 실시간 DOM 렌더, PDF는 같은 마크업을 화면 밖에서 다시 렌더해 캡처한 이미지입니다.
PDF가 텍스트가 아니라 이미지라서 한글 글리프가 픽셀로 구워져 저장되므로, 문서를 여는 쪽에 한글 폰트가 설치돼 있지 않아도 글자가 깨지지 않습니다.
표나 코드 블록이 페이지 경계 근처에서 애매하게 걸린다면, 문단을 나누거나 표를 분할해 명시적으로 페이지를 넘기는 편이 자동 분할보다 보기 좋을 수 있습니다.

자주 묻는 질문

Q. PDF에서 텍스트 검색이나 드래그 선택이 안 돼요.
PDF의 각 페이지는 브라우저 화면을 캡처한 이미지로만 추가되고 텍스트를 그리는 API(doc.text())를 쓰지 않으므로, 선택·검색 가능한 텍스트 레이어가 없기 때문입니다. 검색·선택·복사가 필요하다면 변환 결과 대신 마크다운 원문(.md)을 함께 전달하세요.

Q. 표가 페이지 경계에서 이상하게 잘려요.
한 페이지를 넘는 표는 행 단위로 나뉘고, 분할된 조각마다 원래 헤더 행이 그대로 복제되어 반복됩니다. 다만 한 행 자체가 페이지보다 커도 그 행 중간에서 잘리지는 않고 통째로 배치됩니다.

Q. 제목 바로 아래에서 페이지가 갑자기 넘어가요.
의도된 동작입니다. 헤딩 높이에 최소 45px(약 2줄 분량의 본문)를 더한 값이 남은 공간보다 크면 헤딩을 통째로 다음 페이지로 넘겨, 제목만 페이지 아래에 혼자 남는 상황(고아 헤딩)을 막습니다.

Q. Mermaid 다이어그램이 안 그려져요.
다이어그램마다 따로 렌더링을 시도하므로, 문법 오류가 있는 다이어그램 자리에만 오류 메시지와 원본 코드가 표시되고 나머지 문서는 정상적으로 변환됩니다. 코드를 수정하면 자동으로 다시 렌더링됩니다.

Q. 화학식(mhchem)이나 물리 표기(physics) 명령이 안 먹혀요.
이 도구는 MathJax(v3, KaTeX 아님)의 기본 패키지 6종(base, ams, newcommand, noundefined, textmacros, noerrors)만 등록하고 있어, mhchem·physics·bussproofs 같은 확장 패키지 명령은 지원되지 않습니다. 지원되지 않는 명령을 만나도 문서 변환은 멈추지 않고 빨간 "미정의" 표시로 렌더됩니다.

Q. 잘못된 수식을 넣으면 어떻게 표시되나요?
오류로 변환이 멈추지 않고, 빨간 글씨·연한 핑크 배경의 오류 표시로 렌더됩니다. 이 표시 안에는 일반적인 오류 메시지 대신 원본 수식 소스가 그대로 보여 무엇이 잘못됐는지 바로 확인할 수 있습니다.

Q. 파일이 서버로 전송되나요?
아니요. 마크다운 읽기, 미리보기 렌더링, PDF 생성까지 모두 브라우저 안에서 처리되며 외부 서버로 전송되지 않습니다.

Q. 워드(DOCX)로도 내보낼 수 있나요?
현재는 PDF 내보내기만 제공합니다. 받는 사람이 내용을 편집해야 한다면 마크다운 원문(.md)을 함께 전달하는 방식을 권장합니다.