마크다운 기본 문법: 예제와 함께하는 완벽 가이드
마크다운 기본 문법의 모든 요소를 명확한 예제와 흔한 실수 방지법으로 마스터하세요. 제목, 목록, 링크 등에 대한 최종 참고 가이드입니다.
마크다운 기본 문법은 모든 개발자, 작가, 콘텐츠 크리에이터가 반드시 익혀야 하는 기초입니다. 문서를 작성하든, 블로그 글을 쓰든, GitHub 이슈를 작성하든, 이 핵심 요소들은 매일 사용하게 될 기본 구성 요소입니다.
이 가이드에서는 모든 기본 문법 요소를 명확한 예제, HTML 출력 비교, 그리고 흔한 실수 방지법과 함께 살펴봅니다. 북마크해 두세요 — 생각보다 자주 다시 찾게 될 것입니다.
제목(Headings)
제목은 콘텐츠를 논리적인 계층 구조로 구성합니다. 마크다운은 텍스트 앞에 # 기호를 배치하여 만드는 6단계의 제목을 지원합니다.
# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6
이는 다음과 같은 HTML을 생성합니다:
<h1>Heading Level 1</h1>
<h2>Heading Level 2</h2>
<h3>Heading Level 3</h3>
<h4>Heading Level 4</h4>
<h5>Heading Level 5</h5>
<h6>Heading Level 6</h6>
제목 작성 모범 사례
#과 제목 텍스트 사이에 반드시 공백을 추가하세요. 공백이 없으면 일부 파서에서 제목으로 인식하지 못합니다.
✅ ## This Works
❌ ##This Doesn't
제목을 순서대로 사용하세요. H2에서 H4로 건너뛰지 마세요 — 논리적인 문서 구조가 깨지고 접근성과 SEO에 모두 악영향을 미칩니다. 제목을 목차처럼 생각하세요: 각 단계는 상위 단계 아래에 논리적으로 중첩되어야 합니다.
H1은 페이지당 하나만 사용하세요. H1은 페이지 제목입니다. 나머지는 모두 H2 이하를 사용해야 합니다.
문단과 줄 바꿈
문단은 가장 간단한 마크다운 요소입니다 — 그냥 텍스트를 작성하면 됩니다. 문단을 구분하려면 빈 줄을 삽입하세요.
This is the first paragraph.
This is the second paragraph.
줄 바꿈
이 부분에서 많은 초보자들이 혼란을 겪습니다. 대부분의 마크다운 렌더러에서 Enter를 한 번 누르는 것만으로는 새 줄이 만들어지지 않습니다. 다음 중 하나를 사용해야 합니다:
- 줄 끝에 두 개 이상의 공백을 추가 (그런 다음 Enter를 누르세요)
<br>HTML 태그 사용
This is the first line.
This is the second line.
Or use HTML:<br>
This starts a new line.
흔한 실수
두 줄 사이에서 단순히 Enter를 누르면 렌더링된 결과에서 하나의 문단으로 합쳐집니다:
Line one
Line two
이는 "Line one Line two"로 렌더링됩니다 — 한 줄로 합쳐지는 것이죠. 새 문단을 만들려면 항상 빈 줄을 사용하고, 같은 문단 내에서 줄 바꿈을 하려면 후행 공백을 사용하세요.
텍스트 서식
마크다운을 사용하면 텍스트 강조를 손쉽게 할 수 있습니다. 다음은 핵심 서식 옵션입니다:
굵게 (Bold)
텍스트를 이중 별표 또는 이중 밑줄로 감쌉니다:
**This is bold text**
__This is also bold__
HTML 출력: <strong>This is bold text</strong>
기울임꼴 (Italic)
텍스트를 단일 별표 또는 단일 밑줄로 감쌉니다:
*This is italic text*
_This is also italic_
HTML 출력: <em>This is italic text</em>
굵은 기울임꼴 (Bold and Italic)
두 가지 모두 적용하려면 별표 세 개를 사용합니다:
***Bold and italic***
___Also bold and italic___
**_Or mix like this_**
HTML 출력: <strong><em>Bold and italic</em></strong>
취소선 (Strikethrough)
이중 물결표를 사용합니다 (GFM 확장 기능이지만 거의 모든 곳에서 지원됩니다):
~~This text is crossed out~~
HTML 출력: <del>This text is crossed out</del>
흔한 실수
단어 중간에 밑줄을 사용하는 것은 안정적으로 작동하지 않습니다. 단어 중간의 강조에는 별표를 사용하세요:
✅ This is**very**important
❌ This is__very__important
인용문 (Blockquotes)
인용문은 > 문자로 생성합니다. 출처를 인용하거나, 중요한 참고 사항을 강조하거나, 핵심 정보를 부각시킬 때 주로 사용됩니다.
> Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
> — John Gruber
HTML 출력:
<blockquote>
<p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
— John Gruber</p>
</blockquote>
여러 문단 인용문
문단 사이의 빈 줄에 >를 추가합니다:
> First paragraph of the quote.
>
> Second paragraph of the quote.
중첩 인용문
>>를 사용하여 중첩합니다:
> This is the outer quote.
>
>> This is a nested quote inside it.
다른 요소와 함께 사용하는 인용문
인용문을 다른 마크다운 서식과 결합할 수 있습니다:
> ### A Heading Inside a Quote
>
> - List item one
> - List item two
>
> Text with **bold** and *italic* formatting.
목록 (Lists)
목록은 마크다운에서 가장 자주 사용되는 요소 중 하나입니다. 비정렬 목록, 정렬 목록, 작업 목록의 세 가지 유형이 있습니다.
비정렬 목록
-, *, 또는 +를 마커로 사용합니다. 일관성을 위해 하나를 선택하여 사용하세요:
- First item
- Second item
- Third item
HTML 출력:
<ul>
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
</ul>
정렬 목록
숫자 뒤에 마침표를 사용합니다. 실제 숫자는 중요하지 않습니다 — 마크다운이 자동으로 번호를 매깁니다:
1. First step
2. Second step
3. Third step
흥미롭게도 이것도 동일한 결과를 생성합니다:
1. First step
1. Second step
1. Third step
둘 다 올바르게 1-2-3으로 번호가 매겨진 목록으로 렌더링됩니다. 하지만 소스 파일의 가독성을 위해 순차적인 번호를 사용하는 것이 모범 사례입니다.
중첩 목록
두 칸 또는 네 칸 들여쓰기로 하위 목록을 생성합니다:
1. Main item
- Sub-item A
- Sub-item B
- Sub-sub-item
2. Another main item
작업 목록
작업 목록(GFM 기능)은 미완료 항목에 - [ ], 완료 항목에 - [x]를 사용합니다:
- [x] Write the draft
- [x] Add code examples
- [ ] Proofread the article
- [ ] Publish
흔한 실수
문단 뒤에 목록이 올 때 목록 앞에 빈 줄을 넣는 것을 잊는 경우가 있습니다. 일부 파서에서는 빈 줄이 필수입니다:
✅ Here is my list:
- Item one
- Item two
❌ Here is my list:
- Item one
- Item two
코드 (Code)
코드 표시는 마크다운의 가장 강력한 기능 중 하나이며, 가독성을 위해 올바르게 사용하는 것이 중요합니다.
인라인 코드
인라인 표시를 위해 코드를 단일 백틱으로 감쌉니다:
Use the `print()` function to output text.
HTML 출력: Use the <code>print()</code> function to output text.
코드 자체에 백틱이 포함된 경우, 이중 백틱을 사용합니다:
``There is a literal `backtick` here.``
코드 블록
여러 줄의 코드에는 삼중 백틱(펜스드 코드 블록)과 구문 강조를 위한 선택적 언어 식별자를 사용합니다:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
언어 식별자(javascript, python, html, css, bash 등)를 사용하면 대부분의 렌더러에서 구문 강조가 활성화됩니다. 항상 포함하세요 — 가독성이 크게 향상됩니다.
들여쓰기 코드 블록
네 칸 공백 또는 하나의 탭으로 모든 줄을 들여쓰기하여 코드 블록을 만들 수도 있습니다:
function add(a, b) {
return a + b;
}
하지만 펜스드 코드 블록이 강력히 권장됩니다. 구문 강조를 지원하고 모든 줄을 들여쓸 필요가 없기 때문입니다.
링크 (Links)
링크는 콘텐츠를 연결하는 데 필수적입니다. 마크다운은 여러 가지 링크 형식을 지원합니다.
인라인 링크
가장 일반적인 형식 — 대괄호 안에 텍스트, 소괄호 안에 URL:
[Visit Example](https://example.com)
HTML 출력: <a href="https://example.com">Visit Example</a>
제목이 있는 링크
URL 뒤에 따옴표로 제목을 추가합니다 (마우스를 올리면 툴팁으로 표시됩니다):
[Visit Example](https://example.com "Example Website")
참조 스타일 링크
많은 링크가 있을 때 소스 텍스트를 깔끔하게 유지하려면 참조 스타일을 사용하세요:
I use [Google][1] and [GitHub][2] daily.
[1]: https://google.com "Google"
[2]: https://github.com "GitHub"
이렇게 하면 문단이 깔끔하게 유지되고 모든 URL이 하단에 모이게 됩니다 — 긴 문서에서 특히 유용합니다.
자동 링크
URL이나 이메일을 꺾쇠 괄호로 감싸면 자동으로 링크됩니다:
<https://example.com>
<contact@example.com>
대부분의 최신 렌더러(예: GitHub)는 꺾쇠 괄호 없이도 일반 URL을 자동으로 링크하지만, 꺾쇠 괄호를 사용하면 호환성이 보장됩니다.
흔한 실수
URL의 공백은 인코딩이 필요하다는 것을 잊지 마세요. 공백에는 %20을 사용합니다:
✅ [My Doc](files/my%20document.pdf)
❌ [My Doc](files/my document.pdf)
이미지 (Images)
이미지는 링크와 동일한 문법을 사용하지만, 앞에 느낌표 !를 붙입니다:
HTML 출력: <img src="/path/to/image.webp" alt="Alt text describing the image">
제목이 있는 이미지
링크된 이미지
링크와 이미지 문법을 결합하여 이미지를 클릭 가능하게 만들 수 있습니다:
[](https://example.com)
대체 텍스트 모범 사례
항상 설명적인 대체 텍스트를 작성하세요. 두 가지 중요한 목적이 있습니다:
- 접근성 — 화면 낭독기가 시각 장애가 있는 사용자에게 이미지를 설명하는 데 사용합니다
- SEO — 검색 엔진이 이미지 콘텐츠를 이해하는 데 사용합니다
✅ 
❌ 
❌ 
수평선 (Horizontal Rules)
섹션을 시각적으로 구분하기 위해 수평선(주제 구분선)을 만듭니다. 세 개 이상의 대시, 별표 또는 밑줄을 사용합니다:
---
***
___
세 가지 모두 동일한 HTML을 생성합니다: <hr>
모범 사례: ---를 일관되게 사용하고, 앞뒤로 항상 빈 줄을 추가하세요:
Content above the rule.
---
Content below the rule.
이스케이프 문자
리터럴 별표나 해시 기호를 마크다운 서식 없이 그대로 표시하고 싶다면 어떻게 할까요? 문자 앞에 백슬래시 \를 사용합니다:
\* This is not italic \*
\# This is not a heading
\- This is not a list item
이스케이프할 수 있는 문자의 전체 목록은 다음과 같습니다:
\ Backslash
` Backtick
* Asterisk
_ Underscore
{} Curly braces
[] Square brackets
() Parentheses
# Hash
+ Plus sign
- Hyphen
. Dot
! Exclamation mark
| Pipe
빠른 참조 치트 시트
빠른 검색을 위한 모든 기본 문법 요소 테이블입니다:
Element Syntax HTML
-------------- ------------------ -----------
Heading 1 # Text <h1>
Heading 2 ## Text <h2>
Heading 3 ### Text <h3>
Bold **text** <strong>
Italic *text* <em>
Bold + Italic ***text*** <strong><em>
Strikethrough ~~text~~ <del>
Blockquote > text <blockquote>
Ordered list 1. item <ol><li>
Unordered list - item <ul><li>
Inline code `code` <code>
Link [text](url) <a href>
Image  <img>
Horizontal rule --- <hr>
Line break spaces + Enter <br>
직접 실습해 보세요
마크다운 기본 문법의 모든 요소를 배웠으니, 이제 직접 사용해 볼 차례입니다. 다음 단계를 따라해 보세요:
-
직접 작성하기:
notes.md파일을 만들고 각 문법 요소를 시도해 보세요. 많이 쓸수록 자연스러워집니다. -
미리보기 도구 사용하기: VS Code의 내장 마크다운 미리보기(
Ctrl+Shift+V/Cmd+Shift+V)를 사용하면 입력하는 동안 실시간으로 렌더링된 결과를 확인할 수 있습니다. -
변환하고 공유하기: 마크다운 문서가 완성되면 깔끔한 출력으로 변환하세요 — Markdown를 HTML로 변환기로 웹 게시, Markdown를 PDF로 변환기로 인쇄용 문서, Markdown를 Word로 변환기로 공동 편집이 가능합니다.
-
더 깊이 탐구하기: 기본 문법에 익숙해지면, 마크다운 확장 문법 가이드에서 테이블, 각주, 정의 목록 등을 학습하세요. 마크다운이 완전히 처음이신가요? 마크다운이란에서 전체 그림을 파악해 보세요.
마크다운의 아름다움은 이 기본 요소들이 여러분이 작성해야 할 대부분의 내용을 커버한다는 것입니다. 한 번 마스터하면 GitHub에서 Notion까지, 문서에서 이 글과 같은 블로그 포스트까지 — 어디에서나 활용할 수 있습니다.