Markdown 치트시트: 실용적인 빠른 가이드

대부분의 문서는 처음에 별표와 해시 기호 몇 개만 있는 일반 텍스트 파일에서 시작한다. 그 파일이 보통 Markdown이다. 웹 작성의 유일한 방법은 아니지만, README, 이슈 트래커, 챗봇, 정적 사이트의 기본 형식이다. 렌더링되기 전의 소스 그대로 읽을 수 있기 때문이다.

이 글은 실용적인 빠른 가이드다. 10분과 텍스트 편집기만 있으면 충분하다. 설치는 필요 없다.

Markdown이란

Markdown은 가벼운 마크업 문법이다. John Gruber가 2004년에 원래 사양을 공개했을 때 목표는 단 하나였다. 일반 텍스트로도 보기 좋고, 깔끔하게 HTML로 변환할 수 있는 형식을 만드는 것이다. 그 이후로 GitHub, Obsidian, Notion, 많은 정적 사이트 생성기, 그리고 대부분의 대규모 언어 모델 출력의 입력 형식이 되었다.

핵심 아이디어는 단순하다. 태그 대신 문장 부호로 구조를 표시한다.

# 이것은 제목

이것은 단락이다.

- 이것은 목록 항목
- 이것은 또 다른 항목

파서가 이를 HTML로 변환한다. 파서마다 지원하는 확장이 다륯기 때문에 어떤 표준을 사용하는지가 중요하다.

Markdown 표준은 중요하다

Markdown에는 유일한 공식 표준이 없다. Gruber의 원래 사양에는 빈틈이 있었고, 다양한 도구가 서로 호환되지 않는 방식으로 그 빈틈을 메웠다. 어떤 앱에서 작성한 표를 다른 앱에 붙여넣으면 깨질 수도 있다. 따라서 자신이 대상으로 하는 방언을 알아두어야 한다.

CommonMark. 2014년에 시작된 엄격하고 충분히 테스트된 사양. 핵심 문법을 정확하게 정의한다. 이식성을 원한다면 CommonMark를 사용하라.
GitHub Flavored Markdown(GFM). 표, 작업 목록, 취소선, 울타리 코드 블록, 자동 링크를 추가한다. GitHub README와 issue 댓글에서 사용된다.
Pandoc Markdown. 인용, 각주, 정의 목록, 위첨자·아래첨자, 수식을 추가한다. 학술 작성에서 흔하다.
Obsidian / Quarto / MDX. 위키 링크, 콜아웃, 실행 가능한 코드 셀, 임베디드 컴포넌트를 추가한다. 강력하지만 이식성은 낮다.

일상적인 작업에서는 GFM이 가장 안전하다. 도구 간 이동할 가능성이 있는 장문 문서라면 CommonMark에 문서화된 확장 집합을 더하는 편이 좋다.

Markdown 기초

제목

해시 기호를 1개에서 6개 사용한다. 1개가 가장 크다.

# 제목 1

## 제목 2

### 제목 3

단락과 줄바꿈

단락은 빈 줄로 구분한다. 줄 끝에 공백 2개나 백슬래시를 넣으면 강제 줄바꿈이 된다.

이것이 첫 번째 단락이다.

이것이 두 번째 단락이다.

강조

_기울임_ 또는 _기울임_
**굵게** 또는 **굵게**
**_굵고 기울임_**
~~취소선~~ (GFM 전용)

순서 없는 목록은 -, *, +를 사용한다.

- 항목 1
- 항목 2
  - 중첩 항목

순서 있는 목록은 숫자를 사용한다.

1. 1단계
2. 2단계
3. 3단계

숫자 자체는 정확하지 않아도 된다. 렌더링 시 Markdown이 다시 번호를 매긴다. 하지만 소스의 가독성을 위해 연속된 숫자를 사용하는 것이 좋다.

링크와 이미지

[링크 텍스트](https://example.com)
[제목이 있는 링크](https://example.com "제목")
![대체 텍스트](https://example.com/image.png)

낶부 링크에는 상대 경로를 사용한다.

[Markdown을 PDF로 변환](/tools/markdown-to-pdf)

코드

인라인 코드는 역따옴표 1개로 감싼다: `console.log("hi")`.

코드 블록은 역따옴표 3개로 감싼다.

```python
def hello():
    return "hello"
```


열리는 역따옴표 바로 뒤에 언어 식별자를 추가하면 구문 강조가 적용된다.

## 자주 쓰는 팁과 예제

### 인용

```markdown
> 이것은 인용이다.
> 여러 줄에 걸칠 수 있다.

중첩도 가능하다.

> 바깥쪽 인용
>
> > 중첩된 인용

수평선

---

대시, 별표, 밑줄을 3개 이상 한 줄에 단독으로 배치한다.

작업 목록

GFM은 확인란을 지원한다.

- [x] 초안 작성
- [ ] 표 확인
- [ ] 글 게시

HTML에서는 비활성화된 확인란으로 렌더링된다. 진짜 폼 입력의 대체재는 아니다.

이스케이프

Markdown 기호를 문자 그대로 표시하려면 앞에 백슬래시를 붙인다.

\*기울임 아님\*
\# 제목 아님

고급 팁과 예제

표

표는 GFM 확장이며 원래 Markdown 사양에는 포함되지 않는다.

| 기능      | CommonMark | GFM  |
| --------- | ---------- | ---- |
| 표        | 미지원     | 지원 |
| 작업 목록 | 미지원     | 지원 |

정렬은 선택 사항이다.

| 왼쪽 정렬 | 가울데 정렬 | 오른쪽 정렬 |
| :-------- | :---------: | ----------: |
| A         |      B      |           C |

표는 단순하게 유지한다. 중첩 표, 행 병합, 열 병합은 표준이 아니며 종종 실패한다.

각주

Pandoc과 일부 GFM 파서가 각주를 지원한다.

여기에 진술이 있다.[^1]

[^1]: 이것이 각주 텍스트다.

각주가 포함된 PDF를 렌더링해야 한다면, Pandoc 스타일 문법을 지원하는 변환기를 사용하거나 수동으로 삽입한다.

수식

Pandoc과 많은 최신 편집기는 LaTeX 수식을 지원한다.

인라인 수식: $E = mc^2$

블록 수식:

$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$

수식 렌더링은 파서와 출력 형식에 따라 달라진다. HTML에서는 보통 MathJax나 KaTeX가 필요하다. PDF 변환기에는 LaTeX 백엔드가 필요한 경우가 많다.

정의 목록

Pandoc의 또 다른 확장이다.

용어
: 용어의 정의.

다른 용어
: 다른 정의.

Markdown 안의 HTML

Markdown만으로는 부족할 때 HTML을 직접 쓸 수 있다.

<p style="color: red;">이것은 빨간색 텍스트다.</p>

이것은 레이아웃, 임베디드 동영상, Markdown이 지원하지 않는 속성에 유용하다. 하지만 이식성을 잃게 되므로 절제해서 사용한다.

Markdown을 변환해야 할 때

Markdown은 작성과 버전 관리에 뛰어나다. 그러나 어떤 기기에서도 동일하게 보여야 하는 최종 문서에는 적합하지 않다. 그래서 변환기가 존재한다.

Markdown 초안을 공유 가능한 PDF로 만들고 싶다면 Markdown to PDF 변환기를 사용하라. 브라우저 안에서 실행되므로 파일이 외부로 나가지 않는다.

PDF에서 편집 가능한 Markdown이 필요하다면 PDF to Markdown 변환기를 사용하라. 서버에 업로드하지 않고도 제목, 목록, 단락을 추출한다.