GFM vs CommonMark vs Pandoc Markdown: 구문 비교

마크다운(Markdown)은 같은 파일이 GitHub, Hugo, Obsidian, Pandoc에서 각각 다르게 렌더링될 때까지 하나의 언어처럼 보입니다. 그리고 이 문제는 마크다운이 신뢰할 수 없기 때문이 아닙니다.

“마크다운"은 단일한 보편적인 문서 포맷이 아니라 서로 연관된 구문, 파서, 플랫폼 기능들의 집합을 기술하기 때문입니다. CommonMark는 정확한 이식 가능한 코어를 정의하고, GitHub Flavored Markdown(GFM)은 소프트웨어 협업에 유용한 기능들을 추가하며, Pandoc Markdown은 이 언어를 심각한 문서 작성 포맷으로 확장합니다.

이 중 하나를 선택하는 것은 문서가 어디서 렌더링되어야 하는지에 따라 달라집니다. README 파일, Hugo 블로그 글, 학술 논문은 각각 다른 요구 사항을 가지고 있습니다. 이 비교는 더 넓은 문서 도구의 일부로 포맷화된 변종, 플랫폼별 확장 기능, 실용적인 이식성 규칙을 다루며 대상 환경에 적합한 구문을 선택할 수 있도록 돕습니다. 빠른 구문 참고를 위해, 마크다운 치트시트는 필수적인 포맷 요소들을 다루고 있습니다.

마크다운은 하나의 언어가 아닙니다

원본 마크다운 구문은 의도적으로 작고 느슨하게 지정되었습니다. 이로 인해 읽고 구현하기는 쉬웠지만, 서로 다른 파서들은 모호한 입력을 다르게 해석하기 시작했습니다.

CommonMark는 근본적인 마크다운 구조에 대한 일관된 파싱 규칙을 정의하기 위해 생성되었습니다. GitHub Flavored Markdown(GFM)은 널리 사용되는 여러 확장 기능을 기반으로 이 기초 위에서 구축됩니다.

Pandoc Markdown은 다른 접근 방식을 취합니다. 작은 웹 중심의 구문으로 남아 있지 않고, 인용, 메타데이터, 각주, 정의 목록, 속성, 수학적 표기법과 같은 문서 기능을 추가합니다.

간소화 된 관계도는 다음과 같습니다:

이 계층 구조는 유용하지만, 모든 구현에서 정확한 상속은 아닙니다. 각 렌더러는 독립적으로 구문을 활성화, 비활성화 또는 추가할 수 있습니다.

간결한 답변

이식성이 가장 중요한 경우에는 CommonMark 호환 구문을 사용하세요.

README 파일, 풀 리퀘스트, 이슈 템플릿 및 주로 GitHub 호환 플랫폼을 대상으로 한 기술 문서를 작성할 때는 GFM을 사용하세요.

소스 문서가 PDF, DOCX, EPUB, LaTeX, 슬라이드 또는 인용과 메타데이터를 갖춘 학술 논문으로 변환되어야 하는 경우에는 Pandoc Markdown을 사용하세요.

Hugo 기술 블로그의 경우, 사이트에서 명시적으로 활성화한 Goldmark 확장 기능과 함께 CommonMark 코어를 사용하세요. GitHub에서 볼 수 있는 모든 기능이 Hugo가 GFM 호환이라고 설명되었다는 이유만으로 작동한다고 가정하지 마세요.

개인적인 의견: Hugo 기술 블로그에 대해 하나만 기억할 규칙이 있다면, CommonMark와 GFM 스타일의 표 및 작업 목록을 기본값으로 간주하고, 그 외의 모든 것 — 각주, 수학, 콜아웃, 헤더 속성 — 은 가정된 기본값이 아닌 명시적이고 테스트된 확장 기능으로 간주하세요. 이 하나의 습관이 아래에 설명된 대부분의 이식성 실패를 방지합니다.

CommonMark: 이식 가능한 코어

CommonMark는 기본 마크다운 언어에 대한 공식 규격입니다. 그 주요 공헌은 큰 규모의 기능 모음이 아니라 일관된 파싱입니다.

파서가 다음과 같이 해석해야 하는지 정의합니다:

• 단락
• ATX 및 Setext 헤딩
• 블록 인용
• 번호 목록 및 비번호 목록
• 고정(fenced) 및 들여쓰기 코드 블록
• 강조 및 강한 강조
• 링크 및 이미지
• 참조 스타일 링크
• 인라인 코드
• 테마틱 브레이크
• Raw HTML 블록
• 하드 및 소프트 줄바꿈

CommonMark 문서는 여전히 프레젠테이션 계층에서 다르게 작동할 수 있습니다. CSS, 구문 하이라이팅, 헤딩 앵커, HTML_SANITIZE 및 링크 정책은 코어 파싱 규칙의 범위를 벗어납니다.

따라서 CommonMark는 모든 렌더러가 동일한 페이지를 생성한다는 약속이 아니라, 신뢰할 수 있는 구조적 기준으로 여겨져야 합니다.

이식 가능한 CommonMark 예시

# 서비스 배포

이 서비스는 작은 HTTP API를 노출합니다.

## 요구 사항

- Linux
- Docker
- 8 GB의 메모리

## 서비스 시작

```bash
docker compose up -d
```

자세한 내용은 [구성 가이드](configuration.md)를 참고하세요.

이 유형의 문서는 거의 모든 현대적인 마크다운 환경에서 작동합니다. 변종별 확장 기능에 의존하지 않고 헤딩, 단락, 목록, 고정 코드, 일반 링크를 사용합니다.

GitHub Flavored Markdown: 소프트웨어 프로젝트용 CommonMark

GitHub Flavored Markdown은 CommonMark를 기반으로 한 공식 변종입니다. CommonMark 파싱 모델을 보존하고, 레포지토리 문서화 및 협업에서 흔히 필요한 기능들을 추가합니다.

공식 GFM 규격은 다음을 추가합니다:

• 파이프 표
• 작업 목록 항목
• 취소선
• 확장된 자동 링크
• 일부 Raw HTML 태그에 대한 제한

이러한 확장 기능은 이제 매우 흔하여 많은 사용자가 표준 마크다운의 일부인 것으로 생각하지만, CommonMark 코어의 일부는 아닙니다.

GFM 표

| 백엔드 | 최적의 용도 |
|---|---|
| Ollama | 로컬 실험 |
| vLLM | 공유 추론 |
| SGLang | 구조화된 워크로드 |

엄격한 CommonMark 파서는 이를 일반 단락 텍스트로 처리할 수 있습니다. GFM 호환 파서는 이를 표로 인식합니다. 표 구문 및 정렬 옵션에 대한 더 깊은 이해를 위해 마크다운의 표를 참조하세요.

GFM 작업 목록

- [x] Docker 설치
- [x] 모델 다운로드
- [ ] 모니터링 추가

작업 목록 구문은 이슈, 풀 리퀘스트, 프로젝트 문서에서 유용합니다. 지원하는 렌더러가 아닌 경우, 리터럴 괄호가 포함된 일반 목록으로 나타날 수 있습니다.

GFM 취소선

~~오래된 엔드포인트~~ 새로운 엔드포인트를 사용하세요.

취소선은 널리 지원되지만, 여전히 이식 가능한 CommonMark 구문이 아닌 확장 기능입니다.

GFM 자동 링크

GFM은 각괄호나 명시적인 링크 구문을 필요로 하지 않고 더 많은 URL 형태 및 이메일 형태의 텍스트를 인식합니다.

자세한 내용은 https://example.com/docs을 방문하세요.

엄격한 CommonMark에서는 명시적인 자동 링크에 각괄호를 사용합니다:

<https://example.com/docs>

문서가 알려진 마크다운 프로세서 없이 이동해야 할 경우, 명시적인 형태가 더 안전합니다.

GitHub.com은 공식 GFM보다 더 많은 기능을 지원합니다

흔한 혼동의 원인은 GitHub에서 볼 수 있는 모든 마크다운 기능이 GFM 규격에 속한다고 가정하는 것입니다.

그렇지는 않습니다.

GitHub.com은 GFM 파서 주위에 플랫폼 수준의 처리 및 기능을 추가합니다. 컨텍스트에 따라 GitHub는 다음을 지원할 수 있습니다:

• 수학적 식
• Mermaid 다이어그램
• 알림(Alerts)
• 이슈 및 풀 리퀘스트 참조
• 사용자 및 팀 멘션
• 커밋 참조
• 이모지 쇼트코드
• 접히기 쉬운 HTML 섹션
• 색상 미리보기
• 레포지토리 상대 링크
• 자동 헤딩 앵커

이러한 기능 중 일부는 구문 확장입니다. 다른 일부는 후처리 동작 또는 GitHub 데이터와의 통합입니다.

다른 렌더러가 GitHub의 수학 렌더러, Mermaid 통합, 이슈 참조 또는 알림 스타일링을 구현하지 않고도 GFM 호환임을 정확히 주장할 수 있기 때문에 이 구분이 중요합니다.

GitHub Mermaid 다이어그램

GitHub는 mermaid로 표시된 고정 코드 블록을 다이어그램으로 렌더링합니다:

```mermaid
flowchart LR
    A[Markdown] --> B[Rendered diagram]
```

일반적인 GFM 렌더러는 동일한 블록을 하이라이트된 소스 코드로 표시할 수 있습니다. 마크다운은 여전히 유효하지만, 향상된 렌더링은 플랫폼 특유의 것입니다. Mermaid 구문에 대한 실용적인 입문으로, Mermaid 다이어그램 빠른 시작를 참조하세요.

GitHub 수학적 식

GitHub는 달러 기호 구분자 및 추가 탈출 형태를 사용하여 인라인 및 블록 수학적 식을 지원합니다.

캐시 크기는 대략 $2nlhd$ 바이트입니다.

$$
C = 2nlhd
$$

수학은 공식 GFM의 일부가 아닙니다. 이러한 내용을 다른 렌더러로 이동하려면 KaTeX, MathJax 또는 Pandoc 수학 지원과 같은 호환 가능한 수학 확장 기능이 필요합니다.

GitHub 알림(Alerts)

GitHub는 다음과 같은 알림 스타일 블록 인용을 지원합니다:

> [!WARNING]
> 이 설정을 변경하면 캐시가 정리됩니다.

GitHub에서는 스타일링된 경고로 나타날 수 있습니다. 단순한 CommonMark 렌더러에서는 [!WARNING]이 포함된 일반 블록 인용으로 나타나는 것이 일반적입니다.

이러한 폴백은 읽기 쉬우므로 GitHub 알림은 완전히 사라지는 확장 기능보다 덜 위험합니다. 여전히 이식 가능한 프레젠테이션 요소는 아닙니다.

Pandoc Markdown: 문서 언어로서의 마크다운

Pandoc Markdown은 특정 웹사이트가 아닌 문서 변환을 위해 설계되었습니다. HTML, PDF, DOCX, EPUB, LaTeX, 프레젠테이션 및 기타 포맷을 생성하기 위한 소스 구문으로 마크다운을 사용합니다.

기본 마크다운 리더는 큰 확장 세트입니다. 주요 기능은 다음과 같습니다:

• YAML 메타데이터 블록
• 각주
• 인용
• 여러 표 형식
• 정의 목록
• 수학적 표기
• 헤딩 식별자 및 속성
• 코드 블록 속성
• 고정 구분(fenced divisions)
• 괄호 spans
• 위첨자 및 아래첨자
• 취소선
• 라인 블록
• 번호 매김된 예시 목록
• Raw LaTeX
• Raw HTML
• 자동 섹션 번호 매김
• 참고문헌 처리

Pandoc Markdown은 CommonMark나 공식 GFM보다 훨씬 표현력이 풍부합니다. 이 표현력은 출판에 강력하지만, 교환 포맷으로서 덜 안전합니다.

Pandoc 각주

마크다운에는 여러 개의 호환되지 않는 변종이 있습니다.[^dialects]

[^dialects]: CommonMark, GFM, Pandoc Markdown은 세 가지 중요한
    예시입니다.

각주 구문은 많은 현대 도구에 의해 지원되지만, CommonMark나 공식 GFM의 일부는 아닙니다.

GitHub는 현재 여러 콘텐츠 컨텍스트에서 각주를 렌더링하지만, 이는 공식 GFM 보증이 아닌 GitHub 플랫폼 기능입니다. CommonMark 또는 GFM 호환성만을 주장하는 렌더러는 이를 지원하지 않을 수 있습니다.

Pandoc 인용

PagedAttention은 KV 캐시 메모리 관리에 대해 개선합니다
[@kwon2023pagedattention].

참고문헌 파일 및 인용 스타일이 있으면, Pandoc은 이를 포맷된 학술 인용 및 참고문헌으로 해석할 수 있습니다.

pandoc article.md \
  --citeproc \
  --bibliography references.bib \
  --csl ieee.csl \
  -o article.pdf

인용 구문은 지원하지 않는 렌더러에서도 읽기 쉽게 남아 있지만, Pandoc 또는 다른 호환 가능한 인용 프로세서가 없으면 포맷된 참조가 되지 않습니다. Pandoc의 리더 측 유연성은 반대 방향의 변환 워크플로우의 기반을 형성하기도 합니다 — Pandoc의 확장된 변종을 중간 포맷으로 사용하는 실용적인 예로 Word 문서에서 마크다운으로 변환을 참조하세요.

Pandoc 정의 목록

CommonMark
: 핵심 마크다운에 대한 정확한 규격.

GFM
: 소프트웨어 지향적 확장 기능이 있는 CommonMark 기반 변종.

Pandoc Markdown
: 문서 변환을 위한 확장된 작성 포맷.

정의 목록은 수동, 사전, 기술 서적에서 유용합니다. 지원하지 않는 렌더러에서는 일반적으로 열선점들이 순수 텍스트로 가시적으로 남아 있기 때문에 성능 저하가 큽니다.

Pandoc 헤더 속성

## 캐시 구성 {#cache-config .deployment}

Pandoc은 중괄호를 명시적인 식별자 및 클래스 목록으로 해석합니다. 다른 많은 마크다운 렌더러는 속성 텍스트를 헤딩에 직접 표시합니다.

이것은 모든 곳에서 렌더링되도록 예상되는 문서에 놓아서는 안 되는 유용한 구문의 가장 명확한 예시 중 하나입니다.

Pandoc 고정 구분(Fenced Divisions)

::: warning
이 옵션을 변경하면 서버가 다시 시작됩니다.

Pandoc은이를 클래스가 있는 구조적 구분으로 변환합니다. 템플릿, CSS, 필터 또는 출력 작성자는 그 구조가 어떻게 나타날지 결정할 수 있습니다.

대부분의 CommonMark 및 GFM 렌더러는 이 페ンス(fence)를 인식하지 않습니다. 그들은 콜론과 내용을 일반 텍스트로 표시합니다.

CommonMark 대 GFM 대 Pandoc Markdown

다음 행렬은 GitHub.com, Hugo, Obsidian, GitLab 또는 다른 플랫폼이 추가한 모든 기능이 아닌, 공식 변종들을 기술합니다.

“No"라는 단어는 플랫폼이 절대 해당 기능을 지원하지 않는다는 의미가 아닙니다. 해당 기능이 그 변종의 공식 규격에 의해 보장되지 않는다는 의미입니다.

GitHub에서 어떤 구문이 작동합니까?

README 파일, 이슈, 풀 리퀘스트, 토론, 위키의 경우, GFM이 자연스러운 기준선입니다.

일반적으로 다음을 사용할 수 있습니다:

• CommonMark 구문
• 표
• 작업 목록
• 취소선
• 확장된 자동 링크
• 구문 하이라이팅된 코드 페ンス
• GitHub 특유의 참조
• GitHub 지원 수학
• GitHub 지원 다이어그램
• GitHub 알림
• 콘텐츠 표면에서 지원되는 경우의 각주

이식성 위험은 GitHub가 공식 GFM을 넘어 추가 렌더링을 수행할 때 시작됩니다. Mermaid 다이어그램, 수학적 표기, 이슈 참조, 알림 프레젠테이션은 GitHub 외부에서 생존하지 못할 수 있습니다.

그 밖의 곳에 게시되는 레포지토리 파일의 경우, GitHub 미리보기를 권위 있는 것으로 취급하기보다는 두 번째 렌더러에서 소스를 테스트하세요.

Hugo에서 어떤 구문이 작동합니까?

Hugo는 기본 마크다운 렌더러로 Goldmark를 사용합니다. Goldmark는 CommonMark에 준수하며 GFM의 중요한 부분과 호환되는 확장 기능을 제공합니다.

전형적인 Hugo 구성에서, 다음이 잘 작동합니다:

• CommonMark 구조
• 고정 코드 블록
• 파이프 표
• 취소선
• 작업 목록
• 자동 헤딩 ID
• 구문 하이라이팅
• 확장 기능이 활성화된 경우의 각주
• 활성화된 경우의 정의 목록
• 활성화된 경우의 타이포그래피 치환

Hugo는 마크다운 외부의 기능을 다음을 통해 추가합니다:

• 프론트 매터
• 쇼트코드
• 렌더 훅
• 페이지 리소스
• 내부 참조 함수
• 템플릿 처리
• 사이트 구성

이러한 Hugo 기능은 마크다운 파일과 함께 이동하지 않습니다. Hugo 배포에 대한 실용적인 예로, Hugo를 AWS S3에 배포하기를 참조하세요.

Hugo 프론트 매터는 마크다운 콘텐츠가 아닙니다

Hugo 페이지는 일반적으로 YAML, TOML 또는 JSON 메타데이터로 시작합니다:

---
title: "마크다운 호환성"
description: "마크다운 변종 및 렌더러 비교."
date: 2026-07-31
tags:
  - Markdown
  - documentation
---

Pandoc도 YAML 메타데이터 블록을 인식할 수 있지만, 자체 템플릿 및 작성자에 따라 필드를 해석합니다. GitHub는 일반적으로 블록을 YAML 유사 섹션으로 표시하거나 특정 시스템에서만 레포지토리 메타데이터로 처리합니다.

따라서 동일한 구문은 동일한 의미를 가지지 않으면서도 여러 도구에서 인식될 수 있습니다.

Hugo의 Raw HTML

표준 Hugo 구성에서 Goldmark는 기본적으로 잠재적으로 위험한 Raw HTML을 렌더링하지 않습니다.

다음과 같은 블록은:

<div class="notice">
  이 값을 변경한 후 서비스를 다시 시작하세요.
</div>

Raw HTML 렌더링이 활성화되거나 콘텐츠가 쇼트코드 또는 렌더 훅을 통해 구현되지 않는 한 생략될 수 있습니다.

관리되는 기술 블로그의 경우, Raw HTML을 활성화하는 것은 합리적일 수 있습니다. 여전히 소스의 이식성을 낮추므로 의도적인 사이트 수준의 결정이어야 합니다.

Hugo의 Mermaid

고정된 mermaid 블록은 Hugo 테마, 렌더 훅, 쇼트코드 또는 JavaScript 파이프라인이 이를 다이어그램으로 변환하지 않는 한 여전히 코드 블록일 뿐입니다.

따라서 GitHub와 Hugo는 완전히 다른 렌더링 메커니즘을 사용하면서 동일한 Mermaid 소스를 받아들일 수 있습니다.

Pandoc에서 어떤 구문이 작동합니까?

Pandoc은 여러 마크다운 변종을 명시적으로 읽을 수 있습니다:

pandoc --from=markdown input.md
pandoc --from=commonmark input.md
pandoc --from=gfm input.md
pandoc --from=commonmark_x input.md

이것은 Pandoc의 가장 유용한 이식성 기능 중 하나입니다. 운영자는 모호한 .md 파일 확장자에 의존하기 대신 Pandoc에 소스가 사용한다고 주장하는 변종을 알려줄 수 있습니다.

Pandoc은 개별 확장 기능을 활성화하거나 비활성화할 수도 있습니다:

pandoc \
  --from=markdown-footnotes-pipe_tables \
  input.md \
  -o output.html

또는 더 좁은 포맷에서 시작하여 한 기능을 추가합니다:

pandoc \
  --from=commonmark+footnotes \
  input.md \
  -o output.html

다음으로 사용 가능한 확장 기능을 검사할 수 있습니다:

pandoc --list-extensions=markdown
pandoc --list-extensions=commonmark
pandoc --list-extensions=gfm

이 확장 모델은 강력하지만, “Pandoc Markdown"이 항상 하나의 고정된 구성이 아니라는 것을 의미합니다. 빌드 명령 및 기본값 파일은 문서 규격의 일부입니다.

Obsidian에서 어떤 구문이 작동합니까?

Obsidian은 노트를 마크다운 파일로 저장하지만, 작성 모델에는 여러 애플리케이션 특유의 기능이 포함되어 있습니다.

공통적인 예시는 다음과 같습니다:

• 위키 링크
• 임베드 노트
• 임베드 파일
• 콜아웃
• 블록 참조
• 태그
• 속성
• 하이라이팅
• 주석
• 플러그인에서 Dataview 쿼리
• 애플리케이션 특유의 URI 링크

다음과 같은 위키 링크는:

[[마크다운 호환성]]

Obsidian 볼트 내에서 의미론적입니다. GitHub, CommonMark 및 기본 Pandoc 리더는 일반적으로 이를 리터럴 괄호 텍스트로 표시합니다.

임베드는 더 애플리케이션 특유의 것입니다:

![[compatibility-table]]

참조된 콘텐츠는 파일 자체에 존재하지 않습니다. 따라서 노트를 내보내거나 게시하려면 임베드를 해석하는 확장이 필요합니다.

Obsidian은 .md 파일에 저장하더라도 마크다운 이식성이 보장되지 않는 이유의 좋은 예시입니다. 지식 관리 도구로서의 Obsidian에 대한 실용적인 시각으로, 개인 지식 관리를 위한 Obsidian을 참조하세요.

GitLab에서 어떤 구문이 작동합니까?

GitLab Flavored Markdown은 코어로 CommonMark를 사용하고, 표 및 작업 목록과 같은 GFM 기능을 포함합니다. 그 다음 교차 참조, 수학적 표기, 다이어그램 및 기타 협업 기능과 같은 GitLab 특유의 동작을 추가합니다.

보수적인 GFM으로 작성된 README는 일반적으로 GitHub와 GitLab 사이에서 주요 손상 없이 이동합니다.

플랫폼 통합은 그렇게 신뢰할 수 없이 이동하지 않습니다. 이슈 참조, 사용자 멘션, 다이어그램, 수학 처리 및 특수 블록 구문은 기본 마크다운이 읽기 쉽더라도 다르게 작동할 수 있습니다.

플랫폼 지원 행렬

이 행렬은 일반적인 기본 동작을 기술합니다. 테마, 플러그인, 확장 기능 및 구성은 개별 셀을 변경할 수 있습니다.

“Yes"는 여전히 동일한 HTML 또는 시각적 프레젠테이션을 보장하지 않습니다. 환경이 일반 기능을 인식한다는 의미입니다.

대체로 모든 곳에서 안전한 구문

가장 안전한 이식 가능한 부분 집합에는 다음이 포함됩니다:

• #를 사용하는 ATX 헤딩
• 일반 단락
• 블록 간 빈 줄
• 비번호 목록을 위한 -
• 번호 목록을 위한 1.
• 백틱을 사용하는 고정 코드 블록
• 백틱을 사용하는 인라인 코드
• *text*를 사용하는 강조
• **text**를 사용하는 강한 강조
• 일반 링크
• 일반 이미지
• 블록 인용
• 테마틱 브레이크
• 명시적인 각괄호 자동 링크

의도적으로 보수적인 문서는 다음과 같이 보일 수 있습니다:

# 배포 가이드

이 가이드는 서비스를 배포하는 방법을 설명합니다.

## 요구 사항

- Docker
- Linux
- 지원되는 GPU

## 구성

`compose.yaml`이라는 이름의 파일을 생성하세요.

```yaml
services:
  application:
    image: example/application:1.0
```

자세한 내용은 [구성 참조](config.md)를 확인하세요.

> 업그레이드하기 전에 기존 데이터를 백업하세요.

이 구문은 표, 각주, 속성, 콜아웃 또는 플랫폼 처리에 의존하지 않기 때문에 잘 이동됩니다.

일반적으로 깨지는 구문

이식성 문제는 소수의 기능 주위에 집중되는 경향이 있습니다.

파이프 표

파이프 표는 GFM 지향 도구에 의해 잘 지원되지만, 엄격한 CommonMark에는 지원되지 않습니다.

파서가 이를 인식하지 못할 때 표는 읽을 수 없는 텍스트로 저하될 수 있습니다. highly 이식 가능한 문서의 경우, 짧은 목록이나 빌드 단계에서 생성되는 의미론적 HTML을 고려하세요.

각주

각주 구문은 보편적이 되었지만, 여전히 확장 기능입니다.

서로 다른 도구는 다음을 수행할 수 있습니다:

• 하나의 각주 형식만 지원
• 각주를 다른 위치에 배치
• 다른 식별자를 생성
• 다중 단락 각주를 거부
• 소스를 리터럴로 렌더링

출판 파이프라인이 알려진 경우에만 각주를 사용하세요. README 파일에서 임의의 시스템 사이에서 렌더링되어야 하는 경우 의존하지 마세요.

헤딩 ID 및 속성

이 Pandoc 구문은 이식되지 않습니다:

## 설치 {#installation .procedure}

이식성이 중요한 경우, 일반 헤딩을 사용하고 렌더러가 자체 앵커를 생성하도록 하세요.

모든 대상이 동일한 슬러그화 규칙을 사용하는 경우에만 자동 생성된 헤딩 ID에 대한 링크를 하드코딩하는 것도 피하세요.

콜아웃 및 알림

GitHub, Obsidian, GitLab, MkDocs, Docusaurus 및 Hugo 테마는 모두 콜아웃 유사한 블록을 지원할 수 있지만, 종종 서로 다른 구문을 사용합니다.

이식 가능한 폴백은 일반 블록 인용입니다:

> 경고: 업그레이드하기 전에 데이터베이스를 백업하세요.

시각적으로 덜 인상적이지만, 모든 곳에서 의미를 보존합니다.

위키 링크

위키 링크는 지식 관리 도구 내에서 간결합니다:

[[KV Cache]]

대상 경로, 파일 이름, 헤딩 규칙 및 해석 동작이 애플리케이션에 속하기 때문에, 교환 구문으로서는 적합하지 않습니다.

게시를 위해 의도된 콘텐츠에는 표준 마크다운 링크를 사용하세요:

[KV 캐시](kv-cache.md)

Raw HTML

Raw HTML은 마크다운이 레이아웃을 표현할 수 없을 때의 일반적인 탈출구입니다. 또한 일반적인 이식성 및 보안 실패 요인입니다.

렌더러는 다음을 수행할 수 있습니다:

• HTML을 제거
• 이스케이프
• 선택된 요소를 정제
• 블록은 허용하지만 인라인 요소는 허용하지 않음
• HTML 내부의 마크다운 파싱을 거부
• 신뢰할 수 있는 모드에서만 변경 없이 통과

출판 대상이 관리되는 경우에만 Raw HTML을 사용하세요.

수학적 표기

달러 구분자 수학은 인기 있지만 보편적으로 해석되지 않습니다.

소스는:

복잡도는 $O(n^2)$입니다.

다음 중 하나가 될 수 있습니다:

• 렌더링된 수학
• 달러 기호가 포함된 일반 텍스트
• 잘못된 강조
• 다른 수학 파서의 입력

한 개의 수학 파이프라인을 선택하고 모든 대상 환경에서 테스트하세요.

Mermaid 및 기타 다이어그램 블록

Mermaid 코드 페ンス는 지원하지 않는 렌더러가 일반적으로 이를 코드로 표시하기 때문에 구문적으로 안전합니다.

의미론적 결과는 여전히 다릅니다. 독자는 GitHub에서 렌더링된 아키텍처 다이어그램을 보고 다른 환경에서는 원본 Mermaid 소스를 볼 수 있습니다.

이것은 진정한 호환성이 아니라 우아한 성능 저하입니다.

마크다운 호환성의 세 가지 계층

호환성을 세 가지 계층으로 나누는 것이 도움이 됩니다.

1층: 파싱 호환성

파서가 구조를 인식합니까?

예시로는 헤딩, 표, 각주, 고정 구분이 있습니다.

2층: 변환 호환성

플랫폼이 추가적인 처리를 적용합니까?

예시로는 다음이 있습니다:

• Mermaid 렌더링
• 인용 해석
• 위키 링크 확장
• 이슈 번호 연결
• 쇼트코드 처리
• 목차 생성

3층: 프레젠테이션 호환성

결과가 적절하게 보이고 작동합니까?

예시로는 다음이 있습니다:

• 표 스타일링
• 구문 하이라이팅
• 알림 색상
• 헤딩 앵커
• 반응형 이미지
• 각주 배치
• 수학 폰트

두 플랫폼은 동일한 구문을 파싱하면서 상당히 다른 프레젠테이션을 생성할 수 있습니다.

더 나은 이식성 모델

“유효한 마크다운"인지 묻는 대신, 다음 네 가지 좁은 질문을 하세요:

1. 소스는 어떤 변종으로 작성되었는가?
2. 어떤 파서가 읽는가?
3. 어떤 확장 기능이 활성화되어 있는가?
4. 이후에 어떤 플랫폼 변환이 실행되는가?

예를 들어:

Dialect: CommonMark plus GFM tables
Parser: Goldmark
Extensions: tables, strikethrough, task lists, footnotes
Platform: Hugo
Additional processing: render hooks and Mermaid JavaScript

이 설명은 “사이트가 마크다운을 사용한다"고 말하는 것보다 훨씬 유용합니다.

사용 사례별 변종 선택

README 파일

GFM을 사용하세요.

README 파일은 다음에서 이득을 봅니다:

• 표
• 작업 목록
• 고정 코드
• 자동 링크
• 취소선
• GitHub 참조

레포지토리가 GitLab으로 미러링되거나, 패키지 리지스트리에서 렌더링되거나, 생성된 문서에 포함될 때 GitHub 전용 기능에 대한 과도한 의존성을 피하세요.

Hugo 기술 기사

문서화된 Goldmark 확장 세트와 함께 CommonMark 호환 마크다운을 사용하세요.

빌드 파이프라인을 제어하므로 표, 코드 페ンス, 각주, Mermaid는 합리적일 수 있습니다. 대량의 Raw HTML을 임베드하는 것보다 Hugo 쇼트코드 또는 렌더 훅을 선호하세요.

Hugo 특유의 구문을 분리하고 쉽게 찾을 수 있게 유지하세요.

학술 문서

Pandoc Markdown을 사용하세요.

인용, 참고문헌 처리, 각주, 메타데이터, 수학적 표기, 교차 참조 및 PDF 또는 DOCX로의 변환은 감소된 이식성을 정당화합니다.

Pandoc 명령, 기본값 파일, 필터, 참고문헌 및 템플릿을 소스 옆에 저장하세요. 소스 파일만으로는 빌드를 완전히 기술하지 않습니다.

책 및 장문 문서화

여러 출력 포맷이 중요한 경우, Pandoc Markdown은 보통 세 가지 옵션 중 가장 강력합니다.

문서 복잡성이 증가함에 따라 정의 목록, 인용, 속성, 메타데이터 및 구조적 변환이 더 중요해집니다.

Git 레포지토리에 호스팅되는 웹 전용 문서의 경우, GFM 또는 CommonMark 기반 문서 생성기가 여전히 더 단순할 수 있습니다.

노트 및 개인 지식 베이스

애플리케이션 기능이 실질적인 가치를 제공하는 경우, 선택된 노트 애플리케이션의 네이티브 구문을 사용하세요.

Obsidian 위키 링크, 임베드 및 콜아웃은 볼트 내에서 유용합니다. 내보내기를 원본 파일이 이미 이식 가능한 출판물이라고 가정하기보다 컴파일 과정으로 취급하세요.

알려진 시스템 사이에서 공유 문서

보수적인 CommonMark 부분 집합을 사용하세요.

다음은 피하세요:

• 위키 링크
• 플랫폼 알림
• 헤더 속성
• 인용
• Raw HTML
• 사용자 정의 컨테이너
• 애플리케이션 임베드
• 쇼트코드

이식성은 일반적으로 편의 기능을 포기해야 합니다.

이식 가능한 마크다운을 위한 실용적 규칙

CommonMark 구조로 시작하기

문서 골격에 CommonMark를 사용하세요:

• 헤딩
• 단락
• 목록
• 링크
• 이미지
• 블록 인용
• 코드 블록

이것은 선택적 확장 기능이 실패하더라도 주요 의미가 생존하도록 보장합니다.

GFM 기능을 의도적으로 추가하기

모든 중요한 대상이 지원하는 경우, 표와 작업 목록은 합리적입니다.

“대부분의 도구가 GFM을 지원한다"고 테스트하지 않고서는 가정하지 마세요. 일부는 GFM 호환성을 주장하면서 선택된 확장 기능만 활성화합니다.

플랫폼 확장을 격리하기

플랫폼 특유의 구문을 명확히 식별 가능한 블록에 유지하세요.

예를 들어, Hugo 쇼트코드, Pandoc 인용 또는 Obsidian 임베드를 모든 단락에 흩뿌리는 대신 중앙화하세요.

격리는 후속 변환을 더 쉽게 만듭니다.

우아한 성능 저하를 선호하기

Mermaid 블록은 읽기 쉬운 소스 코드로 저하됩니다. GitHub 알림은 블록 인용으로 저하됩니다.

위키 임베드는 설명되지 않은 파일 이름으로 저하될 수 있고, Pandoc 고정 구분은 콘텐츠 주위에 구두점을 노출할 수 있습니다.

폴백이 이해 가능하게 남아 있는 확장 기능을 선택하세요.

자동 생성된 헤딩 ID에 의존하지 않기

헤딩 앵커 알고리즘은 GitHub, Hugo, Pandoc 및 문서 생성기 사이에서 다릅니다.

문서 간 링크의 경우, 대상 파이프라인이 관리되는 경우에만 렌더러가 지원하는 명시적인 ID를 사용하세요. 그렇지 않으면, 생성된 조각이 아닌 문서로 링크하세요.

빌드 구성을 콘텐츠와 함께 유지하기

Pandoc 확장 기능, Hugo 설정, 플러그인, 필터 및 JavaScript 통합은 마크다운이 어떻게 작동하는지를 결정합니다.

관련 구성 파일을 소스와 함께 커밋하세요:

content/
  article.md
pandoc.yaml
references.bib
config/
  _default/
    markup.yaml
layouts/
  _default/
    _markup/

.md 확장자만으로는 출판 환경을 포착하지 못합니다. 이러한 결정을 문서화하는 구조화된 접근을 위해 AI-Driven Development를 위한 의사결정 기록를 참조하세요.

모든 중요한 대상에 대해 마크다운 테스트하기

한 편집기에서 시각적 미리보기만으로는 충분하지 않습니다. 편집기는 프로덕션 렌더러보다 더 풍부한 변종을 지원할 수 있습니다.

Pandoc의 경우, 명시적인 입력 포맷을 테스트하세요:

pandoc --from=commonmark article.md -o commonmark.html
pandoc --from=gfm article.md -o gfm.html
pandoc --from=markdown article.md -o pandoc.html

경고 및 가시적인 소스 구두점은 어떤 기능이 변종 특유인지를 드러냅니다.

Hugo의 경우, 프로덕션 사이트를 빌드하세요:

hugo --gc --minify

그 다음 편집기 미리보기에만 의존하지 않고 생성된 HTML을 검사하세요.

레포지토리의 경우, 실제 호스팅 플랫폼에서 커밋된 파일을 확인하세요. VS Code의 로컬 마크다운 확장 기능은 GitHub 또는 GitLab과 일치하지 않을 수 있습니다.

일반적인 렌더링 불일치 트러블슈팅

하나의 플랫폼에서 작동했던 파일이 다른 플랫폼에서 깨질 때, 실패는 일반적으로 반복 가능한 패턴 중 하나로 떨어집니다. 아래 표는 실제로 볼 수 있는 증상, 가장 가능성 높은 원인, 그리고 이를 확인하고 수정하기 위한 구체적인 명령 또는 검사를 나열합니다.

이는 마크다운 “버그"를 가정하기 전의 가장 빠른 첫 번째 패스입니다 — 이러한 불일치 중 대부분은 손상된 구문이 아닌 누락된 확장 기능 또는 플랫폼 전용 기능입니다. 누락된 구문 하이라이팅 또는 지원되지 않는 언어 식별자와 같은 코드 페ンス 특유의 문제는 마크다운 코드 블록에 대한 전용 가이드를 참조하세요.

이식 가능한 부분 집합 린팅

마크다운 린터는 렌더러 호환성을 보장할 수 없지만, 피할 수 있는 모호성을 제거할 수 있습니다.

유용한 규칙은 다음과 같습니다:

• 일관된 헤딩 스타일 사용
• 목록 및 코드 블록 주위에 빈 줄 추가
• 들여쓰기 코드보다 고정 코드 사용
• 코드 페ンス 언어 지정
• 건너뛴 헤딩 레벨 피하기
• 일관된 목록 마커 사용
• 구두점 주위 모호한 강조 피하기
• 줄 종료 일관성 유지
• 링크 및 이미지 검증

멀티 타겟 게시의 경우, 구문 린팅에만 의존하지 않고 각 중요한 렌더러에 대해 빌드 테스트를 추가하세요.

Pandoc을 사용하여 변종 간 변환

Pandoc은 문서를 한 변종에서 다른 변종으로 정규화할 수 있습니다:

pandoc \
  --from=markdown \
  --to=gfm \
  article.md \
  -o article-gfm.md

또는 GFM을 Pandoc Markdown으로 변환합니다:

pandoc \
  --from=gfm \
  --to=markdown \
  README.md \
  -o document.md

이것은 유용하지만, 변환이 모든 기능을 보존할 것이라는 보장은 없습니다.

가능한 손실에는 다음이 포함됩니다:

• 플랫폼 특유의 참조
• 콜아웃 스타일링
• 복잡한 표
• 임베드된 애플리케이션 개체
• 사용자 정의 속성
• Raw HTML 동작
• 플러그인 구문
• 다이어그램 렌더링
• 정확한 공백 및 포맷

Pandoc은 원본 소스 포맷보다 문서 구조를 더 잘 보존합니다. 변환을 역방향 가능한 텍스트 포맷터가 아닌 빌드 단계로 취급하세요.

Hugo 사이트용 권장 전략

Hugo 기술 블로그에 대해 가장 실용적인 정책은 다음과 같습니다:

1. 핵심 산문 및 구조에 CommonMark를 사용하세요.
2. 문서화된 소수의 Goldmark 확장 기능을 활성화하세요.
3. 가독성이 향상되는 곳에서 GFM 스타일의 표 및 작업 목록을 사용하세요.
4. Mermaid를 하나의 일관된 렌더 훅 또는 쇼트코드를 통해 구현하세요.
5. 수학을 하나의 문서화된 KaTeX 또는 MathJax 파이프라인을 통해 처리하세요.
6. Hugo 프론트 매터는 콘텐츠 파일의 시작에만 사용하세요.
7. Raw HTML보다 렌더 훅과 쇼트코드를 선호하세요.
8. 가능한 경우 소스 링크를 표준 마크다운 링크로 유지하세요.
9. 이전된 또는 외부에서 가져온 문서를 Hugo를 통해 테스트하세요.
10. GitHub에서 올바르게 렌더링되지 않을 구문을 문서화하세요.

이 접근법은 Hugo 콘텐츠가 보편적으로 이식 가능하지 않다는 것을 수용하면서 이식성 경계를 가시적으로 유지합니다.

가장 나쁜 접근법은 우발적인 변종 혼합입니다: 정의된 빌드 파이프라인 없이 GitHub 알림, Obsidian 임베드, Pandoc 속성, Hugo 쇼트코드가 동일한 문서에 배치되는 경우.

의사결정 표

결론

CommonMark, GitHub Flavored Markdown, Pandoc Markdown은 동일한 제품의 경쟁하는 버전이 아닙니다. 서로 다른 문제를 해결합니다.

CommonMark는 신뢰할 수 있는 파싱 기초를 제공합니다. GFM은 소프트웨어 협업에 실용적인 기능을 추가하며, Pandoc Markdown은 마크다운을 출판 및 변환을 위한 풍부한 소스 언어로 변환합니다.

가장 안전한 규칙은 단순합니다: 실제 대상을 충족하는 가장 작은 변종을 작성하세요. 콘텐츠가 이동해야 할 때는 CommonMark를, GitHub 스타일 협업이 대상일 때는 GFM을, 문서 구조 및 출력 포맷이 보편적 렌더링보다 중요할 때는 Pandoc Markdown을 사용하세요.

마크다운 이식성은 모든 확장 기능을 피함으로써 달성되는 것이 아닙니다. 이는 소스 계약의 일부인 확장 기능이 무엇인지 알고, 중요한 모든 렌더러에서 이를 테스트함으로써 달성됩니다.

참조

• CommonMark Specification
• GitHub Flavored Markdown Spec
• Pandoc Markdown
• Goldmark Documentation
• Hugo Goldmark Configuration
• Writing Mathematical Expressions on GitHub