작가와 개발자를 위한 Markdown 가이드

Markdown은 인터넷에서 범용 글쓰기 형식에 가장 가까운 도구입니다. GitHub README, Notion 문서, Slack 메시지, 문서화 사이트, 블로그 게시물, 개발자 노트 등 다양한 곳에서 사용됩니다. 한 번만 배워두면 앞으로의 커리어 내내 어디서든 활용할 수 있습니다.

Markdown이란?

Markdown은 2004년 John Gruber가 만든 경량 마크업 언어입니다. 핵심 개념은 간단합니다. 간단한 문장 부호 규칙을 사용해 일반 텍스트로 작성하면, 아름답게 서식이 적용된 HTML로 렌더링됩니다.

This **bold text** and *italic text* render instantly.

렌더링 결과: This bold text and italic text render instantly.

원본 텍스트는 렌더링 전에도 충분히 읽기 쉽습니다.

기본 문법

제목

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

제목을 사용해 문서 계층 구조를 만드세요. # H1은 일반적으로 페이지 제목으로 사용되며, 문서당 하나만 사용하는 것이 좋습니다.

강조

**bold text**
*italic text*
***bold and italic***
~~strikethrough~~

목록

Unordered list:
- Item one
- Item two
  - Nested item (indent with 2 spaces)
  - Another nested item
- Item three

Ordered list:
1. First step
2. Second step
3. Third step

링크와 이미지

[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")

![Alt text for image](https://example.com/image.jpg)
![Alt text](./local-image.png "Optional title")

인용구

> This is a blockquote.
> It can span multiple lines.

> You can nest blockquotes:
> > Like this.

수평선

---

(세 개 이상의 대시, 별표, 또는 밑줄을 단독 줄에 입력)

코드 블록

인라인 코드는 백틱 하나를 사용합니다:

Use the `console.log()` function for debugging.

펜스 코드 블록은 백틱 세 개를 사용하며, 문법 강조를 위해 언어 식별자를 선택적으로 추가할 수 있습니다:

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

지원되는 언어에는 javascript, typescript, python, bash, sql, json, yaml, css, html, go, rust 등 수십 가지가 있으며, 렌더러에 따라 다를 수 있습니다.

표

Markdown 표는 파이프 문자와 대시를 사용합니다:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell A   | Cell B   | Cell C   |
| Cell D   | Cell E   | Cell F   |

구분선 행에 콜론을 사용해 열을 정렬할 수 있습니다:

| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

표는 표준 Markdown이 아닌 GitHub Flavored Markdown (GFM)의 기능입니다. GitHub, VS Code, 대부분의 문서화 플랫폼, MDX에서 사용할 수 있습니다.

작업 목록 (GFM)

- [x] Write the introduction
- [x] Add code examples
- [ ] Review and publish
- [ ] Add images

GitHub에서 인터랙티브 체크박스로 렌더링됩니다. 최신 Markdown 렌더러에서 폭넓게 지원됩니다.

Markdown 방언

원본 Markdown은 의도적으로 최소한의 기능만 제공합니다. 이후 다양한 확장 버전이 등장했습니다:

방언	사용처	주요 추가 기능
CommonMark	다양한 플랫폼	표준화된 명세
GitHub Flavored (GFM)	GitHub, GitLab	표, 작업 목록, 취소선, 자동 링크
MDX	React 사이트	Markdown 내 JSX 컴포넌트
Pandoc Markdown	학술 문서	각주, 인용, 수식
MultiMarkdown	macOS 도구	표, 메타데이터, 각주

확실하지 않을 때는 GFM을 사용하세요 — 가장 널리 지원되는 확장 방언입니다.

Front matter

많은 Markdown 프로세서는 메타데이터를 위해 파일 상단에 YAML front matter를 지원합니다:

---
title: "My Article Title"
date: "2026-03-24"
author: "Jane Doe"
tags: ["markdown", "writing", "tools"]
published: true
---

# Article content starts here

Front matter는 문서 본문과 별도로 파싱되어 페이지 제목, 날짜, SEO 메타데이터 등에 활용됩니다.

MDX: Markdown + JSX

MDX는 React 컴포넌트를 포함할 수 있는 Markdown입니다. React 기반 사이트(Next.js, Gatsby, Astro)의 문서화 및 블로그 게시물에 이상적입니다:

import { Alert } from '../components/Alert'

## Important note

<Alert type="warning">
  This feature is deprecated in v3.
</Alert>

Regular **Markdown** content continues below.

이를 통해 Markdown의 단순함과 인터랙티브 컴포넌트의 강력함을 결합할 수 있습니다.

특수 문자 이스케이프

특수 Markdown 문자 앞에 백슬래시를 붙이면 그대로 출력됩니다:

\*not italic\*
\# not a heading
\[not a link\]

더 나은 Markdown 문서를 위한 팁

1. 문장당 한 줄 — Git에서 diff를 더 깔끔하게 만들어줍니다. Markdown은 단일 줄바꿈을 무시하므로 렌더링 결과는 동일합니다.
2. 블록 사이에 빈 줄 — 단락, 제목, 목록, 코드 블록 사이에는 항상 빈 줄을 추가하세요.
3. 일관된 목록 마커 — 순서 없는 목록에는 - 또는 * 중 하나를 선택해 프로젝트 전체에서 통일하세요.
4. 반복 URL에 참조 링크 사용 — 한 번 정의하고 여러 번 사용:

   See the [documentation][docs] and [changelog][docs].
   [docs]: https://example.com/docs
   

5. 모든 이미지에 alt 텍스트 — 접근성과 SEO에 필수적입니다.

가독성 확인

Markdown은 글쓰기를 쉽게 만들어주지만, 쉽게 쓴 글이 읽기 어려운 텍스트가 될 수도 있습니다. 가독성 점수 도구를 사용해 Flesch-Kincaid 학년 수준, 문장 복잡도, 수동태 사용 빈도를 확인해보세요. 일반 독자를 대상으로 한 글은 8~10학년 수준의 명확하고 간결한 언어를 목표로 하세요.

Markdown은 배우는 데 10분이면 충분하지만 평생 도움이 되는 도구 중 하나입니다. 지금 바로 시작해보세요 — 미래의 협업자들(그리고 미래의 자신)이 고마워할 것입니다.