Markdown이란? 문법, CommonMark, GFM

소프트웨어 프로젝트의 README, 메모 앱의 제목 붙은 목록, 채팅 앱에서 별표로 감싸 굵게 만든 단어를 떠올려 보세요. 이 모든 것 뒤에는 같은 아이디어, Markdown이 있습니다. Markdown은 일반 텍스트에 간단한 기호 몇 개를 더해 제목, 목록, 링크, 표를 정의할 수 있게 해 주는 가벼운 마크업 언어입니다. 파일은 어떤 텍스트 편집기에서든 읽을 수 있으면서도, 필요할 때 깔끔한 HTML 페이지, Word 문서, PDF로 바꿀 수 있습니다. 이 글에서는 Markdown이 어떻게 탄생했는지, 핵심 문법, CommonMark와 GitHub Flavored Markdown의 차이, MD 파일을 변환할 때 주의할 점을 다룹니다.

Markdown이란 무엇인가요?

Markdown은 글쓰기 규칙의 모음이자, 그 규칙으로 쓴 텍스트를 HTML로 바꾸는 도구를 가리키는 통칭입니다. 파일은 보통 .md 또는 .markdown 확장자로 저장합니다. 만든 사람인 존 그루버(John Gruber)에 따르면 가장 중요한 설계 목표는 가독성입니다. Markdown 문서는 태그나 서식 명령으로 표시한 것처럼 보이지 않고 일반 텍스트 그대로 게시할 수 있어야 합니다. HTML에서 <strong>중요</strong>라고 써야 하는 것을 Markdown에서는 **중요**라고 쓰며, 원문 그대로도 자연스럽게 읽힙니다.

간략한 역사

존 그루버는 2004년에 Markdown을 만들었고, 에런 스워츠(Aaron Swartz)가 아이디어를 함께 검토하는 역할로 기여했습니다. 문법은 일반 텍스트 이메일의 관습(강조에는 별표, 목록에는 하이픈)과 setext, Textile 같은 이전 마크업 언어에서 영향을 받았습니다. 그루버가 자신의 사이트 Daring Fireball에 공개한 Perl 스크립트 Markdown.pl의 1.0.1 버전은 2004년 12월 17일 날짜로 되어 있습니다.

하지만 그루버의 설명은 공식 사양이라기보다 예시를 통한 설명이었습니다. 모호한 경우(중첩 목록, 들여쓴 코드 블록, HTML 섞어 쓰기)마다 구현체들이 각자 선택을 했고, 같은 텍스트가 도구마다 다른 결과를 내기 시작했습니다. 이에 대한 두 가지 주요 대응이 나왔습니다.

• CommonMark(2014년): 존 맥팔레인(John MacFarlane)이 이끈 사양으로, Markdown을 모호함 없이 정의하고 수백 개의 예시로 검증할 수 있게 했습니다. 첫 버전들은 2014년 가을에 나왔고, 현재 버전은 2024년 1월 28일 자 0.31.2입니다. 사양은 아직 1.0으로 선언되지 않았습니다.
• GitHub Flavored Markdown(GFM, 2017년): CommonMark를 바탕으로 한 GitHub의 공식 사양입니다. 표, 작업 목록, 취소선, 확장 자동 링크, 그리고 보안을 위한 일부 원시 HTML 태그 필터링 같은 확장을 더합니다. 가장 최근 공개된 사양은 2019년 4월 6일 자 0.29-gfm입니다.

Markdown은 인터넷 인프라에서도 인정받았습니다. 2016년 3월에 발행된 RFC 7763은 text/markdown 미디어 유형(MIME 유형)을 등록했으며, 작성자가 의도한 Markdown 변형을 나타내는 선택적 variant 매개변수를 두었습니다.

주요 Markdown 변형

CommonMark와 GFM 외에도 널리 쓰이는 변형이 있습니다. RFC 7763과 함께 발행된 RFC 7764는 그중 몇 가지를 등록하고 사용 지침을 제시했습니다.

• Markdown Extra: 각주, 정의 목록, 표를 추가한 초기 확장입니다.
• MultiMarkdown: 메타데이터, 인용, 상호 참조를 갖춘 학술 글쓰기용 변형입니다.
• Pandoc Markdown: Pandoc 변환기가 쓰는 변형으로, 책과 논문 작성을 위한 확장이 많습니다.

실용적인 원칙을 하나 들자면, 문서에 제목, 목록, 링크, 코드, 간단한 표만 쓴다면 거의 어디서나 똑같이 보입니다. 각주, 정의 목록, 특수 블록 유형에 의존한다면 대상 환경이 어떤 변형을 지원하는지 확인하세요.

핵심 문법

일상적으로 필요한 Markdown 문법은 몇 분이면 배울 수 있습니다.

# 1단계 제목
## 2단계 제목
이 문단에는 **굵게**, *기울임*, `코드`가 있습니다.
- 글머리 기호 목록
- 두 번째 항목
  - 들여쓴 하위 항목
1. 번호 목록
2. 두 번째 단계
[링크 텍스트](https://example.com)
![이미지 설명](image.png)
> 인용문
```
여러 줄 코드 블록
```

GFM이 추가한 표와 작업 목록은 다음과 같습니다.

| 형식 | 확장자 |
|--------|-----------|
| Markdown | .md |
| 일반 텍스트 | .txt |
- [x] 초안 쓰기
- [ ] 검토하기

문단은 빈 줄로 구분합니다. 줄 바꿈 하나는 대부분의 구현에서 같은 문단의 일부로 처리되며, 줄을 강제로 바꾸려면 줄 끝에 공백 두 칸을 넣습니다. Markdown 안에 HTML을 직접 쓸 수도 있습니다. CommonMark는 이를 허용하지만, GFM 같은 환경은 보안을 위해 일부 태그를 막습니다.

Markdown은 어디에 쓰이나요?

• 소프트웨어 개발: README, 변경 이력, 기여 가이드, 그리고 GitHub나 GitLab 같은 플랫폼의 이슈와 코드 리뷰 댓글.
• 기술 문서: Markdown 파일로 웹사이트를 만드는 정적 사이트 생성기.
• 메모: 많은 메모 앱이 메모를 Markdown으로 저장하거나 내보냅니다.
• 채팅과 커뮤니티 플랫폼: Reddit, Discord 같은 플랫폼이 Markdown 변형을 씁니다.
• 글쓰기와 출판: Pandoc 같은 도구로 하나의 Markdown 원본에서 HTML, PDF, DOCX, EPUB을 만들어 냅니다.
• AI 도구: 대화형 AI 비서는 답변을 Markdown으로 서식화하는 경우가 많습니다.

장점과 단점

Markdown은 어떤 프로그램으로 여나요?

Markdown은 일반 텍스트이므로 메모장과 텍스트 편집기(TextEdit)를 포함해 어떤 텍스트 편집기에서든 열립니다. 서식이 적용된 미리보기를 보려면 Visual Studio Code에 내장된 Markdown 미리보기나 Obsidian, Typora 같은 전용 편집기를 쓸 수 있습니다. GitHub와 GitLab은 저장소의 .md 파일을 자동으로 렌더링합니다. 반면 Word는 Markdown을 서식 있는 텍스트로 열지 않으므로 먼저 파일을 변환해야 합니다.

자주 겪는 문제와 해결 방법

목록이나 제목이 렌더링되지 않습니다

CommonMark에서는 제목 기호 뒤에 공백이 필요합니다. ##제목이 아니라 ## 제목이라고 써야 합니다. 문단 바로 뒤에 오는 목록도 올바르게 렌더링되려면 사이에 빈 줄이 필요한 경우가 많습니다.

여러 줄이 붙어 버립니다

줄 바꿈 하나로는 문단이 나뉘지 않습니다. 새 문단을 시작하려면 빈 줄을 두고, 문단 안에서 줄을 바꾸려면 줄 끝에 공백 두 칸을 넣으세요.

표가 한 플랫폼에서는 되고 다른 곳에서는 안 됩니다

표는 그루버의 원래 Markdown에도, CommonMark 핵심에도 포함되지 않으며 GFM 같은 확장에서 옵니다. 대상 플랫폼이 어떤 변형을 지원하는지 확인하세요.

숫자로 시작하는 문단이 번호 목록이 됩니다

"2024. 바쁜 한 해였다" 같은 줄은 숫자와 마침표로 시작하므로 목록으로 해석될 수 있습니다. 마침표 앞에 백슬래시를 넣어(2024\.) 이를 막으세요.

Markdown 파일 변환 팁

저희 변환기에서 Markdown 파일은 서버에 업로드되고 30분 이내에 삭제됩니다. 파일을 읽을 때는 CommonMark와 GitHub 스타일 확장(표, 작업 목록, 각주, 자동 링크)을 적용한 Markdig 라이브러리를 사용합니다.

• Markdown을 PDF로, Markdown을 Word로 변환하면 제목, 목록, 코드 블록, 인용문, 테두리 있는 표가 유지됩니다. 작업 목록의 체크박스는 Word와 PDF에서도 보이도록 ☑와 ☐ 문자로 바뀝니다. 본문은 기본적으로 12pt 세리프 글꼴로, 코드 블록은 고정폭 글꼴로 조판됩니다.
• Markdown을 HTML로 변환하면 README가 문자 인코딩이 선언된 독립된 웹 페이지가 됩니다.
• 반대 방향으로 Word를 Markdown으로, HTML을 Markdown으로, PDF를 Markdown으로 변환하면 GitHub 호환 Markdown이 만들어집니다. 제목, 굵게와 기울임, 목록, 표, 링크, 코드 블록, 인용문은 유지되고 글꼴, 색상, 페이지 레이아웃은 빠집니다. 머리글 행이 없는 표에서는 첫 행이 머리글이 되는데, GFM 표에는 머리글이 반드시 필요하기 때문입니다. "1. 조항"처럼 숫자로 시작하는 일반 문단은 실수로 목록이 되지 않도록 이스케이프됩니다. 파일은 BOM 없는 UTF-8로 저장됩니다.

자주 묻는 질문

MD 파일은 어떻게 여나요?

어떤 텍스트 편집기로든 열 수 있습니다. 서식이 적용된 모습을 보려면 Visual Studio Code의 미리보기나 Markdown 편집기를 쓰고, Word에서 읽고 싶다면 DOCX로 변환하세요.

CommonMark와 GitHub Flavored Markdown은 무엇이 다른가요?

CommonMark는 Markdown의 핵심 문법을 정밀한 규칙으로 정의합니다. GFM은 CommonMark 위에 표, 작업 목록, 취소선, 확장 자동 링크 같은 확장을 더한 상위 집합입니다.

Markdown으로 표를 만들 수 있나요?

네, GFM 같은 확장을 쓰면 세로 막대와 하이픈으로 간단한 표를 만들 수 있습니다. 병합 셀 같은 복잡한 구조가 필요하다면 HTML 표를 쓰거나 Word에서 문서를 작성하세요.

Markdown과 HTML은 무엇이 다른가요?

Markdown은 HTML로 변환하도록 설계된 더 단순한 글쓰기 형식입니다. HTML이 표현할 수 있는 모든 것을 표현하지는 못하지만, 원문은 훨씬 읽기 쉽습니다. 필요하면 Markdown 안에 HTML을 쓸 수도 있습니다.

Markdown에 공식 표준이 있나요?

그루버의 원래 설명은 공식 사양이 아닙니다. 오늘날 가장 널리 받아들여지는 정밀한 정의는 CommonMark이며, text/markdown 미디어 유형은 2016년 3월 RFC 7763으로 등록되었습니다.

출처

• John Gruber, Daring Fireball: Markdown
• CommonMark Spec (버전 이력)
• GitHub Flavored Markdown Spec
• IETF RFC 7763: The text/markdown Media Type (2016년 3월)
• IETF RFC 7764: Guidance on Markdown
• Wikipedia: Markdown (역사, 2차 자료)
• Markdig: .NET용 CommonMark 호환 Markdown 처리기