메인 콘텐츠로 이동
T
QuickToolkit
EN
guide

마크다운(Markdown) 문법 완벽 가이드 — 초보자도 5분이면 마스터

2026-04-14 · 10분 읽기

마크다운이란?

**마크다운(Markdown)**은 일반 텍스트로 서식 있는 문서를 작성할 수 있는 경량 마크업 언어입니다. 2004년 존 그루버(John Gruber)가 만들었으며, HTML보다 훨씬 간단한 문법으로 제목, 볼드, 목록, 링크, 표 등을 표현할 수 있습니다.

마크다운이 널리 사용되는 이유는 배우기 쉽고, 어디서나 사용할 수 있으며, 가독성이 뛰어나기 때문입니다. 별도의 편집기 없이도 메모장이나 텍스트 에디터에서 바로 작성할 수 있고, 렌더링하지 않은 원문 자체도 읽기 편합니다.

어디에서 사용하나요?

마크다운은 현재 수많은 플랫폼에서 기본 문서 형식으로 채택하고 있습니다:

  • GitHub — README, 이슈, PR 설명, 위키
  • Notion — 페이지 작성 시 마크다운 단축키 지원
  • Slack, Discord — 채팅 메시지 서식
  • Jupyter Notebook — 코드와 문서를 함께 작성
  • Jekyll, Hugo, Astro — 정적 사이트 블로그 콘텐츠
  • Obsidian, Typora — 마크다운 기반 노트 앱
  • Velog, Tistory — 한국 블로그 플랫폼

특히 개발자 사이에서는 거의 표준 문서 형식으로 자리 잡았으며, 기술 문서, API 문서, 프로젝트 README 등에서 마크다운을 사용하지 않는 경우를 찾기 어렵습니다.

제목 (Headings)

# 기호의 개수로 제목 수준을 나타냅니다. HTML의 <h1>~<h6>에 해당합니다.

# 제목 1 (h1)
## 제목 2 (h2)
### 제목 3 (h3)
#### 제목 4 (h4)
##### 제목 5 (h5)
###### 제목 6 (h6)

# 뒤에 반드시 공백 한 칸을 넣어야 합니다. #제목처럼 붙여 쓰면 일부 파서에서 인식하지 못합니다.

일반적으로 문서에서 h1은 한 번만 사용하고, 본문 구조는 h2와 h3로 잡는 것이 좋습니다.

텍스트 강조 (Emphasis)

볼드 (Bold)

텍스트를 **로 감싸면 굵게 표시됩니다.

**굵은 텍스트**
__이것도 굵게__

이탤릭 (Italic)

* 하나로 감싸면 기울임꼴이 됩니다.

*기울임 텍스트*
_이것도 기울임_

볼드 + 이탤릭

***굵고 기울임***

취소선 (Strikethrough)

~~로 감싸면 취소선이 적용됩니다.

~~삭제된 텍스트~~

팁

볼드에는 **(별표)를, 이탤릭에는 _(밑줄)을 사용하면 코드에서 구분이 쉬워집니다. 예: **중요한** _강조_ 텍스트

목록 (Lists)

순서 없는 목록

-, *, + 중 아무 기호나 사용할 수 있습니다. -가 가장 보편적입니다.

- 사과
- 바나나
- 체리

순서 있는 목록

숫자 뒤에 .을 붙입니다. 실제 번호와 관계없이 자동으로 순서가 매겨집니다.

1. 첫 번째
2. 두 번째
3. 세 번째

중첩 목록

들여쓰기(스페이스 2~4칸)로 하위 목록을 만들 수 있습니다.

- 과일
  - 사과
  - 바나나
- 채소
  - 당근
  - 브로콜리

링크와 이미지 (Links & Images)

링크

[표시 텍스트](URL) 형식으로 작성합니다.

[QuickToolkit](https://quicktoolkit.app)
[구글](https://www.google.com "구글 홈페이지")

두 번째 예시처럼 URL 뒤에 "제목"을 추가하면 마우스를 올렸을 때 툴팁이 표시됩니다.

이미지

링크 앞에 !를 붙이면 이미지가 됩니다.

![대체 텍스트](이미지URL)
![로고](https://example.com/logo.png "로고 이미지")

대체 텍스트(alt text)는 이미지가 로드되지 않을 때 표시되며, 검색 엔진 최적화(SEO)와 접근성에도 중요합니다.

참조 링크

같은 URL을 여러 번 사용할 때 참조 방식이 편리합니다.

[GitHub][gh]을 방문하세요. [GitHub 문서][gh]도 확인하세요.

[gh]: https://github.com

코드 (Code)

인라인 코드

백틱(`)으로 감싸면 인라인 코드가 됩니다.

`console.log("hello")` 명령어를 실행하세요.

변수명, 함수명, 명령어 등 짧은 코드를 본문에 넣을 때 사용합니다.

코드 블록

백틱 3개(```)로 감싸면 여러 줄의 코드 블록을 만들 수 있습니다. 언어를 지정하면 문법 하이라이팅이 적용됩니다.

```javascript
function greet(name) {
  return `안녕하세요, ${name}님!`;
}
```

지원하는 언어: javascript, python, java, html, css, bash, json, sql, typescript 등 대부분의 프로그래밍 언어를 사용할 수 있습니다.

인용문 (Blockquotes)

> 기호로 인용문을 만듭니다.

> 간단함이 궁극의 정교함이다.
> — 레오나르도 다 빈치

중첩 인용도 가능합니다:

> 첫 번째 인용
>> 중첩된 인용
>>> 더 깊은 인용

인용문은 다른 사람의 말을 인용하거나, 중요한 내용을 강조할 때 사용합니다. 문서에서 주의 사항(Note)이나 팁(Tip)을 표시하는 데도 자주 활용됩니다.

표 (Tables)

파이프(|)와 하이픈(-)으로 표를 만듭니다.

| 이름 | 나이 | 직업 |
|------|------|------|
| 홍길동 | 30 | 개발자 |
| 김철수 | 25 | 디자이너 |
| 이영희 | 28 | 기획자 |

정렬

하이픈 행에 콜론(:)을 추가하여 정렬할 수 있습니다.

| 왼쪽 정렬 | 가운데 정렬 | 오른쪽 정렬 |
|:----------|:----------:|-----------:|
| 텍스트 | 텍스트 | 텍스트 |
| 왼쪽 | 가운데 | 오른쪽 |
  • :--- → 왼쪽 정렬 (기본값)
  • :---: → 가운데 정렬
  • ---: → 오른쪽 정렬

표는 데이터 비교나 스펙 정리에 유용합니다. 다만 복잡한 표가 필요하다면 HTML 태그를 직접 사용하는 것이 낫습니다.

체크리스트 (Task Lists)

- [ ]로 체크박스를 만들 수 있습니다. GitHub에서 특히 유용합니다.

- [x] 마크다운 기본 문법 학습
- [x] 표 만드는 법 익히기
- [ ] 실전 프로젝트에 적용
- [ ] 팀원에게 공유

체크리스트는 GitHub 이슈나 PR에서 진행 상황을 추적하는 데 널리 사용됩니다. [x]로 체크 표시를 하면 체크된 상태로 렌더링됩니다.

수평선 (Horizontal Rules)

세 개 이상의 -, *, _를 사용하면 수평선이 만들어집니다.

---
***
___

수평선은 문서 내에서 주제가 바뀌는 지점을 시각적으로 구분할 때 사용합니다.

이스케이프 (Escaping)

마크다운 특수문자를 그대로 표시하려면 앞에 백슬래시(\)를 붙입니다.

\*이것은 기울임이 아닙니다\*
\# 이것은 제목이 아닙니다
\[이것은 링크가 아닙니다\]

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

확장 문법 — GitHub Flavored Markdown (GFM)

GitHub에서는 표준 마크다운에 추가 기능을 더한 **GFM(GitHub Flavored Markdown)**을 지원합니다.

각주 (Footnotes)

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

[^1]: 존 그루버와 에런 스워츠가 공동 개발했습니다.

접기/펼치기 (Details)

HTML의 <details> 태그를 활용합니다.

<details>
<summary>자세히 보기</summary>

숨겨진 내용이 여기에 들어갑니다.
표, 코드 블록 등도 넣을 수 있습니다.

</details>

자동 링크

URL을 그냥 입력하면 자동으로 링크가 됩니다.

https://quicktoolkit.app

실전 활용 팁

1. README 작성 시 구조

프로젝트 README는 보통 다음 순서로 작성합니다:

# 프로젝트 이름
프로젝트 한 줄 설명

## 설치 방법
## 사용법
## 기여 방법
## 라이선스

2. 문서에서 자주 쓰는 패턴

경고나 정보를 표시할 때 인용문과 이모지를 조합하면 효과적입니다:

> ⚠️ **주의:** 이 작업은 되돌릴 수 없습니다.

> 💡 **팁:** Ctrl+K를 누르면 빠르게 링크를 삽입할 수 있습니다.

3. 긴 문서 관리

문서가 길어지면 상단에 목차(TOC)를 추가하는 것이 좋습니다:

## 목차
- [설치](#설치)
- [사용법](#사용법)
- [FAQ](#faq)

마크다운에서 제목은 자동으로 앵커(anchor)가 되므로, # 뒤에 소문자로 변환된 제목을 넣으면 해당 섹션으로 이동하는 링크가 만들어집니다. 공백은 -로 바꾸고, 특수문자는 제거합니다.

4. 마크다운 편집기 추천

마크다운을 작성할 때 실시간 미리보기를 제공하는 편집기를 사용하면 편리합니다:

편집기특징가격
VS Code확장 프로그램으로 미리보기 지원무료
Typora작성 즉시 렌더링 (WYSIWYG)유료
Obsidian노트 연결 + 마크다운개인 무료
StackEdit웹 브라우저에서 바로 사용무료

마크다운 vs HTML 비교

마크다운은 HTML로 변환되지만, 작성 편의성에서 큰 차이가 있습니다.

기능마크다운HTML
볼드**텍스트**<strong>텍스트</strong>
이탤릭*텍스트*<em>텍스트</em>
링크[텍스트](URL)<a href="URL">텍스트</a>
이미지![alt](URL)<img src="URL" alt="alt">
제목## 제목<h2>제목</h2>

마크다운은 같은 내용을 더 적은 글자 수로 표현할 수 있어 작성 속도가 빠릅니다. 다만 세밀한 스타일링이나 복잡한 레이아웃이 필요하다면 HTML을 직접 사용해야 합니다. 마크다운 문서 안에서 HTML 태그를 혼용하는 것도 가능합니다.

자주 하는 실수

  1. # 뒤에 공백 빠뜨리기 — #제목이 아닌 # 제목으로 써야 합니다
  2. 목록 앞뒤 빈 줄 누락 — 목록 시작 전과 후에 빈 줄을 넣어야 정상 렌더링됩니다
  3. 들여쓰기 불일치 — 중첩 목록에서 들여쓰기를 2칸 또는 4칸으로 통일해야 합니다
  4. 표에서 파이프 누락 — 모든 행의 열 수가 일치해야 합니다
  5. 코드 블록 안에서 마크다운 문법 사용 — 코드 블록 내부는 렌더링되지 않습니다

마무리

마크다운은 한번 익히면 어디에서나 활용할 수 있는 범용 문서 작성 기술입니다. GitHub, Notion, Slack, 블로그 등 대부분의 플랫폼이 마크다운을 지원하므로 투자 대비 활용도가 매우 높습니다.

처음에는 제목, 볼드, 목록, 링크 4가지만 기억하세요. 이것만으로도 일상적인 문서 작성의 90%를 해결할 수 있습니다. 나머지 문법은 필요할 때 이 가이드를 참고하면 됩니다.

텍스트를 다양한 형식으로 변환해야 한다면 텍스트 변환기를, 작성한 문서의 글자 수를 확인하고 싶다면 글자수 세기 도구를 활용해 보세요.

🔢
직접 해보세요
글자수/바이트 세기 →
🔤
직접 해보세요
텍스트 변환기 →

관련 글

📝
JSON이 뭔가요? 초보자를 위한 완벽 가이드
5분 읽기 →
📝
노션 시작하기 — 페이지·블록·데이터베이스 기초
8분 읽기 →