GFM, CommonMark, Pandoc 마크다운: 문법 비교

마르다운은 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 코어를 사용하십시오. Hugo가 GFM 호환이라고 설명된다고 해서 GitHub에서 보이는 모든 기능이 작동한다고 가정하지 마십시오.

의견: Hugo 기술 블로그를 위해 기억해야 할 규칙이 하나라면, CommonMark와 GFM 스타일의 표 및 작업 목록을 기본값으로 취급하고, 나머지 모든 것(각주, 수학, 호출, 헤더 속성)은 가정된 기본값이 아니라 명시적이고 테스트된 확장으로 취급하십시오. 이 단일한 습관은 아래에 설명된 대부분의 포터빌리티 실패를 방지합니다.

CommonMark: 포터블 코어

CommonMark는 기본 마르다운 언어에 대한 형식적인 사양입니다. 그 주요 기여도는 많은 기능의 컬렉션이 아니라 일관된 파싱입니다.

다음에 대한 파서의 해석 방식을 정의합니다:

• 단락
• ATX 및 Setext 헤딩
• 인용문
• 순차 및 비순차 목록
• 울타리 및 들여쓰기 코드 블록
• 강조 및 강한 강조
• 링크 및 이미지
• 참조 스타일 링크
• 인라인 코드
• 주제의 분리
• 원시 HTML 블록
• 하드 및 소프트 줄 바꿈

CommonMark 문서는 여전히 표현 계층에서 다르게 작동할 수 있습니다. CSS, 구문 강조, 헤딩 앵커, HTML 정화 및 링크 정책은 코어 파싱 규칙의 범위 밖에 있습니다.

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

포터블 CommonMark 예시

# Service Deployment

The service exposes a small HTTP API.

## Requirements

- Linux
- Docker
- 8 GB of memory

## Start the service

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

See the [configuration guide](configuration.md) for details.

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

GitHub Flavored Markdown: 소프트웨어 프로젝트를 위한 CommonMark

GitHub Flavored Markdown은 CommonMark를 기반으로 하는 형식적인 변종입니다. 이는 CommonMark 파싱 모델을 유지하고 저장소 문서화 및 협업에 일반적으로 필요한 기능을 추가합니다.

공식 GFM 사양은 다음을 추가합니다:

• 파이프 표
• 작업 목록 항목
• 취소선
• 확장된 자동 링크
• 일부 원시 HTML 태그 주변의 제한

이러한 확장들은 이제 настолько 일반적이어서 많은 사용자가 이들이 표준 마르다운의 일부라고 생각합니다. 그러나 이들은 CommonMark 코어의 일부가 아닙니다.

GFM 표

| Backend | Best use |
|---|---|
| Ollama | Local experiments |
| vLLM | Shared inference |
| SGLang | Structured workloads |

엄격한 CommonMark 파서는 이를 일반 단락 텍스트로 취급할 수 있습니다. GFM 호환 파서는 이를 표로 인식합니다. 표 구문 및 정렬 옵션에 대한 더 깊은 분석은 마르다운의 표를 참조하십시오.

GFM 작업 목록

- [x] Install Docker
- [x] Download the model
- [ ] Add monitoring

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

GFM 취소선

Use the ~~old endpoint~~ new endpoint.

취소선은 널리 지원되지만, 여전히 포터블 CommonMark 구문이 아닌 확장입니다.

GFM 자동 링크

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

Visit https://example.com/docs for details.

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

<https://example.com/docs>

명시적 형태는 문서가 알려지지 않은 마르다운 프로세서를 통해 이동해야 할 때 더 안전합니다.

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

자주 발생하는 혼란의 원인은 GitHub에서 보이는 모든 마르다운 기능이 GFM 사양에 속한다는 가정입니다.

그렇지 않습니다.

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

• 수학적 표현식
• Mermaid 다이어그램
• 알림
• 이슈 및 풀 리퀘스트 참조
• 사용자 및 팀 멘션
• 커밋 참조
• 이모티콘 숏코드
• 접이식 HTML 섹션
• 색상 미리보기
• 저장소 상대 링크
• 자동 헤딩 앵커

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

이러한 구별은 중요하며, 다른 렌더러는 GitHub의 수학 렌더러, Mermaid 통합, 이슈 참조 또는 알림 스타일링을 구현하지 않고도 GFM 호환성을 정확하게 주장할 수 있습니다.

GitHub Mermaid 다이어그램

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

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

일반적인 GFM 렌더러는 동일한 블록을 강조된 소스 코드로 표시할 수 있습니다. 마르다운은 여전히 유효하지만, 향상된 렌더링은 플랫폼 특화입니다. Mermaid 구문에 대한 실용적인 소개는 Mermaid 다이어그램 퀵스타트를 참조하십시오.

GitHub 수학적 표현식

GitHub는 달러 구분 기호와 추가 이스케이프 형태를 사용하여 인라인 및 블록 수학적 표현식을 지원합니다.

The cache size is approximately $2nlhd$ bytes.

$$
C = 2nlhd
$$

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

GitHub 알림

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

> [!WARNING]
> Changing this setting clears the cache.

GitHub에서는 스타일화된 경고로 나타날 수 있습니다. 일반 CommonMark 렌더러에서는 [!WARNING]을 포함하는 일반 인용문으로 나타납니다.

이러한 폴백은 읽을 수 있어 GitHub 알림이 완전히 사라지는 확장보다 덜 위험합니다. 그러나 여전히 포터블 표현 요소는 아닙니다.

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

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

기본 마르다운 리더에는 큰 확장 세트가 포함되어 있습니다. 중요한 기능은 다음과 같습니다:

• YAML 메타데이터 블록
• 각주
• 인용문
• 다양한 표 형식
• 정의 목록
• 수학적 표기법
• 헤딩 식별자 및 속성
• 코드 블록 속성
• 울타리 분할
• 괄호로 묶인 범위
• 위 첨자 및 아래 첨자
• 취소선
• 줄 블록
• 번호 매겨진 예시 목록
• 원시 LaTeX
• 원시 HTML
• 자동 섹션 번호 매기기
• 참고문헌 처리

Pandoc Markdown은 CommonMark 또는 공식 GFM보다 훨씬 더 표현력이 풍부합니다. 이러한 표현력은 출판에는 강력하지만 교환 형식으로는 덜 안전합니다.

Pandoc 각주

Markdown has several incompatible dialects.[^dialects]

[^dialects]: CommonMark, GFM, and Pandoc Markdown are three
    important examples.

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

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

Pandoc 인용문

PagedAttention improves KV cache memory management
[@kwon2023pagedattention].

참고문헌 파일 및 인용 스타일과 함께 Pandoc는 이를 서식이 지정된 학술 인용문 및 참고문헌으로 해결할 수 있습니다.

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

인용문 구문은 지원되지 않는 렌더러에서 읽을 수 있게 유지되지만, Pandoc 또는 다른 호환 인용문 프로세서 없이 서식이 지정된 참조가 되지는 않습니다. Pandoc의 리더 측 유연성은 또한 반대 방향의 변환 워크플로우의 기반이 됩니다 — Pandoc의 확장된 변종을 중간 형식으로 사용하는 실용적인 예는 Word 문서를 마르다운으로 변환을 참조하십시오.

Pandoc 정의 목록

CommonMark
: A precise specification for core Markdown.

GFM
: A CommonMark-based dialect with software-oriented extensions.

Pandoc Markdown
: An extended authoring format for document conversion.

정의 목록은 매뉴얼, 용어집 및 기술 책에서 유용합니다. 이들은 지원하지 않는 렌더러에서 일반적으로 나쁘게 퇴화하며, 콜론 줄은 일반 텍스트로 가시적으로 남아 있습니다.

Pandoc 헤딩 속성

## Cache Configuration {#cache-config .deployment}

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

이는 모든 곳에서 렌더링될 것으로 예상되는 문서에 배치해서는 안 되는 유용한 구문의 가장 명확한 예 중 하나입니다.

Pandoc 울타리 분할

::: warning
Changing this option restarts the server.

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

대부분의 CommonMark 및 GFM 렌더러는 울타리를 인식하지 않습니다. 이들은 콜론과 콘텐츠를 일반 텍스트로 표시합니다.

CommonMark vs GFM vs 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: "Markdown Compatibility"
description: "Compare Markdown dialects and renderers."
date: 2026-07-31
tags:
  - Markdown
  - documentation
---

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

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

Hugo의 원시 HTML

Goldmark는 표준 Hugo 구성에서 잠재적으로 안전하지 않은 원시 HTML을 기본적으로 렌더링하지 않습니다.

다음과 같은 블록은:

<div class="notice">
  Restart the service after changing this value.
</div>

원시 HTML 렌더링이 활성화되거나 콘텐츠가 숏코드 또는 렌더 후크를 통해 구현되지 않는 한 생략될 수 있습니다.

제어된 기술 블로그의 경우 원시 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 링크

다음과 같은 위키 링크는:

[[Markdown Compatibility]]

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**을 사용한 강한 강조
• 일반 링크
• 일반 이미지
• 인용문
• 주제의 분리
• 명시적 각괄호 자동 링크

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

# Deployment Guide

This guide explains how to deploy the service.

## Requirements

- Docker
- Linux
- A supported GPU

## Configuration

Create a file named `compose.yaml`.

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

For more information, see the [configuration reference](config.md).

> Back up existing data before upgrading.

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

일반적으로 깨지는 구문

포터빌리티 문제는 소수의 기능 주변에 집중되는 경향이 있습니다.

파이프 표

파이프 표는 GFM 중심 도구에서 잘 지원되지만 엄격한 CommonMark에서는 그렇지 않습니다.

표는 인식하지 않는 파서를 통과할 때 읽을 수 없는 텍스트로 퇴화할 수 있습니다. 매우 포터블한 문서의 경우 짧은 목록 또는 빌드 단계 동안 생성된 의미론적 HTML을 고려하십시오.

각주

각주 구문은 일반적이 되었지만 여전히 확장입니다.

다양한 도구는 다음과 다를 수 있습니다:

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

발행 파이프라인이 알려진 경우 각주를 사용하십시오. 임의의 시스템 전반에 렌더링되어야 하는 README 파일에서 이에 의존하지 마십시오.

헤딩 ID 및 속성

이 Pandoc 구문은 포터블하지 않습니다:

## Installation {#installation .procedure}

포터빌리티가 중요한 경우 일반 헤딩을 사용하고 렌더러가 자체 앵커를 생성하도록 하십시오.

모든 타겟이 동일한 슬러그화 규칙을 사용하지 않는 한 자동 생성된 헤딩 ID에 링크를 하드코딩하는 것도 피하십시오.

호출 및 알림

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

포터블 폴백은 일반 인용문입니다:

> Warning: Back up the database before upgrading.

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

위키 링크

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

[[KV Cache]]

타겟 경로, 파일 이름, 헤딩 규칙 및 해결 동작이 애플리케이션에 속하기 때문에 이들은 나쁜 교환 구문입니다.

게시를 위한 콘텐츠에서 표준 마르다운 링크를 사용하십시오:

[KV cache](kv-cache.md)

원시 HTML

원시 HTML은 마르다운이 레이아웃을 표현할 수 없을 때 일반적인 탈출구입니다. 이는 또한 일반적인 포터빌리티 및 보안 실패입니다.

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

• HTML을 제거
• 이스케이프
• 선택된 요소 정화
• 인라인 요소가 아닌 블록 허용
• HTML 내부의 마르다운 파싱 거부
• 신뢰 모드에서만 변경 없이 전달

원시 HTML은 발행 타겟이 제어될 때만 사용하십시오.

수학적 표기법

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

소스:

The complexity is $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는 빌드 파이프라인을 제어하기 때문에 합리적일 수 있습니다. 원시 HTML을 대량으로 임베딩하는 대신 Hugo 숏코드 또는 렌더 후크를 선호하십시오.

Hugo 특정 구문을 고립되고 쉽게 찾을 수 있게 유지하십시오.

학술 문서

Pandoc Markdown을 사용하십시오.

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

Pandoc 명령, 기본 파일, 필터, 참고문헌 및 템플릿을 소스 옆에 저장하십시오. 소스 파일 자체는 빌드를 완전히 설명하지 않습니다.

책 및 장문 문서

여러 출력 형식이 중요한 경우 Pandoc Markdown은 세 옵션 중 가장 강력한 옵션입니다.

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

Git 저장소에 호스팅되는 웹 전용 문서의 경우 GFM 또는 CommonMark 기반 문서 생성기가 더 단순할 수 있습니다.

노트 및 개인 지식베이스

애플리케이션 기능이 진정한 가치를 제공하는 경우 선택된 노트 애플리케이션의 네이티브 구문을 사용하십시오.

Obsidian 위키 링크, 임베드 및 호출은 볼트 내부에서 유용합니다. 내보내기를 컴파일 프로세스로 취급하고 원시 파일이 이미 포터블한 게시물이라고 가정하지 마십시오.

알려지지 않은 시스템 간 공유 문서

보수적인 CommonMark 하위 집합을 사용하십시오.

피하십시오:

• 위키 링크
• 플랫폼 알림
• 헤딩 속성
• 인용문
• 원시 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 기반 개발을 위한 결정 기록을 참조하십시오.

모든 중요한 타겟에 대해 마르다운을 테스트

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

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

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

잠재적 손실은 다음을 포함합니다:

• 플랫폼 특정 참조
• 호출 스타일링
• 복잡한 표
• 임베디드 애플리케이션 객체
• 커스텀 속성
• 원시 HTML 동작
• 플러그인 구문
• 다이어그램 렌더링
• 정확한 공백 및 서식

Pandoc는 원래 소스 서식보다 문서 구조를 더 잘 보존합니다. 변환을 빌드 단계로 취급하고, 가역 텍스트 서식기로 취급하지 마십시오.

Hugo 사이트를 위한 권장 전략

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

1. 코어 산문 및 구조에 CommonMark 사용.
2. 문서화된 작은 Goldmark 확장 세트 활성화.
3. 가독성을 향상하는 곳에서는 GFM 스타일 표 및 작업 목록 사용.
4. Mermaid를 하나의 일관된 렌더 후크 또는 숏코드를 통해 구현.
5. 수학을 하나의 문서화된 KaTeX 또는 MathJax 파이프라인을 통해 처리.
6. 콘텐츠 파일의 시작에서만 Hugo 프론트 매터 사용.
7. 원시 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