문서 사이트 구축 (MkDocs vs Docsify)¶

마크다운 문서를 웹사이트로 만들 때 쓰는 도구 비교.

도구 비교¶

	MkDocs Material	Docsify	VitePress
언어	Python	JavaScript	JavaScript
설치	`pip install mkdocs-material`	npm 또는 CDN	npm
빌드	필요 (`mkdocs build`)	불필요 (브라우저 렌더링)	필요
한국어 검색	강력	약함 (토큰 문제)	좋음
사이드바	nav 설정으로 자동	`_sidebar.md` 수동 작성	config 수동
다크모드	내장	플러그인	내장
코드 복사	내장	플러그인	내장
속도	빠름 (정적 파일)	약간 느림 (런타임 렌더링)	빠름
커스텀	CSS + JS 오버라이드	CSS + JS	Vue 컴포넌트
배포	Cloudflare/Vercel/GitHub Pages	아무 정적 호스팅	Cloudflare/Vercel

언제 뭘 쓰나¶

"문서 사이트 만들고 싶다"
  │
  ├─ 한국어 문서 + 검색 중요?
  │     ├─ YES → MkDocs Material
  │     └─ NO → 아래로
  │
  ├─ 빌드 없이 간단하게?
  │     ├─ YES → Docsify
  │     └─ NO → 아래로
  │
  └─ Vue 기반 + 고급 커스텀?
        └─ VitePress

대부분의 경우 MkDocs Material이 정답. 한국어 검색이 결정적 차이.

MkDocs Material 핵심 설정¶

설치¶

pip install mkdocs-material

프로젝트 구조¶

프로젝트/
├── mkdocs.yml          ← 설정 (nav, 테마, 플러그인)
├── docs/               ← 마크다운 문서들
│   ├── index.md        ← 홈페이지
│   ├── stylesheets/    ← 커스텀 CSS
│   └── javascripts/    ← 커스텀 JS
└── site/               ← 빌드 결과 (.gitignore)

mkdocs.yml 핵심¶

site_name: "사이트 이름"
docs_dir: docs

theme:
  name: material
  language: ko
  palette:
    - scheme: default    # 라이트
    - scheme: slate      # 다크

nav:
  - Home: index.md
  - 카테고리:
    - 문서 제목: 파일명.md

로컬 미리보기¶

mkdocs serve -a 127.0.0.1:8100

배포 (Cloudflare Pages)¶

GitHub repo 생성 + push (Direct Upload 절대 X)
Cloudflare Pages → Connect to Git
Build command: pip install mkdocs-material && mkdocs build
Build output: site
이후 push만 하면 자동 배포

커스텀 팁¶

카테고리별 색상 (사이드바)¶

/* nth-child로 카테고리 순서에 색상 지정 */
.md-nav--primary > .md-nav__list > .md-nav__item:nth-child(2) > .md-nav__link {
  border-left: 4px solid #43A047;
  background: rgba(67, 160, 71, 0.08);
}

사이드바 토글 (햄버거 메뉴)¶

MkDocs Material에 데스크톱 사이드바 토글은 기본 없음. JS로 추가:

// 버튼 생성 → 헤더에 삽입 → body에 class 토글
document.body.classList.toggle("sidebar-hidden");

body.sidebar-hidden .md-sidebar--primary {
  transform: translateX(-100%);
  width: 0;
}

새 문서 추가 시¶

docs/ 폴더에 md 파일 추가
mkdocs.yml의 nav에 한 줄 추가
push → 자동 배포

Docsify 기본 사용법 (참고)¶

빌드 없이 가장 간단하게 문서 사이트 만들 때.

초기 설정¶

npx docsify-cli init ./docs

구조¶

docs/
├── index.html      ← Docsify 로더 (CDN)
├── README.md        ← 홈페이지
├── _sidebar.md      ← 사이드바 메뉴 (수동)
└── guide.md         ← 문서들

_sidebar.md 예시¶

- [홈](/)
- 카테고리
  - [문서1](/doc1)
  - [문서2](/doc2)

Docsify는 문서 추가 시 _sidebar.md를 수동 편집해야 함.

실전 사례¶

프로젝트	도구	URL
자동화 학습 가이드	MkDocs Material	study-guide-docs.pages.dev
캘리버 EPUB 가이드	Docsify	calibre-guide.vercel.app