특징:
- 마크다운 전용 (배우기 쉬움)
- 빠른 검색, 깔끔한 UI
- 플러그인 풍부
- 정적 사이트 생성
장점:
- 설정 간단 (YAML)
- 로컬 개발 서버 빠름
- Vercel/Netlify/GitHub Pages 배포 용이
- Material for MkDocs 테마 우수
정의
MkDocs는 마크다운 파일로 작성한 기술 문서를 정적 웹사이트로 자동 변환해주는 오픈소스 도구입니다.
마크다운 파일들 (.md)
↓
MkDocs
↓
완성된 웹사이트 (HTML + CSS + JS)🎯 핵심 특징
| 항목 | 설명 |
|---|---|
| 언어 | Python 기반 |
| 입력 | 마크다운 (.md) |
| 출력 | 정적 HTML 웹사이트 |
| 라이선스 | BSD 오픈소스 (무료) |
| 설치 | pip install mkdocs |
🚀 주요 기능
1️⃣ 마크다운 기반
markdown
# 제목 1
## 제목 2
### 제목 3
- 리스트 항목
- 또 다른 항목
**굵은 텍스트**, *기울임*
[링크](https://example.com)2️⃣ 자동 네비게이션
- 디렉토리 구조 → 자동 메뉴 생성
- 목차 자동 생성
- 검색 기능 내장
3️⃣ 라이브 프리뷰
bash
mkdocs serve
# http://localhost:8000 에서 실시간 확인4️⃣ 테마 지원
- 기본 테마 포함
- Material for MkDocs (가장 인기)
- 추가 테마 다수
5️⃣ 플러그인
- 검색 고도화
- 다국어 지원
- SEO 최적화
- 등등
📁 프로젝트 구조
my-project/
├── mkdocs.yml # 설정 파일
├── docs/
│ ├── index.md # 홈페이지
│ ├── getting-started.md
│ ├── installation.md
│ ├── api/
│ │ ├── overview.md
│ │ └── reference.md
│ └── guide/
│ └── tutorial.md
└── site/ # 생성된 웹사이트 (배포용)⚙️ 설정 파일 예시 (mkdocs.yml)
yaml
site_name: My Project
site_description: 프로젝트 문서
theme:
name: material
language: ko
nav:
- Home: index.md
- 시작하기: getting-started.md
- 설치: installation.md
- API:
- 개요: api/overview.md
- 레퍼런스: api/reference.md
- 가이드: guide/tutorial.md
plugins:
- search🔄 작업 흐름
bash
# 1️⃣ 설치
pip install mkdocs mkdocs-material
# 2️⃣ 프로젝트 생성
mkdocs new my-docs
# 3️⃣ 마크다운 작성
# docs/ 폴더에 .md 파일 생성
# 4️⃣ 로컬에서 미리보기
mkdocs serve
# 5️⃣ 배포용 빌드
mkdocs build
# 6️⃣ 웹에 배포
# site/ 폴더를 호스팅 서버에 업로드