TL;DR — CommonMark와 GFM의 차이
- GitHub에서 흔히 "깃허브 마크다운 문법"이라고 부르는 요소 중 표, 취소선, 체크박스, URL 자동 링크는 사실 표준이 아니라 확장입니다. CommonMark는 마크다운의 "표준 사양"으로, 제목·목록·강조·링크·이미지·코드·인용 같은 기본 구문만 엄격하게 정의합니다.
- GFM(GitHub Flavored Markdown)은 그 GFM spec이 "CommonMark의 엄격한 상위 집합(strict superset)"이라고 설명하는 방언입니다. CommonMark에 표, 취소선, 체크박스, 확장 자동 링크, raw HTML 제한이라는 5가지 확장을 추가합니다.
- GitHub.com에서 쓸 수 있는
[!NOTE]같은 알림(callout), 이모지 숏코드,@mention, 이슈 참조, Mermaid 다이어그램, 수식, 각주는 GFM spec이 아니라 GitHub.com 고유의 레이어입니다. GitHub 밖에서는 기본적으로 동작하지 않습니다. - 문단 안에서 한 번만 줄바꿈(soft break)했을 때
<br>로 바뀌는지 여부는 CommonMark와 GFM spec이 같습니다(바뀌지 않음). GitHub.com의 이슈·PR 코멘트 창만 예외적으로 줄바꿈하며,.md파일과는 동작이 다릅니다. - 어떤 방언으로 쓸지 고민된다면 순수 CommonMark 범위에 담으면 호환성이 가장 높고, GitHub 중심이라면 GFM 확장까지 쓸 수 있다고 기억하면 충분합니다.
- FormatArc의 Markdown to HTML 변환기는 GFM 확장(표, 취소선, 체크박스, 자동 링크)을 지원하는 변환 도구입니다. 내 마크다운이 GFM 확장에 의존하는지 확인하는 용도로도 쓸 수 있습니다.
요점: 표는 CommonMark 핵심 사양에 포함되지 않습니다. GFM spec 쪽에서 취소선·체크박스·확장 자동 링크·raw HTML 제한과 나란히 확장 기능으로 정의되어 있습니다.
CommonMark와 GFM의 관계 — GFM은 CommonMark를 기반으로 한 확장 사양
CommonMark새 탭에서 열립니다는 본래 모호했던 마크다운 문법을 테스트 스위트와 함께 엄격하게 다시 정의한 프로젝트입니다. 구현마다 달라지는 결과를 없애고, 어떤 파서로 처리해도 같은 결과가 나오는 것을 목표로 합니다. 사양으로서는 의도적으로 확장을 받아들이지 않고, 제목·문단·목록·링크·이미지·강조·코드·인용 같은 핵심 구문만 규정합니다.
GFM(GitHub Flavored Markdown)새 탭에서 열립니다은 GitHub이 쓰는 마크다운 방언이며, GFM spec 스스로 "CommonMark의 엄격한 상위 집합"이라고 설명합니다. 문법 관계로 정리하면 다음과 같습니다.
- 올바른 CommonMark 문서는 GFM 파서에서도 완전히 같게 렌더링된다
- GFM은 CommonMark에 몇 가지 확장을 "추가"했을 뿐, 핵심 구문을 바꾸지는 않았다
다만 "상위 집합"이라는 말은 GFM spec의 설명 범위 안에서만 정확합니다. GitHub.com의 실제 렌더링, 라이브러리별 구현, CommonMark 최신 버전과의 세부 차이까지 넣으면 예외도 있습니다. 이 글에서는 "GFM spec이 정의하는 확장"과 "GitHub.com이 독자적으로 더하는 기능"을 나눠서 정리합니다.
비교표 — CommonMark와 GFM의 기능 대응
| 기능 | CommonMark | GFM spec | GitHub.com에서 추가 |
|---|---|---|---|
제목(#) | ✓ | ✓ | — |
| 문단·목록·인용 | ✓ | ✓ | — |
강조(**굵게** / _기울임_) | ✓ | ✓ | — |
| 링크·이미지 | ✓ | ✓ | — |
| 인라인 코드·펜스 코드 블록 | ✓ | ✓ | — |
| raw HTML 삽입 | ✓ | ✓(일부 태그 금지) | 추가 샌타이즈 있음 |
표(| col |) | ✗ | ✓ | ✓ |
취소선(~~text~~) | ✗ | ✓ | ✓ |
체크박스(- [ ] / - [x]) | ✗ | ✓ | ✓ |
| 확장 자동 링크(URL 자동 링크화) | ✗ | ✓ | ✓ |
알림(> [!NOTE] 등) | ✗ | ✗ | ✓ |
이모지 숏코드(:smile:) | ✗ | ✗ | ✓ |
@mention / 이슈·PR 참조 / 커밋 SHA | ✗ | ✗ | ✓ |
| Mermaid 다이어그램·수식(KaTeX) | ✗ | ✗ | ✓ |
각주([^1]) | ✗ | ✗ | ✓ |
포인트는 세 칸으로 나뉘어 있다는 점입니다. 표나 취소선 등은 GFM spec의 확장이므로 GFM 대응 파서라면 GitHub 밖에서도 동작합니다. 반면 알림·이모지·각주는 GFM spec에 포함되지 않아 GitHub.com(이나 이를 흉내 낸 플랫폼)에서만 보증됩니다.
어떤 GFM 확장이 기본으로 켜져 있는가 — 6개 렌더러 실측
위 비교표가 보여 주는 것은 "각 사양이 무엇을 정의하는가"이며, 손안의 파서가 초기 설정에서 무엇을 하는지는 알려 주지 않습니다. 그래서 실측했습니다. 같은 마크다운 조각(파이프 표, ~~x~~, ~x~, - [ ] todo, 맨 URL, 각주 [^1])을 JavaScript 파서 5종과 GitHub 공식 Markdown API에 통과시킨 결과입니다(2026-07-31 실측. 재현 스크립트와 결과는 저장소의 scripts/benchmarks/commonmark-vs-gfm/에 커밋되어 있습니다).
| 렌더러(버전) | 표 | ~~x~~ | ~x~ 물결표 1개 | 체크박스 - [ ] | 맨 URL | 각주 [^1] |
|---|---|---|---|---|---|---|
| commonmark.js 0.31.2(레퍼런스 구현) | 파이프가 문자인 채 | 문자인 채 | 문자인 채 | [ ]가 문자인 채 | 문자인 채 | 링크로 변질 |
| marked 18.0.5(기본값) | <table> | <del> | <del> | 체크박스 | 링크화 | 링크로 변질 |
| markdown-it 14.2.0(default 프리셋) | <table> | <s> | 문자인 채 | [ ]가 문자인 채 | 문자인 채 | 링크로 변질 |
| remark 15.0.1(플러그인 없음) | 파이프가 문자인 채 | 문자인 채 | 문자인 채 | [ ]가 문자인 채 | 문자인 채 | 링크로 변질 |
| remark 15.0.1 + remark-gfm 4.0.1 | <table> | <del> | <del> | 체크박스 | 링크화 | 각주로 렌더링 |
GitHub Markdown API(markdown 모드) | <table> | <del> | <del> | [ ]가 문자인 채 | 링크화 | 각주로 렌더링 |
실측에서 알 수 있는 것을 정리합니다.
- 같은
~~x~~라도 marked / remark-gfm / GitHub은<del>을, markdown-it은<s>를 출력합니다. "GFM 대응" 파서끼리도 요소 이름 자체가 다릅니다 - GFM spec의 취소선 규칙은 물결표 1개 또는 2개를 허용합니다. marked / remark-gfm / GitHub은
~x~도 취소선으로 만들지만, markdown-it은 물결표 2개가 필수라서~x~를 문자인 채 남겨 둡니다 - GitHub 공식 Markdown API는 기본
markdown모드에서- [ ]를 대괄호 문자인 채 남겨 둡니다.<input type="checkbox">를 출력하는 것은 코멘트 문맥용gfm모드뿐이며, README에서 보던 체크박스가 모든 엔드포인트에서 나오는 것은 아닙니다 - markdown-it의 default 프리셋은 표와 취소선을 켜는 한편, 맨 URL 자동 링크(
linkify)는 꺼져 있습니다. "기본으로 GFM 대응"은 부분적으로만 참입니다 - 각주 미지원 파서는
[^1]: note를 무시하지 않고 링크 참조 정의로 해석합니다. 그 결과text[^1]은 조용히<a href="note">^1</a>로 변합니다. 반대로 remark-gfm과 GitHub은 각주가 GFM spec에 포함되지 않음에도 각주로 렌더링합니다
내 마크다운이 GFM 대응 파서에서 어떻게 변환되는지는 Markdown to HTML 변환기에 붙여넣으면 바로 확인할 수 있습니다. marked(gfm: true)가 브라우저 안에서만 동작합니다.
CommonMark에 표가 없는 이유 — 핵심 사양이 의도적으로 제외했다
CommonMark 사양은 표를 의도적으로 핵심 구문에서 빼 두었습니다. 파이프와 하이픈으로 만드는 표(| col | col |)는 GFM spec 쪽에서 정의되어 있으며, 절 제목 자체가 "Tables (extension)새 탭에서 열립니다"입니다. GFM 스스로 표를 확장 기능으로 명시하고 있는 셈입니다. 같은 "(extension)" 표기는 취소선·체크박스·확장 자동 링크·raw HTML 제한에도 붙어 있으며, 모두 핵심 구문이 아니라 확장이라는 위치입니다.
즉 확장을 켜지 않은 순수 CommonMark 렌더러에서는 | col |이 파이프가 붙은 문단으로 남고, GFM 대응 렌더러에서 처음 <table>이 됩니다. 이 경위는 CommonMark 포럼 논의 스레드새 탭에서 열립니다나 commonmark-spec#393새 탭에서 열립니다에서도 반복해서 다뤄졌으며, 표가 핵심 사양 범위 밖이라는 것은 원문 사양에서 확인할 수 있습니다.
특정 렌더러가 표를 GFM 확장으로 다루는지 확인하고 싶다면, 두 행짜리 표를 Markdown to HTML 변환기에 붙여넣고 <table>이 출력되는지 보면 됩니다.
일반 텍스트는 유효한 CommonMark 문서인가
마크다운을 프로그램으로 검증할 때 자주 나오는 의문이 "그냥 평문 문단도 유효한 마크다운이라고 할 수 있는가"입니다. CommonMark spec은 이것을 2.1절 "Characters and lines"에서 직접 답합니다.
Any sequence of characters is a valid CommonMark document.
즉 잘못된(invalid) CommonMark 문서라는 것이 존재하지 않습니다. 파싱은 실패하지 않으며, 텍스트가 어떤 구문 요소를 포함하는지 판정할 뿐입니다. 보통 줄의 나열은 4.8절 "Paragraphs"가 다룹니다.
A sequence of non-blank lines that cannot be interpreted as other kinds of blocks forms a paragraph.
따라서 평범한 문장만 있는 파일은 "문단의 모음"으로서 유효한 CommonMark 문서입니다(0.31.2 spec의 2.1절새 탭에서 열립니다과 4.8절새 탭에서 열립니다). 게다가 GFM spec은 CommonMark의 엄격한 상위 집합이므로, 같은 텍스트는 그대로 유효한 GFM 문서이기도 합니다. 확장은 구문을 추가할 뿐 기존 텍스트를 invalid하게 만들지 않습니다. 세상의 "마크다운 밸리데이터"가 문법 오류가 아니라 스타일 규약이나 렌더링 기대치를 검사하는 것은, 사양 수준에서는 마크다운에 구문 오류가 존재하지 않기 때문입니다.
평문이 문단이 아니게 되는 경계는 하나 있으며, 같은 4.8절이 이것을 정합니다.
However, the first line may be preceded by up to three spaces of indentation. Four spaces of indentation is too many:
줄 앞 들여쓰기가 반각 공백 3개까지라면 문단 그대로입니다. 4개가 되면 4.4절새 탭에서 열립니다의 indented code block으로 바뀝니다. 같은 절에는 "An indented code block cannot interrupt a paragraph, so there must be a blank line between a paragraph and a following indented code block."라는 규칙도 있어서, 문단 바로 뒤에 빈 줄 없이 이어진 경우에는 코드 블록이 되지 않습니다.
공백 3개의 들여쓰기.
여기까지 하나의 문단입니다.
빈 줄 뒤에 공백 4개의 들여쓰기.
이것은 코드 블록입니다.
규칙은 이것뿐입니다. 빈 줄 뒤에 4개 들여쓰기를 하기 전까지, 평범한 글은 평범한 글 그대로입니다.
실제로 HTML로 변환하면 무엇이 달라지는가
CommonMark만 처리하는 파서와 GFM 대응 파서는 같은 마크다운이라도 출력 HTML이 달라집니다. 다음 입력으로 비교해 봅니다.
| 상품 | 재고 |
| --- | --- |
| 사과 | 3 |
~~품절~~ 재고 있음
- [x] 입고 확인
- [ ] 가격표 교체
CommonMark 전용 파서에서는 | 상품 | 재고 | 행이 표가 되지 않고 파이프 기호가 붙은 문단 그대로 출력되며, ~~품절~~도 취소선이 되지 않고 문자 그대로 물결표가 남고, - [x]는 보통 목록 항목이 됩니다. GFM 대응 파서라면 <table>, <del>, <input type="checkbox">를 포함한 HTML로 변환됩니다.
즉 "마크다운이 깨져 보인다"고 느꼈다면, 원인이 플랫폼 사이의 방언 차이인 경우가 많습니다. 내 마크다운이 GFM 확장에 의존하는지 확인하려면 Markdown to HTML 변환기에 붙여넣고 출력 HTML을 보는 것이 가장 빠릅니다.
GFM이 CommonMark에 추가한 5가지 확장
표(테이블)
파이프 |와 하이픈 -로 만드는 표입니다. CommonMark에는 표 정의가 없으므로 표는 GFM 확장 기능이라는 위치가 됩니다. GFM spec의 Tables (extension)새 탭에서 열립니다 절(GFM spec 섹션 4.10)에 정의되어 있습니다. CommonMark만 구현한 렌더러에서는 표로 그려지지 않고 파이프가 붙은 텍스트가 그대로 남습니다. 정렬 지정(:--- / :---: / ---:)이나 셀 안 파이프의 이스케이프 같은 세부 규칙은 위의 비교표와 실측 표를 참고하세요. 자세한 작성법은 마크다운 표 작성법을 참고하세요.
취소선
~~지우고 싶은 텍스트~~로 <del> 요소가 됩니다. 물결표 2개로 감싸는 방식은 GFM 확장이며 CommonMark에는 포함되지 않습니다. GFM spec의 Strikethrough (extension)새 탭에서 열립니다 절(GFM spec 섹션 6.5)을 참조하세요. 물결표 1개(~x~)까지 허용하는지는 파서별로 다른데, 위의 실측에서 markdown-it만 2개를 요구했습니다.
체크박스(작업 목록)
목록 항목 앞에 - [ ](미완료) 또는 - [x](완료)를 쓰면 체크박스로 그려집니다. 이 구문은 GFM spec의 Task list items (extension)새 탭에서 열립니다 절(GFM spec 섹션 5.3)에 정의되어 있습니다. GitHub에서는 이슈나 PR 본문에서 클릭해서 상태를 바꿀 수 있지만, 그 "클릭으로 전환" 동작은 GitHub.com 쪽 기능이며, 그냥 HTML로 출력하는 렌더러에서는 정적인 체크박스가 됩니다.
확장 자동 링크
https://example.com처럼 URL을 그대로 쓰면 자동으로 링크가 됩니다. CommonMark에서 URL을 링크로 만들려면 <https://example.com>처럼 홑화살괄호로 감싸야 하지만, GFM은 괄호 없는 맨 URL도 감지해 링크화합니다. 이 맨 URL 동작은 GFM spec의 Autolinks (extension)새 탭에서 열립니다 절(GFM spec 섹션 6.9)에 규정되어 있으며, CommonMark 자체의 홑화살괄호 자동 링크와는 별개입니다.
raw HTML 제한(disallowed raw HTML)
CommonMark도 GFM도 마크다운 안에 raw HTML을 쓰는 것을 허용합니다. 차이는 GFM이 <script> / <iframe> / <style> 등 극히 일부 태그를 "금지된 raw HTML"로 무효화한다는 점입니다. 게다가 GitHub.com에서는 이것과 별개의 레이어에서 더 엄격한 HTML 샌타이즈가 걸립니다(속성 제거 등). FormatArc의 Markdown to HTML 변환기는 구문 변환만 수행하므로, 신뢰할 수 없는 입력을 변환했다면 출력 HTML은 별도로 샌타이즈하세요.
각 규칙이 어디에 정의되어 있는가 — 사양 원문 확인
위 내용을 원문으로 확인하고 싶다면 제3자의 정리가 아니라 사양 그 자체를 직접 보세요.
- 핵심 구문은 CommonMark Spec새 탭에서 열립니다(John MacFarlane 저)에 정의되어 있습니다. 제목·문단·목록·링크·이미지·강조·코드·인용을 다루면서, 표·취소선·체크박스·맨 URL 자동 링크는 명시적으로 정의하지 않습니다.
- 여기서 다룬 4가지 GFM 확장은 각각 GitHub Flavored Markdown Spec새 탭에서 열립니다에 독립된 절을 가지며, 모두 제목에 "(extension)"이 붙어 있습니다.
- Tables (extension)새 탭에서 열립니다 — GFM spec 섹션 4.10
- Task list items (extension)새 탭에서 열립니다 — GFM spec 섹션 5.3
- Strikethrough (extension)새 탭에서 열립니다 — GFM spec 섹션 6.5
- Autolinks (extension)새 탭에서 열립니다 — GFM spec 섹션 6.9
각 GFM 제목의 "(extension)" 표기는 이것들이 핵심 구문이 아니라 CommonMark에 대한 추가라는 것을 사양 스스로 보여 주는 표시입니다. 금지된 raw HTML 규칙도 마찬가지로 GFM spec의 Disallowed Raw HTML (extension)새 탭에서 열립니다 절에 정의되어 있습니다.
GFM spec이 아니라 GitHub.com 고유 기능
다음 기능들은 "GitHub 마크다운"으로 자주 소개되지만 GFM spec에는 없습니다. GitHub.com(그리고 이를 흉내 낸 일부 서비스)에서만 동작한다고 보세요.
- 알림(callout) —
> [!NOTE]/> [!TIP]/> [!IMPORTANT]/> [!WARNING]/> [!CAUTION]의 5종. 색이 입혀진 콜아웃으로 그려집니다. - 이모지 숏코드 —
:smile:같은:name:표기법. 표준 마크다운에는 이모지 개념이 없습니다. @mention/ 이슈·PR 참조 / 커밋 SHA —@username,#123, 커밋 해시를 자동으로 링크화합니다. 저장소 문맥이 없으면 의미를 갖지 못하는 기능입니다.- Mermaid 다이어그램·수식 —
```mermaid코드 블록과$...$수식. 이것도 GitHub.com 렌더링 파이프라인의 추가 기능입니다. - 각주 —
[^1]형식. GitHub.com은 지원하지만 GFM spec 차분에는 없습니다.remark-gfm이나 Hugo의 Goldmark처럼 도구에 따라 GFM 계열 확장과 함께 각주도 켜지는 경우가 있지만, 그것은 각 구현의 판단입니다.
이것들을 쓴 마크다운을 GitHub 밖(README를 그대로 옮겨 붙인 블로그, 문서 도구 등)으로 가져가면 대부분 그대로 평문으로 표시됩니다. GitHub.com 전용 문법으로 간주하는 것이 안전합니다.
문단 안 줄바꿈(hard line break) 처리의 차이
여기는 오해가 많은 부분입니다. CommonMark에서든 GFM spec에서든, 문단 안에서 한 번만 줄바꿈(soft break)하면 <br>이 되지 않고 앞뒤 행이 이어진 하나의 문단이 됩니다. 줄바꿈을 <br>로 만들려면 행 끝에 반각 공백 2개를 두거나, 행 끝에 백슬래시 \를 두거나, <br> 태그를 직접 써야 합니다. 이것은 CommonMark와 GFM에서 공통 동작입니다. 참고로 백슬래시는 줄바꿈뿐 아니라 기호가 서식으로 해석되지 않게 하는 이스케이프에도 쓰입니다. 어떤 기호에 어떻게 적용되는지는 마크다운 이스케이프 문자 정리를 참고하세요.
행 끝 공백 2개가 먹지 않는 곳이 있는데, 같은 4.8절이 "Final spaces or tabs are stripped before inline parsing, so a paragraph that ends with two or more spaces will not end with a hard line break:"라고 정하고 있습니다. 행 끝 공백이 효력을 갖는 곳은 문단 안에서 행과 행을 잇는 위치이고, 문단 끝에서는 효력이 없습니다.
예외는 GitHub.com의 이슈 / PR / Discussion 코멘트 창으로, 여기만 "한 번의 줄바꿈을 그대로 <br>로 만드는" 설정입니다. 반면 같은 GitHub 위에서도 .md 파일(README나 문서)은 CommonMark / GFM 표준 동작이라서 공백 2개나 \가 필요합니다. "GitHub 코멘트 창에서는 줄바꿈이 됐는데 README에서는 안 된다"는 현상의 원인이 바로 이것입니다.
어떤 플랫폼·도구가 어느 방언인가
정확히는 "순수 CommonMark", "CommonMark + GFM 확장", "독자 방언" 중 어느 쪽에 가까운가라는 시각이 됩니다. 대표적인 것들을 정리합니다.
| 플랫폼 / 도구 | 채택한 마크다운 |
|---|---|
| GitHub.com | GFM + GitHub.com 고유 기능(알림·이모지·mention·Mermaid·각주 등) |
| GitLab | GLFM(GitLab Flavored Markdown). CommonMark + GFM 호환 + GitLab 독자 확장 |
| 독자 방언(CommonMark 기반으로 조정. 일부 GFM 기능 미지원) | |
| Stack Overflow | 독자 방언(CommonMark 쪽이지만 GFM의 표 등은 오랫동안 미지원) |
| Discord | 독자 서브셋(코드 블록·취소선 등에 한정. 표 없음) |
| Obsidian | CommonMark + 독자 확장([[wikilink]]·콜아웃·태그 등). GFM의 표와 체크박스도 지원 |
| Notion | 독자 방언. 내보낼 때의 마크다운은 GFM 쪽이지만 에디터 표기법은 Notion 고유 |
| VS Code 미리보기 | markdown-it 기반(CommonMark + GFM의 표·취소선 등 확장) |
| Hugo | Goldmark(CommonMark 준수 + GFM 호환 확장. 설정에서 활성화) |
| Jekyll | kramdown(독자 방언. GFM 호환 처리 모드도 있음) |
| Astro / Docusaurus | remark 기반. remark-gfm으로 GFM 확장을 켜는 구성이 일반적 |
| MkDocs | Python-Markdown(독자 방언. 확장 플러그인으로 기능 추가) |
"GFM 대응"이라고 적혀 있어도 GitHub.com 고유의 알림이나 이모지까지 지원한다는 뜻은 아닙니다. 반대로 "CommonMark 전용" 도구라도 플러그인을 더하면 GFM 확장을 쓸 수 있는 경우가 많습니다. 최종적으로는 쓰고 있는 라이브러리나 서비스 문서에서 "어떤 확장이 켜져 있는지"를 확인하는 것이 확실합니다.
내 환경이 GFM 대응인지 확인하는 방법
복잡한 조사 없이도 다음 순서로 대략 판정할 수 있습니다.
- 표(
| col |), 취소선(~~text~~), 체크박스(- [ ])를 하나씩 써 보고 그려지면 GFM 확장에 대응한다 - 라이브러리를 쓴다면 설정을 본다.
marked는gfm: true, remark는remark-gfm플러그인, markdown-it은 기본으로 GFM의 표·취소선이 켜져 있다(단, 맨 URL 자동 링크는linkify를 켜지 않으면 꺼져 있다. 위의 실측 매트릭스 참조) - 정적 사이트 생성기라면 설정 파일을 확인한다. Hugo는
markup.goldmark.extensions, Astro는markdown.remarkPlugins에remark-gfm이 있는지 등
마크다운 파일이 애초에 GFM 확장에 의존하는지 알고 싶을 뿐이라면, Markdown to HTML 변환기에 붙여넣어 표와 취소선이 HTML로 바뀌는지 보면 한눈에 알 수 있습니다.
어느 쪽을 기준으로 마크다운을 써야 하는가
- 호환성이 가장 높은 것은 순수 CommonMark 범위에 담는 것입니다. 어떤 렌더러에서도 거의 확실하게 의도대로 표시됩니다.
- GitHub이나 그에 준하는 플랫폼(GitLab, 대부분의 문서 도구)이 전제라면 GFM 확장(표, 취소선, 체크박스, 자동 링크)까지 써도 문제없습니다. 실무에서는 이 범위가 표준적입니다.
[!NOTE]같은 알림, 이모지 숏코드,@mention, Mermaid, 각주는 "GitHub.com 밖에서는 깨진다는 전제"로 쓰세요. README에는 편리하지만, 복사해서 블로그에 붙이면 평문이 됩니다.- 배포나 이식을 생각한다면 raw HTML을 가능한 한 섞지 않는 편이 안전합니다. CommonMark든 GFM이든 raw HTML을 포함한 문서는 샌타이즈와 렌더러 구현에 따라 동작이 좌우됩니다.
FormatArc의 마크다운 변환 도구는 어느 방언인가
FormatArc의 Markdown to HTML 변환기는 내부에서 marked를 gfm: true로 동작시킵니다. 그래서 다음과 같습니다.
- GFM spec의 확장(표, 취소선, 체크박스, 확장 자동 링크)은 그대로 HTML로 변환됩니다
- 문단 안의 줄바꿈(soft break)은
breaks: false에 해당하는 동작으로<br>이 되지 않습니다. CommonMark / GFM spec과 같고, GitHub.com 코멘트 창의 줄바꿈 동작과는 다릅니다 - GitHub.com 고유의 알림(
[!NOTE]등), 이모지 숏코드,@mention, Mermaid, 각주는 지원하지 않습니다. GFM spec의 기능이 아니기 때문입니다
역방향인 HTML to Markdown 변환기도 출력하는 마크다운은 표와 취소선을 포함한 GFM 쪽 형식입니다. 어느 쪽도 브라우저 안에서 처리가 끝나며, 회원가입도 업로드도 필요 없습니다. 사내 비공개 문서를 붙여넣어도 외부로 전송되지 않습니다. 변환 방법을 자세히 알고 싶다면 마크다운을 HTML로 변환하는 방법을, 역변환은 HTML을 마크다운으로 변환하는 방법을 참고하세요.
자주 묻는 질문
CommonMark와 GFM 중 어떤 걸로 마크다운을 써야 하나요?
가장 호환성이 높은 것은 순수 CommonMark 범위입니다. GitHub이나 그에 준하는 플랫폼이 전제라면 GFM 확장(표, 취소선, 체크박스, 자동 링크)까지 써도 됩니다. [!NOTE] 같은 GitHub.com 고유 기능은 GitHub 밖에서 깨진다는 전제로 쓰세요.
CommonMark에는 표 문법이 없나요?
없습니다. 표는 GFM 확장 기능이며 CommonMark 사양에는 포함되어 있지 않습니다. CommonMark만 구현한 렌더러에서는 | col |이 그대로 파이프가 붙은 텍스트로 표시됩니다. 표가 그려지지 않을 때는 먼저 헤더 행과 구분 행의 열 수가 일치하는지 확인하세요.
GitHub의 [!NOTE] 알림을 다른 도구에서도 쓸 수 있나요?
기본적으로 GitHub.com(과 일부 이를 흉내 낸 서비스)에서만 동작합니다. GFM spec에는 알림 정의가 없으므로, 다른 마크다운 렌더러에서는 > [!NOTE]가 인용 블록 안의 텍스트로 그대로 표시됩니다.
Obsidian이나 Notion은 GFM 호환인가요?
완전 호환은 아닙니다. Obsidian은 CommonMark를 기반으로 GFM의 표와 체크박스도 지원하면서 [[wikilink]] 같은 독자 표기법을 갖고 있습니다. Notion도 독자 방언이며, 내보낼 때의 마크다운은 GFM 쪽이지만 에디터 안의 표기법은 Notion 고유입니다. 쓰기 전에 각 도구의 문서에서 지원 표기법을 확인하세요.
FormatArc는 어느 방언으로 변환하나요?
GFM 쪽입니다. Markdown to HTML 변환기는 marked를 gfm: true로 동작시키므로 표, 취소선, 체크박스, 자동 링크에 대응합니다. 문단 안의 줄바꿈은 <br>로 만들지 않습니다(CommonMark / GFM spec과 같음). GitHub.com 고유의 알림·이모지·mention·Mermaid·각주는 지원하지 않습니다.
정리
CommonMark는 마크다운의 표준 사양이고, GFM은 그 위에 5가지 확장(표, 취소선, 체크박스, 확장 자동 링크, raw HTML 제한)을 더한 방언입니다. GitHub.com에서 보던 알림과 이모지, @mention, Mermaid, 각주는 그 위에 얹힌 GitHub.com 고유의 레이어이며, GitHub 밖에서는 기본적으로 동작하지 않습니다.
어떤 방언으로 쓸지 고민될 때는 호환성 우선이면 CommonMark, GitHub 중심이면 GFM 확장까지, GitHub.com 고유 기능은 깨진다는 전제로, 라고 기억해 두면 곤란하지 않습니다. 내 마크다운이 GFM 확장에 의존하는지 확인하고 싶을 때나 마크다운을 HTML로 변환하고 싶을 때는 Markdown to HTML 변환기를 사용하세요. 브라우저만으로 끝나며, 회원가입도 업로드도 필요 없습니다.