Markdown 완벽 가이드 — CommonMark·GFM·AST·MDX·프로덕션 패턴

이 글의 범위

마크다운을 “문법만” 알고 쓰는 단계를 넘어, 파서가 무엇을 보장하는지, 중간 표현(AST)에서 무엇이 일어나는지, 확장은 어디에 끼워 넣는지, MDX가 왜 별도인지, 운영 환경에서 무엇을 고정해야 하는지를 정리합니다. Astro·Vite·React 계열과 Node 생태계의 unified / remark / rehype 관점을 기준으로 설명하되, 개념은 다른 구현에도 이식할 수 있습니다.

---

1. 파서 아키텍처: CommonMark와 GFM

1-1. 왜 “마크다운” 하나로 부르기 어렵나

오리지널 마크다운(2004)은 구현 세부사항이 모호했으며, 이로 인해 서로 다른 파서가 서로 다른 HTML을 만들었습니다. 이를 해소하기 위해 CommonMark가 등장했습니다. CommonMark는 문법을 명시하고, 블록/인라인 구조와 우선순위(precedence)를 규정하며, 정규화된 파싱 동작을 목표로 합니다.

GFM(GitHub Flavored Markdown)은 CommonMark를 기반으로 테이블, 취소선, 작업 목록(task list), 자동 링크 등을 추가한 방언(dialect)입니다. “표준 마크다운”이라는 표현은 이제 보통 CommonMark + 선택적 확장을 가리키는 경우가 많습니다.

1-2. 전형적인 파싱 파이프라인

대부분의 구현은 개념적으로 다음 단계를 따릅니다.

1. 전처리(선택): 줄바꿈 정규화, BOM 제거 등.
2. 블록 구조 파싱: 문서를 줄 단위로 훑으며 문단, 제목, 목록, 인용, 코드 펜스, HTML 블록 등 블록 트리를 만듭니다. 여기서 중첩 깊이·연속 블록의 병합 규칙이 구현마다 미묘하게 갈립니다(표준화의 이유).
3. 인라인 파싱: 각 블록 내부에서 강조, 링크, 코드 스팬, 이스케이프 등을 처리합니다. delimiter stack 같은 알고리즘이 쓰이기도 합니다.
4. AST 생성: 내부적으로는 DOM이 아니라 추상 구문 트리(또는 중간 표현)로 둡니다.
5. 직렬화: HTML, React 트리, 문자열 등으로 출력합니다.

실무 포인트: 동일한 .md라도 “CommonMark만”, “GFM”, “GFM + 수학(KaTeX)”처럼 프리셋을 바꾸면 결과 HTML이 달라집니다. 문서 팀에서는 파서 이름과 버전, 활성 확장 목록을 문서화하는 것이 좋습니다.

1-3. CommonMark가 강하게 고정하는 것

• 블록 경계: 빈 줄, 들여쓰기, 목록 마커 등에 따른 블록 시작/종료.
• 이스케이프와 코드 스팹: 백틱·별표·꺾쇠 등의 의미.
• HTML 블록 처리: 원시 HTML을 허용하는 범위(구현·플러그인에 따라 후속 단계에서 sanitize).

1-4. GFM이 추가로 건드리는 것

• 테이블: 파이프 테이블 문법과 정렬 구문(:--- 등).
• 취소선: ~~텍스트~~ (구현에 따라 strikethrough 노드).
• 작업 목록: - [ ] / - [x] 형태(출력 시 checkbox가 될 수 있음).
• autolink: URL·이메일 자동 감지.

---

2. AST 구조와 변환

2-1. AST가 필요한 이유

HTML로 바로 가도 되지만, 현대 도구는 중간에 AST를 두어 다음을 합니다.

• 콘텐츠 변환: 제목 ID 자동 부여, 외부 링크에 rel 추가, 코드 블록에 언어 라벨 검증.
• 교차 플랫폼: 동일 AST에서 HTML, PDF, React 트리로 분기.
• 린트: 금지 패턴(예: 이미지에 alt 누락) 검사.
• 보안: 특정 노드 제거/치환 후 직렬화.

2-2. mdast와 hast: 두 층의 트리

JavaScript 생태계의 unified에서는 흔히 다음을 구분합니다.

• mdast: Markdown AST. heading, paragraph, code, link 등 마크다운 의미 단위.
• hast: HTML AST. element, text, properties 등 HTML 구조 단위.

흐름은 보통 markdown → mdast(remark) → hast(rehype) → HTML 문자열입니다. 중간에 중간 표현을 바꾸는 것이 핵심입니다.

2-3. 변환 단계에서 자주 하는 작업

• remark 플러그인: heading 노드에 id 속성을 계산해 붙이거나, 링크를 상대 경로에서 절대 경로로 치환.
• rehype 플러그인: pre > code에 클래스명 규칙을 맞추거나, 외부 a에 target/rel 부여.
• 직렬화 옵션: HTML을 예쁘게 들여쓰기할지, 한 줄로 압축할지는 SEO보다는 디프·캐시·바이트 이슈에 영향을 줍니다.

2-4. AST 관점의 “함정”

• 원문 위치 정보(position): 소스맵·에러 메시지에 필요. 플러그인이 노드를 복제할 때 position이 어긋나면 린트 경고 줄 번호가 틀어질 수 있습니다.
• HTML 삽입: 마크다운 안의 원시 HTML은 hast로 흡수되는 과정에서 예상과 다른 부모-자식 관계가 될 수 있습니다. 이후 sanitize 단계와 상호작용합니다.

---

3. 확장 메커니즘

3-1. 문법 확장 vs 변환 파이프라인 확장

확장은 크게 두 갈래입니다.

1. 파서 수준 확장: GFM, front matter, footnote, 수식 등 문법 자체를 인식하게 만드는 것. micromark 기반의 확장(extension) 조합으로 구성되는 경우가 많습니다.
2. AST 변환 확장: 이미 트리가 생긴 뒤 노드 조작으로 기능을 얹는 것. 예: 모든 이미지를 figure로 감싸기.

둘 다 “플러그인”이라 부르지만 디버깅 난이도와 실패 모드가 다릅니다. 문법 확장은 토큰화/블록 규칙과 맞물려 엣지 경우가 생기으며, AST 변환은 노드 타입 가정이 깨지면 런타임 오류가 납니다.

3-2. micromark·mdast-util 계열의 역할

• micromark: 스트리밍에 가까운 저수준 토큰화/파싱 기반. 확장을 조합해 작고 예측 가능한 문법 추가를 목표로 합니다.
• mdast-util- 유틸*: 특정 노드 타입을 다루는 헬퍼(예: heading에서 텍스트 추출).

3-3. 커스텀 디렉티브·매크로

일부 팀은 :::note 같은 디렉티브나 짧은 매크로를 도입합니다. 이는 (1) 파서 확장으로 새 블록을 인식하거나, (2) 직전 전처리로 토큰을 치환하거나, (3) AST 이후에 특수 노드를 일반 노드로 바꾸는 방식으로 구현합니다.

실무 권장: 팀원이 많다면 단일 공식 확장 세트를 정하며, 개인별 프리프로세서 스크립트를 줄이는 편이 장기적으로 유지보수 비용이 낮습니다.

---

4. MDX 내부

4-1. MDX가 해결하려는 문제

MDX는 문서와 컴포넌트를 한 파일에서 결합하려는 요구에서 나왔습니다. 즉, “마크다운 → HTML”만이 아니라 JSX를 동일 파일에 두고, 빌드 시 자바스크립트 모듈로 취급하려는 것입니다.

4-2. 컴파일 경로(개념)

최신 MDX(예: MDX 3 계열)는 구현 세부가 버전마다 다르지만, 개념적으로는:

1. 파싱: MDX는 마크다운과 JSX를 동시에 이해하는 통합 파서가 필요합니다. JSX 구간은 자바스크립트 파서(예: acorn + 플러그인)로 들어갑니다.
2. AST 상에서의 혼합: MDX AST는 mdast와 ESTree 사이를 잇는 형태의 노드를 포함합니다(구현체명은 버전에 따름).
3. 변환: JSX는 실행 가능한 형태(예: _jsx 호출 트리)로 내려가고, 마크다운 쪽은 HTML/JSX 생성 코드와 합쳐집니다.
4. 번들러 통합: Vite/esbuild는 이 출력을 모듈 그래프에 넣습니다.

4-3. MDX에서 특히 신경 써야 할 점

• 컴포넌트 스코프: MDX 파일에서 쓰는 컴포넌트는 어디서 import되거나 전역 주입되는지 명확해야 합니다. Astro·Next 등 프레임워크마다 제공 방식이 다릅니다.
• 표현식과 보안: JSX 안에서 객체 리터럴, 함수 호출이 가능해지면, “문서”가 코드 실행에 가까워집니다. 신뢰할 수 없는 기여자의 MDX를 그대로 빌드에 넣는 것은 CI 정책·리뷰·샌드박스가 필요합니다.
• 프리프로세서와의 순서: front matter, import, export가 섞이면 파이프라인 순서가 틀어져 “빌드는 되는데 런타임에서 컴포넌트가 undefined” 같은 문제가 납니다.

4-4. “MDX vs remark만” 선택 기준

• MDX: 인터랙티브 데모, 짧은 컴포넌트 삽입, 디자인 시스템 문서.
• remark/rehype만: 순수 문서, HTML만으로 충분, 공격 면적 최소화.

---

5. 프로덕션 마크다운 패턴

5-1. 재현 가능한 빌드

• 락 파일로 remark/rehype/micromark 버전을 고정합니다.
• 프리셋을 코드로 명시합니다(예: “GFM + slug + autolink head”). README 한 줄이 아니라 설정 파일에 두는 것이 안전합니다.

5-2. 보안: XSS와 OEmbed

• 사용자 입력이 아니라도 서드파티 플러그인이 악성 script를 삽입할 수 있는지 검토합니다.
• rehype-sanitize 등으로 허용 태그/속성을 제한합니다. style, on* 이벤트 속성은 기본적으로 위험합니다.
• 임베드(iframe)는 도메인 화이트리스트를 고려합니다.

5-3. 성능

• 대형 문서에서는 플러그인 체인이 길수록 빌드 시간이 늘어납니다. 불필요한 구문 강조(clone/추가 AST 순회)를 줄입니다.
• 수천 개의 파일을 처리하는 SSG에서는 병렬 처리와 증분 빌드 전략이 중요합니다(도구별 지원 상이).

5-4. 품질: 린트와 스타일 가이드

• remark-lint 규칙으로 제목 레벨 스킵 금지, 링크 유효성 등을 강제합니다.
• 용어집·대소문자 규칙은 자동화가 어렵기 때문에 리뷰 체크리스트로 보완합니다.

5-5. 이식성

• 벤더 종속 문법(특정 위키의 매크로 등)을 쓰면 타 플랫폼 이전 비용이 큽니다. 장기 문서는 CommonMark + 소수 확장을 기준선으로 두는 편이 안전합니다.

---

정리

마크다운은 단순한 텍스트 형식이지만, CommonMark/GFM 같은 방언 선택, mdast→hast 변환, 파서 vs AST 플러그인, MDX의 JSX 컴파일 경로, 보안·재현성·린트를 이해해야 프로덕션급 문서 파이프라인을 설계할 수 있습니다. 팀에서는 “어떤 dialect와 플러그인 체인을 쓰는지”를 코드와 문서로 고정하며, 출력 HTML이 달라질 수 있는 지점을 리뷰와 CI로 관리하는 것이 좋습니다.

---

참고로 알아두면 좋은 키워드

• CommonMark 스펙, GFM 스펙
• unified, remark, rehype, mdast, hast
• micromark, mdast-util
• MDX 컴파일, acorn, esbuild
• rehype-sanitize, CSP(Content Security Policy)

이 키워드로 공식 문서와 구현체 소스를 읽으면, 사용 중인 프레임워크(Astro 등)의 기본 MD/MDX 설정을 더 정확하게 튜닝할 수 있습니다.

---

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. CommonMark와 GFM 파서 구조, AST·remark/rehype 변환, 확장 메커니즘, MDX 내부 동작, 문서 파이프라인 실무 패턴까지 마크다운의 내부와 운영을 한 번에 정리합니다. 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 또는 관련 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

---

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

• Babel 완벽 가이드 | 파서·AST·파이프라인·트랜스파일러·Presets·Plugins·실전
• Astro Content Collections 완벽 가이드 | 타입 안전·스키마·MDX·블로그 구축
• Astro View Transitions 심화 가이드 — 부드러운 페이지 전환과 MPA UX

---

이 글에서 다루는 키워드 (관련 검색어)

Markdown, 가이드, CommonMark·GFM·AST·MDX·프로덕션 등으로 검색하시면 이 글이 도움이 됩니다.