Markdown 치트시트: GitHub Flavored Markdown 완전 레퍼런스

Markdown은 GitHub README, 풀 리퀘스트 설명, 문서 사이트, 노트 앱 등 어디서나 쓰입니다. GitHub Flavored Markdown(GFM)은 CommonMark 명세를 테이블, 작업 목록, 취소선, 자동 링크로 확장합니다. 이 치트시트에서 모든 내용을 한 곳에 정리합니다.

Markdown을 실시간으로 미리보기 →

제목

# H1 — 페이지 제목
## H2 — 섹션
### H3 — 하위 섹션
#### H4
##### H5
###### H6

제목 계층으로 문서를 구조화합니다. H1은 보통 문서 제목, H2/H3은 섹션에 사용합니다.

강조

문법	결과
`italic` 또는 `_italic_`	italic
`bold` 또는 `__bold__`	bold
`*bold italic*`	bold italic
`~~strikethrough~~`	~~strikethrough~~（GFM 전용）

순서 없는 목록

- 항목 하나
- 항목 둘
  - 중첩 항목 (2칸 들여쓰기)
  - 또 다른 중첩 항목
- 항목 셋

목록 마커로 -, *, + 사용 가능합니다. 목록 내에서 일관성을 유지하세요.

순서 있는 목록

1. 첫 번째 단계
2. 두 번째 단계
   1. 하위 단계
   2. 하위 단계
3. 세 번째 단계

실제 숫자는 중요하지 않습니다. Markdown은 어떤 숫자든 순서대로 렌더링합니다.

작업 목록 (GFM)

- [x] 저장소 설정
- [x] README 작성
- [ ] CI 설정 추가
- [ ] 첫 번째 릴리즈 배포

GitHub에서 issue, PR, 프로젝트 문서에서 인터랙티브 체크박스로 렌더링됩니다.

코드

인라인 코드

인라인 코드에는 백틱 사용: `variable_name`, `npm install`, `const x = 1`

펜스 코드 블록

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

지원되는 언어 식별자: js, javascript, ts, typescript, python, py, bash, sh, go, rust, java, c, cpp, json, yaml, html, css, sql, diff, markdown 등 다수.

구문 강조 없는 코드

```
일반 텍스트 블록
구문 강조 없음
```

링크

[링크 텍스트](https://example.com)
[제목이 있는 링크](https://example.com "마우스오버 제목")
[참조 스타일 링크][ref-id]

[ref-id]: https://example.com

자동 링크 (GFM)

GFM은 URL과 이메일 주소를 자동으로 링크로 변환합니다:

https://github.com 은 클릭 가능한 링크가 됩니다
user@example.com 은 mailto 링크가 됩니다

이미지

![대체 텍스트](image.png)
![대체 텍스트](image.png "선택적 제목")
![참조 스타일][img-ref]

[img-ref]: /path/to/image.png

이미지에 링크 추가:

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

테이블 (GFM)

| 컬럼 1 | 컬럼 2 | 컬럼 3 |
|--------|--------|--------|
| 셀     | 셀     | 셀     |
| 셀     | 셀     | 셀     |

컬럼 정렬

| 왼쪽   | 가운데 | 오른쪽 |
|:-------|:------:|-------:|
| 정렬   | 가운데 | 오른쪽 |

:--- — 왼쪽 정렬 (기본값)
:---: — 가운데 정렬
---: — 오른쪽 정렬

테이블을 완벽하게 정렬할 필요는 없습니다. 파이프만 있으면 됩니다.

인용구

> 이것은 블록 인용구입니다.
>
> 여러 단락에 걸쳐 사용할 수 있습니다.

> 중첩 인용구 레벨 1
>> 중첩 인용구 레벨 2

수평선

다음 중 하나로 수평선을 만들 수 있습니다:

---
***
___

각주 (GFM 확장)

이 주장은 인용이 필요합니다.[^1]

[^1]: 출처: 신뢰할 수 있는 참고문헌, 2024년.

Markdown에서 HTML 사용

대부분의 Markdown 렌더러에서 원시 HTML이 지원됩니다:

<details>
<summary>클릭하여 펼치기</summary>

여기에 숨겨진 콘텐츠. GitHub에서는 **Markdown**이 HTML 블록 내에서도 작동합니다.

</details>

GitHub README의 접이식 섹션에 주로 사용됩니다.

문자 이스케이프

Markdown 문자를 이스케이프하려면 백슬래시를 사용합니다:

\*이탤릭이 아님\*
\`코드가 아님\`
\# 제목이 아님

이스케이프 가능한 문자: \, `, *, _, {, }, [, ], (, ), #, +, -, ., !

GitHub 전용 확장

멘션

@username — 사용자 멘션
@org/team — 팀 멘션

Issue·PR 참조

#123          — issue/PR 번호 123으로 링크
user/repo#123 — 저장소 간 참조
SHA           — 특정 커밋으로 링크 (7자 이상)

이모지 (GFM)

:rocket: :white_check_mark: :warning: :tada:

GitHub은 이모지 단축코드 목록에서 이것들을 렌더링합니다. 자주 쓰이는 것들:

:warning: — ⚠️
:white_check_mark: — ✅
:x: — ❌
:rocket: — 🚀
:memo: — 📝

CommonMark vs GFM

기능	CommonMark	GFM
단락, 제목, 목록	✅	✅
펜스 코드 블록	✅	✅
강제 줄바꿈	✅	✅
테이블	❌	✅
작업 목록	❌	✅
취소선	❌	✅
자동 링크	부분적	✅
멘션/issue 참조	❌	✅

GitHub용으로 작성할 때는 GFM을 자유롭게 사용하세요. 최대 이식성(정적 사이트 생성기, 다른 도구)을 위해서는 CommonMark에 머무르세요.

README 모범 사례

좋은 GitHub README에는 보통 다음이 포함됩니다:

프로젝트 제목과 한 줄 설명
배지 — 빌드 상태, 버전, 라이선스
설치 — 명령어가 있는 코드 블록
사용법 — 코드가 있는 짧은 예제
API 레퍼런스 — 주요 옵션의 테이블 또는 목록
기여 — CONTRIBUTING.md로의 링크
라이선스 — 라이선스 유형 한 줄

Markdown 미리보기

라이브 미리보기 없이 Markdown을 작성하면 오류가 발생하기 쉽습니다 — 특히 테이블과 중첩 목록. 커밋하기 전에 미리보기 도구에 내용을 붙여넣어 렌더링을 확인하세요.

라이브 Markdown 미리보기 사용해보기 → — GitHub Flavored Markdown을 실시간으로 렌더링, 계정 불필요.

제목

강조

목록