md to pdf
1. 마크다운을 PDF로
자기소개서를 마크다운으로 작성한 뒤 PDF로 출력하면 페이지가 의도치 않게 잘리는 경험, 한 번쯤 해보셨을 겁니다. 노션에서 마크다운 문서를 작성하고 PDF로 변환할 때마다 속도는 느리고, 페이지 넘김 위치를 맞추려면 공백을 수동으로 삽입하면서 결과물을 반복 확인해야 했습니다. 작성과 동시에 PDF 레이아웃을 즉시 확인할 수 있는 도구가 있으면 좋겠다는 생각에서 이 도구를 만들었습니다.
이 도구는 표준 마크다운(GFM) 문법을 지원하며, 이미지 삽입·표·기본 문서 작성 등 실무에 필요한 핵심 기능에 집중해 구현했습니다. 참고로 노션은 표준 마크다운 위에 자체적인 확장 문법을 사용하기 때문에 노션 전용 문서를 그대로 붙여넣으면 일부 서식이 달라질 수 있습니다. 대신 표준 문법을 사용하는 온라인 에디터라면 어디서든 동일한 결과물을 바로 확인할 수 있습니다.
2. 도구 사용법 가이드
마크다운 미리보기를 통해 텍스트 문서를 구조화하고 실시간으로 시각화된 미리보기를 확인하는 과정은 매우 간단하고 효율적입니다.
a. 텍스트 입력 및 실시간 문서 미리보기
- 미리보기 화면 좌측의 텍스트 입력창에 마크다운 문법을 활용하여 글을 작성합니다. 굵게, 기울임체, 취소선, 밑줄 같은 기본 텍스트 서식은 물론, 헤딩(H1~H6) 제목 태그를 통해 전체 문서의 뼈대를 구성합니다. 텍스트를 타이핑할 때마다 우측의 실시간 미리보기 창에 서식이 적용된 최종 결과물이 즉시 렌더링되어 시각적으로 문서의 완성도를 점검할 수 있습니다.
b. 상단 툴바를 이용한 편리한 서식 지정
- 복잡한 마크다운 문법을 모두 외우지 않아도 미리보기 상단에 위치한 직관적인 툴바 버튼을 클릭하여 쉽고 빠르게 텍스트 서식을 적용합니다. 인용문 삽입, 인라인 및 다중 코드 블록 작성, 순서가 있는 숫자 리스트나 기호 목록, 프로젝트 관리를 위한 할 일 체크리스트(Task List) 등을 버튼 한 번으로 문서 본문에 정확하게 추가합니다.
c. 이미지 첨부하기
- 문서의 이해도를 높이는 시각 자료를 추가하기 위해 내 컴퓨터에 저장된 이미지를 직접 업로드하거나 외부 인터넷 이미지의 링크 URL을 삽입합니다. 또한 체계적인 데이터 정리가 필요할 때는 표 삽입 기능을 활용하여 행과 열의 기준을 나누고 정보를 일목요연하게 나열하며, 가로 구분선을 활용하여 문단 간의 경계를 깔끔하게 구분합니다.
d. PDF 문서 변환 및 MD 파일 내보내기
- 문서 편집이 완료되면 결과물을 로컬 PC로 손쉽게 저장합니다. 하단의 다운로드 기능을 통해 작성한 원본 텍스트를 마크다운 표준인 MD 확장자 파일로 내보내기 하거나, 미리보기 화면의 레이아웃 그대로를 깔끔한 고화질 PDF 문서 파일로 변환하여 인쇄, 출력 및 외부 공유용으로 안전하게 저장합니다. 필요에 따라 화면 분할, 편집 전용, 미리보기 전용, 전체화면 모드를 활용하여 글쓰기 몰입도를 높입니다.
3. 표준화 되어가고 있는 마크다운 문서
요즘에는 마크다운을 표준 문서 포맷으로 채택하는 곳이 빠르게 늘고 있습니다. 개발자라면 README 작성이 선택이 아닌 필수라는 것을 잘 알고 계실 겁니다. GitHub, GitLab, Bitbucket 모두 마크다운을 기본 문서 포맷으로 채택하고 있으며, 잘 작성된 README는 프로젝트의 첫인상을 결정합니다. 실시간 미리보기를 통해 헤딩 계층 구조, 코드 블록 렌더링, 테이블 정렬 등을 push 전에 완벽하게 검증할 수 있습니다.
a. 마크다운을 지원하는 주요 플랫폼들
현재 마크다운은 개발 생태계를 훨씬 넘어서 확산되어 있습니다.
| 플랫폼 | 마크다운 지원 | 주요 활용 |
|---|---|---|
| GitHub / GitLab | README, Issues, PR, Wiki | 프로젝트 문서화 |
| Notion | 마크다운 호환 편집기 | 팀 협업 노트 |
| Obsidian | 완전한 마크다운 기반 | 개인 지식 관리 |
| Jekyll / Hugo | 마크다운 기반 정적 사이트 | 기술 블로그 |
| Slack / Discord | 일부 마크다운 문법 지원 | 팀 커뮤니케이션 |
| Jupyter Notebook | 마크다운 셀 지원 | 데이터 분석 문서 |
4. 알아두면 좋은 마크다운 핵심 문법들
**마크다운(Markdown)**은 2004년 존 그루버(John Gruber)가 에런 스워츠(Aaron Swartz)와 함께 만든 경량 마크업 언어입니다. HTML처럼 텍스트에 구조와 서식을 부여하지만, 문법이 훨씬 간결하고 직관적이라 원문 자체만으로도 읽기 편합니다.
핵심 설계 철학은 단순합니다: "쓰기 쉽고, 읽기 쉽고, HTML로 변환하기 쉬운" 텍스트 포맷을 만드는 것. 이메일에서 이미 자연스럽게 사용하던 텍스트 표현 — 강조를 위한 **별표**, 들여쓰기, 기울임 등 — 을 그대로 문법으로 가져와 구조화된 문서를 빠르게 작성할 수 있습니다.
a. 마크다운 핵심 문법 요소
| 문법 요소 | 마크다운 입력 | 렌더링 결과 | 활용 빈도 |
|---|---|---|---|
| 헤딩 | # H1, ## H2, ### H3 | 제목 계층 구조 | ★★★★★ |
| 굵게 | **텍스트** | 텍스트 | ★★★★★ |
| 기울임 | *텍스트* | 텍스트 | ★★★★☆ |
| 코드 인라인 | `코드` | 코드 | ★★★★★ |
| 코드 블록 | ```언어명 ``` | 문법 강조 코드 블록 | ★★★★★ |
| 링크 | [텍스트](URL) | 클릭 가능한 링크 | ★★★★☆ |
| 이미지 |  | 이미지 렌더링 | ★★★★☆ |
| 테이블 | | 열1 | 열2 | | 정렬된 표 | ★★★★☆ |
| 인용문 | > 텍스트 | 들여쓰기 인용 블록 | ★★★☆☆ |
| 체크박스 | - [ ] 항목 | 할 일 목록 | ★★★☆☆ |
b. 마크다운 방언(Flavors)의 차이
마크다운은 원래 명세가 불명확한 부분이 많아서, 각 플랫폼마다 자체적인 확장 문법(Flavor)을 추가했습니다.
| Flavor | 주요 특징 | 사용처 |
|---|---|---|
| CommonMark | 표준화 시도, 엄격한 명세 | 일반적인 기준 |
| GFM (GitHub Flavored Markdown) | 테이블, 체크박스, 코드 블록 강조 | GitHub, GitLab |
| MultiMarkdown | 각주, 정의 목록, 수식 지원 | 학술 문서 |
| MDX | JSX 컴포넌트 삽입 가능 | React 기반 문서 |
| kramdown | Jekyll 기본 파서 | GitHub Pages |
Note
이 도구는 GFM(GitHub Flavored Markdown) 기준으로 렌더링됩니다. GitHub README에서 보이는 것과 동일한 결과물을 확인할 수 있습니다.
c. PR 설명과 커밋 체크리스트
d. 팀 위키 및 기술 블로그 초안
팀 위키나 기술 블로그 초안을 마크다운으로 작성하면 플랫폼 의존성 없이 이식성이 보장됩니다. 나중에 플랫폼을 교체하더라도 .md 파일만 있으면 어디서든 임포트할 수 있습니다. Notion, Confluence, Ghost 등 대부분의 협업 도구가 마크다운 가져오기를 지원합니다.
5. 실수하기 쉬운 마크다운 문법들
마크다운 문법은 단순해 보이지만, 실제로 작성하다 보면 "분명히 맞게 썼는데 왜 이렇게 나오지?"라는 상황을 자주 겪습니다.
a. 줄바꿈이 적용되지 않는 문제
원인: 마크다운에서 단순 엔터 한 번은 줄바꿈으로 처리되지 않습니다. HTML 렌더링 기준으로 단락을 나누려면 **빈 줄(엔터 두 번)**이 필요합니다.
// ❌ 렌더링 결과: 한 줄로 붙어서 출력됨
첫 번째 줄
두 번째 줄
// ✅ 올바른 방법: 빈 줄 삽입
첫 번째 줄
두 번째 줄
강제로 줄바꿈(<br>)을 삽입하려면 줄 끝에 공백 두 칸을 추가하는 방법도 있습니다.
b. 코드 블록 안에 backtick이 포함된 경우
원인: 코드 블록을 감싸는 backtick과 내용 안의 backtick이 충돌하여 렌더링이 깨집니다.
// ❌ 렌더링 깨짐
`코드 안에 `backtick` 포함`
// ✅ 이중 backtick으로 감싸기
``코드 안에 `backtick` 포함``
c. 테이블 정렬이 깨지는 경우
원인: 마크다운 테이블은 반드시 헤더 행과 구분선(---) 행이 있어야 합니다. 셀 개수가 불일치하거나 구분선이 누락되면 테이블 전체가 텍스트로 출력됩니다.
// ❌ 구분선 누락으로 테이블이 텍스트로 출력
| 이름 | 나이 |
| 홍길동 | 30 |
// ✅ 올바른 테이블 형식
| 이름 | 나이 |
| :----- | :--: |
| 홍길동 | 30 |
d. 헤딩이 인식되지 않는 경우
원인: # 기호 뒤에 반드시 공백이 한 칸 있어야 헤딩으로 인식됩니다. 공백 없이 바로 텍스트가 이어지면 일반 텍스트로 처리됩니다.
// ❌ 헤딩으로 인식되지 않음
#제목없는헤딩
// ✅ # 뒤에 공백 필수
# 제목 있는 헤딩
e. 이미지가 보이지 않는 경우
원인: 이미지 URL이 잘못되었거나, 로컬 파일 경로를 사용했지만 브라우저 보안 정책으로 접근이 차단된 경우입니다.
// ❌ 로컬 절대 경로는 브라우저에서 접근 불가
// ✅ 절대 URL 또는 도구의 이미지 업로드 기능 사용
f. 공통 패턴: 마크다운 트러블슈팅의 핵심
위의 모든 문제는 공통적으로 마크다운 파서가 예상하는 형식과 실제 입력의 불일치에서 발생합니다. 해결 전략은 세 가지입니다.
- 빈 줄로 블록 요소를 명확히 구분하기 — 단락, 헤딩, 코드 블록 전후에 빈 줄 삽입
- 특수문자는 이스케이프(
\) 처리 — 마크다운 문법으로 오해받는 문자들 - 실시간 미리보기로 즉시 검증 — 이 도구를 사용하는 가장 큰 이유
6. 생각해볼 거리
마크다운이 결국 HTML로 변환된다면, 처음부터 HTML을 쓰면 안 되는 걸까요?
기술적으로는 가능합니다. 마크다운 문서 안에 HTML 태그를 직접 사용할 수도 있고, 처음부터 HTML로 문서를 작성할 수도 있습니다. 하지만 마크다운의 진짜 가치는 원문 자체의 가독성에 있습니다. <h2>제목</h2>보다 ## 제목이 훨씬 읽기 편하고, 협업 시 비개발자도 쉽게 수정할 수 있습니다. 또한 마크다운은 플랫폼에 따라 다양한 출력 형식(HTML, PDF, EPUB 등)으로 변환할 수 있어 유연성이 훨씬 높습니다.
마크다운 표준화는 왜 이렇게 오래 걸렸을까요?
존 그루버가 마크다운을 만든 2004년부터 CommonMark가 출범한 2014년까지 무려 10년이 걸렸습니다. 원인은 초기 명세의 모호함이었습니다. 예를 들어 "중첩된 목록은 들여쓰기를 몇 칸으로 해야 하는가?"같은 질문에 원래 명세는 명확한 답을 주지 않았습니다. 각 플랫폼이 자체적으로 해석하다 보니 파편화가 심해졌고, 이를 해결하기 위해 Jeff Atwood(Stack Overflow 창립자) 등이 CommonMark 표준화 작업을 시작했습니다. 지금도 완전한 통일은 이루어지지 않았고, GFM이 사실상의 표준(de facto standard)으로 자리 잡은 상황입니다.
AI 시대에도 마크다운은 계속 중요할까요?
오히려 AI 시대에 마크다운의 중요성은 높아지고 있습니다. ChatGPT, Claude 등 대부분의 LLM이 응답을 마크다운 형식으로 출력하며, 프롬프트 엔지니어링에서도 구조화된 지시를 위해 마크다운 문법을 활용합니다. AI가 생성한 마크다운 결과물을 검증하고 수정하는 능력은 개발자의 새로운 필수 역량이 되고 있습니다. 또한 RAG(검색 증강 생성) 파이프라인에서 문서를 마크다운으로 전처리하면 LLM이 더 잘 이해하는 구조화된 컨텍스트를 제공할 수 있습니다.
