문서 사이트 생성기 비교 — Hugo, MkDocs, Docusaurus, Starlight 중 무엇을 고를까
팀 문서를 정적 사이트로 만들기로 했다면, 다음 질문은 하나입니다. 어떤 도구로 만들 것인가입니다. 후보는 많지만, 실제로 자주 비교되는 것은 네 가지입니다. 이 글은 그 네 가지(Hugo, MkDocs, Docusaurus, Starlight)를 모두 직접 끝까지 만들어 본 경험을 바탕으로 선택을 돕습니다.
후보 네 가지 #
- Hugo — Go로 만든 정적 사이트 생성기입니다. 문서 테마로는 Hextra가 대표적입니다. 단일 바이너리와 압도적인 빌드 속도가 강점입니다.
- MkDocs — Python 기반입니다. Material 테마와 함께 쓰면 설정이 적고 깔끔합니다.
- Docusaurus — React 기반입니다. MDX와 다국어, 버전 관리를 핵심 기능으로 갖춘, 가장 무거우면서 확장성이 높은 도구입니다.
- Starlight — Astro 기반의 문서 테마입니다. 비교적 최근에 떠오른 선택지로, 마케팅 사이트와 문서를 한 프로젝트에 담기 좋습니다.
한눈에 비교 #
| 도구 | 런타임 | 설치 | 검색 | 버전 관리 | i18n | 확장성 |
|---|---|---|---|---|---|---|
| Hugo (Hextra) | Go 단일 바이너리 | 보통(Go 필요) | 내장 | 없음(폴더 수동) | 내장 | 테마 범위 |
| MkDocs (Material) | Python | 쉬움(pip) | 내장 | mike(플러그인) | 플러그인 | 테마 + 확장 |
| Docusaurus | Node / React | 무거움 | 별도(Algolia, 플러그인) | 내장 | 내장 | 최강(MDX, React) |
| Starlight | Node / Astro | 보통 | 내장(Pagefind) | 플러그인 | 내장 | Astro 컴포넌트 |
런타임이 첫 관문 #
가장 먼저 갈리는 지점은 어떤 언어 생태계 위에서 동작하느냐입니다. Hugo는 단일 바이너리라 설치가 가볍지만, Hextra 같은 모듈 테마를 쓰면 Go가 필요합니다. MkDocs는 pip install 한 줄이면 충분해서 Python 팀에 가장 자연스럽습니다. Docusaurus와 Starlight는 Node 생태계 위에서 동작합니다. 결국 팀이 이미 쓰는 언어와 같은 쪽이 문제가 가장 적습니다.
기본 검색을 제공하는 쪽 #
매뉴얼에서 검색은 선택이 아니라 필수입니다. 여기서 Docusaurus만 성격이 다릅니다. Hugo Hextra, MkDocs Material, Starlight는 검색을 기본 내장해 서버 없이 바로 동작하지만, Docusaurus는 Algolia DocSearch나 로컬 검색 플러그인을 직접 붙여야 합니다. 검색을 빨리 붙이고 싶다면 나머지 셋이 한 발 앞섭니다.
버전 관리가 중요하다면 #
제품 버전이 자주 올라가고 옛 문서를 함께 유지해야 한다면 이 축이 결정적입니다. Docusaurus는 버전 스냅샷과 버전 선택 드롭다운을 내장합니다. MkDocs는 mike라는 도구로, Starlight는 커뮤니티 플러그인으로 비슷한 기능을 제공합니다. Hugo는 전용 기능이 없어 폴더로 직접 나눠야 합니다. 버전 요구가 강할수록 Docusaurus가 유리합니다.
확장성 — 어디까지 바꿀 수 있나 #
문서를 넘어 인터랙티브 요소나 커스텀 페이지가 필요하다면 확장성이 중요합니다. Docusaurus는 마크다운 안에서 React 컴포넌트를 쓰는 MDX로 확장성이 가장 높습니다. Starlight도 Astro 컴포넌트로 비슷한 유연성을 줍니다. Hugo와 MkDocs는 테마와 확장이 정한 범위 안에서 깔끔하게 동작하는 편입니다.
시작 명령 한 줄 #
각 도구로 첫 사이트를 만드는 명령은 다음과 같습니다.
# Hugo + Hextra
hugo new site my-docs && cd my-docs && hugo mod get github.com/imfing/hextra
# MkDocs Material
pip install mkdocs-material && mkdocs new .
# Docusaurus
npx create-docusaurus@latest my-docs classic
# Starlight
npm create astro@latest -- --template starlight어떤 상황에 맞나 #
- 가장 가볍고 빠르게, 단일 바이너리로 끝내고 싶다면 → Hugo
- Python 팀이고 설정은 최소로 깔끔하게 가고 싶다면 → MkDocs Material
- 버전, 다국어가 많은 대형 제품 문서이고 React를 활용하고 싶다면 → Docusaurus
- 마케팅 사이트에 문서를 얹거나 Astro 생태계를 쓴다면 → Starlight
정답은 없습니다. 팀이 쓰는 언어, 검색, 버전 요구의 강도, 확장성을 따져 보면 자연스럽게 한 도구로 좁혀집니다.
더 깊이 보기 — 도구별 실전 시리즈 #
각 도구로 설치부터 배포, 운영까지 문서 사이트를 끝까지 만드는 과정은 시리즈로 정리해 두었습니다.
네 시리즈 모두 같은 6편 목차(설치 → 정보 구조 → 콘텐츠 → 배포 → 다국어, 버전 → 운영)를 따르므로, 비교하며 읽기에도 좋습니다.