마크다운의 탄생

2004년 12월, 블로거이자 작가인 존 그루버(John Gruber)는 에런 스워츠(Aaron Swartz)와 함께 마크다운을 세상에 내놓았다. 그들의 철학은 단순했다:

"마크다운 형식의 문서는, 변환하지 않고 그 자체로도 읽힐 수 있어야 한다."

HTML을 직접 쓰는 건 고통이었다. <p>, <strong>, <a href="..."> 같은 태그가 글 사이사이를 메우면, 정작 내용은 태그 속에 묻혀버린다. 그루버는 이메일 문화에서 영감을 받았다. 이메일에서 인용할 때 >를 쓰고, 강조할 때 *별표*로 감싸는 그 관습. 이미 사람들이 쓰고 있는 평문 표기법을 정리하면 되는 거였다.

에런 스워츠는 변환 엔진의 핵심 로직을 설계했다. 그는 당시 불과 17세였다. 나중에 RSS 1.0 명세 공동 저자, Creative Commons 설립 참여, Reddit 합병 등을 이끈 천재 해커이기도 했다.

마크다운은 두 가지를 동시에 가리킨다:

1. 일반 텍스트 서식 지정을 위한 문법(syntax)
2. 그 텍스트를 HTML로 변환하는 펄(Perl) 스크립트

CommonMark와 GFM으로의 진화

원본 마크다운에는 한 가지 문제가 있었다. 명세가 모호했다. 같은 마크다운 문서를 파서마다 다르게 해석하는 일이 빈번했다. 2014년, 존 맥팔레인(John MacFarlane)을 중심으로 CommonMark 프로젝트가 출범했다. 600개 이상의 테스트 케이스로 구성된 엄밀한 명세를 만들어, "이 마크다운은 반드시 이렇게 렌더링되어야 한다"를 정의했다.

GitHub는 여기서 한 발 더 나갔다. CommonMark를 기반으로 표(Tables), 작업 목록(Task Lists), 취소선, 자동 링크 등을 추가한 GFM(GitHub Flavored Markdown)을 만들었다. 오늘날 대부분의 개발자가 "마크다운"이라고 부르는 것은 사실 GFM이다.

제목 (Headers)

# 기호의 개수로 제목 수준을 정한다. # 하나면 가장 큰 제목(h1), 여섯 개면 가장 작은 제목(h6). 반드시 # 뒤에 공백을 넣어야 한다.

대안 문법으로, h1은 텍스트 아래 ===, h2는 ---를 써도 된다:

제목 1
======

제목 2
------

강조 (Emphasis)

목록 (Lists)

순서 없는 목록 (Unordered)

-, *, + 중 아무거나 쓸 수 있다. 하나로 통일하는 게 좋다.

순서 있는 목록 (Ordered)

숫자 + 마침표. 실제 번호는 상관없다 — 파서가 자동으로 매긴다. 하지만 1.부터 시작하는 것이 관례.

링크 (Links)

이미지 (Images)

링크 문법 앞에 !를 붙이면 이미지가 된다.

![대체 텍스트](이미지URL)
![대체 텍스트](이미지URL "캡션")


<img src="image.png" alt="설명" width="400">

인용구 (Blockquotes)

줄 앞에 >를 붙인다. 중첩도 가능하다.

코드 (Code)

인라인 코드

백틱(`` ` ``) 하나로 감싼다: `console.log("hello")` → console.log("hello")

코드 블록 (Fenced Code Block)

백틱 세 개(```)로 감싸고, 첫 줄에 언어를 명시하면 구문 강조가 적용된다.

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

console.log(greet("Markdown"));

지원되는 언어: javascript, python, java, html, css, bash, json, sql, go, rust, typescript 등.

가로선 (Horizontal Rules)

세 개 이상의 ---, ***, ___ 중 아무거나 쓴다.

---
***
___

모두 동일하게 렌더링된다:

이스케이프 (Escape)

마크다운 문법에 사용되는 특수 문자를 그대로 출력하려면 앞에 \를 붙인다.

\*이건 기울임이 아니다\*
\# 이건 제목이 아니다
\[이건 링크가 아니다\](url)

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

표 (Tables)

파이프(|)와 하이픈(-)으로 구성한다. 정렬은 콜론(:)으로 지정.

작업 목록 (Task Lists)

GFM 확장. - [ ]는 미완료, - [x]는 완료.

취소선 (Strikethrough)

물결표 두 개(~~)로 감싼다.

~~이 기능은 더 이상 지원되지 않습니다.~~

결과: 이 기능은 더 이상 지원되지 않습니다.

각주 (Footnotes)

본문에 [^1]을 넣고, 문서 어딘가에 [^1]: 설명을 추가한다.

마크다운은 존 그루버가 만들었다[^1].

[^1]: John Gruber, Daring Fireball, 2004년.

수학 공식 (LaTeX)

인라인: $E = mc^2$, 블록: $$로 감싼다.

인라인 수식: $f(x) = x^2 + 2x + 1$

블록 수식:
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

GitHub, Obsidian, Notion, Jupyter Notebook 등에서 지원. 일반 마크다운 에디터에서는 MathJax 또는 KaTeX 라이브러리가 필요하다.

이모지 (Emoji)

콜론으로 감싼 단축코드를 쓴다 (GitHub, Slack 등 지원):

다이어그램 (Mermaid)

마크다운 코드 블록에 mermaid 언어를 지정하면 다이어그램이 렌더링된다. GitHub, GitLab, Obsidian, Notion 등에서 네이티브 지원.

플로우차트 (Flowchart)

```mermaid
graph TD
    A[시작] --> B{조건 확인}
    B -->|Yes| C[실행]
    B -->|No| D[종료]
    C --> D
```

시퀀스 다이어그램

```mermaid
sequenceDiagram
    사용자->>서버: 로그인 요청
    서버->>DB: 사용자 조회
    DB-->>서버: 결과 반환
    서버-->>사용자: 인증 토큰
```

파이 차트

```mermaid
pie title 마크다운 사용처
    "GitHub" : 40
    "기술 블로그" : 25
    "문서 도구 (Notion, Obsidian)" : 20
    "기타" : 15
```

Git 그래프

```mermaid
gitGraph
    commit
    commit
    branch develop
    commit
    commit
    checkout main
    merge develop
    commit
```

베스트 프랙티스

1. 공백 관리

• # 뒤에 반드시 공백 — # 제목 (O), #제목 (X)
• 단락 사이에 빈 줄 하나 — 붙어 있으면 하나의 단락으로 합쳐진다
• 목록 앞뒤에 빈 줄 — 일부 파서에서 목록이 깨지는 것을 방지
• 줄바꿈은 줄 끝에 공백 2개, 또는 <br>

2. 문서 구조화 전략

• h1은 문서당 1개 — 문서 제목에만 사용
• h2 ~ h4로 계층 구조 — h2는 대주제, h3는 소주제, h4는 세부 항목
• 계층을 건너뛰지 않는다 — h2 다음에 바로 h4가 오면 안 된다
• 목차(TOC) — 긴 문서에는 상단에 목차를 넣는다

3. 실무에서 자주 쓰는 패턴

접이식 섹션 (HTML 혼용)

<details>
<summary>클릭하면 열립니다</summary>

숨겨진 내용. **마크다운도 됩니다.**

- 목록도 되고
- `코드`도 된다

</details>

뱃지 (Shield.io)

![Build](https://img.shields.io/badge/build-passing-brightgreen)
![License](https://img.shields.io/badge/license-MIT-blue)

키보드 키

<kbd>Ctrl</kbd> + <kbd>C</kbd>로 복사

결과: Ctrl + C로 복사

치트시트

한눈에 보는 마크다운 문법 요약. 복사해서 바로 쓸 수 있다.