Skip to content

Markdown 치트시트

서식 있는 텍스트를 위한 경량 마크업 언어입니다.

01

시작하기

제목과 문단

제목에는 #을 사용합니다(1~6단계). 대체 문법으로 H1에는 ===, H2에는 ---를 씁니다. 문단 사이에는 빈 줄이 필요합니다. Markdown은 일반 텍스트만으로도 읽기 쉽도록 설계되었습니다.

markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Alternative Heading 1
=====================

Alternative Heading 2
---------------------

This is a paragraph. Just write
plain text. Leave a blank line
between paragraphs.

줄바꿈

줄 끝에 공백 두 개 또는 백슬래시를 넣으면 강제 줄바꿈(<br>)이 됩니다. 없으면 한 줄 개행은 문단 안에서 합쳐지는 소프트 랩(soft wrap)으로 처리됩니다. 문단을 구분할 때는 항상 빈 줄을 남겨 두세요.

markdown
First line  
Second line (two trailing spaces above)

Or use a backslash at end of line\
to force a line break.

Soft wrap without break:
just continue on the next line
and it joins into one.

주석

Markdown에는 공식 주석 문법이 없지만, HTML 주석(<!-- -->)은 대부분의 렌더러에서 동작하며 출력에 나타나지 않습니다. [//]: # 트릭은 빈 링크 참조를 이용해 메모를 추가합니다. 주석은 원본 소스에는 그대로 보입니다.

markdown
<!-- HTML comments work in most Markdown -->

[//]: # (This is a comment)

[//]: # "Another comment style"

<!-- 
  Multi-line comment
  not rendered in output
-->

공백과 들여쓰기

줄 앞 공백 4개는 텍스트를 코드 블록으로 만들어 버리므로 의도치 않은 들여쓰기에 주의하세요. 중첩 리스트에서는 들여쓰기가 중요합니다(단계당 2~4칸). 탭은 보통 공백 4개로 취급됩니다. 파서마다 렌더링 차이를 피하려면 공백을 일관되게 사용하세요.

markdown
Paragraph one.

    This is an indented code block
    because of 4 spaces.

> Quoted text needs > prefix.

   Three spaces is just text
   (less than 4).

수평선

하이픈, 별표, 밑줄 3개 이상이면 수평선(<hr>)이 됩니다. 하이픈이 가장 흔합니다. 문자 사이 공백은 허용됩니다. 가독성을 위해 수평선 앞뒤에 빈 줄을 두세요. --- (수평선)을 # (제목)과 혼동하지 않도록 주의하세요.

markdown
---

***

___

   * * *

Text above

---

Text below
02

텍스트 서식

굵게(Bold)

별표 또는 밑줄 두 개로 굵게(<strong>) 표시합니다. snake_case처럼 단어 중간에서는 밑줄이 동작하지 않으므로 별표 쪽이 권장됩니다. 굵은 텍스트 안에 다른 강조를 중첩할 수 있습니다. 필요하면 HTML <strong> 태그도 대안으로 쓸 수 있습니다.

markdown
**bold text**
__also bold__

**bold with *italic* inside**

<strong>HTML bold also works</strong>

**bold**

기울임(Italic)

별표 또는 밑줄 한 개로 기울임(<em>)을 만듭니다. 별표는 단어 중간에서도 동작하지만, 밑줄은 단어 내부 밑줄을 문자 그대로 취급합니다(no_italic_here). 대안으로 <em>을 쓸 수 있습니다. 기울임은 단순 스타일이 아니라 강조의 의미로 사용합니다.

markdown
*italic text*
_also italic_

*italic*

<em>HTML italic</em>

normal *italic* normal

굵게 + 기울임 조합

별표/밑줄 세 개는 굵게와 기울임을 동시에 적용합니다. 서로 중첩하는 것도 가능합니다. 굵은 텍스트 안에 기울임을 넣거나 그 반대도 됩니다. 렌더링 결과는 순서와 무관하지만, 가독성을 위해 순서를 일관되게 유지하세요.

markdown
***bold and italic***
___also both___

**_bold and italic_**
*__bold and italic__*

combine **bold** and *italic*

취소선

물결표 두 개(~~)로 취소선을 만들며, GitHub Flavored Markdown의 기능으로 이제 널리 지원됩니다. HTML <del>과 <s> 태그가 동일한 대안입니다. 표준(원조) Markdown에는 취소선이 포함되어 있지 않습니다.

markdown
~~strikethrough~~

~~crossed out text~~

<del>HTML delete</del>
<s>HTML strikethrough</s>

~~done~~ and ~~pending~~

하이라이트

등호 두 개(==)로 하이라이트하는 것은 일부 파서가 지원하는 확장 기능입니다(GFM 핵심에는 없음). HTML <mark> 태그는 어디서든 동작합니다. 핵심 용어에 주의를 끌 때 아껴서 사용하세요. 남용하면 효과가 줄어듭니다.

markdown
==highlighted text==

<mark>HTML mark</mark>

This is ==important== text.

Compare **bold**, *italic*, ==mark==.

아래첨자와 위첨자

물결표(아래첨자)와 캐럿(위첨자) 문법(~ ~, ^ ^)은 표준 Markdown이나 GFM에는 없는 확장 기능입니다. Pandoc, R Markdown 등 일부에서 지원합니다. 어디서든 쓰려면 HTML <sub>, <sup> 또는 유니코드 문자를 사용하세요.

markdown
H~2~O is water

E = mc^2^

x^2^ + y^2^ = r^2^

1st^st^ January

CO~2~ emissions
03

리스트

순서 없는 리스트

순서 없는 리스트 항목에는 -, *, +를 사용합니다. 하나를 골라 일관되게 쓰세요(-가 가장 흔합니다). 중첩 항목은 2~4칸 들여쓰기합니다. 같은 리스트에서 마커를 섞으면 일부 파서에서 문제가 생길 수 있습니다. 한 줄에 항목 하나씩 작성합니다.

markdown
- item one
- item two
- item three

* asterisk works too
+ plus sign also works

  - sub-item (indent 2 spaces)
  - another sub-item

순서 있는 리스트

순서 있는 리스트는 숫자 뒤에 마침표를 붙입니다. 실제 숫자가 연속일 필요는 없습니다. Markdown이 번호를 다시 매깁니다. 특정 번호부터 시작하려면 첫 항목에 그 번호를 쓰세요(10.이면 10부터 시작). 모든 항목을 1.로 쓰면 자동 번호가 매겨집니다.

markdown
1. first
2. second
3. third

1. auto-numbered
1. still increments
1. third item

10. starts at 10
11. next

중첩 리스트

중첩 리스트 항목은 2~4칸 들여쓰기합니다(혼합 타입에서는 4칸이 가장 안전). 단계별로 순서 있는/없는 리스트를 섞을 수 있습니다. 3단계 이상 깊은 중첩은 가독성을 해치므로 구조를 다시 고려해 보세요. 들여쓰기는 일관되게 유지하세요.

markdown
1. top level
   - nested unordered
   - second nested
2. back to top
   1. nested ordered
   2. another
3. third top

- fruits
  - apple
    - granny smith
  - banana

태스크 리스트

태스크 리스트 문법(- [x], - [ ])은 GitHub Flavored Markdown 확장입니다. 체크박스는 GitHub/GitLab에서 인터랙티브하게 렌더링됩니다. 순서 있는/없는 리스트 모두에서 동작합니다. README, 이슈 트래커, 진행 상황 추적에 유용합니다.

markdown
- [x] completed task
- [ ] incomplete task
- [ ] another todo

1. [x] done
2. [ ] not done

- [x] Write the docs
- [ ] Review PR
- [ ] Deploy

느슨한 리스트 vs 조밀한 리스트

리스트 항목 사이에 빈 줄이 있으면 '느슨한(loose)' 리스트가 되어 각 항목이 <p>로 감쌉니다. 빈 줄이 없으면 '조밀한(tight)' 리스트가 되어 <p>로 감싸지 않습니다. HTML 출력에서 간격 차이로 이어집니다. 문단 감싸기를 조절하려면 빈 줄을 의도적으로 추가하세요.

markdown
- tight item
- tight item
- tight item

- loose item

- loose item

- loose item

여러 문단이 있는 리스트

리스트 항목에 여러 문단이나 블록 요소를 넣으려면 이어지는 내용을 4칸(또는 리스트 마커 내용에 맞춰) 들여쓰기합니다. 빈 줄로 하위 블록을 구분합니다. 복잡한 리스트 구조에는 필수적이지만 실수하기 쉬운 부분입니다.

markdown
- First item

  Second paragraph of first item.

- Second item

  > A blockquote inside a list item.
  >
  > Must be indented to align.

- Third item
05

이미지

기본 이미지

이미지 문법은 링크와 같지만 앞에 !가 붙습니다. alt 텍스트는 접근성을 위해 필수입니다. 스크린 리더에 이미지를 설명하고, 이미지 로드에 실패할 때 표시됩니다. 경로는 상대, 절대, URL 모두 가능합니다. 제목(title)은 선택 사항입니다.

markdown
![alt text](image.png)

![alt text](https://example.com/img.png)

![alt text](/path/to/image.png "Optional title")

alt 텍스트가 있는 이미지

alt 텍스트는 의미 있고 간결해야 합니다. 'image'가 아니라 이미지의 목적을 설명하세요. 장식용 이미지는 빈 alt(alt='')로 스크린 리더가 건너뛰게 하는 것이 허용됩니다. 'image of', 'picture of' 같은 표현은 쓰지 마세요. 스크린 리더가 이미 알려 줍니다.

markdown
![A diagram showing the system architecture](architecture.png)

![Photo: mountain landscape at sunset](mountains.jpg "Sunset over the Alps")

![](decorative-icon.png)

링크된 이미지

이미지 문법을 링크 문법 안에 중첩하면 [![alt](img)](url) 이미지를 링크로 감쌀 수 있습니다. 전체 크기 이미지로 연결되는 썸네일, CI 상태에 연결되는 배지, 홈으로 연결되는 로고에 흔히 씁니다. alt 텍스트는 이미지가 아니라 이동 목적지를 설명하세요.

markdown
[![alt text](thumbnail.png)](https://example.com/full)

[![logo](logo.png "Visit home")](/)

[![badge](https://img.shields.io/build.svg)](https://ci.example.com)

참조 이미지

참조 이미지는 링크와 같은 참조 방식을 ! 접두사와 함께 사용합니다. 이미지 참조를 한 번 정의하고 재사용하세요. 같은 이미지가 여러 번 나올 때나 이미지가 많은 문단의 가독성을 지킬 때 유용합니다.

markdown
![alt text][img-ref]

[img-ref]: https://example.com/image.png "Title"

![alt][logo]

[logo]: /assets/logo.png

이미지 크기와 Figure

표준 Markdown에는 이미지 크기 문법이 없습니다. HTML <img>의 width/height 속성을 사용하세요. 백분율 너비로 반응형 크기 조절이 가능합니다. <figure> + <figcaption> 조합은 (HTML5) 의미론적 캡션을 제공합니다. 일부 확장 Markdown(Pandoc)은 ![alt](img){width=300}을 지원합니다.

markdown
<img src="image.png" width="300" height="200" alt="sized image">

<img src="banner.png" width="100%" alt="responsive">

<figure>
  <img src="diagram.png" alt="flowchart">
  <figcaption>Figure 1: System flow</figcaption>
</figure>
06

인라인 코드와 이스케이프

인라인 코드

인라인 코드는 백틱 한 개로 감쌉니다. 코드 안에 백틱을 보여 주려면 구분자를 백틱 두 개(또는 더 많이) 사용하세요. 인라인 코드는 고정폭으로 렌더링되고 Markdown으로 파싱되지 않습니다. 파일명, 명령어, 코드 식별자에 적합합니다.

markdown
Use the `printf()` function.

Inline code: `const x = 42;`

Code with backticks: ``use `code` here``

A `<div>` element.

코드 스팬에서 백틱 이스케이프

코드 스팬 안에 백틱을 넣으려면 내부의 백틱보다 많은 백틱을 구분자로 사용하세요. 백틱 하나는 백틱 두 개로 감쌉니다. 코드 스팬 밖에서는 백슬래시로 백틱을 이스케이프합니다. 닫는 펜스는 여는 펜스와 길이가 같아야 합니다.

markdown
To show a backtick inside code,
use more backticks as delimiters:

`` ` ``        one backtick
`` a`b ``      backtick inside text

Use \ to escape outside code:
A literal backtick: \`

코드 스팬과 공백

코드 스팬은 내부 공백을 그대로 보존합니다. 알아 두면 좋은 트릭: 내용 앞뒤를 공백 하나로 감싸면, 원래라면 잘려 나갈 앞뒤 공백을 표시할 수 있습니다. 양쪽 끝 공백 하나씩은 자동으로 제거됩니다.

markdown
`  spaced  `  (spaces preserved)

` code ` with one space pad

`function f() { return; }`

`  multi   word   code  `

백슬래시 이스케이프

백슬래시는 특수 Markdown 문자를 이스케이프합니다: 백틱, 별표, 밑줄, 중괄호, 대괄호, 괄호, 해시, 플러스, 마이너스, 마침표, 느낌표, 그리고 백슬래시 자체. 이스케이프된 문자는 그대로 렌더링됩니다. 서식으로 해석될 수 있는 문자만 이스케이프하세요.

markdown
\*not italic\*
\_not italic\_
\#not a heading
\[not a link](url)
\`not code\`
\\backslash itself
\!not an image

이스케이프가 필요한 문자

위 문자들이 Markdown에서 이스케이프 가능한 문자들입니다. 모든 곳에서 다 이스케이프할 필요는 없습니다. #은 줄 시작에서만, -는 리스트 문맥에서만 의미가 있습니다. 확실하지 않으면 이스케이프하세요. 중괄호와 괄호는 보통 링크, 템플릿 문자열 같은 특정 문맥에서만 이스케이프가 필요합니다.

markdown
\\     backslash
\`     backtick
\*     asterisk
\_     underscore
\{ \}  curly braces
\[ \]  square brackets
\( \)  parentheses
\#     hash
\+     plus
\-     minus
\.     dot
\!     exclamation
07

코드 블록

들여쓰기 코드 블록

4칸(또는 탭) 들여쓰기는 코드 블록을 만듭니다. 들여쓰기 코드 블록은 문법 강조와 언어 태그가 없습니다. 리스트 항목 안에서는 (연속 줄로 취급되어) 사용할 수 없습니다. 새 문서에는 펜스 코드 블록을 권장하며, 들여쓰기 블록은 레거시 방식입니다.

markdown
Normal paragraph.

    // indented code (4 spaces)
    function hello() {
      console.log("hi");
    }

Back to normal text.

펜스 코드 블록

백틱 세 개 또는 물결표 세 개로 펜스 코드 블록을 만듭니다. 펜스는 들여쓰기 블록보다 권장됩니다. 모호하지 않고 언어 힌트도 지원하기 때문입니다. 코드 자체에 백틱 세 개가 들어 있을 때 물결표(~~~)가 유용합니다. 항상 같은 문자 수로 펜스를 닫으세요.

markdown
```
plain code block
multiple lines
```

~~~
also a fenced block
using tildes
~~~

문법 강조

여는 펜스 바로 뒤에 언어 식별자(예: js, python)를 붙이면 문법 강조가 적용됩니다. 대부분의 렌더러는 highlight.js 또는 Prism을 사용합니다. 흔한 별칭: js, ts, py, rb, sh, json, html, css. 언어를 모르면 생략하고 일반 고정폭으로 두세요.

markdown
```javascript
const greet = (name) => {
  console.log(`Hello, ${name}!`);
};
```

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

```bash
echo "Hello, $USER"
```

중첩 코드 펜스

코드 블록 안에 백틱을 표시하려면 다른 펜스를 사용하세요(백틱 내용에는 물결표, 또는 내부보다 많은 백틱). 백틱 네 개 펜스는 백틱 세 개를 포함하는 내용을 감쌉니다. 닫는 펜스는 여는 펜스와 길이가 같아야 합니다.

markdown
Use four backticks to wrap triple backticks:

````
```js
console.log("inside");
```
````

Or use tildes to wrap backtick content:

~~~
```js
code with backticks
```
~~~

리스트 안의 코드

리스트 항목 안의 펜스 코드 블록은 리스트 텍스트에 맞춰 들여쓰기해야 합니다(일반적으로 - 리스트는 3칸, 1. 리스트는 4칸). 리스트 안의 들여쓰기 코드 블록은 8칸이 필요합니다(리스트 4칸 + 코드 4칸). 들여쓰기 맞추기는 Markdown에서 가장 까다로운 작업 중 하나입니다.

markdown
1. Item with code:

   ```
   code block indented to align
   ```

2. Next item with inline `code`.

- Or indent code 4 spaces beyond
      the list marker (8 total).
08

인용 블록

기본 인용 블록

> 문자로 인용 블록을 시작합니다. 모든 줄에 붙일 수도 있고 첫 줄에만 붙일 수도 있으며, 대부분의 파서는 연속된 줄을 합칩니다. 인용 블록은 들여쓰기된 스타일 인용(<blockquote>)으로 렌더링됩니다. 인용, 콜아웃, 발췌 강조에 활용하세요.

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

> Or just prefix the first line
and continuation lines without >
will still be part of the quote.

여러 줄 인용 블록

인용 블록 안에서 문단을 구분하려면 빈 > 줄을 사용하세요(그렇지 않으면 합쳐집니다). 빈 줄의 >는 인용이 이어짐을 유지합니다. 문단 사이에 빈 줄이 없으면 하나의 문단으로 흐릅니다. 항상 일반 줄로 인용을 종료하세요.

markdown
> First paragraph of quote.
>
> Second paragraph of quote.
>
> > Nested quote starts here.
> > Continues on next line.

End of quote.

중첩 인용 블록

> 여러 개로 인용 블록을 중첩합니다(두 단계는 >>, 세 단계는 >>>). 가독성을 위해 공백을 추가하세요. 3단계 이상 깊은 중첩은 읽기도 스타일링도 어려우니 평탄화를 권장합니다. HTML 출력에서는 단계마다 들여쓰기가 추가됩니다.

markdown
> Outer quote
>
> > Inner nested quote
> > still nested
>
> Back to outer

> Outer
>> Deeper
>>> Deepest level

다른 요소와 함께 쓰는 인용

인용 블록에는 대부분의 Markdown 요소를 넣을 수 있습니다: 제목, 리스트, 코드, 강조, 심지어 표까지. 인용 안에 유지하려면 각 줄에 > (와 공백)를 붙이세요. 콜아웃용으로 강력하지만, 복잡한 내용은 > 정렬에 주의가 필요합니다.

markdown
> ## Heading in quote
>
> - list item one
> - list item two
>
> *italic* and **bold** work too.
>
> ```
> code block inside quote
> ```

출처가 있는 인용

Markdown에는 공식 인용 출처 문법이 없습니다. 흔한 관례: 새 줄에 em 대시로 작성자를 표시하거나, 의미론적 인용을 위해 <footer>와 <cite>가 포함된 HTML <blockquote>를 사용합니다. 학술적 인용에는 출처를 각주로 남기는 것도 고려해 보세요.

markdown
> Be the change you wish to see
> in the world.

> — Mahatma Gandhi

> "Simplicity is the soul of efficiency."
> — Austin Freeman

<blockquote>
  <p>Quote text.</p>
  <footer>— <cite>Author</cite></footer>
</blockquote>
09

표

기본 표

표는 파이프(|)로 열을 구분하고 하이픈 행으로 헤더를 구분합니다. 헤더 행은 필수입니다. 줄 양 끝의 파이프는 선택 사항이지만 가독성에 도움이 됩니다. 열 너비는 중요하지 않으며 셀이 자동으로 맞춰집니다. 표는 GitHub Flavored Markdown 확장 기능입니다.

markdown
| Name  | Age | City     |
|-------|-----|----------|
| Alice | 30  | NYC      |
| Bob   | 25  | London   |
| Carol | 35  | Paris    |

셀 정렬

구분 행의 콜론이 정렬을 결정합니다: :--- 왼쪽, :---: 가운데, ---: 오른쪽. 콜론이 없으면 기본은 왼쪽입니다. 정렬은 열 전체에 적용되고 HTML 출력에서 text-align CSS로 반영됩니다. 숫자 열(오른쪽 정렬)과 헤더(가운데 정렬)에 유용합니다.

markdown
| Left   | Center | Right  |
|:-------|:------:|-------:|
| left   | center | right  |
| L      | C      | R      |

| Default | alignment |
|---------|-----------|
| no mark | left      |

서식이 있는 표

셀에는 인라인 Markdown을 넣을 수 있습니다: 굵게, 기울임, 코드, 링크, 취소선, 이모지. 블록 요소(제목, 리스트, 코드 블록)는 셀 안에서 동작하지 않으며 필요하면 HTML을 사용하세요. 가독성을 위해 셀 내용은 짧게 유지하고, 리터럴 파이프는 백슬래시로 이스케이프하세요.

markdown
| Feature    | Status | Notes              |
|------------|:------:|--------------------|
| **Bold**   | done   | *finished*         |
| `code`     | wip    | [docs](docs.md)    |
| ~~old~~    | removed| gone in v2         |
| [link][1]  | done   | see [ref][1]       |

복잡한 표

표는 많은 행과 열로 확장할 수 있지만 셀 단위는 단순하게 유지됩니다. 콤마가 있는 코드 스팬은 백틱으로 감싸세요. 리터럴 파이프는 백슬래시와 파이프로 이스케이프합니다. 복잡한 데이터(여러 줄 셀, 중첩 표)에는 HTML <table>이 필요합니다. 표가 너무 넓어지면 리스트 사용을 고려하세요.

markdown
| Name  | Role    | Skills              | Available |
|-------|---------|---------------------|:---------:|
| Alice | Lead    | `js`, `ts`, `go`   | yes       |
| Bob   | Junior  | `py`, `sql`         | no        |
| Carol | Senior  | `rust`, `c++`       | yes       |

Escaped pipe: \| literal

표 팁과 한계

Markdown 표에는 한계가 있습니다: 셀 병합 불가, 여러 줄 내용 불가, 블록 요소 불가, 중첩 표 불가. 이런 경우 원시 HTML을 사용하세요. 표는 작고 훑어 보기 쉽게 유지하고, 각주나 긴 텍스트가 필요하면 분할하세요. TablesGenerator.com 같은 도구로 빠르게 만들 수 있습니다.

markdown
| A | B |
|---|---|
| 1 | 2 |

Tip: Use \| to escape pipes.

Limitation: no multi-line cells,
no blockquotes, no lists in cells.

For complex tables, use HTML:
<table><tr><td>cell</td></tr></table>
10

각주

기본 각주

각주는 본문의 [^id] 마커와 다른 곳의 [^id]: 정의로 구성됩니다. id는 숫자나 단어 모두 가능합니다. 렌더러는 클릭 가능한 위첨자 번호와 문서 하단의 각주 섹션을 만듭니다. GFM, Pandoc 및 대부분의 최신 파서가 지원합니다.

markdown
Here is a sentence with a footnote.[^1]

[^1]: This is the footnote text.

Another sentence.[^note]

[^note]: Footnotes can use named labels.

여러 참조

하나의 각주는 여러 번 참조될 수 있으며, 모든 [^id]가 같은 정의로 연결됩니다. 각주 정의의 연속 줄은 들여쓰기합니다. 첫 참조에 위첨자 번호가 붙고, 이후 참조는 같은 각주로 연결됩니다.

markdown
Use the term[^term] twice[^term] in the text.

[^term]: A single definition referenced
    multiple times.

First[^1] and second[^1] reference.

[^1]: One definition, two links back.

인라인 각주

인라인 각주(^[text])는 각주 내용을 참조 위치에 바로 넣으며, Pandoc과 일부 확장에서 지원합니다(GFM 핵심에는 없음). 모든 내용을 한곳에 두지만 읽는 흐름을 방해할 수 있습니다. 짧은 메모에 사용하고, 긴 각주는 참조 방식이 좋습니다.

markdown
Here is an inline footnote^[The note text
right here in the body.] in a sentence.

Pandoc also supports: ^[inline notes].

And another[^1].

[^1]: Traditional reference style.

각주 위치

각주 정의는 문서 어디에 두어도 되며, 렌더러가 모아서 마지막에 표시합니다. 연속 줄은 들여쓰기하세요(4칸). 각주는 인용 블록과 리스트 항목 안에서도 동작합니다. 소스에서의 위치는 출력 위치에 영향을 주지 않습니다.

markdown
Body text with a note.[^1]

More paragraphs here.

[^1]: Definitions can appear anywhere.
    They float to the bottom in output.

> Even inside blockquotes.[^2]

[^2]: The renderer collects all notes
    and renders them at the end.

코드와 서식이 있는 각주

각주 정의에는 인라인 Markdown(굵게, 기울임, 코드)과 여러 문단 내용(연속 줄을 4칸 들여쓰기)을 사용할 수 있습니다. 각주 안의 들여쓰기 코드 블록은 8칸이 필요합니다. 각주는 간결하게 유지하세요. 긴 기술 내용은 본문이나 부록이 좋습니다.

markdown
See the API[^api] for details.

[^api]: Use `fetch('/api/data')` to call.
    Supports **bold** and *italic*.
    Multi-paragraph: indent each line.

    Code blocks need indentation:
        indented code inside footnote
11

정의 리스트

기본 정의 리스트

정의 리스트는 한 줄에 용어를 쓰고 다음 줄에 콜론(:)과 정의를 씁니다. PHP Markdown Extra, Pandoc 및 일부 확장에서 지원합니다(GFM 핵심에는 없음). <dl><dt><dd>로 렌더링됩니다. 용어집과 용어-정의 쌍에 유용합니다.

markdown
Term
: Definition of the term.

Markdown
: A lightweight markup language.

HTML
: HyperText Markup Language.

여러 용어

콜론 없이 연속된 여러 용어가 하나의 정의를 공유할 수 있습니다. 각 용어는 <dt>가 되고 정의는 <dd>가 됩니다. 같은 개념에 이름이나 별칭이 여러 개일 때 유용합니다. 용어는 각각 별도의 줄에 쓰세요.

markdown
CSS
Cascading Style Sheets
: A style sheet language.

JS
JavaScript
: A programming language.

Both terms
: Share one definition.

여러 정의

하나의 용어에 콜론으로 시작하는 정의가 연속되면 여러 개의 <dd> 요소가 만들어집니다. 용어의 서로 다른 의미나 측면을 나열할 때 유용합니다. 콜론 줄 하나가 별도의 정의 항목이 됩니다.

markdown
Markdown
: A markup language.
: A tool for writing for the web.

Apple
: A fruit.
: A technology company.

중첩 정의 리스트

정의 리스트를 중첩하려면 안쪽 리스트를 바깥 정의 안에서 (2~4칸) 들여쓰기해야 합니다. 파서 지원이 제각각이라 모든 렌더러가 중첩을 다루지는 못합니다. 복잡한 계층 구조는 신뢰성을 위해 HTML <dl>을 고려하세요. 대상 렌더러에서 테스트해 보세요.

markdown
Term
: Definition one.

  Nested term
  : Nested definition.

: Definition two for top term.

블록 요소가 있는 정의 리스트

정의 리스트 항목에는 여러 문단, 인용 블록, 코드 블록을 넣을 수 있습니다. 이어지는 내용을 (콜론보다 더) 4칸 들여쓰기하세요. 안의 코드 블록은 총 8칸이 필요합니다. 강력하지만 깨지기 쉬우므로, 복잡한 내용은 HTML <dl>이 안전합니다.

markdown
Markdown
:   A markup language.

    With multiple paragraphs in the
    definition (indent 4 spaces).

    > Blockquote inside definition.

:   Second definition with code:

        indented code (8 spaces)
12

목차

자동 목차

대부분의 파서는 기본적으로 목차를 자동 생성하지 않습니다. 일부(toc 플러그인을 쓰는 marked, MDX)는 [TOC] 또는 {:toc} 자리표시자를 지원합니다. Doctoc, markdown-toc 같은 도구는 제목으로부터 목차를 생성합니다. 정적 사이트에서는 목차 컴포넌트가 빌드 또는 런타임에 제목 앵커를 읽습니다.

markdown
## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Usage](#usage)
4. [FAQ](#faq)

Some parsers auto-generate a TOC
with `[TOC]` or `{:toc}` markers.

수동 목차

수동 목차는 제목 앵커로 가는 링크의 중첩 리스트입니다. 앵커 id는 제목 텍스트에서 파생됩니다(소문자, 공백은 하이픈, 문장부호 제거). 제목 계층에 맞게 들여쓰기하세요. 제목이 바뀌면 수동으로 갱신하거나 생성기를 사용하세요.

markdown
# My Document

## Contents
- [Intro](#intro)
- [Setup](#setup)
  - [Prerequisites](#prerequisites)
  - [Install](#install)
- [Usage](#usage)

## Intro
...

앵커 생성 규칙

앵커 생성은 파서마다 다릅니다. 흔한 규칙: 소문자화, 공백을 하이픈으로, 문장부호 제거, 영숫자 유지. GitHub는 이모지와 일부 유니코드를 유지합니다. 숫자와 점은 종종 제거됩니다. 확실하지 않으면 렌더링된 HTML을 확인해 실제 id를 찾으세요.

markdown
## Hello World        -> #hello-world
## Hello, World!      -> #hello-world
## C++ & Rust         -> #c--rust
## Uber Heading       -> #uber-heading
## 1. Getting Started  -> #1-getting-started
## API v2.0           -> #api-v20

커스텀 앵커 ID

신뢰할 수 있는 앵커를 위해 명시적 ID를 추가하세요. {#id} 속성 문법은 Pandoc, marked 및 일부 확장에서 동작합니다. HTML <a id="..."> 트릭은 어디서든 동작하며, 제목 앞이나 안에 놓습니다. 커스텀 ID는 제목 텍스트가 바뀌어도 유지됩니다.

markdown
## Heading {#custom-id}

<a id="my-anchor"></a>
## Heading

## Heading<a id="also"></a>

[link to custom](#custom-id)

목차 내비게이션과 되돌아가기 링크

맨 위로 링크는 긴 문서에서 내비게이션을 개선합니다. <details>/<summary> HTML은 접을 수 있는 목차를 만들어 사이드바나 긴 README에 좋습니다. 앵커 링크와 결합해 부드러운 이동을 구현하세요. 고정 헤더를 보정하려면 CSS에 scroll-margin-top을 추가하세요.

markdown
## Section

Content here.

[Back to top](#table-of-contents)

---

<details>
<summary>Table of Contents</summary>

- [Section 1](#section-1)
- [Section 2](#section-2)
</details>
13

이모지와 특수 문자

이모지 숏코드

이모지 숏코드(:name:)는 GitHub/GitLab이 지원합니다(EmojiOne/Twemoji 세트 사용). 이름 붙은 이모지가 수천 개 있습니다. 숏코드는 편리하지만 이식성이 없어 GFM이 아닌 파서에서는 문자 그대로 표시될 수 있습니다. 최대 호환성을 위해서는 원시 유니코드 이모지를 사용하세요.

markdown
:smile: :heart: :thumbsup: :rocket:

GFM supports shortcodes:
:sparkles: new feature :tada:

:checkered_flag: launch!
:bug: fixed issue #42

흔한 이모지

대부분의 최신 편집기와 렌더러는 원시 유니코드 이모지를 바로 처리하므로 붙여 넣기만 하면 됩니다. 숏코드는 GitHub 전용입니다. 이모지는 톤과 상태를 전달합니다(결과는 체크/크로스, 버그는 벌레). 공식 문서에서는 아껴 쓰고, README와 변경 로그에서는 좋습니다.

markdown
:smile: smile    :heart: heart    :thumbsup: thumbsup
:rocket: rocket   :star: star     :warning: warning
:check: check    :x: cross       :bulb: bulb
:fire: fire      :tada: tada      :bug: bug
:book: book      :wrench: wrench  :zap: zap

HTML 엔티티

Markdown은 HTML로 통과되므로 HTML 엔티티가 동작합니다. 리터럴 앰퍼샌드에는 &amp;를(특히 URL/속성에서), 꺾쇠 괄호에는 &lt; &gt;를, 기호에는 &copy; &reg; &trade;를 쓰세요. 숫자 형태(&#169;)와 16진수(&#x00A9;)는 모든 유니코드 문자를 표현합니다.

markdown
&amp;  &lt;  &gt;  &quot;  &apos;

&copy;  &reg;  &trade;

&mdash; &ndash; &hellip;

&#169;  &#x00A9;

Use &amp; to show a literal &.

특수 문자

Markdown은 기본적으로 일반 문장부호를 타이포그래픽 문자(스마트 쿼트)로 바꾸지 않습니다. HTML 엔티티를 쓰거나 유니코드를 붙여 넣으세요. em 대시와 컬리 쿼트는 타이포그래피를 개선합니다. 많은 편집기가 자동 교정합니다. 화살표와 기호는 엔티티가 가장 명확합니다.

markdown
-- em dash (or &mdash;)
-- en dash (or &ndash;)
... ellipsis (or &hellip;)
' ' curly quotes (&lsquo; &rsquo;)
" " curly quotes (&ldquo; &rdquo;)
-> arrow (or &rarr;)
(tm) (r) (c)

이모지와 Markdown 조합

이모지는 제목, 리스트, 굵게, 링크, 인용 블록 등 모든 Markdown 요소와 결합됩니다. 변경 로그, README, 이슈 템플릿에 시각적 힌트를 더합니다. 이모지 사용은 일관되게 유지하세요(예: 변경 로그 관례를 지키기). 공식/학술 글쓰기에서는 피하세요.

markdown
## New Features

- :sparkles: Added dark mode
- :bug: Fixed login bug
- :memo: Updated docs

**Status:** :white_check_mark: Ready

> :warning: **Warning:** Deprecated!

[:book: Read the docs](/docs)
14

Mermaid 다이어그램

Mermaid 플로우차트

Mermaid는 텍스트 기반 다이어그램 언어로, GitHub, GitLab, 많은 정적 사이트 생성기가 렌더링합니다. Mermaid 코드는 mermaid 펜스 블록으로 감쌉니다. flowchart TD(위→아래) 또는 LR(왼쪽→오른쪽)이 방향을 정의합니다. 노드는 [], {}, ()로 모양이 다릅니다.

markdown
```mermaid
flowchart TD
    A[Start] --> B{Is it?}
    B -->|Yes| C[Do it]
    B -->|No| D[Do not]
    C --> E[End]
    D --> E
```

Mermaid 시퀀스 다이어그램

시퀀스 다이어그램은 참여자들 사이의 시간 흐름별 상호작용을 보여 줍니다. ->>는 실선 화살표(요청), -->>는 점선 화살표(응답)입니다. participant로 액터를 선언합니다. API 흐름, 프로토콜, 메시지 전달 문서화에 유용하며 GitHub에서 자동 렌더링됩니다.

markdown
```mermaid
sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B-->>A: Hi Alice!
    A->>B: How are you?
    B-->>A: Good, thanks!
```

Mermaid 클래스 다이어그램

클래스 다이어그램은 객체지향 구조를 모델링합니다. +는 public, -는 private, #는 protected입니다. <|--은 상속을 나타냅니다. Mermaid는 연관, 컴포지션, 인터페이스를 지원합니다. Markdown 안에서 바로 코드 아키텍처를 문서화하기 좋습니다.

markdown
```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound() void
    }
    class Dog {
        +fetch() void
    }
    Animal <|-- Dog
```

Mermaid 상태 다이어그램

상태 다이어그램은 상태 전이를 보여 줍니다. [*]는 시작/종료 상태를 표시합니다. 화살표에 이벤트로 전이를 레이블합니다(state --> state: event). 프로토콜, UI 상태, 객체 수명 주기 문서화에 유용합니다. stateDiagram-v2가 최신 문법입니다.

markdown
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Done: complete
    Processing --> Error: fail
    Done --> [*]
    Error --> [*]
```

Mermaid 간트 차트

간트 차트는 프로젝트 일정을 시각화합니다. dateFormat이 날짜 파싱을 설정합니다. 태스크는 id, 시작, 기간(예: 7d)을 사용합니다. 'after a1'로 태스크를 연결합니다. 섹션은 관련 태스크를 묶습니다. README와 프로젝트 계획에 유용하며, 외부 도구 없이 GitHub에서 자동 렌더링됩니다.

markdown
```mermaid
gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Design
    Spec        :a1, 2024-01-01, 7d
    Mockups     :after a1, 5d
    section Build
    Develop     :2024-01-13, 14d
    Test        :7d
```

Mermaid 파이 차트

파이 차트는 비율을 백분율로 표시합니다(값은 상대적). 제목은 선택 사항입니다. 레이블은 따옴표 안에, 값은 콜론 뒤에 씁니다. Mermaid는 git 그래프, ER 다이어그램, 저니 맵, 마인드 맵도 지원하며, 지원 플랫폼에서는 Markdown에서 모두 렌더링됩니다.

markdown
```mermaid
pie title Browser Market Share
    "Chrome" : 65
    "Safari" : 18
    "Edge" : 5
    "Firefox" : 3
    "Other" : 9
```
15

GitHub Flavored Markdown

태스크 리스트 (GFM)

GitHub Flavored Markdown(GFM) 태스크 리스트는 GitHub에서 인터랙티브 체크박스로 렌더링됩니다. [x]는 체크, [ ]는 미체크입니다. 이슈, PR, 댓글, README에서 동작합니다. 이슈 목록에는 진행 바가 표시됩니다. 이제 GitHub 밖에서도 널리 지원됩니다.

markdown
- [x] Done task
- [ ] Todo task
- [ ] Another todo

## Project Status
- [x] Design
- [x] Implement
- [ ] Test
- [ ] Deploy

취소선 (GFM)

GFM은 표준 Markdown에 취소선(~~text~~)을 추가했습니다. 여러 줄에 걸쳐 동작하고 다른 서식과 결합됩니다. <del>로 렌더링됩니다. 원래 GFM 확장이었으나 지금은 CommonMark 스펙 추가 사항에 포함됩니다. 수정 사항과 폐기 표시에 유용합니다.

markdown
~~deleted text~~

old ~~price~~ new

~~this line is wrong~~

Combine: **bold ~~struck~~ text**

~~multi-line
strikethrough~~

표 (GFM)

표는 GFM 기능입니다(원조 Markdown에는 없음). 헤더 행과 구분 행이 있는 파이프 문법이 필요합니다. GFM 표는 정렬, 인라인 서식, 이스케이프된 파이프를 지원합니다. 병합, 중첩 같은 복잡한 표는 HTML로 전환하세요.

markdown
| Feature    | Status |
|------------|:------:|
| Tables     | yes    |
| Tasks      | yes    |
| Auto-links | yes    |

Tables are core to GFM, not in
the original Markdown spec.

GitHub Alerts

GitHub Alerts(2023+)는 인용 블록 첫 줄에 [!TYPE] 마커를 사용합니다: NOTE, TIP, IMPORTANT, WARNING, CAUTION. GitHub에서 서로 다른 색과 아이콘으로 렌더링됩니다. README와 문서의 콜아웃에 좋습니다. 문법은 GitHub 전용입니다.

markdown
> [!NOTE]
> Useful information that users
> should know.

> [!WARNING]
> Urgent info about risks.

> [!IMPORTANT]
> Key information.

> [!TIP]
> Helpful advice.

원시 HTML 제한

GFM은 안전을 위해 원시 HTML을 필터링합니다. <script>, <style>, <title>, 때때로 <iframe>과 이벤트 핸들러가 제거됩니다. 사용자 생성 콘텐츠에서 XSS를 막기 위함입니다. <details>, <kbd>, <sup> 같은 안전한 HTML은 통과됩니다. HTML을 섞을 때는 렌더러의 허용 목록을 확인하세요.

markdown
GFM sanitizes some HTML tags:

<script>alert('xss')</script>
<style>body { color: red; }</style>
<title>Page</title>

These are stripped for security.

자동 링크 (GFM)

GFM은 꺾쇠 괄호 없이도 bare URL(https://...)과 www. 도메인을 자동 링크합니다. 이식성을 위해서는 꺾쇠 괄호(<url>)가 모든 계열에서 동작합니다. 자동 링크는 의외로 동작할 수 있으므로, URL을 문자 그대로 다른 텍스트와 나란히 표시하려면 꺾쇠 괄호를 쓰세요.

markdown
Visit https://example.com now.

www.google.com auto-links too.

<https://example.com> always works.

In GFM, bare URLs and www. links
become clickable automatically.
16

확장 문법

하이라이트

==text== 하이라이트 문법은 확장 기능입니다(GFM이나 CommonMark에는 없음). Markdown-it에 플러그인을 쓰는 일부 파서가 지원합니다. HTML <mark> 태그는 어디서든 지원됩니다. 핵심 용어를 강조할 때 사용하고, 남용하면 효과가 줄어듭니다.

markdown
==highlighted text==

<mark>HTML highlight</mark>

Some parsers (not GFM core) support
==this syntax== for highlighting.

Use <mark> for universal support.

아래첨자와 위첨자

아래첨자(~text~)와 위첨자(^text^)는 표준이 아닌 Pandoc/markdown-it 확장입니다. 어디서든 표시하려면 HTML <sub>/<sup> 또는 유니코드를 사용하세요. Markdown으로 쓴 과학·수학 콘텐츠에서 유용합니다.

markdown
H~2~O (subscript)

x^2^ (superscript)

E = mc^2^

H~2~SO~4~

Pandoc/R Markdown support ~ and ^.

속성 문법

{#id .class key=val} 속성 문법(Pandoc, 일부 markdown-it 플러그인)은 요소에 HTML 속성을 붙입니다. 스타일링 훅, 커스텀 앵커, 링크 타깃에 유용합니다. 이식성이 없어 지원하지 않는 파서에서는 문자 그대로 표시됩니다. 아껴서 사용하세요.

markdown
## Heading {#id .class}

![alt](img.png){width=50%}

[link](url){target=_blank}

> Quote {.callout}

커스텀 컨테이너

커스텀 컨테이너(:::type ... ::: )는 VuePress, Docusaurus, VitePress 등 문서 도구에서 지원합니다. 스타일이 적용된 콜아웃 박스로 렌더링됩니다. type이 CSS 클래스로 매핑됩니다. 테마가 있는 문서에 좋지만 일반 Markdown 렌더러로는 이식되지 않습니다.

markdown
:::note
This is a note container.
:::

:::warning
This is a warning.
:::

::: details Open me
Hidden content.
:::

수식과 LaTeX (KaTeX)

수식 지원은 렌더러에 따라 다릅니다. GitHub는 $...$ 인라인과 $$...$$ 블록을 지원합니다(MathJax/KaTeX 사용). 모든 Markdown 파서가 수식을 지원하는 것은 아닙니다. 최대 호환성을 위해 수식을 이미지로 렌더링하거나 MathJax를 직접 사용하세요. 과학·기술 문서에서 유용합니다.

markdown
Inline: $E = mc^2$ in a sentence.

Block:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Some parsers support \( \) and
\[ \] delimiters too.
17

도구와 편집기

VS Code

VS Code에는 Markdown 미리보기가 내장되어 있고 확장 생태계가 풍부합니다. Markdown All in One은 단축키(굵게, 목차, 미리보기)를 추가합니다. markdownlint는 스타일을 강제합니다. Preview Enhanced는 다이어그램, 수식, 내보내기를 지원합니다. 편한 편집을 위해 word wrap을 설정하세요.

markdown
# VS Code Markdown extensions:
- Markdown All in One
- Markdown Preview Enhanced
- markdownlint
- Pandoc

# Built-in preview: Ctrl+Shift+V
# Side-by-side: Ctrl+K V

# Settings:
"[markdown]": {
  "editor.wordWrap": "on",
  "editor.quickSuggestions": true
}

Typora

Typora는 인기 있는 WYSIWYG Markdown 편집기입니다. 입력하는 대로 인라인 렌더링되어 분할 창 워크플로가 필요 없습니다. GFM, 표, 코드 펜스, 수식, Mermaid를 지원합니다. 내장 도구로 다양한 형식으로 내보냅니다. 유료지만 완성도가 높고 글쓰기 중심 워크플로에 적합합니다.

markdown
Typora: a WYSIWYG Markdown editor.

- Live rendering as you type
- No split pane (instant preview)
- Supports tables, diagrams, math
- Export to PDF, HTML, Word, LaTeX
- Themes and custom CSS

Shortcuts:
- Ctrl+/ toggle source code mode
- Ctrl+B bold, Ctrl+I italic

Obsidian

Obsidian은 노트를 로컬 Markdown 파일로 저장하며 위키 링크, 백링크, 그래프 뷰, 태그 같은 강력한 기능을 제공합니다. 콜아웃, 임베드, Dataview로 Markdown을 확장합니다. Zettelkasten과 개인 지식 관리에 이상적입니다. 개인 사용은 무료입니다.

markdown
Obsidian: a Markdown knowledge base.

- Plain-text .md files (local-first)
- Bidirectional [[wiki links]]
- #tags and nested tags
- Backlinks and graph view
- Plugins for almost everything
- Callouts: > [!note] Title

[[note|alias]] for renamed links.

Markdown 린트

markdownlint는 Markdown 파일 전반에서 일관된 스타일을 강제합니다. 규칙은 .markdownlint.json에서 설정합니다. 흔히 끄는 규칙: 산문용 MD013(줄 길이), HTML이 필요할 때 MD033(인라인 HTML). MD040은 코드 펜스에 언어를 붙이도록 상기시킵니다. CI와 편집기와 통합됩니다.

markdown
# .markdownlint.json (config)

{
  "MD013": false,
  "MD024": { "siblings_only": true },
  "MD033": false,
  "default": true
}

# Rules (examples):
# MD013 line length
# MD024 no duplicate headings
# MD033 no inline HTML
# MD040 fenced code needs language

Pandoc

Pandoc은 문서 변환의 '만능 칼'입니다. Markdown을 HTML, PDF, Word, LaTeX, EPUB, 슬라이드로 (그 반대로도) 변환합니다. Markdown 확장(인용, 수식, 정의 리스트, raw 속성)을 지원합니다. -s 플래그는 독립 문서를 만듭니다. 학술·출판 워크플로에 필수적입니다.

markdown
# Convert Markdown to many formats:

pandoc input.md -o output.html
pandoc input.md -o output.pdf
pandoc input.md -o output.docx
pandoc input.md -o slides.pdf

# Markdown to a self-contained HTML:
pandoc input.md -s -o output.html

# With a table of contents:
pandoc input.md --toc -o output.html

# Support extensions:
pandoc -f markdown+smart input.md

온라인 편집기

온라인 편집기는 빠른 수정과 공유에 좋습니다. StackEdit과 Dillinger는 기능이 완전한 단독 편집기입니다. HackMD/HedgeDoc은 실시간 협업을 더합니다. GitHub 웹 편집기에는 Preview 탭이 있습니다. 모두 표준 Markdown을 지원하며, GFM 기능은 GitHub 편집기에서 가장 잘 동작합니다.

markdown
Popular online Markdown editors:

- StackEdit (stackedit.io)
  Full-featured, syncs to cloud.

- Dillinger (dillinger.io)
  Clean, exports to many formats.

- HackMD / HedgeDoc
  Real-time collaborative editing.

- GitHub web editor
  Preview tab for .md files.

- Markdown Live Preview
  Lightweight, instant preview.
18

베스트 프랙티스

가독성 우선

Markdown의 핵심 원칙은 일반 텍스트로도 읽기 쉬워야 한다는 것입니다. 가장 읽기 쉬운 문법을 고르세요: # 제목, - 리스트, **굵게**. 과도한 중첩과 서식 남용을 피하세요. 텍스트 편집기에서 원본이 읽기 편하다면 Markdown을 잘 쓰고 있는 것입니다.

markdown
# Good: readable as plain text
## Section
Use **bold** for emphasis, not
__bold__ (asterisks are clearer).

# Bad: hard to read raw
##Section or ***overkill***

Tip: Preview raw Markdown often.
If it reads well as text, it is good.

줄 길이와 줄바꿈

두 가지 유효한 접근이 있습니다. 하드 랩(한 문장 한 줄)은 git diff가 깔끔하고 편집이 쉽습니다. 소프트 랩(한 문단 한 줄)은 재배치 작업이 없습니다. 프로젝트마다 하나를 정해 일관되게 유지하세요. 편집기의 wrap 폭(보통 80~120자)도 그에 맞게 설정하세요.

markdown
# Hard wrap (one sentence per line):
This is sentence one.
This is sentence two.

# Soft wrap (paragraph as one line):
This is a long paragraph that
continues on without hard breaks,
relying on editor wrapping.

# Many projects prefer one sentence
# per line for clean git diffs.

일관성

Markdown은 같은 결과에 여러 문법을 제공합니다(굵게 ** vs __, 리스트 - vs * vs +). 프로젝트마다 하나의 관례를 정하고 markdownlint로 강제하세요. 일관성은 독자와 기여자의 인지 부담을 줄이고 자동화 처리를 쉽게 만듭니다.

markdown
# Pick one style and stick to it:

- Use - for lists (not * or +)
- Use ** for bold (not __)
- Use * for italic (not _)
- Use ``` for fences (not ~~~)
- Use # for headings (not ===/--)

Consistent style is more
maintainable and professional.

링크 베스트 프랙티스

긴 URL은 참조 링크를 써서 본문을 읽기 쉽게 유지하세요. 짧은 로컬 참조에는 인라인 링크가 좋습니다. 설명적인 링크 텍스트는 접근성과 SEO에 도움이 됩니다. 'click here'는 피하세요. 제목은 툴팁으로 맥락을 더합니다. 참조 정의는 섹션 끝이나 문서 끝에 모아 두세요.

markdown
# Reference links for long URLs:
See the [docs][docs] for details.

[docs]: https://example.com/very/long/url

# Inline for short links:
Edit [index.js](index.js).

# Title for context:
[API](api.md "REST API reference")

Keep link text descriptive,
not 'click here' or 'link'.

접근성

Markdown에서도 접근성이 중요합니다: 이미지에 의미 있는 alt 텍스트(장식용은 빈 alt), 설명적인 링크 텍스트('click here' 금지), 올바른 제목 계층(단계 건너뛰기 금지), Markdown이 부족한 곳의 의미론적 HTML(kbd, abbr, cite). 스크린 리더는 이런 것들에 의존합니다.

markdown
# Always add alt text to images:
![Diagram of the system](diagram.png)

# Empty alt for decorative images:
![](spacer.png)

# Descriptive link text:
[Read the installation guide](install.md)

# Avoid: [click here](url)
# Use heading hierarchy in order.

# Use semantic HTML when needed:
<kbd>Ctrl</kbd> + <kbd>C</kbd>

흔한 실수

흔한 함정: 블록 요소(리스트, 인용, 코드) 주변의 빈 줄 누락, 중첩 리스트의 들여쓰기 불일치, 닫지 않은 코드 펜스, 탭/공백 혼용. 게시 전 항상 미리보기하세요. markdownlint로 문제를 자동 잡고, 대상 렌더러에서 직접 테스트하세요.

markdown
# Missing blank line before lists:
Text
- item  # may merge with text!

# Fix:
Text

- item

# Unclosed code fence:
```
code
# (missing closing fence)

# Inconsistent list indentation:
- a
  - b (2 spaces)
   - c (3 spaces — may break)

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.