마크다운(Markdown)은 배우는 데 10분, 익숙해지는 데 하루면 충분하지만, 제대로 알고 쓰는 사람은 의외로 드물다. 줄바꿈이 왜 안 먹히는지, 표는 어떻게 만드는지, 체크박스는 표준인지 확장인지 — 이런 걸 매번 검색하게 된다. 이 글은 그 검색을 끝내기 위한 체계적 레퍼런스다. 기본 문법부터 깃허브 확장 문법(GFM)까지, 원본 소스와 렌더 결과를 나란히 두고 정리했다. 북마크해 두고 필요할 때 찾아보는 용도로 쓰면 된다.
결론부터 말하면, 마크다운의 핵심 철학은 하나다 — “소스 그 자체가 읽혀야 한다.” 태그로 뒤덮인 HTML과 달리, 마크다운은 서식 기호가 최소한이라 편집기에서 날것으로 봐도 문서로 읽힌다. 이 원칙만 기억하면 대부분의 문법이 자연스럽게 이해된다.
마크다운이란 — 기원과 세 가지 방언
마크다운은 2004년 존 그루버(John Gruber)가 애런 스워츠(Aaron Swartz)와 함께 만들었다. 목표는 “웹에 쓰는 글을, HTML 태그 없이도 읽고 쓰기 쉬운 일반 텍스트로 작성하는 것”이었다. 그래서 마크다운 문서는 변환 전에도 그 자체로 읽힌다.
문제는 초기 명세가 모호해서 구현마다 결과가 달랐다는 점이다. 그래서 오늘날 마크다운에는 크게 세 갈래가 있다.
| 방언 | 설명 | 쓰이는 곳 |
|---|---|---|
| 오리지널 마크다운 | 2004년 그루버 원안 | 초기 블로그 |
| CommonMark | 2014년 표준화된 엄격한 명세 | 대부분의 앱 기반 |
| GFM(GitHub Flavored) | CommonMark + 표·체크박스·취소선 등 확장 | 깃허브·노션·디스코드 등 |
출처: John Gruber “Daringfireball: Markdown”(2004), CommonMark Spec(2014), GitHub Flavored Markdown Spec.
오늘날 우리가 실무에서 마주치는 건 대부분 GFM 계열이다. 이 글도 기본 문법(CommonMark)과 확장 문법(GFM)을 나눠 설명한다.
기본 문법 ① 제목·문단·강조
**제목(Heading)**은 #의 개수로 단계를 표현한다. 1개는 h1, 6개는 h6까지다.
# 제목 1 (가장 큼)
## 제목 2
### 제목 3주의: #과 글자 사이에 반드시 공백이 있어야 한다. #제목은 제목으로 인식되지 않는다.
**강조(Emphasis)**는 별표(*)나 밑줄(_)로 준다.
*기울임* 또는 _기울임_
**굵게** 또는 __굵게__
***굵은 기울임***
~~취소선~~ (GFM)각각 기울임, 굵게, 굵은 기울임, 취소선으로 렌더된다.
문단과 줄바꿈이 초보자가 가장 많이 막히는 부분이다. 마크다운에서 문단은 빈 줄로 구분한다. 그냥 엔터 한 번은 무시된다.
이 두 줄은
한 문단으로 붙는다.
빈 줄이 있어야 새 문단이 된다.줄 안에서 강제로 줄바꿈하려면 줄 끝에 공백 2칸을 넣거나, 백슬래시(\)를 넣는다. 이 ‘보이지 않는 공백 2칸’ 규칙 때문에 많은 사람이 줄바꿈에 애를 먹는다.
기본 문법 ② 목록·링크·이미지
순서 없는 목록은 -, *, + 중 아무거나, 순서 있는 목록은 1. 형식으로 만든다. 중첩은 **들여쓰기(보통 공백 2칸)**로 한다.
- 사과
- 배
- 신고배 (중첩: 앞에 공백 2칸)
- 나주배
1. 첫째
2. 둘째팁: 순서 있는 목록은 숫자를 1. 1. 1.로 다 써도 렌더 시 자동으로 1, 2, 3이 된다. 중간에 항목을 추가할 때 번호를 다시 매길 필요가 없다.
링크와 이미지는 문법이 거의 같고, 이미지는 앞에 !만 붙는다.
[표시할 텍스트](https://example.com)
[툴팁 있는 링크](https://example.com "마우스 올리면 뜨는 설명")
이미지의 대체 텍스트(alt)는 접근성과 SEO에 중요하므로 비워두지 않는 게 좋다.
기본 문법 ③ 코드·인용·표
코드는 마크다운에서 가장 유용한 기능 중 하나다. 문장 안의 짧은 코드는 백틱(`) 하나로 감싸고, 여러 줄은 백틱 3개로 감싼 **코드 블록(fenced code block)**을 쓴다. 여는 백틱 뒤에 언어를 적으면 문법 강조(syntax highlighting)가 된다.
문장 안의 `inline code` 는 백틱 하나.
```python
def hello():
print("여러 줄 코드는 백틱 3개")
```**인용(Blockquote)**은 >로 시작한다. 겹치면 중첩 인용이 된다.
> 인용문입니다.
>> 중첩 인용입니다.인용문입니다.
중첩 인용입니다.
**표(Table)**는 원래 GFM 확장이지만 이제 거의 표준처럼 쓰인다. 파이프(|)로 칸을 나누고, 두 번째 줄의 콜론(:) 위치로 정렬을 정한다.
| 왼쪽정렬 | 가운데 | 오른쪽 |
|:--------|:------:|-------:|
| a | b | c |:---는 왼쪽, :---:는 가운데, ---:는 오른쪽 정렬이다.
확장 문법(GFM) — 체크박스·각주·자동링크
깃허브 계열에서 널리 쓰이는 확장 문법들이다. 앞서 본 표·취소선도 여기 속한다.
**체크박스(작업 목록)**는 목록에 [ ](빈칸)와 [x](체크)를 붙인다.
- [x] 끝난 일
- [ ] 남은 일**각주(Footnote)**는 본문에 [^1]을 달고, 아래에 내용을 정의한다.
본문에 각주를 단다.[^1]
[^1]: 각주 내용은 문서 아무 곳에나 정의하면 된다.자동 링크는 URL을 < >로 감싸거나(CommonMark), GFM에서는 그냥 URL만 써도 링크가 된다. **수평선(구분선)**은 ---, ***, ___ 중 하나를 한 줄에 단독으로 쓴다.
---자주 하는 실수와 실전 팁
레퍼런스의 핵심은 ‘함정 회피’다. 아래 다섯 가지가 실무에서 가장 자주 겪는 문제다.
- 줄바꿈이 안 돼요 → 엔터 한 번은 무시된다. 문단 분리는 빈 줄, 줄바꿈은 줄 끝 공백 2칸(또는
\). #이 제목이 안 돼요 →#과 글자 사이 공백을 빠뜨렸다.##제목(✗) →## 제목(○).- 중첩 목록이 깨져요 → 들여쓰기 칸 수가 안 맞다. 상위 항목 기호에 맞춰 보통 공백 2칸으로 정렬한다.
- 별표·백틱을 글자 그대로 쓰고 싶어요 → 앞에 백슬래시(
\)를 붙여 이스케이프한다.\*별표\*→ *별표*. - 표가 안 그려져요 → 헤더와 본문 사이
|---|구분선을 빠뜨렸다. 이 줄이 없으면 표가 아니라 그냥 텍스트가 된다.
또 하나의 팁: 마크다운은 대부분 HTML을 그대로 허용한다. 마크다운으로 안 되는 표현(가운데 정렬, 특정 색 등)은 <div>, <span> 같은 HTML을 섞어 쓰면 된다. 단, 플랫폼에 따라 HTML을 막는 경우도 있으니 확인이 필요하다.
한눈에 보는 치트시트
자주 쓰는 문법만 한 표로 모았다. 이 표 하나만 저장해 둬도 대부분 해결된다.
| 하고 싶은 것 | 문법 | 비고 |
|---|---|---|
| 제목 | # ~ ###### | #과 글자 사이 공백 필수 |
| 굵게 | **굵게** | 별표 2개 |
| 기울임 | *기울임* | 별표 1개 |
| 취소선 | ~~취소~~ | GFM |
| 목록(무순서) | - 항목 | *, +도 가능 |
| 목록(순서) | 1. 항목 | 숫자 자동 정렬 |
| 체크박스 | - [ ] / - [x] | GFM |
| 링크 | [텍스트](URL) | — |
| 이미지 |  | 앞에 ! |
| 인라인 코드 | `코드` | 백틱 1개 |
| 코드 블록 | ```언어 | 백틱 3개+언어 |
| 인용 | > 인용 | 중첩은 >> |
| 표 | | A | B | | 아래 |---| 필수 |
| 수평선 | --- | 단독 줄 |
| 줄바꿈 | 줄 끝 공백 2칸 | 또는 \ |
So What — 왜 지금도 마크다운인가
마크다운이 20년 넘게 살아남은 이유는 단순함 때문만이 아니다. 어디서나 통하기 때문이다. 깃허브, 노션, 옵시디언, 디스코드, 슬랙, 챗GPT·클로드 같은 AI 챗봇의 답변까지 — 오늘날 텍스트를 다루는 거의 모든 도구가 마크다운을 이해한다. 한 번 익히면 평생 여러 플랫폼에서 쓰는 셈이다.
특히 AI 시대에 마크다운의 가치는 더 커졌다. AI에게 구조화된 지시를 내리거나, AI의 답변을 문서로 정리하거나, 프롬프트를 관리할 때 마크다운은 사실상의 공용어다. 서식은 최소한으로, 구조는 명확하게 — 이 마크다운의 철학은 사람이 읽기에도, 기계가 파싱하기에도 이상적이다.
결국 마크다운을 체계적으로 익힌다는 것은, 특정 앱의 기능을 배우는 게 아니라 텍스트를 구조화하는 보편 문법을 익히는 일이다. 이 글을 북마크해 두고, 막힐 때마다 위 치트시트를 펼쳐 보시길.
참고 출처
- John Gruber, “Markdown”, Daring Fireball, daringfireball.net
- CommonMark Spec, commonmark.org
- GitHub Flavored Markdown Spec, github.github.com/gfm
댓글
✍️ 편집자 모드 — 이 댓글은 공개되지 않고 편집자에게만 전달됩니다.