はじめに
優れたOSSのオンラインドキュメントは、大抵内容も素晴らしいのですがUXも素晴らしいと感じることが多いです。
あの洗練されたUIをもつWebサイトはほとんどの場合、技術文書作成向けの静的サイトジェネレータが使用されています。
この記事では独断と偏見でおすすめの技術文書の作成に利用可能な静的サイトジェネレータを5つ紹介します。
1. Docusaurus
- 公式ドキュメント: https://docusaurus.io/
DocusaurusはMeta社のチームが開発しているReactベースの静的サイトジェネレータです。
Docusaurusのメリット
- 豊富な機能
- 高いカスタマイズ製
- スタイルの変更などが比較的容易
Docusaurusのデメリット
- 高機能すぎるゆえにVitePressやVuePressよりかは若干パフォーマンスが悪い
- あくまでVitePressなどと比較しての話で気になる程ではない
コメント
一番に最初に選択肢にあがる人気・知名度ともに高い静的サイトジェネレータです。
迷ったらこれを使っておけば良いと思います。
個人的にはデフォルトのスタイルだと見出し文字が大きすぎると感じるのでデザインはそこまで洗練されてはいない印象があります。
2. VitePress
- 公式ドキュメント: https://vitepress.dev/
Vue製の静的サイトジェネレーターです。
公式ドキュメントによるとVitePressは「VuePressの精神的後継」にあたるとされています。
その名の通り、バンドルツールは vite が採用されています。
VuePressと以下の違いがあると謳っています。
- DXの大幅に改善
- パフォーマンスの向上
- デフォルトテーマがより洗練
- APIがより柔軟にカスタマイズ可
VitePressのメリット
- 洗練されたデザイン
- 高いパフォーマンス
VitePressのデメリット
- Docusaurusなどと比べると機能がやや少ない
コメント
個人的には一番好きです。デフォルトのthemeが洗練されていてとてもいいです。
機能も必要なものは揃っていて困ることはあまりないと思います。
パフォーマンスもすごく良いです。爆速です。
3. Starlight
公式ドキュメント: https://starlight.astro.build/
StarlightはAstro製のドキュメントWebサイト生成ツール。
誕生したのは2023年の3月頃と比較的新しいです。
Starlightのメリット
- 高いパフォーマンス
- AstroベースなのでReact、Vue、Svelteなど、様々なフレームワークのコンポーネントを混在させて使用することが可能
Starlightのデメリット
- Docusaurusなどと比べると機能が少ない
- MPAなのでページ遷移時のUXはSPAに劣る
コメント
Astro製なので初期レンダー時間はおそらく他と比べて短いと思います。
ただ、MPAなのでページ遷移はSPAと比べるとやや遅く感じます。
4. Nextra
公式ドキュメント: https://nextra.site/
NextraはNext.js製のWebサイト生成ツールです。
Nextraのメリット
- Next.jsの機能が使える
Nextraのデメリット
- ドキュメントに特化した機能は少なめ
コメント
Nextraは汎用的なWebサイト生成ツールなのでドキュメント生成に特化した機能は少なめです。
Next.jsの機能を使用したい場合は採用を検討できると思います。
5. MkDocs
公式ドキュメント: https://www.mkdocs.org/
MkDocsはPython製の静的サイトジェネレータです。
MkDocsをベースとしてマテリアルデザインを採用した Material for MkDocs というものもあります。
MkDocsのメリット
- 手軽に導入できる
MkDocsのデメリット
- JavaScript製のツールと比べると柔軟なカスタマイズには向いていない
- 機能はやや少ない
コメント
今回紹介した中では唯一JavaScript製ではない静的サイトジェネレータです。
素のMkDocsはデザインがあまり良くないですがMaterial for MkDocsは結構いいです。
ただドキュメント向けの機能面ではDucusaurusやVitePressと比べて少ないように見えます。
また、JavaScript製のツールのようにMarkdown内にReactコンポーネントやVueコンポーネントを埋め込んで柔軟にサイトを構築するといったことはできないです。
番外編
5選の中に入れなかったツールです。
VuePress
VitePressの前身となるVue製の静的サイトジェネレータです。
v1はmaintenance modeなので、あえて採用する理由はあまりないと思います。
Sphinx
Python製のドキュメント生成ツールです。
HTML以外にもPDF、EPUB、TeXと様々なフォーマットで出力可能です。
Pythonの公式ドキュメントで採用されていることでも有名です。
機能面は悪くはないですが個人的には洗練されたthemeが少ない印象です。
docsy
Googleが開発するHugoの技術文書向けtheme。
機能面もデザイン面もそれほど良いとは思えないです。
とは言え普通に使えるので、Hugoに慣れている人には良いかもしれません。
終わりに
今回は独断と偏見でおすすめのサイトジェネレータを5つ紹介しました。
もし気になるツールがある場合は是非、採用してみてください。
Discussion