Markdown 문법 총정리: 개발자와 블로거를 위한 완벽 가이드

GitHub README 작성하는데 HTML로 삽질하고 있다면 멈추세요. 마크다운 쓰면 5분이면 끝나는 일이에요. # 하나 붙이면 제목, ** 두 개 감싸면 볼드, - 찍으면 리스트. 이게 전부예요. 2004년에 존 그루버가 만든 이후로 개발자 세계에서 사실상의 문서 표준이 된 이유가 있어요 — 배우는 데 10분이면 충분하거든요.

왜 마크다운을 배워야 하나요?

마크다운은 현대 개발 생태계 곳곳에 있습니다. GitHub, GitLab, Bitbucket, Stack Overflow, Reddit, Discord, Notion, Obsidian, Jira, Confluence 등 모두 마크다운을 지원합니다. 마크다운을 한 번 배우면 수십 개의 플랫폼에서 서식 작성 능력을 갖게 됩니다. WYSIWYG 에디터보다 빠르고, 버전 관리에 친화적이며, HTML, PDF 등 어떤 형식으로든 변환할 수 있는 깔끔하고 이식성 높은 텍스트를 생성합니다.

개발자 도구를 넘어, 마크다운은 학술 논문 작성(Pandoc 등), 이메일 작성(다수의 이메일 클라이언트가 지원), 심지어 도서 출판에도 점점 더 활용되고 있습니다. 마크다운 학습에 대한 투자는 디지털 생활 전반에 걸쳐 효과를 발휘합니다.

기본 문법: 제목, 굵게, 기울임

제목은 해시(#) 기호로 만듭니다. #이 하나면 H1, 두 개면 H2, 최대 H6까지 가능합니다. 해시 뒤에 반드시 공백을 넣으세요. 강조는 *기울임* 또는 _기울임_으로 기울임체를, **굵게** 또는 __굵게__로 볼드체를 만듭니다. 조합도 가능합니다: ***굵은 기울임***.

# 제목 1 (H1)
## 제목 2 (H2)
### 제목 3 (H3)
#### 제목 4 (H4)

*기울임* 또는 _기울임_
**굵게** 또는 __굵게__
***굵은 기울임***
~~취소선~~

문단은 빈 줄로 구분합니다. 텍스트 중간의 단순 줄바꿈은 새 문단이 되지 않으며, 블록 사이에 빈 줄이 필요합니다. 문단 내 줄바꿈은 줄 끝에 공백 2개 또는 백슬래시(\)를 추가합니다. 수평선은 하이픈 3개(---), 별표 3개(***), 밑줄 3개(___)로 만듭니다.

목록: 순서 있는 목록과 순서 없는 목록

순서 없는 목록은 하이픈(-), 별표(*), 또는 플러스(+) 뒤에 공백을 넣어 만듭니다. 순서 있는 목록은 숫자와 마침표를 사용합니다. 2~4칸 들여쓰기로 중첩 목록을 만들 수 있습니다. 순서 있는 목록의 번호는 유연하게 처리되어, 모든 항목에 1을 사용해도 순차적으로 렌더링됩니다.

- 항목 하나
- 항목 둘
  - 하위 항목
  - 또 다른 하위 항목
- 항목 셋

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

- [x] 완료된 작업
- [ ] 미완료 작업

체크박스(할 일 목록)는 GitHub Flavored Markdown의 확장 기능입니다. - [ ]로 미완료, - [x]로 완료 항목을 표시합니다. 이슈 설명이나 PR 템플릿에서 액션 아이템 추적에 특히 유용합니다.

링크와 이미지

링크는 [표시 텍스트](URL) 형식입니다. 호버 제목은 [표시 텍스트](URL "제목")으로 추가합니다. 참조형 링크는 본문에 [텍스트][ref], 문서 하단에 [ref]: URL을 정의합니다. 이미지는 같은 문법에 느낌표를 붙입니다: .

[구글 방문](https://google.com)
[구글 방문](https://google.com "구글 홈페이지")

[참조 링크][1]
[1]: https://example.com

![이미지 대체 텍스트](https://example.com/image.png)
![대체 텍스트](image.png "이미지 제목")

<!-- 링크가 걸린 이미지 -->
[![대체 텍스트](image.png)](https://example.com)

코드: 인라인과 블록

인라인 코드는 백틱(`)으로 감쌉니다: `코드`. 코드 블록은 코드 전후에 각각 별도 줄의 삼중 백틱(```)을 사용합니다. 여는 백틱 뒤에 언어 식별자를 추가하면 구문 강조가 됩니다. 대부분의 마크다운 처리기가 JavaScript, Python, TypeScript, HTML, CSS, JSON, Bash, SQL 등 수십 가지 언어의 하이라이팅을 지원합니다.

인라인: `console.log()`로 디버깅합니다.

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

```python
def greet(name):
    return f"안녕하세요, {name}님!"
```

    // 들여쓰기 코드 블록 (4칸)
    const x = 42;

표 (테이블)

표는 파이프(|)와 하이픈(-)으로 열과 행을 만듭니다. 두 번째 줄이 정렬을 정의합니다: 왼쪽(기본), 가운데(:---:), 오른쪽(---:). 소스에서 완벽하게 정렬할 필요는 없습니다 — 마크다운 처리기가 자동으로 포맷팅합니다.

| 기능   | 마크다운  | HTML    |
|--------|:--------:|--------:|
| 제목   | 쉬움     | 장황함   |
| 목록   | 간단     | 복잡함   |
| 표     | 보통     | 번거로움 |
| 학습   | 빠름     | 느림     |

고급 기능

기본 문법 외에도 많은 마크다운 변형이 문서에 더 많은 기능을 추가하는 확장 기능을 지원합니다:

• 각주: 본문에 [^1]을 추가하고 하단에 [^1]: 각주 내용을 정의. GitHub, Obsidian 등에서 지원.
• 정의 목록: 한 줄에 용어, 다음 줄에 : 정의 (들여쓰기). PHP Markdown Extra 등에서 지원.
• 이모지: :emoji_name: 문법 사용 (예: :rocket:, :tada:). GitHub, Slack, Discord에서 지원.
• 수학 수식: $인라인 수식$과 $$디스플레이 수식$$에 LaTeX 문법 사용. GitHub, Obsidian, Jupyter에서 지원.
• Mermaid 다이어그램: ```mermaid 코드 블록으로 플로차트, 시퀀스 다이어그램 등 생성. GitHub 등에서 지원.
• 경고 상자(Admonitions): 인용 블록에 > [!NOTE], > [!WARNING], > [!TIP] 사용. GitHub, Obsidian에서 지원.

인용 블록은 줄 시작에 꺽쇠(>)를 사용합니다. 중첩(>>)이 가능하고, 내부에 다른 마크다운 요소를 포함할 수 있으며, 인용문, 노트, 경고 상자 등에 활용됩니다. 많은 플랫폼이 인용 블록을 확장하여 색상이 있는 경고 상자를 지원합니다.