마크다운 완벽 가이드: 문법, 팁 & 모범 사례

2026년 3월 31일 · 12분 읽기

마크다운이란?

마크다운은 2004년 John Gruber가 Aaron Swartz와 협력하여 만든 경량 마크업 언어입니다. 렌더링 없이도 읽을 수 있는 일반 텍스트 문법을 사용하여 서식이 지정된 텍스트를 작성할 수 있습니다. 워드 프로세서에서 버튼을 클릭하거나 장황한 HTML 태그를 작성하는 대신, 제목에는 #, 굵은 텍스트에는 **, 목록에는 -와 같은 간단하고 직관적인 문자를 사용합니다.

마크다운의 철학은 우아하게 단순합니다: 소스 텍스트는 렌더링된 출력만큼 읽기 쉬워야 합니다. 텍스트 편집기에서 마크다운 파일을 열면 특수 소프트웨어나 렌더링 엔진 없이도 즉시 구조와 내용을 이해할 수 있습니다.

마크다운은 소프트웨어 개발 세계 전반에 걸쳐 기술 문서 작성, 문서화, README 파일, 블로그 게시물, 노트 작성의 사실상 표준이 되었습니다. GitHub, GitLab, Reddit, Stack Overflow, Discord, Slack, Notion, Obsidian과 같은 주요 플랫폼이 모두 마크다운을 기본적으로 지원하므로 개발자, 기술 작가, 콘텐츠 제작자에게 필수적인 기술입니다.

마크다운을 사용하는 이유는?

• 속도와 효율성: **굵게**를 작성하는 것이 <strong>굵게</strong>를 입력하거나 서식 도구 모음을 사용하는 것보다 훨씬 빠릅니다
• 범용 이식성: 일반 텍스트 파일은 호환성 문제 없이 모든 운영 체제와 모든 텍스트 편집기에서 작동합니다
• 버전 관리 친화적: 마크다운을 사용하면 Git diff가 깔끔하고 의미 있어 협업과 변경 추적이 간단합니다
• 방해 없는 작성: 서식 도구 모음의 방해나 복잡한 인터페이스 없이 오직 당신과 콘텐츠만
• 쉬운 변환: Pandoc과 같은 도구를 사용하여 마크다운을 HTML, PDF, DOCX, LaTeX 및 수십 가지 다른 형식으로 쉽게 변환할 수 있습니다
• 미래 보장: 일반 텍스트 파일은 수십 년 후에도 읽을 수 있으며, 구식이 될 수 있는 독점 형식과 달리
• 접근성: 적절하게 구조화된 마크다운은 의미론적 HTML로 변환되어 스크린 리더의 접근성을 향상시킵니다

제목과 문서 구조

제목은 마크다운에서 문서 구조의 근간입니다. # 기호를 사용하며, 해시 마크의 수가 1부터 6까지의 제목 수준을 결정합니다:

# 제목 1
## 제목 2
### 제목 3
#### 제목 4
##### 제목 5
###### 제목 6

# 기호 뒤에 항상 공백을 포함하세요—대부분의 마크다운 프로세서가 이를 요구하며 가독성을 향상시킵니다. 렌더링된 출력은 적절한 HTML 제목 태그(<h1>부터 <h6>까지)를 생성하며, 이는 문서 구조, 접근성 및 SEO에 중요합니다.

제목 모범 사례

수준을 건너뛰지 않고 제목 수준을 순차적으로 사용하세요. H1에서 H3로 건너뛰지 마세요—이는 문서 계층 구조를 깨뜨리고 스크린 리더 사용자에게 접근성 문제를 일으킵니다. 제목을 개요로 생각하세요: 각 수준은 이전 수준 내에 논리적으로 중첩되어야 합니다.

대부분의 문서는 하나의 H1 제목(제목)만 가져야 하며, 주요 섹션에는 H2 제목, 하위 섹션에는 H3-H6을 사용합니다. 이는 사람과 검색 엔진 모두가 이해할 수 있는 명확한 정보 계층 구조를 만듭니다.

대체 제목 문법

마크다운은 밑줄을 사용하는 H1 및 H2 제목의 대체 문법도 지원합니다:

제목 1
=========

제목 2
---------

이 문법은 유효하지만 해시 마크 문법이 더 일반적이고 6개의 제목 수준을 모두 지원하므로 대부분의 작가에게 선호되는 선택입니다.

텍스트 서식 필수 요소

마크다운은 일반적인 텍스트 서식 요구 사항에 대해 간단하고 직관적인 문법을 제공합니다. 이러한 서식 옵션은 단락 내에서 인라인으로 작동하며 더 복잡한 스타일을 위해 결합할 수 있습니다.

강조 문법 세부 사항

별표(*)와 밑줄(_) 모두 강조에 사용할 수 있지만 별표가 더 일반적으로 사용되고 권장됩니다. 주요 차이점: 별표는 단어 중간에서 작동하지만(un*frigging*believable), 밑줄은 단어 경계가 필요합니다.

굵은 텍스트의 경우 이중 별표 또는 밑줄을 사용합니다. 기울임 텍스트의 경우 단일 별표 또는 밑줄을 사용합니다. 굵은 기울임 텍스트의 경우 세 개를 결합합니다. 이러한 일관성은 마크다운 소스를 더 읽기 쉽고 예측 가능하게 만듭니다.

특수 문자 이스케이프

리터럴 별표, 밑줄 또는 기타 마크다운 문법 문자를 표시해야 하는 경우 백슬래시로 이스케이프하세요:

이것은 \*기울임이 아님\*이고 \*\*굵게가 아님\*\*
제목을 만들지 않고 해시 마크를 표시하려면 \#를 사용

이스케이프가 필요한 일반적인 문자는 다음과 같습니다: \ ` * _ { } [ ] ( ) # + - . !

목록: 순서 있는, 순서 없는, 중첩된

목록은 마크다운에서 정보를 구성하는 데 기본적입니다. 만들기 쉽고 계층적 콘텐츠를 위한 중첩을 지원합니다.

순서 없는 목록

-, * 또는 + 뒤에 공백을 사용하여 순서 없는(글머리 기호) 목록을 만듭니다. 세 가지 마커 모두 동일하게 작동하지만 문서 내에서 일관성을 유지하면 가독성이 향상됩니다:

- 첫 번째 항목
- 두 번째 항목
- 세 번째 항목
  - 중첩된 항목 (2칸 들여쓰기)
  - 또 다른 중첩된 항목
- 네 번째 항목

중첩된 목록의 표준 들여쓰기는 2칸이지만 일부 파서는 4칸을 허용합니다. 최대 호환성을 위해 2칸을 사용하세요.

순서 있는 목록

순서 있는(번호가 매겨진) 목록은 마침표와 공백이 뒤따르는 숫자를 사용합니다:

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

유용한 기능이 있습니다: 사용하는 실제 숫자는 중요하지 않습니다. 마크다운은 렌더링될 때 목록을 자동으로 순차적으로 번호를 매깁니다. 모든 항목에 1.을 사용할 수 있어 번호를 다시 매기지 않고도 항목을 쉽게 재정렬할 수 있습니다:

1. 첫 번째 항목
1. 두 번째 항목
1. 세 번째 항목

이것은 적절하게 번호가 매겨진 1, 2, 3 목록으로 렌더링됩니다. 이 기술은 긴 목록을 유지 관리하거나 항목을 자주 재정렬할 때 특히 유용합니다.

작업 목록

많은 마크다운 종류(GitHub Flavored Markdown 포함)는 체크박스가 있는 작업 목록을 지원합니다:

- [x] 완료된 작업
- [ ] 미완료 작업
- [ ] 또 다른 미완료 작업

작업 목록은 프로젝트 관리, 이슈 추적 및 문서의 할 일 목록에 매우 유용합니다.

정의 목록

일부 확장 마크다운 문법은 용어집 및 용어 정의를 위한 정의 목록을 지원합니다:

용어 1
: 용어 1에 대한 정의

용어 2
: 용어 2에 대한 첫 번째 정의
: 용어 2에 대한 두 번째 정의

보편적으로 지원되지는 않지만 정의 목록은 기술 문서 및 용어집에 유용합니다.

링크와 이미지

마크다운은 소스 텍스트를 읽기 쉽게 유지하면서 하이퍼링크와 이미지를 쉽게 추가할 수 있습니다.

인라인 링크

가장 일반적인 링크 문법은 링크 텍스트에 대괄호를, URL에 괄호를 사용합니다:

[링크 텍스트](https://example.com)
[제목이 있는 링크](https://example.com "호버 텍스트")

선택적 제목 텍스트는 사용자가 링크 위로 마우스를 가져갈 때 툴팁으로 나타납니다. 이는 보이는 링크 텍스트를 복잡하게 만들지 않고 추가 컨텍스트를 제공하는 데 유용합니다.

참조 스타일 링크

많은 링크가 있거나 반복되는 URL이 있는 문서의 경우 참조 스타일 링크가 가독성을 향상시킵니다:

이것은 [링크][1]이고 여기 [또 다른 링크][2]가 있습니다.

[1]: https://example.com
[2]: https://example.com/page "선택적 제목"

숫자 대신 설명적인 참조를 사용할 수도 있습니다:

[Google][google]과 [GitHub][gh]를 확인하세요.

[google]: https://google.com
[gh]: https://github.com

참조 정의는 문서의 어디에나 나타날 수 있으며 출력에 렌더링되지 않습니다. 많은 작가들이 섹션 끝이나 문서 끝에 배치합니다.

자동 링크

URL 또는 이메일 주소를 꺾쇠 괄호로 감싸 자동 링크를 만듭니다:

<https://example.com>
<[email protected]>

대부분의 최신 마크다운 파서는 베어 URL도 자동으로 클릭 가능한 링크로 변환하지만 이 동작은 모든 플랫폼에서 보장되지 않습니다.

이미지

이미지 문법은 느낌표 접두사가 있는 링크 문법과 거의 동일합니다:

![대체 텍스트](image.jpg)
![대체 텍스트](image.jpg "이미지 제목")

대체 텍스트는 접근성에 중요합니다—스크린 리더 사용자를 위해 이미지를 설명하고 이미지 로드에 실패할 때 표시됩니다. 항상 이미지의 내용과 목적을 전달하는 의미 있는 대체 텍스트를 제공하세요.

참조 스타일 문법도 이미지에 작동합니다:

![로고][logo]

[logo]: /images/logo.png "회사 로고"

이미지 링크

이미지를 클릭 가능하게 만들려면 이미지 문법을 링크 문법으로 감싸세요:

[![대체 텍스트](thumbnail.jpg)](full-size.jpg)

이 기술은 이미지 갤러리나 썸네일을 전체 해상도 버전에 링크하는 데 일반적으로 사용됩니다.

코드 블록과 구문 강조

마크다운은 코드 표시에 탁월하여 기술 문서 및 프로그래밍 튜토리얼에 선호되는 형식입니다.

인라인 코드

텍스트 내의 짧은 코드 스니펫의 경우 단일 백틱을 사용합니다:

출력을 표시하려면 `print()` 함수를 사용하세요.
`config.json` 파일에는 설정이 포함되어 있습니다.

코드에 백틱이 포함된 경우 이중 백틱을 사용하여 감싸세요:

``코드에서 `백틱` 사용``

펜스 코드 블록

여러 줄 코드 블록의 경우 코드 앞뒤에 삼중 백틱(```) 또는 삼중 물결표(~~~)를 사용합니다:

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

이것은 고정폭 글꼴과 보존된 공백으로 적절하게 서식이 지정된 코드 블록을 만듭니다.

구문 강조

구문 강조를 활성화하려면 여는 백틱 바로 뒤에 프로그래밍 언어를 지정하세요:

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

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
#!/bin/bash
echo "안녕하세요, 세계!"
```