ドキュメントサイトジェネレーター比較 — Hugo・MkDocs・Docusaurus・Starlight、どれを選ぶか
チームのドキュメントを静的サイトで作ると決めたら、次の問いは決まっています。どのツールで作るかです。候補は多いものの、実際によく比較されるのは4つです。この記事は、その4つ(Hugo・MkDocs・Docusaurus・Starlight)をすべて実際に最後まで作ってみた経験をもとに、選択を助ける記事です。
候補は4つ #
- Hugo — Go で作られた静的サイトジェネレーターです。ドキュメントテーマでは Hextra が代表的です。単一バイナリと圧倒的なビルド速度が強みです。
- MkDocs — Python ベースです。Material テーマと一緒に使うと設定が少なく、すっきりします。
- Docusaurus — React ベースです。MDX と多言語・バージョン管理を1級機能として備えた、最も重く、そして天井が高いツールです。
- Starlight — Astro ベースのドキュメントテーマです。比較的最近に登場した選択肢で、マーケティングサイトとドキュメントを1つのプロジェクトにまとめるのに向いています。
ひと目で比較 #
| ツール | ランタイム | インストール | 検索 | バージョン管理 | 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 かローカル検索プラグインを自分でつなぐ必要があります。検索を早く出したいなら、残りの3つが一歩先です。
バージョン管理が必要なら #
製品のバージョンが頻繁に上がり、古いドキュメントも一緒に維持しなければならないなら、この軸が決め手になります。Docusaurus はバージョンのスナップショットと選択ドロップダウンを内蔵します。MkDocs は mike というツールで、Starlight はコミュニティプラグインで、似た機能を足します。Hugo は専用機能がないので、フォルダで手動に分けます。バージョンの要求が強いほど Docusaurus が有利です。
天井 — どこまでカスタマイズできるか #
素のドキュメントを超えてインタラクティブな要素やカスタムページが必要なら、天井が重要です。Docusaurus は Markdown の中で 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
正解はありません。チームが使う言語、検索・バージョンの要求の強さ、カスタマイズの天井。この3つを検討すれば、自然と1つのツールに絞られます。
さらに深く — ツール別の実戦シリーズ #
各ツールでインストールからデプロイ・運用まで、ドキュメントサイトを最後まで作る流れはシリーズにまとめてあります。
4つのシリーズはすべて同じ6回構成(インストール → 情報構造 → コンテンツ → デプロイ → 多言語・バージョン → 運用)に沿っているので、比較しながら読むのにも向いています。