문서 사이트 구축 (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를 수동 편집해야 함.

Docsify 고급 — 카테고리별로 사이드바 나누기 (2026-04-25 추가)¶

상황: 한 사이트에 여러 카테고리가 쌓이면 사이드바가 너무 길어져서 탐색이 불편해짐. 카테고리별로 다른 사이드바를 보여주고 상단에 네비를 두면 훨씬 깔끔.

원리 — 3가지 기능 조합: 1. loadNavbar: true + _navbar.md → 상단 네비 2. alias 설정 → 경로별로 다른 _sidebar.md 매핑 ("한 건물에 층마다 다른 안내판") 3. 각 카테고리 폴더에 README.md → 네비 클릭 시 404 방지

index.html 설정¶

window.$docsify = {
  name: '사이트 이름',
  loadSidebar: true,
  loadNavbar: true,        // ← 네비 활성화
  subMaxLevel: 3,
  sidebarDisplayLevel: 0,  // ← 모든 섹션 기본 접힘
  alias: {
    '/weekly/claude/.*/_sidebar.md': '/weekly/claude/_sidebar.md',
    '/weekly/chatgpt/.*/_sidebar.md': '/weekly/chatgpt/_sidebar.md',
    '/.*/_sidebar.md': '/_sidebar.md'   // ← 기본(전체) 사이드바
  }
}

_navbar.md 예시¶

* [전체](/)
* [Claude](/weekly/claude/)
* [ChatGPT](/weekly/chatgpt/)

폴더 구조¶

site/
├── _navbar.md                          ← 상단 네비
├── _sidebar.md                         ← 전체 사이드바 (통합)
├── weekly/
│   ├── claude/
│   │   ├── _sidebar.md                ← Claude 전용 사이드바
│   │   ├── README.md                  ← 랜딩(네비 클릭 시)
│   │   └── 2026-04-22.md
│   └── chatgpt/
│       ├── _sidebar.md
│       ├── README.md
│       └── ...

접기/펼치기 플러그인은 링크 형태 헤더만 섹션으로 인식한다.

❌ * **Claude** (굵은 텍스트) → 섹션 인식 안 됨, 계속 펼쳐져 있음
✅ * [**Claude**](/weekly/claude/) (링크) → 섹션으로 인식, 비활성 섹션 자동 접힘

자동화 팁 (Python 스크립트로 생성)¶

문서가 많아지면 사이드바/네비/README를 수동 관리하기 불가능. 스크립트로 생성하면 편리:

MODEL_CONFIG = [
    {"key": "claude",  "name": "Claude",  "nav": True},
    {"key": "chatgpt", "name": "ChatGPT", "nav": True},
    {"key": "gemini",  "name": "Gemini",  "nav": False},  # 잠깐 숨김
]

카테고리를 끄고 켤 때 플래그 하나만 바꾸면 복구됨
"변하지 않는 건 분리" 원리 — 비활성 카테고리도 스캔 로직은 유지, 출력만 제어

→ 실제 사례: D:\Sites\youtube-reports\update_sidebar.py

실전 사례¶

프로젝트	도구	URL
자동화 학습 가이드	MkDocs Material	study-guide-docs.pages.dev
캘리버 EPUB 가이드	Docsify	calibre-guide.vercel.app
행글라이터 기획실	Docsify (네비+모델별 사이드바)	youtube-reports.vercel.app