블로그로 돌아가기
Reference 2026-04-26

마크다운 플레이버 비교: CommonMark, GFM, MDX

문서, 블로그, 콘텐츠 관리에 맞는 마크다운 플레이버 선택.

마크다운은 하나의 언어가 아니라, 우연히 같은 성을 쓰는 방언들의 가족입니다. John Gruber의 2004년 원본은 Perl 스크립트와 비공식 설명이었고, 핵심 질문들을 미해결로 남겼습니다. 강조 마커는 어떻게 중첩되는가? 들여쓰기 몇 칸이 목록 항목을 이어가는가? 중첩 블록 앞에 빈 줄이 필요한가? 모든 구현이 서로 다르게 답했고, 그래서 같은 문서가 세 플랫폼에서 세 가지로 렌더링될 수 있습니다. 주요 플레이버를, 그리고 여러분의 툴체인이 실제로 어떤 것을 말하는지 이해하면 포맷팅 서프라이즈라는 버그 계급 전체가 사라집니다.

CommonMark: 공식 기준선

CommonMark(2014, Pandoc으로 유명한 John MacFarlane 주도)는 비공식 설명을 600개 이상의 적합성 예제와 두 개의 레퍼런스 구현(C의 cmark, commonmark.js)을 갖춘 엄밀한 사양으로 바꿨습니다. 파서마다 달랐던 모호함을 정확히 고정합니다.

  • 정확한 강조 규칙: 구분자가 강조를 여는지 닫는지는 좌우 플랭킹 구분자 런으로 결정됩니다. 단어 내부의 별표 쌍은 기울임이 되지만 공백으로 둘러싸인 별표는 문자 그대로 남는 이유입니다
  • 목록 연속: 콘텐츠가 항목의 콘텐츠 열까지 들여쓰기되면 그 항목 소속. 마법의 4칸이 아님
  • 각자 시작·종료 조건을 가진 7가지 HTML 블록 유형
  • 우선순위: 링크 문법이 강조를 이기고, 코드 스팬이 모든 인라인을 이김

콘텐츠가 여러 도구에서 동일하게 렌더링되어야 한다면 CommonMark에 맞춰 쓰고, 그것이 정의하지 않는 것은 피하세요.

1단계 제목


=========
__굵게__ 와 _기울임_ 과 코드

[링크](https://example.com)
1. 순서 있는 항목


   콘텐츠 열까지 들여쓴 연속 문단

GFM: CommonMark에 개발자 필수 기능을 더한 것

GitHub Flavored Markdown은 공식적으로 엄격한 상위집합입니다. GitHub은 이를 CommonMark에 정확히 다섯 개의 확장(테이블, 작업 목록 항목, 취소선, 자동 링크, 위험한 원시 HTML 태그를 제거하는 tagfilter)을 더한 사양으로 발행합니다. 각주, 이모지 숏코드, 멘션은 GFM 사양이 아니라 그 위에 얹힌 GitHub 플랫폼 기능입니다. 다른 "GFM 호환" 렌더러가 각주를 거부할 때 중요한 차이입니다.

|컬럼|타입|


|----|----|


|id  |int |
* [x] 배포됨


* [ ] 대기 중
~~폐기됨~~ 그리고 https://autolinked.example.com

미묘한 차이 하나: .md 파일에서 GitHub은 사양대로 단일 개행을 소프트 브레이크로 처리하지만, 이슈와 댓글에서는 단일 개행이 하드 라인 브레이크가 됩니다. 두 컨텍스트 사이에 텍스트를 복사하면 렌더링이 달라집니다.

MDX: 컴파일되는 마크다운

MDX는 마크업 방언이라기보다 컴파일 타깃입니다. 각 파일이 ES 모듈이 됩니다. 컴포넌트를 임포트하고, 값을 익스포트하고, JSX를 삽입하고, 표현식을 인라인 평가할 수 있습니다.

import { Chart } from '../components/Chart';


export const data = [4, 8, 15, 16];
합계는 {data.reduce((a, b) => a + b, 0)} 입니다.
<Chart values={data} />

이 힘에는 실질적 비용이 따릅니다. 원시 HTML이 더 이상 통과하지 못합니다. 꺾쇠괄호 콘텐츠는 JSX로 파싱되므로 class는 className이 되어야 하고, <br> 같은 닫히지 않은 태그는 문법 오류이며, 떠도는 { 하나가 표현식을 시작합니다. 문서 하나의 빌드 에러가 사이트 전체 빌드를 깨뜨릴 수 있고, 비개발자 기여자는 마크다운을 매력적으로 만들었던 "그냥 텍스트"라는 보장을 잃습니다. 문서에 정말로 라이브 컴포넌트가 필요할 때(인터랙티브 문서, 디자인 시스템) MDX를, 모두가 쓰고 리뷰해야 할 때 GFM을 선택하세요.

더 넓은 가족

  • Pandoc Markdown — 학술계의 강자: 인용, 수식, 정의 목록, 속성 블록, LaTeX·DOCX 등으로의 변환.
  • Djot — 마크다운의 파싱 사마귀를 제거한 MacFarlane의 포스트 CommonMark 실험(게으른 연속 없음, 들여쓰기 모호성 없음). 주목할 가치는 있으나 아직 주류는 아님.
  • markdown-it, remark, goldmark, comrak — 파서 계층. remark는 문서를 플러그인 파이프라인이 있는 AST로 노출하며(MDX와 대부분의 React 문서 프레임워크의 기반), goldmark는 Hugo를 구동하고, comrak은 Rust GFM 구현입니다.

보안 노트

마크다운의 원시 HTML 통과는 사용자 제출 마크다운이 기본적으로 XSS 벡터라는 뜻입니다. 신뢰할 수 없는 입력의 렌더링 파이프라인에는 렌더링 후 살균이 필요합니다. HTML 출력에 rehype-sanitize나 DOMPurify를 적용하세요. 마크다운 소스에 대한 정규식 필터링은 확실하게 우회 가능합니다.

선택

  • README, 위키, 팀 문서: GFM
  • 인터랙티브 문서 사이트: MDX (Docusaurus, Astro, Next.js)
  • 렌더러 간 최대 이식성: 엄격한 CommonMark
  • 학술·인쇄 지향 글쓰기: Pandoc

프런트 매터와 수식

너무 흔해서 핵심 마크다운처럼 느껴지지만 어느 사양에도 속하지 않는 확장이 둘 있습니다. YAML 프런트 매터 — 파일 상단 --- 펜스 사이의 메타데이터 — 는 Jekyll이 대중화한 정적 사이트 관례입니다. 플러그인이 제거하지 않으면 CommonMark 파서는 이를 주제 구분선과 뒤따르는 텍스트로 취급합니다. 수식도 비슷합니다. $x^2$ 스팬과 $$...$$ 블록은 remark-math, markdown-it-texmath, 또는 플랫폼 측 KaTeX/MathJax 렌더링으로 처리되며, 공백과 이스케이프를 둘러싼 구분자 규칙이 조금씩 다릅니다. 두 기능 모두 플러그인 없는 렌더러에서는 조용히 눈에 보이는 쓰레기로 강등되므로, 파이프라인이 어떤 확장을 켰는지 문서화하세요. 저장소 README의 한 줄이 "왜 메타데이터가 그대로 보이나요" 버그 리포트 대부분을 예방합니다.

sdk.is/markdown-editor 의 마크다운 에디터로 쓰면서 문서가 어떻게 렌더링되는지 미리 확인하세요.