ドキュメントサイトを作ろうと思ったきっかけ
静的なドキュメントサイトを構築するにあたって、候補に挙がったのが MkDocs と Docusaurus。
いずれも人気があり、優れたツールであることは間違いありません。
実際に両方を試してみた結果、それぞれの良さと、自分にとっての合わなさが見えてきました。
MkDocs: Markdown中心で構成も簡素。導入は非常にスムーズ
最初に試したのはMkDocsでした。 YAMLで設定ファイルを書き、Markdownファイルを配置するだけでサイトが構築できる点が魅力です。
pip install mkdocs
mkdocs new .
mkdocs serve
Material for MkDocs テーマを適用すれば、見栄えも整い、文書としての完成度も高くなります。
Markdownも素直に扱え、ドキュメントを書くという目的に集中しやすい印象でした。
ただし、ページ数が増えるとビルドが重くなる
プロジェクトの規模が大きくなるにつれて、ビルド処理が遅くなっていきました。
mkdocs serve での再ビルドに毎回時間を取られるようになり、作業効率に支障が出てきたのです。
約1,500のファイルに対して、ビルドに約20秒掛かり、差分更新もできないため、ストレスに感じることもありました。
- プラグインの相性によるトラブルも発生しやすい
- 設定変更やトラブルシューティングに時間を割く場面が増える
結果として、「書くこと」に集中しにくくなってしまいました。
Docusaurus: 高機能だが構築に手間がかかる
次に試したのがDocusaurusです。
Reactベースの設計で、柔軟性と拡張性に非常に優れており、表現力も豊かです。
npx create-docusaurus@latest my-site classic
cd my-site
npm start
多言語対応、全文検索、ブログ機能、カスタムコンポーネントなどが標準で備わっており、開発者向けのドキュメントとしては理想的とも言えます。
しかし、MDX形式が扱いづらかった
DocusaurusはMarkdownではなく MDX (JSXが混ざったMarkdown) を使います。 柔軟な表現が可能な一方で、以下のような課題がありました。
Markdownの再利用性が下がる
- JSX構文との混在により、Markdownファイル単体での再利用が難しい
- 書きながら表示を気にする必要があり、「書くこと」への集中が阻害される
最終的な判断: より軽量な方法へ回帰
DocusaurusもMkDocsも非常に優れたツールでしたが、 「自分が継続して書ける環境ではなかった」 というのが率直な感想です。
現在はより軽量なツールに移行しています:
- Markdown + 静的ジェネレーター (Hugo)
- シンプルな構成で、執筆に集中できる環境
終わりに
機能が豊富であることは素晴らしいことですが、機能の多さが執筆のハードルになるなら、それは本末転倒かもしれません。
私にとって大切だったのは、書きたいときに迷わず書ける環境でした。
ツール選びは、目的や価値観に大きく依存します。その中で、自分に合った“ちょうどよさ”を見つけることが、長く続ける鍵になるのではないかと感じています。
