Docusaurus は、 Facebook が開発した静的サイトジェネレータで、サクッと高速な Web サイトを作成することができるのが特徴です。
2023/12 時点での GitHub スター数は ⭐️ 49.9k です。
Links
- 公式ページ: docusaurus.io
- GitHub: facebook/docusaurus
特徴
公式がトップページに掲げている 5 つの特徴です。
- MDX: MDX というマークダウンと React が合体したファイル形式を利用できるので、 React 単体で作るときのように、ページを作成するのにわざわざ React を書く必要がありません。マークダウンを描くだけでページを作成できます。逆に、マークダウンで書いたコンテンツの中に React コンポーネントを埋め込むことが可能です。
- React: React で作られているので、カスタマイズが容易です。Docusaurus が用意している豊富なプラグインを活用しつつ、独自のサイトを作ることができます。
- 多言語対応: ローカライゼーションにデフォルトで対応しています。Git や Crowdin などの翻訳マネージャを使用してドキュメントを翻訳し、個別にデプロイできます。
- バージョン管理: プロジェクトとドキュメントのリリースを同期させることができます。
- コンテンツ検索: Algolia をデフォルトでサポートします。他の検索エンジンもサポートしています。
Crowdin とは
Algolia の料金
歴史
そもそも、なぜ Docusaurus が生まれたかというと、次の 4 つの要求を満たすためだったようです。
- Web サイトのインフラを考える時間がもったいない。適切なドキュメントを作成することに重点が置かれるべき。
- ブログの投稿、全文検索、バージョン管理など、Facebook のオープンソース Web サイトに必要な機能を備えている。
- アップデートやバグ修正を簡単に push できる。
- 全てのプロジェクトで一貫した UI を提供する。
以下、「 ドキュサウルスの誕生 」の意訳です。
Facebook は多くのオープンソースプロジェクトを抱えています。
もともと、それらのプロジェクトは、それぞれ独自の Web サイト上にドキュメントをデプロイしていました。しかし、「全てのドキュメントの UX を統一したい」「全てのドキュメントに検索フォームを追加したい」といった要求が発生すると、全てのプロジェクトに合わせて独自の改修を行う必要が出てきました。
そこで Jekyll でテンプレートを作成し、テンプレートのソースを手動でリポジトリにコピーする運用を始めました。新しく立ち上げられたオープンソースプロジェクトのほとんどに採用されました。既存のプロジェクトの中には、 Jekyll の点プレーに変換したものもあります。
この方法にも、問題がありました。全てのプロジェクトには一貫性があるにもかかわらず、全てのプロジェクトに対して同一の更新をかけられないという問題です。なぜなら、一度プロジェクトにテンプレートをコピーしてしまうと、その後にテンプレートを制御できなくなるためです。それぞれのプロジェクトは、必要に応じてテンプレートを自由に変更し、プロジェクト固有の機能をテンプレートに適用してしまっています。それによって、プロジェクトは同じテンプレートを共有していますが、時間経過とともに一貫性が失われていきました。新しいバージョンのテンプレートを適用すると、既存のサイトが壊れたり、独自に追加した機能が削除される可能性もあります。各プロジェクト一つ一つに手作業で更新をかけることは可能ですが、それぞれのプロジェクトで多言語対応をサポートする必要が出てきたとき、この方法に限界がきたと分かりました。
そこで、ポートフォリオ全体にわたって Web サイトを最新の状態に保ち、一貫性も保つという課題を解決するために何ができるかを考えました。また、複数のプロジェクトで同じ静的サイトジェネレータを共有したいと考えていました。同じテンプレートから始めて、ニーズに合わせてサイトのテーマを柔軟にカスタマイズして適応できるようなサイト生成ソフトウェアです。
ここで生まれたのが Docusaurus です！
Facebook では、Web 開発の経験があまりないチームや、主にプロジェクトを紹介するための基本的なサイトを必要としているチームでも、Docusaurus を使用してドキュメント Web サイトを迅速に立ち上げられるようになりました。Docusaurus は、 Jest の多言語対応や、React native のバージョン管理など、高度な機能を必要とするサイトでも活用されています。さまざまなプロジェクトがサイトの新機能をリクエストすると、それらは Docusaurus に追加され、全てのプロジェクトに提供されます。その結果、さまざまなプロジェクトのさまざまなサイトを保守するために必要な作業が大幅に削減されます。私たちのチームは、機能の追加、バグの修正、ドキュメントの作成により多くの時間を費やし、プロジェクトをより健全に保つことに集中できるようになりました。
感想
実際に触ってみて、Docusaurus は「レールに乗っている間はとても快適で、外れようとするときつい」タイプのフレームワークだと感じました。インストールした時点でほとんどサイトが出来上がっていて、Docusaurus が想定していないカスタマイズをしようとすると難しいです。静的サイトジェネレータだと Gatsby.js もそのように感じましたが、Docusaurus はさらにその傾向が強いと思います。
それもそのはず、Docusaurus が生まれた歴史を知って、そのように作られているんだなというのがよく分かりました。私たちがドキュメントを作るとき、どんな技術を使うかやデザインの良さを追求してしまいがちですが、「適切なドキュメントを作成することに重点が置かれるべき」という Docusaurus の思想はとても素敵だと思いました。