빠른 비교
| 범위 | 대표 기능 | 이식성 |
|---|---|---|
| CommonMark | heading, paragraph, list, code fence, link | 가장 높음 |
| GFM extension | table, task list, strikethrough, footnote, autolink 확장 | GitHub 계열에서 강함 |
| 사이트별 extension | admonition, Mermaid, custom component | 렌더러 의존 |
| MDX | JSX component, expression, import/export | 빌드 파이프라인 의존 |
호환성 기준
CommonMark는 공통 기반이고 GFM은 GitHub의 확장 dialect다
CommonMark는 Markdown 문법을 예측 가능하게 만들기 위한 공통 규격이다. GitHub Flavored Markdown(GFM)은 CommonMark를 기반으로 하면서 GitHub user content에서 쓰는 확장 기능을 더한 dialect다. 따라서 GitHub에서 잘 보이는 문법이 순수 CommonMark 렌더러에서도 그대로 동작한다고 가정하면 안 된다.
CommonMark 중심 문법
- # Heading
- - List
- [Link](url)
- ```js code fence ```
GFM 확장 문법
- tables
- task list items
- strikethrough
- extended autolinks표, task list, 취소선은 GFM 확장으로 봐야 한다
실무 문서에서 자주 쓰는 표, 체크박스 목록, ~~취소선~~은 GitHub에서는 자연스럽게 렌더링되지만 CommonMark 표준 핵심 문법은 아니다. GitHub README, issue, PR 설명처럼 GitHub 안에서 소비되는 문서에는 적합하다. 반면 PDF 변환, 다른 정적 사이트 빌더, 사내 위키로 옮길 문서라면 렌더러의 GFM 지원 여부를 먼저 확인해야 한다.
raw HTML은 보안 후처리와 렌더러 정책을 같이 본다
CommonMark와 GFM 모두 raw HTML을 다룰 수 있지만, 실제 플랫폼은 보안과 일관성을 위해 sanitize 단계를 둘 수 있다. GitHub도 GFM을 HTML로 변환한 뒤 추가 후처리와 sanitization을 수행한다. 따라서 <script>, inline style, 특정 HTML 속성처럼 보안에 민감한 표현은 Markdown 원본에 있어도 렌더링 결과에서 제거될 수 있다.
확장 문법을 쓰면 fallback을 같이 설계해야 한다
문서가 GitHub 밖에서도 읽혀야 한다면 확장 문법을 쓸 때 fallback을 둔다. 표가 지원되지 않는 환경에서는 짧은 bullet 목록으로 바꿀 수 있는지, task list가 체크박스로 렌더링되지 않아도 의미가 전달되는지, 취소선이 그대로 노출돼도 독자가 이해할 수 있는지 확인해야 한다.
선택 기준
| 상황 | 우선 문법 |
|---|---|
| 여러 렌더러에서 읽힐 문서 | CommonMark 중심 |
| GitHub README, issue, PR | GFM 적극 사용 |
| 정적 사이트로 배포 | 빌드 파이프라인의 plugin 확인 |
| PDF/Word 변환 | CommonMark + 변환기 지원 기능 |
| 문서가 이동할 가능성이 큼 | 확장 문법 최소화 |
공식 참고: CommonMark Spec, GitHub Flavored Markdown Spec
주의할 점
GitHub에서 잘 렌더링된다는 사실은 Markdown 표준 호환성을 의미하지 않습니다. 표, task list, footnote, Mermaid, alert 같은 기능은 대상 렌더러가 지원하는지 확인하고 이동 가능한 문서에는 fallback을 남기는 편이 안전합니다.
실패 예시
- GitHub README의 task list와 alert를 그대로 사내 위키로 옮김
- 결과: 체크박스와 alert 스타일이 사라지고 원문 기호만 노출됨
- 대응: CommonMark 중심 표현으로 바꾸거나 위키 렌더러의 확장 지원을 먼저 확인한다참고 링크
2 sources