Markdown 치트시트 — 자주 쓰는 문법 모음 (예제 포함)

Markdown 은 John Gruber 가 2004 년에 만든 가벼운 마크업 언어다. "메일에 쓸 만한 평문이 그대로 HTML 이 되는" 컨셉. CommonMark (2014) 가 표준화 하고, GitHub Flavored Markdown (GFM) 이 표·체크박스·자동 링크 등 흔히 쓰는 확장을 박았다. 이 가이드는 두 표준을 합쳐 실제 자주 쓰는 문법만 정리한다.

헤딩

# H1 (페이지 제목, 한 페이지에 하나)
## H2 (섹션)
### H3 (서브섹션)
#### H4
##### H5
###### H6

대안 문법 (Setext) — H1 은 ===, H2 는 --- 밑줄. 현대 도구는 atx 스타일 (#) 을 거의 다 지원하므로 그쪽이 권장.

인라인 스타일

**굵게** 또는 __굵게__
*기울임* 또는 _기울임_
~~취소선~~
`인라인 코드`
==하이라이트== (일부 도구만)

한글 문장 안 이*탈*릭 처럼 단어 중간에 박으면 일부 파서가 못 잡는다. 공백으로 분리하거나 영문 단어에만 적용.

리스트

- 순서 없음 (-, *, + 모두 가능)
- 둘째 줄
  - 들여쓰기 2 스페이스로 중첩
    - 다시 중첩

1. 순서 있음
2. 자동 번호 매김
3. 실제로 어떤 숫자를 써도 1 부터 다시 매김
   1. 중첩 — 3 스페이스 (또는 탭)

중첩 들여쓰기는 2 스페이스 또는 4 스페이스 가 안전. 탭은 파서마다 다르게 처리.

링크와 이미지

[표시 텍스트](https://example.com)
[표시 텍스트](https://example.com "툴팁 텍스트")

자동 링크: <https://example.com>

참조 스타일:
이 글은 [Markdown][1] 에서 시작했다.

[1]: https://daringfireball.net/projects/markdown/

이미지: ![대체 텍스트](image.png)
이미지 + 링크: [![alt](image.png)](https://example.com)

참조 스타일은 본문 가독성이 좋다 — 긴 URL 이 본문 흐름을 깨지 않음. 같은 링크를 여러 번 쓸 때도 ID 하나만 정의하면 된다.

코드 블록

인라인 `code` 는 백틱 한 개.

```
일반 코드 블록 (펜스). 언어 명시 X.
```

```javascript
// 언어 명시 — 신택스 하이라이트
const x = 42;
```

들여쓰기 4 스페이스로도 코드 블록:
    function foo() {
      return 42;
    }

펜스 안에 백틱을 박으려면 외곽 펜스를 백틱 4 개로 늘리거나 ~~~ (틸드) 사용. 코드 안 백틱 3 개와 충돌 회피.

인용

> 한 줄 인용.
>
> 빈 줄 사이에 `>` 만 박아 단락 구분.
>
> > 중첩 인용.

> 인용 안에 **굵게**·*기울임*·`코드` 모두 가능.
> 리스트도 들어간다:
>
> - 항목 1
> - 항목 2

표 (GFM 확장)

| 왼쪽 | 가운데 | 오른쪽 |
|:---|:---:|---:|
| A | B | C |
| 1 | 2 | 3 |

구분자 행의 콜론 위치가 정렬 — :--- 왼쪽, :---: 가운데, ---: 오른쪽. 시각 정렬을 위해 파이프 사이 공백을 맞춰 두면 가독성 ↑ (파서는 무시).

셀 안 줄바꿈은 <br> 만 가능. 진짜 줄바꿈은 표 구조를 깬다. 복잡한 표가 필요하면 HTML <table> 직접 작성.

체크박스 (GFM)

- [ ] 미완료 항목
- [x] 완료
- [ ] 중첩 가능
  - [x] 하위 완료

GitHub Issues / PRs / README 에서 가장 많이 쓰인다. 일반 리스트 안에[ ] / [x] 패턴.

각주 (확장)

본문에 각주[^1] 를 박는다.

[^1]: 각주 본문. 페이지 하단에 자동으로 모임.

CommonMark 표준은 아니지만 GFM, Pandoc, MkDocs 등이 지원. 학술/문서 목적에 유용.

수평선

---  (대시 3 개)
***  (별표 3 개)
___  (밑줄 3 개)

모두 같은 결과. --- 가 가장 일반적.

줄바꿈과 단락

Markdown 의 흔한 함정 — 한 줄 띄어 쓰는 게 단락 구분, 단순 줄바꿈은 무시된다.

첫 줄.
이 문장은 같은 단락 (줄바꿈 무시).

빈 줄 한 번 = 새 단락.

줄 끝에 스페이스 두 개
=> 강제 줄바꿈 (<br>)

보이지 않는 trailing space 가 까다로워 일부 파서는 \ (백슬래시 + 개행) 도 지원.

HTML 임베드

대부분의 Markdown 파서는 HTML 태그를 그대로 통과시킨다.

<details>
<summary>접히는 섹션</summary>

여기 안엔 다시 **마크다운** 사용 가능.

</details>

<sub>아래첨자</sub> 또는 <sup>위첨자</sup>

단, GitHub README 등 일부 환경은 보안상 일부 태그 (script, iframe) 를 걸러낸다.

이스케이프

특수 문자를 그대로 출력하려면 \ 앞에 박는다.

\* 별표 그대로
\# 헤딩이 안 되게
\_ 밑줄 그대로
\` 백틱 그대로

이모지와 멘션 (GFM)

:rocket: :tada: :white_check_mark:
@username  ← GitHub 등에서 멘션
#123       ← Issue 참조

변환 도구

직접 결과를 확인하면서 작성하는 게 가장 빠르다 — Markdown 프리뷰 는 입력을 실시간 렌더링한다 (DOMPurify 로 XSS 차단). 기존 HTML 을 Markdown 으로 옮길 때는 HTML → Markdown 가 헤딩·리스트· 링크·코드·표를 자동 변환한다.

흔한 함정

리스트 사이 줄바꿈 — 리스트 두 개가 빈 줄 없이 붙어 있으면 합쳐진다. 빈 줄 한 줄 사이에 박아야 분리.
표 안 파이프 — 셀 안에 | 를 넣으려면 \| 로 이스케이프.
중첩 리스트의 들여쓰기 — 2 스페이스는 일부 파서가 못 잡는다. 4 스페이스가 가장 호환.
코드 블록 안 백틱 3 개 — 외곽 펜스를 4 개로 늘리거나 ~~~ 사용.

요약

헤딩 #, 볼드 **, 기울임 *, 코드 `.
리스트는 - / 1., 중첩은 들여쓰기 (2 또는 4 스페이스).
링크 [text](url), 이미지 ![alt](url).
코드 블록은 ``` 펜스 + 언어. 표·체크박스는 GFM 확장.
줄바꿈 두 번 = 새 단락. 단순 개행은 무시.

헤딩