마크다운 문법 총정리: GitHub 스타일 예제로 배우는 치트 시트

마크다운(Markdown)은 일반 텍스트로도 읽기 쉬운 서식 있는 글을 쓰는 가장 간단한 방법입니다. README 파일, 기술 문서, 메모, 채팅 메시지, 정적 사이트가 모두 마크다운을 씁니다. 이 치트 시트는 실제로 자주 쓰는 문법을 정리했으며, GitHub, GitLab, 대부분의 문서화 도구, 그리고 Markdown Preview Editor가 지원하는 방언인 GitHub-Flavored Markdown(GFM)을 중심으로 설명합니다.

아래 예제는 모두 온라인 에디터에 붙여 넣어 결과를 나란히 확인할 수 있습니다.

제목

줄 앞에 #를 1~6개 쓰고 공백을 한 칸 띄웁니다. # 하나는 페이지 제목, ##는 섹션, ###는 하위 섹션입니다.

markdown# 페이지 제목
## 섹션
### 하위 섹션
#### 더 작은 제목

문서마다 # 제목은 하나만 두고, 단계를 건너뛰지 마세요(예: ##에서 바로 ####로). 스크린 리더와 검색 엔진은 제목 구조로 페이지를 이해하며, 대부분의 미리 보기 도구는 제목으로 목차를 만듭니다.

문단과 줄 바꿈

문단은 빈 줄로 구분된 한 줄 이상의 텍스트입니다. 문단 안에서 줄을 한 번 바꾸는 것은 무시되고 두 줄이 이어 붙습니다. 줄 바꿈을 강제하려면 줄 끝에 공백 두 칸이나 백슬래시를 넣으세요.

markdown끝에 공백 두 칸이 있는 첫째 줄  
같은 문단의 둘째 줄.

빈 줄 다음에는 새 문단이 시작됩니다.

강조

Markdown Preview Editor를 비롯한 많은 에디터는 인기 있는 확장 문법도 지원합니다. ==highlight==(강조 표시), 아래 첨자 H~2~O, 위 첨자 x^2^, :smile: 형태의 이모지 단축 코드가 그렇습니다. 이들은 GFM 표준이 아니므로, 사용하기 전에 게시할 플랫폼에서 지원하는지 확인하세요.

목록

글머리 기호 목록에는 -, *, +를, 번호 목록에는 숫자를 씁니다. 공백 2~4칸으로 들여 쓰면 항목이 중첩됩니다.

markdown- 우유
- 빵
  - 통밀빵
  - 호밀빵
- 커피

1. 저장소 복제하기
2. 의존성 설치하기
3. 빌드 실행하기

번호 목록은 번호가 정확하지 않아도 됩니다. 모든 줄에 1.을 써도 1, 2, 3으로 표시됩니다. 다른 번호(예: 5.)로 시작하면 목록이 그 번호부터 시작됩니다.

할 일 목록(체크박스)

할 일 목록은 목록 항목을 체크박스로 바꾸는 GFM 확장 문법입니다. README, 릴리스 계획, 회의록에 안성맞춤입니다.

markdown- [x] 초안 작성
- [x] 스크린샷 추가
- [ ] 글 게시

링크

markdown[링크 텍스트](https://example.com)
[제목이 있는 링크](https://example.com "마우스를 올리면 표시됨")
<https://example.com>

[설치 가이드][install]를 읽어 보세요.

[install]: https://example.com/docs/install

마지막 형태는 참조 링크입니다. URL을 문서 맨 아래에 한 번만 정의하므로 긴 문단도 읽기 쉽게 유지됩니다. [Setup](docs/setup.md) 같은 상대 링크는 같은 프로젝트의 다른 파일을 가리킵니다. Markdown Preview Editor에서는 해당 문서가 다른 탭에 열려 있으면 그 탭으로 전환됩니다.

이미지

이미지는 링크 문법 앞에 느낌표를 붙입니다. 대괄호 안의 텍스트는 대체 텍스트로, 이미지를 볼 수 없는 사람을 위해 이미지를 설명하세요.

markdown![실시간 미리 보기가 있는 에디터](images/screenshot.png)
![로고](https://example.com/logo.svg "선택 사항인 제목")

로컬 이미지를 참조하는 문서를 미리 볼 때는 폴더 전체를 열거나 이미지를 .md 파일과 함께 끌어 놓아야 미리 보기 도구가 상대 경로를 찾을 수 있습니다.

코드

인라인 코드는 백틱 하나로 감쌉니다. 코드 블록은 백틱 세 개로 감싸고, 구문 강조를 위해 언어 이름을 적습니다.

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

자주 쓰는 언어 이름: js, ts, python, bash, json, yaml, html, css, sql, go, rust, diff. 코드 자체에 백틱 세 개가 들어 있다면 위 예제처럼 백틱 네 개로 감싸세요.

표

열은 파이프(|)로 구분하고, 머리글 아래에 대시로 된 줄을 넣습니다. 구분선의 콜론으로 정렬을 지정합니다.

markdown| 기능      | 무료 | 비고               |
|:----------|:----:|-------------------:|
| 미리 보기 |  ✅  | 입력하는 대로 갱신 |
| 내보내기  |  ✅  | HTML, PDF, .md     |

:---는 왼쪽 정렬, :---:는 가운데 정렬, ---:는 오른쪽 정렬입니다. 원문에서 열이 딱 맞을 필요는 없지만, 좋은 에디터는 읽기 쉽게 유지해 줍니다. Markdown Preview Editor의 도구 모음에는 표 템플릿을 바로 넣어 주는 표 버튼이 있습니다.

인용문과 알림 상자

줄 앞에 >를 붙이면 인용문이 됩니다. GitHub는 알림 상자(alerts)도 지원합니다. 첫 줄이 특별한 인용문으로, 색이 있는 강조 상자로 표시됩니다.

markdown> 일반 인용문.

> [!NOTE]
> 사용자가 알아야 할 유용한 정보.

> [!TIP]
> 더 잘하기 위한 도움말.

> [!WARNING]
> 즉시 주의가 필요한 긴급 정보.

알림 상자는 NOTE, TIP, IMPORTANT, WARNING, CAUTION 다섯 가지입니다. 아껴 쓰세요. 섹션마다 하나는 눈에 띄지만, 다섯 개가 연달아 있으면 소음이 됩니다.

각주

각주를 쓰면 부연 설명을 본문에서 분리할 수 있습니다. 각주 내용은 어디에 정의해도 되며, 문서 끝에 표시됩니다.

markdownMarkdown은 2004년에 만들어졌습니다.[^1]

[^1]: 존 그루버가 에런 스워츠의 도움을 받아 만들었습니다.

가로줄과 이스케이프

한 줄에 대시, 별표, 밑줄을 세 개 이상 쓰면 가로줄이 됩니다: ---. 앞에 빈 줄을 넣으세요. 그러지 않으면 텍스트 바로 아래의 ---가 그 텍스트를 제목으로 바꿉니다.

마크다운이 해석해 버리는 문자를 그대로 표시하려면 백슬래시로 이스케이프하세요: \*not italic\*, \# not a heading, \$5(수식이 켜져 있을 때 유용).

수식과 다이어그램

기술 문서에서는 두 가지 확장 문법이 사실상 표준이 되었습니다.

• 수식 — 인라인 수식은 $E = mc^2$, 별도 줄 수식은 $$ … $$. 자세한 내용은 마크다운에서 수식 쓰기 가이드를 참고하세요.
• 다이어그램 — 언어를 mermaid로 지정한 코드 블록으로 순서도, 시퀀스 다이어그램, 간트 차트 등을 그립니다. 마크다운에서 Mermaid 다이어그램 그리기를 참고하세요.

프런트 매터

정적 사이트 생성기는 파일 맨 위의 YAML 블록에서 메타데이터를 읽습니다.

yaml---
title: My post
date: 2026-09-27
tags: [markdown, docs]
---

좋은 미리 보기 도구는 이 블록을 텍스트로 렌더링하지 않고 숨깁니다. Markdown Preview Editor가 바로 그렇게 합니다.

다음 단계

문법을 아는 것은 절반일 뿐이고, 나머지 절반은 쓰면서 결과를 확인하는 것입니다. 파일을 업로드하지 않고 마크다운을 온라인으로 미리 보는 방법을 읽어 보고, 문서가 완성되면 마크다운을 HTML이나 PDF로 변환하는 방법도 알아보세요.