Markdown

Markdown 은 평문 (plain text) 으로 쓰면서도 구조화된 문서를 표현할 수 있게 해 주는 가벼운 마크업 언어입니다. 개발 문서·README·이슈·블로그·메모에 광범위하게 쓰입니다.

1. Markdown 에 대한 이야기

Markdown 은 2004 년 John Gruber 가 Aaron Swartz 와 함께 설계해 발표했습니다. 목표는 두 가지:

1. 평문으로 읽었을 때 자연스러워야 한다.
2. HTML 로 매끄럽게 변환되어야 한다.

원래의 명세는 비교적 짧고 모호한 부분이 있었습니다. 같은 문법이 구현체마다 다르게 해석되는 일이 잦아지자, 2014 년에 CommonMark 가 표준화 작업으로 등장. 그 위에 GitHub 가 표·태스크리스트·자동링크 같은 확장을 더한 GFM (GitHub Flavored Markdown) 을 정의해 사실상의 사용자 표준이 됐습니다.

2. CommonMark 와 GFM

항목	CommonMark	GFM
기본 문법 (헤더 · 강조 · 목록 · 링크)	정의	상속
표 (table)	없음	있음
태스크리스트 (- [ ])	없음	있음
스트라이크스루 (~~text~~)	없음	있음
자동 URL 링크	약함	강함
코드블록 언어 표기	있음	있음

GitHub · GitLab · Bitbucket 같은 호스팅이 GFM 을 렌더링하므로 README 는 보통 GFM 을 가정해 작성됩니다.

3. 헤더 · 강조 · 목록

# H1
## H2
### H3

*italic* 또는 _italic_
**bold** 또는 __bold__
~~strikethrough~~  (GFM)

- 항목 A
- 항목 B
  - 중첩

1. 첫째
2. 둘째

4. 링크 · 인용 · 코드

[링크 텍스트](https://example.com)
![대체 텍스트](path/to/image.png)

> 인용문은 한 단계 들여 표시.

인라인 코드 — `code`. 블록:

```python
def hello():
    print("hello")
```

코드블록 첫 줄에 언어 이름을 적으면 GitHub · VS Code · 정적 사이트 생성기들이 신택스 하이라이팅 적용. 의도적으로 일반 텍스트를 표시할 때는 text 또는 비워 두는 관행.

5. 표 · 태스크리스트 (GFM)

| 항목 | 값 |
|---|---|
| 이름 | alice |
| 나이 | 30 |

콜론으로 정렬 — |:---| 왼쪽, |---:| 오른쪽, |:---:| 가운데.

- [x] 완료된 항목
- [ ] 미완 항목

6. 코드블록 언어 명시가 중요한 이유

• 신택스 하이라이팅 — 가독성이 명확히 좋아짐.
• GitHub 검색·렌더링 — 일부 도구가 언어 메타데이터로 코드만 인덱싱.
• 변환 도구 친화 — pandoc · MDX 같은 변환기가 더 정확한 출력.
• AI 도구 친화 — 코드 추출·분석 시 언어 정보가 정확도를 높임.

7. README 가 마크다운인 관행

README 는 Unix 시절부터 평문이었습니다. GitHub 가 2008 년 출시되면서 저장소 루트의 README.md 를 자동으로 HTML 로 렌더링해 보여 주기 시작했고, 이후 거의 모든 호스팅이 같은 관행을 따랐습니다. 현재 README 라는 이름은 관습일 뿐이지만 호스팅이 자동 렌더링하는 파일명 목록 (README.md · README.markdown · Readme.md) 에 들어 있어 그대로.

8. 한계와 보완

Markdown 은 의도적으로 단순합니다. 다음 영역은 지원이 약하거나 없음:

• 정교한 스타일링 (폰트 · 색 · 간격).
• 복잡한 레이아웃 (다단 · 사이드바).
• 동적 컴포넌트.
• 각주·참고문헌 (일부 확장에서만).
• 메타데이터 (front matter 라는 관행).

도구	무엇을 더하는가
MDX	Markdown 안에서 React/JSX 컴포넌트.
AsciiDoc	더 풍부한 문서 마크업. O'Reilly 출판.
reStructuredText	Python 진영 (Sphinx) 의 표준. 더 엄격하고 확장성.
Pandoc	거의 모든 마크업 사이의 변환기.
Front matter (YAML · TOML)	파일 상단에 메타데이터 블록 (Jekyll · Hugo · Astro).

---
title: 문서 제목
date: 2026-04-25
tags: [markdown, docs]
---

# 본문 시작

9. 미리보기 도구

작업	macOS · Linux	Windows
VS Code 미리보기	Cmd+K V	Ctrl+K V
pandoc 변환	pandoc README.md -o README.html	동일
터미널 렌더링	glow README.md 또는 mdcat	glow (Scoop · winget)

10. 자주 걸리는 자리

코드블록 들여쓰기 — 4 스페이스 들여쓰기도 코드블록을 만듭니다. 의도치 않게 목록 안 텍스트가 코드로 바뀌는 일.

인라인 백틱 안에 백틱이 있을 때 — 두 개의 백틱으로 감싸면 안쪽 단일 백틱을 살릴 수 있음.

줄바꿈 — 한 줄 띄우지 않고 그냥 엔터를 치면 같은 단락으로 이어집니다. 강제 줄바꿈은 두 칸 공백 + 엔터 또는 빈 줄.

HTML 태그가 그대로 통함 — 일부 렌더러는 보안상 일부 태그를 거름 (GitHub 의 <script> 차단).

표 안에서 | 를 텍스트로 쓰려면 \| 로 이스케이프.

헤더 위아래에 빈 줄이 없으면 일부 렌더러에서 헤더로 인식 안 됨.

하고픈 말

Markdown 은 가장 단순한 마크업이라 학습 비용이 거의 0 이지만, GFM 의 표·태스크·자동링크 + front matter + 코드블록 언어 명시 셋이 함께 있을 때 진가를 발휘합니다. 정교한 레이아웃이 필요한 자리는 MDX 또는 AsciiDoc 으로 한 단계 올라가는 길.

Next

• text-encoding-line-endings
• first-terminal-day

CommonMark Spec · GFM Spec · Daring Fireball Markdown · MDX · Pandoc 를 참고합니다.