마크다운 확장 문법 가이드: 마크다운 표, 각주, 체크박스 작성법
마크다운 확장 문법은 John Gruber가 2004년에 공개한 원본 명세 이후에 추가된 서식 요소들을 통틀어 부르는 말입니다. 2004년 명세는 11가지 기본 요소만 정의했고, 표, 각주, 체크박스(작업 목록), 취소선은 아예 포함하지 않았습니다. 그 빈자리는 이후 프로젝트들이 채웠습니다. MultiMarkdown이 2005년에 표와 각주를 도입했고, 2006년에 등장한 Pandoc은 모든 프로세서 가운데 가장 큰 확장 세트를 갖추었으며, CommonMark는 2014년에 확장 여지를 남긴 채 핵심 명세를 표준화했고, GitHub은 2017년에 GFM 명세를 발표했습니다. 이 페이지의 모든 요소는 에디터의 실시간 미리보기에서 그대로 렌더링되므로, 5초만 붙여넣어 보면 대상 앱이 지원하는지 바로 확인할 수 있습니다.
지원 현황표
12가지 확장 요소를 모두 지원하는 애플리케이션은 없으므로, 게시하기 전에 반드시 대상 플랫폼의 지원 여부를 확인해야 합니다. 가장 흔히 쓰이는 4개 플랫폼만 봐도 지원 범위가 크게 갈립니다.
| 요소 | GitHub | Obsidian | Discord | Pandoc |
|---|---|---|---|---|
| 표 | 지원 | 지원 | 미지원 | 지원 |
| 펜스 코드 블록 | 지원 | 지원 | 지원 | 지원 |
| 각주 | 지원 | 지원 | 미지원 | 지원 |
| 제목 ID | 자동만 | 부분 지원 | 미지원 | 지원 |
| 정의 목록 | 미지원 | 미지원 | 미지원 | 지원 |
| 취소선 | 지원 | 지원 | 지원 | 지원 |
| 체크박스(작업 목록) | 지원 | 지원 | 미지원 | 지원 |
| 이모지 숏코드 | 지원 | 플러그인 | 지원 | 확장 기능 |
| 하이라이트 | 미지원 | 지원 | 미지원 | 확장 기능 |
| 아래 첨자와 위 첨자 | HTML만 | HTML만 | 미지원 | 지원 |
| URL 자동 링크 | 지원 | 지원 | 지원 | 확장 기능 |
실무에서 쓸 수 있는 요령 하나: 표, 펜스 코드 블록, 취소선, 체크박스는 거의 어디서나 렌더링됩니다. 반대로 정의 목록, 하이라이트, 아래 첨자, 위 첨자 4가지는 실패할 가능성이 가장 높은 요소입니다.
표
마크다운 표는 파이프 문자(|)로 열을 구분하고, 하이픈 3개 이상으로 이루어진 구분선으로 머리글 행을 표시합니다. 바깥쪽 파이프는 대부분의 파서에서 생략할 수 있지만, 호환성이 좋아지므로 그대로 두는 것이 좋습니다.
| Feature | Status |
| :------ | -----: |
| Export | Done |
| Sync | Open |
구분선 행의 콜론이 정렬을 제어합니다. :---는 왼쪽 정렬, :---:는 가운데 정렬, ---:는 오른쪽 정렬입니다. 파서는 해당 열의 모든 셀에 정렬을 적용합니다. 하이픈 개수는 열마다 맞출 필요가 없습니다. 셀 안에 파이프 문자 자체를 표시하려면 HTML 엔티티 |를 쓰면 되고, GitHub에서는 백슬래시 이스케이프 \|도 허용됩니다. 셀에는 굵은 글씨나 코드 스팬 같은 인라인 서식은 넣을 수 있지만, 목록이나 제목 같은 블록 요소는 넣을 수 없습니다.
이 문법은 MultiMarkdown이 2005년에 도입했고 GFM이 2017년에 채택했습니다. GitHub, GitLab, Obsidian, Pandoc은 표를 렌더링합니다. Discord는 렌더링하지 않습니다.
펜스 코드 블록
펜스 코드 블록은 백틱 3개로 열고 닫으며, 2004년 명세의 4칸 들여쓰기 방식과 달리 들여쓰기가 필요 없습니다. 대부분의 파서에서는 물결표 3개도 대체 펜스로 쓸 수 있습니다.
```python
def total(items):
return sum(items)
```
여는 펜스 바로 뒤에 언어 식별자를 붙이면 구문 강조가 켜집니다. 많은 웹 렌더러가 내부에서 사용하는 라이브러리인 highlight.js는 약 200개 언어의 정의를 제공하며, 자주 쓰이는 식별자로는 python, js, json, bash, sql이 있습니다. 코드 블록 안에 또 다른 코드 블록을 표시하려면 바깥쪽 펜스를 백틱 4개로 만들면 됩니다.
지원 범위는 모든 확장 요소 가운데 가장 넓습니다. GitHub, Obsidian, Discord, Pandoc 모두 펜스 블록을 렌더링하며, 4곳 모두 언어별 구문 강조를 적용합니다.
각주
마크다운 각주는 2개 부분으로 구성됩니다. 본문에 [^1] 형태로 쓰는 참조 표시와, 파일 어디에나 둘 수 있는 [^1]: 뒤에 내용을 적는 정의입니다. 렌더러는 모든 정의를 페이지 하단에 모으고, 참조와 정의를 양방향 링크로 연결합니다.
The claim has a published source.[^1]
[^1]: Smith, 2024, p. 41.
식별자에는 숫자뿐 아니라 단어도 쓸 수 있습니다. 출력 번호는 라벨이 아니라 문서에 등장한 순서를 따르므로 [^note]는 [^1]과 완전히 똑같이 동작합니다. 정의 아래에 4칸 들여쓰기로 문단을 이어 붙이면 각주 하나에 여러 문단을 담을 수 있습니다.
각주는 MultiMarkdown이 2005년에 처음 지원했고, Pandoc과 Obsidian은 완전히 지원하며, GitHub은 2021년에 각주 렌더링을 추가했습니다. Discord는 각주를 지원하지 않습니다.
제목 ID
사용자 지정 제목 ID는 제목 줄 끝에 중괄호로 적습니다. ## Refund Policy {#refunds}라고 쓰면 id="refunds"를 가진 h2 요소가 출력됩니다. 이 ID는 링크와 CSS에서 쓸 수 있는 안정적인 앵커가 됩니다.
## Refund Policy {#refunds}
Jump straight to [the refund policy](#refunds).
링크는 해시(#)와 ID를 대상으로 지정한 일반 마크다운 링크입니다. 전체 페이지 URL 뒤에 #refunds를 붙이면 외부 페이지에서도 같은 위치로 이동할 수 있습니다.
중괄호 형식을 해석하는 것은 Pandoc과 PHP Markdown Extra입니다. GitHub은 이 형식을 무시하지만 제목 텍스트에서 자동으로 ID를 생성하므로 #refund-policy로 연결하는 링크는 GitHub에서도 동작합니다. Obsidian은 제목 링크에 자체 [[Note#Heading]] 패턴을 사용합니다. Discord는 메시지에서 제목을 렌더링하지만 앵커 기능은 없습니다.
정의 목록
정의 목록은 하나의 용어에 1개 이상의 정의를 짝지어 주는 문법입니다. 용어를 한 줄에 단독으로 적고, 다음 줄부터 콜론과 공백으로 시작하는 정의를 이어 갑니다.
Markdown
: A plain-text formatting syntax released in 2004.
Parser
: Software that converts markdown into HTML.
: Also called a processor.
출력은 <dt>와 <dd>를 자식으로 가진 진짜 <dl> 요소이므로, 용어집을 만들 때나 스크린 리더 접근성 면에서 의미가 있습니다. 콜론 줄을 여러 개 쌓으면 하나의 용어에 여러 정의를 붙일 수 있습니다.
지원 범위는 좁습니다. 이 문법을 정의한 것은 PHP Markdown Extra이고, Pandoc과 MultiMarkdown도 해석합니다. GitHub과 Obsidian은 콜론 줄을 일반 텍스트로 출력하며 Discord도 마찬가지입니다. GitHub에서는 <dl> HTML을 직접 쓰는 것이 확실한 대안입니다.
취소선
취소선은 텍스트 양쪽을 물결표 2개로 감싸는 문법으로, like this처럼 가로줄이 그어진 텍스트로 렌더링됩니다. GFM에서 나온 요소이며 HTML 출력은 <del> 요소입니다.
~~Ship v2 on Friday.~~ Moved to Monday.
GitHub은 한쪽에 물결표 1개만 써도 허용합니다. 그래도 이식성을 위해 2개를 쓰는 것이 좋습니다. Pandoc에서는 물결표 1개가 아래 첨자를 뜻하므로, 문자 1개 차이로 의미가 완전히 뒤집힙니다.
지원은 거의 보편적입니다. GitHub, Obsidian, Discord, Pandoc 모두 물결표 2개 취소선을 렌더링합니다.
체크박스(작업 목록)
마크다운 체크박스 항목은 일반 목록 항목과 같은 방식으로 시작하고 대괄호를 추가합니다. - [ ]는 미완료 작업, - [x]는 완료된 작업입니다. 빈 대괄호 안의 공백은 반드시 있어야 합니다.
- [x] Draft the outline
- [x] Write the copy
- [ ] Publish the page
이 문법은 GitHub이 2013년에 도입했으며, 이슈와 풀 리퀘스트에서는 체크박스가 클릭 가능해져 클릭하면 원본 마크다운이 함께 업데이트됩니다. GitHub은 작업 개수도 집계해서 이슈에 "2 of 3 tasks" 같은 진행 상황을 표시합니다. Obsidian은 읽기 보기에서 클릭 가능한 체크박스를 렌더링하고, Pandoc은 작업 목록을 HTML 체크박스로 변환합니다. Discord는 대괄호를 입력한 문자 그대로 보여 줍니다.
이모지
마크다운 파일에 이모지를 넣는 방법은 2가지입니다. 유니코드 문자를 직접 붙여넣거나, 숏코드를 확장해 주는 애플리케이션에서 :rocket: 같은 숏코드를 입력하는 것입니다. 붙여넣은 이모지는 UTF-8 파일이라면 어디서든 살아남으므로, 숏코드가 통하지 않는 곳에서도 🎯는 표시됩니다.
Release day :tada: went live at 9 am.
숏코드는 이모지 이름을 콜론 2개 사이에 넣은 형태입니다. GitHub은 약 1,800개의 숏코드를 확장하고, Discord는 자체 세트에 더해 서버별 커스텀 이모지도 확장합니다. Obsidian은 숏코드에 커뮤니티 플러그인이 필요하지만 붙여넣은 이모지는 기본으로 표시하며, Pandoc은 emoji 확장을 켠 경우에만 숏코드를 확장합니다. 이름이 플랫폼마다 다르기 때문에, GitHub에서 되는 숏코드가 다른 곳에서도 된다는 보장은 없습니다.
하이라이트
하이라이트는 텍스트 양쪽을 등호 2개로 감싸는 문법으로, ==like this==가 보통 노란색의 형광펜 스타일 배경으로 렌더링됩니다. HTML 출력은 <mark> 요소입니다.
The deadline moved to ==14 March== at noon.
확장 요소 가운데 이식성이 가장 낮은 축에 듭니다. Obsidian은 기본으로 렌더링하고, Pandoc은 mark 확장을 켜면 해석합니다(2023년에 나온 Pandoc 3.0부터 사용 가능). GitHub과 Discord는 등호를 그대로 출력합니다. 문법이 통하지 않는 곳에서도 HTML을 통과시키는 렌더러라면 <mark> 태그가 동작하며, GitHub의 readme 파일도 여기에 포함됩니다.
아래 첨자와 위 첨자
아래 첨자는 H2O처럼 문자를 물결표 1개로 감싸고, 위 첨자는 x^2^처럼 캐럿 1개로 감쌉니다. 두 형식 모두 일반적인 웹 플레이버가 아니라 Pandoc의 확장 세트에서 나온 것입니다.
H~2~O freezes at 0 degrees.
E = mc^2^ dates from 1905.
Pandoc은 이를 <sub>와 <sup> 요소로 변환합니다. GitHub과 Obsidian은 물결표와 캐럿 형식을 무시하지만 HTML 태그는 통과시키므로 H2O는 두 곳 모두에서 동작합니다. Discord는 둘 다 지원하지 않습니다. 물결표 충돌에 주의해야 합니다. 물결표 1개를 취소선으로 처리하는 앱에서는 아래 첨자로 쓰려던 텍스트에 가로줄이 그어집니다.
URL 자동 링크
URL 자동 링크는 https://example.com 같은 주소만 적어도 대괄호 문법 없이 클릭 가능한 링크로 바꿔 주는 기능입니다. GFM이 2017년 명세에서 autolink 확장으로 이 동작을 공식화했습니다.
Full docs at https://example.com/docs
GitHub과 Discord는 URL만 적어도 링크로 바꾸고, Obsidian도 읽기 보기에서 같은 방식으로 동작합니다. Pandoc은 autolink_bare_uris 확장을 켜지 않는 한 이 동작이 꺼져 있습니다. URL이 링크로 변하는 것을 막으려면 백틱으로 감싸면 됩니다. 코드 스팬은 절대 링크화되지 않으므로 설정 예시나 자리 표시자 도메인에서는 https://example.com이 일반 텍스트로 남습니다.
자주 묻는 질문
확장 문법도 공식 마크다운 명세에 포함됩니까?
아닙니다. 2004년 명세가 정의하는 것은 11가지 기본 요소이며, 이 페이지의 모든 요소는 이후에 나온 플레이버와 프로세서에서 온 것입니다. 마크다운에는 표준을 관리하는 기구가 없으며, 애플리케이션마다 지원이 다른 이유가 바로 여기에 있습니다.
확장 문법을 가장 많이 지원하는 마크다운 플레이버는 무엇입니까?
가장 넓은 범위를 지원하는 것은 Pandoc으로, 30가지가 넘는 선택형 문법 확장을 갖추고 있으며 이 페이지의 12가지 요소를 모두 해석합니다. 다만 웹 게시가 목적이라면 GFM이 더 실용적인 기준입니다. GitHub, GitLab, 그리고 최신 에디터 대부분이 GFM을 따르기 때문입니다.
표가 GitHub에서는 렌더링되는데 Discord에서는 안 되는 이유는 무엇입니까?
Discord는 채팅에 맞춘 좁은 마크다운 부분집합만 구현했으며, 표, 각주, 체크박스(작업 목록), 정의 목록을 제외했습니다. 이 부분집합에 포함되는 것은 굵게, 기울임, 취소선, 제목, 펜스 코드 블록입니다. Discord에 올릴 콘텐츠는 이 5가지 요소 안에서 작성해야 합니다.
게시하기 전에 확장 문법을 테스트하려면 어떻게 해야 합니까?
온라인 에디터의 실시간 미리보기에 해당 요소를 붙여넣으면 됩니다. GFM과 각주를 1초 안에 렌더링합니다. 그 밖의 플랫폼이라면 2줄짜리 샘플을 대상 앱에 직접 붙여넣어 확인하는 것이 좋습니다. 가장 흔한 4가지 경우는 지원 현황표에 정리되어 있습니다.