마크다운 완벽 가이드 - 기초부터 고급까지

마크다운(Markdown)은 존 그루버(John Gruber)가 2004년에 만든 경량 마크업 언어입니다. 마크다운의 핵심 철학은 "읽기 쉽고, 쓰기 쉬운 일반 텍스트 형식"을 제공하는 것입니다. 복잡한 HTML 태그를 사용하지 않고도 간단한 기호만으로 문서의 구조와 서식을 표현할 수 있어, 개발자뿐만 아니라 기술 문서 작성자, 블로거, 연구자 등 다양한 분야에서 널리 사용되고 있습니다.

2026년 현재, 마크다운은 GitHub, GitLab, Notion, Obsidian, Slack, Discord, Reddit 등 수많은 플랫폼에서 기본 문서 형식으로 채택되어 있습니다. 이 가이드에서는 마크다운의 기초 문법부터 고급 기능까지 체계적으로 학습하고, 실무에서 마크다운을 효과적으로 활용하는 방법을 알아보겠습니다. 작성한 마크다운을 바로 확인해보고 싶다면 마크다운 미리보기 도구를 활용해 보세요.

마크다운 기본 문법

제목 (Headings)

마크다운에서 제목은 # 기호를 사용하여 작성합니다. #의 개수에 따라 제목의 수준(H1~H6)이 결정됩니다.

# H1 - 최상위 제목
## H2 - 두 번째 수준 제목
### H3 - 세 번째 수준 제목
#### H4 - 네 번째 수준 제목
##### H5 - 다섯 번째 수준 제목
###### H6 - 여섯 번째 수준 제목

제목 작성 모범 사례:

H1은 문서당 하나만 사용합니다
제목 수준을 건너뛰지 마세요 (H2 다음에 H4를 사용하지 않음)
# 뒤에 반드시 공백을 넣으세요
제목 전후로 빈 줄을 넣으면 가독성이 향상됩니다

단락과 줄 바꿈

마크다운에서 단락은 빈 줄로 구분합니다. 같은 단락 안에서 줄을 바꾸려면 줄 끝에 공백 2개를 넣거나 <br> 태그를 사용합니다.

이것은 첫 번째 단락입니다.

이것은 두 번째 단락입니다. 빈 줄로 단락이 구분됩니다.

이 줄 끝에 공백 두 개가 있으면
다음 줄로 바뀝니다.

텍스트 강조 (Emphasis)

텍스트를 강조하는 다양한 방법이 있습니다.

*이탤릭(기울임)* 또는 _이탤릭_
**볼드(굵게)** 또는 __볼드__
***볼드 이탤릭*** 또는 ___볼드 이탤릭___
~~취소선~~

렌더링 결과:

마크다운 문법	결과	용도
`텍스트`	이탤릭	용어, 강조
`텍스트`	볼드	중요 내용 강조
`*텍스트*`	볼드 이탤릭	매우 중요한 내용
`~~텍스트~~`	~~취소선~~	삭제/변경 표시
`텍스트`	`코드`	인라인 코드

목록 (Lists)

순서 없는 목록 (Unordered List)

- 항목 1
- 항목 2
  - 하위 항목 2-1
  - 하위 항목 2-2
    - 더 깊은 항목
- 항목 3

* 별표도 사용 가능
+ 더하기도 사용 가능

순서 있는 목록 (Ordered List)

1. 첫 번째 항목
2. 두 번째 항목
   1. 하위 첫 번째
   2. 하위 두 번째
3. 세 번째 항목

{/*  번호가 자동으로 정렬됩니다 */}
1. 첫 번째
1. 두 번째 (1로 써도 2로 표시)
1. 세 번째 (1로 써도 3으로 표시)

정의 목록 (Definition List)

용어 1
: 정의 1에 대한 설명입니다.

용어 2
: 정의 2에 대한 설명입니다.
: 추가 설명도 가능합니다.

링크 (Links)

{/*  인라인 링크 */}
[ToolBox Hub](https://toolboxhubs.com)

{/*  타이틀 포함 */}
[마크다운 미리보기](https://toolboxhubs.com/ko/tools/markdown-preview "마크다운 미리보기 도구")

{/*  참조 링크 */}
[GitHub][github-link]
[Google][1]

[github-link]: https://github.com
[1]: https://google.com

{/*  URL 자동 링크 */}
<https://toolboxhubs.com>

{/*  이메일 링크 */}
<email@example.com>

이미지 (Images)

{/*  기본 이미지 */}
![대체 텍스트](이미지-URL)

{/*  타이틀 포함 */}
![스크린샷](./screenshot.png "도구 스크린샷")

{/*  참조 방식 */}
![로고][logo]
[logo]: ./logo.png "회사 로고"

{/*  HTML로 크기 지정 */}
<img src="image.png" alt="이미지" width="400" />

인용문 (Blockquotes)

> 이것은 인용문입니다.
> 여러 줄에 걸쳐 작성할 수 있습니다.

> 중첩된 인용문도 가능합니다.
>> 이것은 중첩된 인용문입니다.
>>> 더 깊이 중첩할 수 있습니다.

> **팁:** 인용문 안에서도 마크다운 서식을 사용할 수 있습니다.
> - 목록도 가능합니다
> - `코드`도 가능합니다

수평선 (Horizontal Rule)

---
***
___

세 가지 모두 동일한 수평선을 생성합니다. ---를 가장 많이 사용합니다.

코드 블록 (Code Blocks)

코드 블록은 개발자가 마크다운을 사용하는 가장 큰 이유 중 하나입니다.

인라인 코드

변수 `count`의 타입은 `number`입니다.
`npm install` 명령어를 실행하세요.

펜스드 코드 블록 (Fenced Code Blocks)

백틱 세 개(```)로 코드 블록을 만들고, 언어를 지정하면 구문 강조(syntax highlighting)가 적용됩니다.

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

greet('개발자');
```

지원되는 주요 언어 식별자:

언어	식별자	언어	식별자
JavaScript	`javascript` 또는 `js`	Python	`python` 또는 `py`
TypeScript	`typescript` 또는 `ts`	Java	`java`
HTML	`html`	CSS	`css`
JSON	`json`	YAML	`yaml` 또는 `yml`
Bash/Shell	`bash` 또는 `sh`	SQL	`sql`
Go	`go`	Rust	`rust`
C/C++	`c` / `cpp`	C#	`csharp` 또는 `cs`
Ruby	`ruby` 또는 `rb`	PHP	`php`
Swift	`swift`	Kotlin	`kotlin`
Markdown	`markdown` 또는 `md`	Diff	`diff`

Diff 코드 블록

코드 변경 사항을 보여줄 때 유용합니다.

```diff
- const oldFunction = function() {
-   return 'old';
- };
+ const newFunction = () => {
+   return 'new';
+ };
```

테이블 (Tables)

마크다운 테이블은 파이프(|)와 하이픈(-)을 사용하여 만듭니다.

기본 테이블

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

정렬

| 왼쪽 정렬 | 가운데 정렬 | 오른쪽 정렬 |
|:----------|:----------:|----------:|
| 왼쪽 | 가운데 | 오른쪽 |
| Left | Center | Right |
| ABC | DEF | GHI |

:--- : 왼쪽 정렬 (기본값)
:---: : 가운데 정렬
---: : 오른쪽 정렬

테이블 팁

{/*  테이블 안에서 서식 사용 */}
| 기능 | 설명 | 상태 |
|------|------|------|
| **로그인** | `JWT` 기반 인증 | 완료 |
| **결제** | *PG 연동* 필요 | 진행 중 |
| ~~회원탈퇴~~ | 요구사항 변경 | 취소 |

{/*  파이프 문자 이스케이프 */}
| 표현식 | 결과 |
|--------|------|
| `a \| b` | OR 연산 |

체크리스트 (Task Lists)

GitHub Flavored Markdown(GFM)에서 지원하는 체크리스트 기능입니다.

## 프로젝트 진행 상황

- [x] 프로젝트 초기 설정
- [x] 데이터베이스 스키마 설계
- [x] API 엔드포인트 구현
- [ ] 프론트엔드 UI 개발
- [ ] 테스트 작성
- [ ] 배포 파이프라인 설정

## 코드 리뷰 체크리스트

- [x] 코드 스타일 준수 확인
- [x] 타입 안전성 확인
- [ ] 에러 처리 확인
- [ ] 성능 이슈 확인
- [ ] 보안 취약점 확인

GitHub에서는 이슈와 PR에서 체크리스트를 대화식으로 클릭하여 상태를 변경할 수 있습니다.

GFM (GitHub Flavored Markdown) 확장 기능

GitHub Flavored Markdown은 표준 마크다운을 확장한 것으로, GitHub에서 사용되는 추가 기능들을 제공합니다.

자동 링크

{/*  URL이 자동으로 링크로 변환됩니다 */}
https://toolboxhubs.com

{/*  이슈/PR 참조 */}
#123
username/repo#123

{/*  사용자 멘션 */}
@username

{/*  SHA 참조 */}
a1b2c3d
username/repo@a1b2c3d

각주 (Footnotes)

마크다운은 존 그루버가 만들었습니다[^1]. 아론 스워츠도 개발에 참여했습니다[^2].

[^1]: 존 그루버(John Gruber)는 Daring Fireball 블로그의 운영자입니다.
[^2]: 아론 스워츠(Aaron Swartz)는 RSS, Creative Commons 등의 개발에도 참여한 프로그래머입니다.

경고 블록 (Alerts) - GitHub 확장

> [!NOTE]
> 알아두면 유용한 정보입니다.

> [!TIP]
> 더 나은 방법을 제시하는 팁입니다.

> [!IMPORTANT]
> 꼭 알아야 하는 중요한 정보입니다.

> [!WARNING]
> 주의가 필요한 내용입니다.

> [!CAUTION]
> 위험할 수 있는 내용에 대한 경고입니다.

수학 공식 (Math) - GitHub 확장

{/*  인라인 수학 */}
아인슈타인의 공식: $E = mc^2$

{/*  블록 수학 */}
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

다이어그램 (Mermaid) - GitHub 확장

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

```mermaid
sequenceDiagram
    participant 클라이언트
    participant API서버
    participant 데이터베이스

    클라이언트->>API서버: POST /api/users
    API서버->>데이터베이스: INSERT INTO users
    데이터베이스*/}>API서버: 결과 반환
    API서버*/}>클라이언트: 201 Created
```

고급 마크다운 기법

HTML 혼합 사용

마크다운에서 HTML 태그를 직접 사용할 수 있습니다. 예를 들어 details와 summary 태그로 접을 수 있는 섹션을 만들 수 있고, kbd 태그로 키보드 입력을 표시할 수 있습니다. mark 태그로 형광펜 효과를, sub과 sup 태그로 위첨자/아래첨자를 만들 수 있습니다.

주요 HTML 태그 활용 예시:

접기/펼치기: details와 summary 태그 조합
키보드 키 표시: kbd 태그 (예: Ctrl + C)
텍스트 강조: mark 태그
화학식/수식: sub(아래첨자), sup(위첨자) 태그

이스케이프 문자

마크다운에서 특수 문자를 그대로 표시하려면 백슬래시(\)를 사용합니다.

\* 별표를 그대로 표시
\# 해시 기호를 그대로 표시
\[ 대괄호를 그대로 표시
\` 백틱을 그대로 표시
\| 파이프를 그대로 표시

{/*  이스케이프가 필요한 문자들 */}
\   백슬래시
`   백틱
*   별표
_   밑줄
{}  중괄호
[]  대괄호
()  소괄호
#   해시
+   더하기
-   하이픈
.   점
!   느낌표
|   파이프

앵커 링크 (목차 만들기)

## 목차

- [소개](#소개)
- [설치 방법](#설치-방법)
- [사용법](#사용법)
  - [기본 사용법](#기본-사용법)
  - [고급 사용법](#고급-사용법)
- [FAQ](#faq)

## 소개
여기에 소개 내용...

## 설치 방법
여기에 설치 방법...

앵커 링크 규칙:

모든 문자를 소문자로 변환
공백은 하이픈(-)으로 대체
특수 문자는 제거
한글도 지원 (GitHub, GitLab 등)

실무 활용 예시

README.md 작성

# 프로젝트 이름

![빌드 상태](https://img.shields.io/badge/build-passing-brightgreen)
![버전](https://img.shields.io/badge/version-1.0.0-blue)
![라이선스](https://img.shields.io/badge/license-MIT-green)

프로젝트에 대한 간단한 설명을 여기에 작성합니다.

## 주요 기능

- 기능 1: 설명
- 기능 2: 설명
- 기능 3: 설명

## 시작하기

### 필수 조건

- Node.js 20 이상
- npm 또는 yarn

### 설치

\```bash
git clone https://github.com/username/project.git
cd project
npm install
\```

### 실행

\```bash
npm run dev
\```

## 기여하기

1. 프로젝트를 포크합니다
2. 기능 브랜치를 만듭니다 (`git checkout -b feature/amazing-feature`)
3. 변경사항을 커밋합니다 (`git commit -m 'Add amazing feature'`)
4. 브랜치에 푸시합니다 (`git push origin feature/amazing-feature`)
5. Pull Request를 생성합니다

## 라이선스

MIT License - 자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.

API 문서 작성

## API 엔드포인트

### 사용자 생성

`POST /api/v1/users`

#### 요청 헤더

| 헤더 | 값 | 필수 |
|------|---|------|
| Content-Type | application/json | 예 |
| Authorization | Bearer {token} | 예 |

#### 요청 본문

\```json
{
  "name": "홍길동",
  "email": "hong@example.com",
  "role": "editor"
}
\```

#### 응답 (201 Created)

\```json
{
  "id": "user_123",
  "name": "홍길동",
  "email": "hong@example.com",
  "role": "editor",
  "createdAt": "2026-03-10T09:00:00Z"
}
\```

#### 에러 응답

| 상태 코드 | 설명 |
|-----------|------|
| 400 | 잘못된 요청 (입력 검증 실패) |
| 401 | 인증 필요 |
| 409 | 이메일 중복 |
| 500 | 서버 내부 오류 |

회의록 / 기술 노트

# 2026년 3월 스프린트 회의록

**날짜:** 2026-03-10
**참석자:** @hong, @kim, @lee
**작성자:** @hong

## 논의 사항

### 1. 인증 시스템 리팩토링

- [x] JWT에서 세션 기반으로 전환 검토
- [ ] OAuth2 통합 설계 완료
- [ ] 기존 사용자 마이그레이션 계획

> **결정:** JWT를 유지하되, Refresh Token Rotation을 도입하기로 함

### 2. 성능 최적화

| 페이지 | 현재 LCP | 목표 LCP |
|--------|---------|---------|
| 메인 | 3.2초 | 1.5초 |
| 검색 | 4.1초 | 2.0초 |
| 상세 | 2.8초 | 1.2초 |

### 액션 아이템

1. **@hong** - Refresh Token Rotation 구현 (3/15까지)
2. **@kim** - 이미지 최적화 파이프라인 구축 (3/12까지)
3. **@lee** - 검색 페이지 쿼리 최적화 (3/14까지)

마크다운 에디터 및 도구

온라인 도구

마크다운을 작성하고 실시간으로 미리 볼 수 있는 도구를 활용하면 생산성이 크게 향상됩니다:

마크다운 미리보기 - ToolBox Hub의 실시간 마크다운 미리보기 도구
JSON 포맷터 - API 문서 작성 시 JSON 예제 정리
Base64 인코더/디코더 - 이미지 Base64 인코딩

데스크톱 에디터

에디터	플랫폼	특징	가격
VS Code	Windows, Mac, Linux	확장 기능 풍부, 미리보기	무료
Obsidian	Windows, Mac, Linux	양방향 링크, 그래프 뷰	개인 무료
Typora	Windows, Mac, Linux	WYSIWYG 편집	$14.99
iA Writer	Mac, iOS, Windows	집중 모드, 미니멀	$49.99
Mark Text	Windows, Mac, Linux	오픈소스 WYSIWYG	무료

VS Code 마크다운 확장 기능

추천 확장 기능:
1. Markdown All in One - 단축키, 목차 자동 생성, 수학 지원
2. Markdown Preview Enhanced - 향상된 미리보기
3. markdownlint - 마크다운 문법 검사
4. Paste Image - 클립보드 이미지 붙여넣기
5. Markdown Table Formatter - 테이블 자동 정렬

마크다운 변환

마크다운은 다양한 형식으로 변환할 수 있습니다.

Pandoc을 활용한 변환

# 마크다운 -> HTML
pandoc input.md -o output.html

# 마크다운 -> PDF
pandoc input.md -o output.pdf --pdf-engine=xelatex

# 마크다운 -> Word (docx)
pandoc input.md -o output.docx

# 마크다운 -> 프레젠테이션 (reveal.js)
pandoc input.md -o slides.html -t revealjs -s

# HTML -> 마크다운
pandoc input.html -o output.md

프로그래밍에서의 마크다운 처리

// JavaScript에서 마크다운을 HTML로 변환
import { marked } from 'marked';
import DOMPurify from 'dompurify';

// 기본 변환
const markdown = '# Hello World\n\nThis is **bold** text.';
const html = marked(markdown);

// XSS 방지를 위한 sanitization
const safeHtml = DOMPurify.sanitize(html);

// 커스텀 렌더러
const renderer = new marked.Renderer();
renderer.link = (href, title, text) => {
  const isExternal = href.startsWith('http');
  const target = isExternal ? ' target="_blank" rel="noopener noreferrer"' : '';
  return `<a href="${href}"${target}>${text}</a>`;
};

marked.use({ renderer });

마크다운 작성 팁과 모범 사례

1. 일관된 스타일 유지

{/*  좋은 예: 일관된 목록 마커 사용 */}
- 항목 1
- 항목 2
- 항목 3

{/*  나쁜 예: 마커 혼용 */}
- 항목 1
* 항목 2
+ 항목 3

2. 줄 길이 제한

가독성을 위해 한 줄의 길이를 80~120자로 제한하는 것이 좋습니다. 특히 Git으로 관리되는 문서의 경우, 짧은 줄이 diff를 더 읽기 쉽게 만듭니다.

3. 의미 있는 링크 텍스트 사용

{/*  좋은 예 */}
자세한 내용은 [마크다운 공식 가이드](https://daringfireball.net/projects/markdown/)를 참고하세요.

{/*  나쁜 예 */}
자세한 내용은 [여기](https://daringfireball.net/projects/markdown/)를 클릭하세요.

4. 이미지에 대체 텍스트 작성

{/*  좋은 예: 설명적인 대체 텍스트 */}
![프로젝트 아키텍처 다이어그램 - 클라이언트, API 서버, 데이터베이스의 관계](./architecture.png)

{/*  나쁜 예: 의미 없는 대체 텍스트 */}
![이미지](./architecture.png)

5. markdownlint 규칙 활용

// .markdownlint.json
{
  "MD013": { "line_length": 120 },
  "MD033": false,
  "MD041": true,
  "MD024": { "siblings_only": true }
}

주요 규칙 설명:

규칙	설명	권장 설정
MD001	제목 레벨 순차 증가	활성화
MD009	줄 끝 공백	활성화
MD013	줄 길이 제한	120자
MD024	중복 제목 금지	siblings_only
MD033	인라인 HTML 금지	비활성화 (필요 시)
MD041	첫 줄은 H1이어야 함	활성화

결론

마크다운은 단순하면서도 강력한 문서 작성 도구입니다. 기본 문법만으로도 대부분의 문서 작성 요구를 충족할 수 있으며, GFM 확장 기능을 활용하면 체크리스트, 다이어그램, 수학 공식까지 표현할 수 있습니다.

마크다운을 효과적으로 활용하는 핵심은 꾸준한 연습입니다. README 파일, 기술 블로그, 회의록, API 문서 등 다양한 상황에서 마크다운을 사용해 보면서 자연스럽게 익혀보세요. 그리고 마크다운 미리보기 도구를 활용하여 작성한 마크다운이 어떻게 렌더링되는지 실시간으로 확인하면서 작성하면 더욱 효율적입니다.

마크다운 문법이 익숙해지면 문서 작성 속도가 비약적으로 향상되고, 일관성 있는 문서를 만들 수 있게 됩니다. 이 가이드를 참고하여 마크다운 마스터로 거듭나시길 바랍니다.