Markdown은 John Gruber가 2004년에 단 하나의 우아한 목표를 가지고 만들었습니다: 자연스럽게 읽히는 일반 텍스트를 작성하고, 그것을 깔끔한 HTML로 변환합니다. 20년이 지난 지금, 그것은 어디에나 있습니다 — GitHub README 파일, 풀 리퀘스트 설명, Slack 메시지, Notion 문서, 블로그 게시물, AI 채팅 응답. 의식적으로 생각하든 하지 않든, 여러분은 남은 커리어 동안 매일 사용하게 될 도구 중 하나입니다.

Markdown이 실제로 무엇인가

Markdown은 그 위에 경량의 읽기 쉬운 구문이 레이어된 일반 텍스트입니다. 줄의 시작에 있는 #는 <h1>이 됩니다. **이중 별표**로 단어를 감싸면 굵게 됩니다. 백틱은 인라인 코드를 생성합니다. 핵심 설계 철학은 Markdown 소스가 렌더링되기 전에도 있는 그대로 읽기 쉬워야 한다는 것입니다. 강조를 위해 *별표로 감싼* 이메일을 작성하거나 불릿 목록을 위해 대시를 사용한 적이 있다면, 이미 Markdown과 매우 유사한 것을 작성하고 있었던 것입니다.

다음은 빠른 전후 비교입니다. 왼쪽의 Markdown이 오른쪽의 HTML을 생성합니다:

markdown
## Getting Started

Install the package with **npm**:

`npm install my-library`

Then import it in your project — see the [docs](https://example.com) for details.
html
<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>

위쪽을 작성하면; Markdown 프로세서가 아래쪽을 생성합니다. 이 변환 단계는 편집기나 CI 파이프라인에 있으면 보이지 않게 됩니다.

핵심 구문 — 모든 변형이 공유하는 부분

어떤 Markdown 변형을 사용하든, 이 빌딩 블록들은 어디서나 작동합니다:

  • 제목 — # H1, ## H2, ### H3 (최대 6단계)
  • 굵게 및 기울임꼴 — **굵게**, *기울임꼴*, ***둘 다***
  • 링크 — [링크 텍스트](https://url.com)
  • 이미지 — ![대체 텍스트](image.png)
  • 인라인 코드 — `백틱`으로 스니펫을 감싸고; 삼중 백틱으로 펜스 코드 블록을 엽니다
  • 인용구 — >로 줄을 시작합니다
  • 순서 없는 목록 — - 또는 *로 시작하는 줄
  • 순서 있는 목록 — 1., 2. 등으로 시작하는 줄
  • 수평선 — 세 개 이상의 대시: ---

다음은 위의 모든 것을 함께 사용하는 현실적인 README 스니펫입니다:

markdown
# json-transform

> A zero-dependency library for transforming JSON structures.

## Installation

```bash
npm install json-transform
```

## Usage

```js
import { transform } from 'json-transform';

const result = transform(input, schema);
```

## Features

- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies

See the [full documentation](https://json-transform.dev/docs) for advanced options.

---

MIT License
팁: 저희 Markdown 미리보기 도구를 사용하여 Markdown을 붙여넣고 즉시 렌더링된 것을 확인하세요 — GitHub에 푸시하기 전에 구문을 확인할 때 유용합니다.

변형 문제 — CommonMark, GFM 및 기타

문제가 있습니다: "Markdown"은 하나의 것이 아닙니다. Gruber의 원래 2004 명세는 의도적으로 느슨했으며, 이것이 수년간 호환되지 않는 구현들로 이어졌습니다. 다른 파서들이 중첩 목록, 인용구 내의 빈 줄, 강조와 링크 사이의 우선순위와 같은 엣지 케이스를 다르게 처리했습니다. 동일한 소스 파일이 다른 도구에서 다르게 렌더링될 것입니다.

CommonMark(2014년 출시)가 이것을 고쳤습니다. GitHub, Stack Overflow, Reddit의 사람들을 포함한 개발자 그룹이 652개의 예제로 구성된 테스트 스위트로 모든 엣지 케이스를 다루는 엄격하고 모호하지 않은 명세를 작성했습니다. 대부분의 현대 도구들은 이제 CommonMark를 기준으로 사용합니다.

GitHub은 CommonMark를 자체 추가 기능으로 확장하고 GitHub Flavored Markdown (GFM)을 게시했습니다. GFM은 GitHub README, 이슈, 풀 리퀘스트에서 작성하는 것입니다. 다른 많은 도구들도 GFM 확장을 채택했지만 전부는 아닙니다 — GitHub에서 렌더링되는 것이 정적 사이트 생성기나 메모 작성 앱에서 같은 방식으로 렌더링되지 않을 수도 있습니다. 어떤 변형을 도구가 지원하는지 아는 것이 많은 머리 긁기를 절약합니다.

GitHub Flavored Markdown 확장

GFM은 CommonMark 위에 GitHub와 GFM 상위 집합을 지원하는 모든 도구에서 항상 사용하게 될 다섯 가지 기능을 추가합니다:

표 — 대시 구분 행이 있는 파이프로 구분된 열:

markdown
| Method  | Returns       | Mutates? |
|---------|---------------|----------|
| map()   | new array     | No       |
| filter()| new array     | No       |
| sort()  | same array    | Yes      |

작업 목록 — 이슈와 풀 리퀘스트의 체크박스:

markdown
- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag release

취소선 — 이중 물결표로 텍스트를 감쌉니다:

markdown
~~deprecated API~~ — use `newMethod()` instead

언어 힌트가 있는 펜스 코드 블록 — 여는 백틱 뒤의 언어 식별자가 구문 강조 표시를 트리거합니다:

markdown
```python
def parse_config(path: str) -> dict:
    with open(path) as f:
        return json.load(f)
```

자동 링크 — https://example.com과 같은 베어 URL은 [텍스트](url) 구문 없이 자동으로 클릭 가능하게 됩니다. 이슈 댓글에서는 편리하지만 링크하고 싶지 않은 URL을 붙여넣으면 놀랄 수 있습니다.

저희 Markdown 포맷터를 사용하여 일관성 없는 간격을 정리하고, 목록 들여쓰기를 정규화하고, 펜스 코드 블록 구분자를 표준화하세요 — 저장소에 문서를 커밋하기 전에 유용합니다.

실제로 Markdown을 사용하게 될 곳

Markdown은 처음 접했을 때 대부분의 개발자가 예상하는 것보다 더 많은 곳에 나타납니다:

  • GitHub와 GitLab — README 파일, 이슈, 풀 리퀘스트 설명, 위키, 심지어 커밋 메시지 본문. 모든 저장소에는 최소한 README.md가 있습니다.
  • 정적 사이트 생성기 — Jekyll, Hugo, Eleventy, Astro, Next.js는 모두 Markdown 콘텐츠 파일을 허용합니다. .md 파일에 게시물을 작성하면 생성기가 빌드 시간에 HTML 페이지로 변환합니다.
  • 문서 도구 — MkDocs, Docusaurus, GitBook은 완전히 Markdown 소스를 중심으로 구축되어 있습니다. 오픈 소스 라이브러리는 거의 모두 이 중 하나를 사용합니다.
  • 메모 작성 앱 — Obsidian, Notion, Bear, Typora는 모두 Markdown을 기본 형식으로 사용합니다(다양한 확장으로). 메모는 독점 데이터베이스가 아닌 이식 가능한 일반 텍스트 파일입니다.
  • CMS 플랫폼 — Ghost는 기본적으로 Markdown을 사용합니다. Contentful과 Strapi는 모두 Markdown 필드를 지원합니다. 헤드리스 CMS 설정은 일반적으로 장문 콘텐츠를 Markdown 문자열로 저장합니다.
  • AI 도구 — ChatGPT와 Claude는 기본적으로 Markdown을 출력합니다. AI 응답의 코드 스니펫, 굵은 용어, 불릿 목록은 Markdown입니다 — 채팅 UI가 렌더링하지만, 기본 텍스트는 **굵게**와 ```python입니다.

Markdown vs HTML — 언제 무엇을 사용할까

Markdown은 HTML로 변환되지만, HTML이 할 수 있는 모든 것을 표현할 수는 없습니다. <div class="card">, data-* 속성, aria-* 속성에 해당하는 것이 없습니다. 단순한 산문 콘텐츠 — 문서, README, 블로그 게시물, 변경 로그 — 에는 Markdown이 더 빠르게 작성하고 원시 형태에서 훨씬 더 읽기 쉽습니다. 복잡한 UI 컴포넌트, 사용자 정의 레이아웃, 또는 특정 속성이 필요한 접근성 어노테이션의 경우 HTML이 필요합니다.

좋은 소식: 대부분의 Markdown 프로세서는 원시 HTML을 변경 없이 통과시킵니다. 두 가지를 혼합할 수 있습니다. <figcaption>이 있는 <figure>나 <details> 공개 위젯이 필요하다면, .md 파일에 직접 HTML을 작성하세요. 프로세서가 그대로 통과시킵니다. 이 탈출구를 드물게 사용하세요 — 파일의 3분의 1 이상이 원시 HTML이라면, 직접 HTML을 작성하고 저희 HTML 포맷터를 사용하여 깔끔하게 유지하는 편이 낫습니다.

  • Markdown을 사용하세요: 문서, README, 변경 로그, 블로그 게시물, 지식 기반 글, API 설명 필드
  • HTML을 사용하세요: 정확한 레이아웃, 사용자 정의 컴포넌트, 폼, 특정 속성이 필요한 요소
  • 둘 다 혼합하세요: 주로 산문 콘텐츠에 몇 가지 구조적 예외가 있는 경우(반응형 표, 비디오 삽입)

마무리

Markdown은 겉으로는 단순해 보입니다 — 몇 가지 구두점 규칙처럼 보이지만, 거의 모든 주요 오픈 소스 프로젝트의 문서를 지원합니다. 핵심 구문을 배우는 데는 약 10분이 걸립니다. 변형 차이(CommonMark vs GFM vs SSG가 사용하는 것)를 이해하는 것이 가끔 문서 도구와 싸우는 개발자와 그렇지 않은 개발자를 구분합니다.

공식 참조: 표준화된 명세를 위한 CommonMark, GitHub 확장을 위한 GitHub Flavored Markdown, 실용적인 치트 시트 참조를 위한 Markdown 가이드. 일상적인 작성을 위해, 저희 Markdown 미리보기는 즉시 렌더링된 출력을 볼 수 있게 하며, Markdown 포맷터는 소스 파일을 일관되게 유지합니다.

← All Markdown articles Browse all categories →