Markdown 완전 가이드：기초 문법부터 실전 활용까지

GitHub에서 깔끔하게 정리된 README를 본 적 있나요? 아니면 Notion에서 별표를 입력했더니 굵은 글자로 바뀌어 놀란 적 있나요? 그 뒤에 있는 문법이 바로 Markdown입니다. 2004년에 탄생해 이제는 거의 모든 디지털 글쓰기 환경에 스며든 경량 마크업 언어를 역사·문법·응용까지 완전히 알아봅니다.

1. Markdown이란 무엇인가? 탄생부터 지금까지

2004년, 블로거 겸 프로그래머 John Gruber와 보안 연구자 Aaron Swartz가 함께 Markdown을 설계했습니다. 목표는 단순했습니다. 일반 텍스트로 읽어도 자연스럽고, 한 번에 깔끔한 HTML로 변환할 수 있는 문법을 만드는 것. 'Markdown'이라는 이름은 'Markup(마크업)'의 반의어로, 최소한의 기호로 최대한의 서식을 표현한다는 철학을 담고 있습니다.

Markdown의 핵심 설계 원칙은 세 가지입니다. 순수 텍스트 우선（어떤 텍스트 편집기에서도 열 수 있음）, 시각적 직관성（기호 모양이 기능을 암시함）, 변환 가능성（HTML·PDF·Word·LaTeX등 다양한 형식으로 출력 가능）.

오늘날 GitHub, GitLab, Stack Overflow, Reddit, Discord, Notion, Obsidian, Confluence, VS Code 등 거의 모든 기술 도구가 Markdown을 표준 글쓰기 언어로 채택하고 있습니다.

2. Markdown vs. Word vs. HTML: 상황에 맞는 선택

형식	최적 사용 상황	주요 장점	주요 한계
Word / Google Docs	업무 문서, 계약서, 공식 보고서	WYSIWYG, 복잡한 레이아웃, 변경 추적	벤더 잠금, Git과 호환성 약함
HTML	스타일 정밀 제어가 필요한 웹 페이지	완전한 제어, 브라우저 네이티브	장황한 문법, 원문 가독성 낮음
Markdown	기술 문서, README, 블로그, 메모	순수 텍스트, 가볍고 가독성 높으며 Git 친화적	복잡한 레이아웃에는 HTML 혼용 필요

Markdown의 핵심 강점은 순수 텍스트라는 점입니다. git diff로 한 줄 단위 변경 이력 추적, 어떤 OS에서도 열기, Pandoc으로 형식 일괄 변환, 전문 검색이 모두 가능합니다.

3. 기본 문법: 제목·단락·텍스트 스타일

제목 (Headings)

# H1 페이지 제목 (문서당 하나를 권장)
## H2 주요 섹션
### H3 하위 섹션
#### H4
##### H5
###### H6

모범 사례: 본문 섹션은 H2부터 시작하세요. 제목 단계를 건너뛰면 (예: H2→H4) 스크린 리더가 문서 구조를 올바르게 파악하지 못합니다.

텍스트 스타일

**굵게** 또는 __굵게__
*기울임* 또는 _기울임_
***굵고 기울임***
~~취소선~~

4. 목록: 순서 없음·순서 있음·중첩


- 첫 번째 항목
- 두 번째 항목


1. 첫 번째 단계
2. 두 번째 단계


- 프론트엔드
  - HTML
  - CSS
  - JavaScript
    1. 변수와 타입
    2. 함수

5. 링크와 이미지

[표시 텍스트](https://example.com)
[표시 텍스트](https://example.com "호버 시 툴팁")

![대체 텍스트](https://example.com/image.png)

접근성 포인트: 대체 텍스트는 "image.png" 같은 무의미한 텍스트가 아닌 "시스템 아키텍처 개요도"처럼 내용을 설명하는 텍스트로 작성하세요.

6. 코드: 인라인 코드와 펜스드 코드 블록


`npm install` 실행 후 `npm run dev`로 서버를 시작합니다.


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

자주 사용하는 언어 식별자: javascript, python, php, bash, css, html, json, yaml.

7. 인용 블록 (Blockquote)

> 인용할 내용을 여기에 씁니다.
> 여러 줄에 걸칠 경우 각 줄에 > 를 붙입니다.
>
> **주의**: 이 API는 v3.0에서 더 이상 사용되지 않습니다.

> 외부 인용
> > 중첩 인용

8. 표 (GFM 확장 문법)

| 언어       | 종류   | 학습 난이도 |
| ---------- | ------ | ----------- |
| Python     | 인터프리터 | 낮음    |
| JavaScript | 인터프리터 | 중간    |
| Rust       | 컴파일러   | 높음    |

구분선의 콜론으로 열 정렬 지정: :--- 왼쪽, ---: 오른쪽, :---: 가운데.

9. 고급 문법

작업 목록 (GFM)

- [x] Markdown 가이드 읽기
- [x] VS Code 설치
- [ ] Prettier 설정
- [ ] 첫 번째 Pull Request 제출

YAML Front Matter

정적 사이트 생성기(Hugo, Jekyll, Next.js)는 YAML Front Matter로 문서 메타데이터를 정의합니다:

---
title: "Markdown 완전 가이드"
date: 2026-03-23
tags: ["Markdown", "글쓰기"]
---

본문은 여기서 시작합니다...

10. Markdown 방언과 명세

CommonMark: 가장 엄밀하게 정의된 명세. 모호함을 없애고 테스트로 완전히 커버됩니다.
GFM (GitHub Flavored Markdown): CommonMark에 표, 작업 목록, Alerts를 추가한 사실상의 업계 표준.
MDX: Markdown과 JSX의 결합. Next.js·Astro·Docusaurus에서 광범위하게 사용됩니다.
Quarto: 학술·데이터 과학 분야에서 Python·R 코드를 문서에 삽입해 실행할 수 있습니다.

11. Markdown이 빛나는 주요 활용 사례

GitHub / GitLab 프로젝트 문서: README.md·CHANGELOG.md·CONTRIBUTING.md는 오픈 소스 프로젝트의 필수 파일입니다.
개인 지식 관리: Obsidian·Logseq·Joplin은 디스크에 Markdown 파일로 메모를 저장해 벤더 잠금이 없습니다.
기술 블로그·정적 사이트: Hugo·Jekyll·Astro는 Markdown 문서를 빌드 시 HTML로 변환합니다.
협업 도구·채팅: Notion·Confluence는 전체 Markdown을, Slack·Discord는 서브셋을 지원합니다.
API 문서·기술 명세: Swagger/OpenAPI, npm README는 Markdown을 표준으로 사용합니다.

12. 자주 발생하는 실수와 모범 사례

단락 사이에는 완전히 빈 줄 하나가 필요합니다. Enter 한 번만으로는 단락이 나뉘지 않습니다.
# 뒤에는 반드시 공백을 넣어야 합니다. #제목은 엄격한 렌더러에서 제목으로 인식되지 않습니다.
목록의 3단계 이상 중첩은 가독성을 크게 해칩니다. 제목+표 구조로 재구성을 고려하세요.
같은 문서에서 목록 기호(- 또는 *)를 혼용하지 마세요.
반드시 대상 플랫폼에서 미리보기를 확인한 후 게시하세요. 렌더링 결과는 플랫폼마다 다를 수 있습니다.
팀 프로젝트에서는 markdownlint를 CI/CD에 통합해 스타일을 통일하고 불필요한 diff를 줄이세요.

지금 바로 해보세요

이 사이트의 온라인 Markdown 편집기를 열고 이 글의 코드 샘플을 붙여넣어 보세요. 왼쪽에 입력하면 오른쪽에서 실시간으로 미리보기가 업데이트됩니다. 읽는 것보다 직접 손을 움직이는 것이 훨씬 빠르게 익혀집니다.

마치며

Markdown의 매력은 '낮은 진입 장벽, 높은 천장'에 있습니다. 기본 문법은 5분 안에 습득할 수 있고, 그것만으로도 일상적인 용도의 대부분을 커버할 수 있습니다. 더 나아가 Git·정적 사이트 생성기·지식 관리 시스템과 결합하면 매우 강력한 글쓰기 워크플로를 구축할 수 있습니다.

무엇보다 중요한 것은 Markdown이 내용 자체에 집중하게 해준다는 점입니다. 글꼴 조정, 툴바 클릭, 플랫폼 간 서식 깨짐을 걱정할 필요 없이 오직 쓰는 것에만 집중할 수 있습니다. 지금 바로 .md 파일을 하나 만들고 첫 문장을 써보세요.