Docusaurusのご紹介
1つまたは複数のオープンソースWebサイトの管理に役立つDocusaurusをご紹介できることを大変嬉しく思います。
私たちは、以下の理由によりDocusaurusを作成しました。
- Webサイトのインフラストラクチャについて心配するのではなく、優れたドキュメントの作成に集中できるようにするため。
- ブログのサポート、検索、バージョン管理など、多くのオープンソースWebサイトに必要な機能を提供するため。
- 更新、新機能、バグ修正をすべての人に一度に簡単にプッシュできるようにするため。
- そして最後に、すべてのオープンソースプロジェクトに一貫したルックアンドフィールを提供するため。
Docusaurusは、チームがインフラストラクチャや設計の詳細を気にすることなく、ドキュメントWebサイトを簡単に公開できるように設計されたツールです。ユーザーが提供する必要があるのは、Markdownで記述されたドキュメントファイル、Reactで記述された提供されたホームページのカスタマイズ、およびいくつかの構成変更のみです。Docusaurusは、デフォルトのスタイル、サイトのフォーマット、シンプルなドキュメントナビゲーションを提供することにより、残りの部分を処理します。ユーザーは、簡単な初期化スクリプトを使用してnpmまたはyarnを介してインストールすることで、すぐに使用できるWebサイトの例を作成できるため、簡単に使い始めることができます。
Docusaurusは、ブログサポート、国際化、検索、バージョン管理など、コアとなるWebサイトとドキュメントの機能をすぐに使用できます。一部のプロジェクトではこれらの機能がまったく必要ない場合もありますが、これらの機能を有効にするには、一般的に、インフラストラクチャを最初から追加するのではなく、構成オプションを更新するだけで済みます。Docusaurusにさらに機能が追加されると、ユーザーは最新バージョンに簡単に更新できます。これは、npmまたはyarn updateを実行し、構成オプションを更新するだけで実行できます。ユーザーまたはチームは、新しい機能が追加されるたびにWebサイト全体のインフラストラクチャを手動で再構築する必要がなくなります。
docusaurusの誕生
Facebookがオープンソースプログラムを開始した当初、多くのチームはそれぞれのオープンソースプロジェクトにカスタムWebサイトを実装していました。このアプローチは、オープンソースプログラムチームがプロジェクトチームのドキュメントの改善を支援するように依頼された場合に課題をもたらしました。各サイトは固有であったため、ブログ、一貫したナビゲーション、検索などの基本的なインフラストラクチャを追加することは困難な作業になりました。
オープンソースチームは、プロジェクトWebサイトの開始点として使用できるJekyllに基づく標準テンプレートを作成することで、この問題の軽減を試みました。私たちは新しいプロジェクトに、テンプレートソースをリポジトリに手動でコピーし、ドキュメントを作成し、公開するように依頼しました。このテンプレートアプローチは、開始されたほとんどのオープンソースプロジェクトで採用されました。既存のプロジェクトの中には、カスタムWebサイトの実装を新しいテンプレートに変換したものさえありました。
「テンプレートをリポジトリにコピーする」アプローチの問題点は、プラットフォームが一貫していても、更新のプッシュが既にテンプレートを使用しているプロジェクトスイート全体で維持できなくなることです。これは、プロジェクトがテンプレートをリポジトリにコピーした後、テンプレートの制御を失ったためです。プロジェクトは、必要に応じてテンプレートを自由に修正し、独自のプロジェクト固有の機能を適用できました。そのため、プロジェクトは同じサイト生成プラットフォームを共有していますが、時間の経過とともにテンプレートに追加された新機能を利用できないほど十分に転用されています。既存のサイトが壊れたり、独自に追加した機能が削除されたりする可能性があるため、すべての現在のプロジェクトに新しいバージョンのテンプレートを「コピー」するように依頼する簡単な方法はありませんでした。代わりに、各プロジェクトに更新を手動で1つずつ適用する必要がありました。これは、プロジェクトがテンプレート内で国際化のサポートをチームに要求し始め、テンプレートの構造と生成方法に低レベルの変更が必要になった場合に非常に問題になりました。
そこで、ポートフォリオ全体でサイトの更新と一貫性を維持するという課題を軽減するために何ができるかを考え始めました。また、複数のプロジェクトで同じサイト生成ソフトウェアを共有したいと考えていました。同じテンプレートから始めて、サイトのテーマをニーズに合わせてカスタマイズおよび調整できる柔軟性を持たせたいと考えていました。サイトを拡張およびカスタマイズできる必要がありますが、修正と機能で基盤となるインフラストラクチャを更新すると、プロジェクトは簡単に、破壊的な変更なしに更新できる必要があります。
Docusaurusが誕生しました！
Facebookでは、Docusaurusを使用すると、特にWeb開発の経験があまりないチームや、主にプロジェクトを紹介するための基本的なサイトが必要なチームのために、ドキュメントWebサイトを使用してさまざまなプロジェクトを迅速に稼働させることができます。Docusaurusは、Jestの国際化やReact Nativeのバージョン管理など、より高度な機能を必要とするサイトを既にサポートしています。さまざまなプロジェクトがサイトの新しい機能をリクエストすると、それらはDocusaurusに追加され、同時にすべてのプロジェクトに提供されます！これらをすべてまとめることで、さまざまなプロジェクトのさまざまなサイトを維持するために必要な作業が大幅に削減されます。私たちのチームは、機能の追加、バグの修正、ドキュメントの作成により多くの時間を費やすことで、プロジェクトの健全性を維持することに集中できます。
すぐに使い始める
Docusaurusを実行しているサイトは、基本的に使いやすくしたいと考えていました。1つのインストールコマンドと簡単な構成で、実際にデフォルトの実行中のWebサイトを作成できます。
docusaurus-initを実行すると、次のような構造が表示されます。
root-of-repo
├── docs-examples-from-docusaurus
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ ├── example-doc4.md
│ └── example-doc5.md
├── website
│ ├── blog-examples-from-docusaurus
│ │ ├── 2016-03-11-blog-post.md
│ │ └── 2017-04-10-blog-post-two.md
│ ├── core
│ │ └── Footer.js
│ ├── node_modules
│ ├── package.json
│ ├── pages
│ ├── sidebars.json
│ ├── siteConfig.js
│ └── static
node_modulesとpackage.jsonを除いて、表示されるすべてのディレクトリとファイルは、DocusaurusベースのWebサイトにコンテンツをカスタマイズおよび追加する場所です。docsフォルダーは、ドキュメントを表すMarkdownを追加する場所です。blogフォルダーは、ブログ投稿のMarkdownを追加する場所です。siteConfig.jsは、サイトのほとんどのカスタマイズを行う場所です。sidebars.jsonは、ドキュメントのサイドバーのレイアウトとコンテンツを維持する場所です。pagesフォルダーは、サイトにカスタムページを追加する場所です。staticフォルダーは、すべての静的アセット（CSSスタイルシートや画像など）が配置される場所です。coreフォルダーは、サイトのコアコンポーネント（この場合はフッター）をカスタマイズできる場所です。
Docusaurusの仕組み
Docusaurusは、主にJavaScriptとReactで記述されており、古いテンプレートで使用していたJekyllを置き換えています。MarkdownレンダリングにはRemarkableを、コードブロックの構文の強調表示にはhighlight.jsを使用しています。Docusaurusの機能のコアは、Docusaurusリポジトリのlibディレクトリにあります。一般的な構造は次のようになります。
root-of-Docusaurus
├── lib
│ ├── core
│ ├── server
│ │ ├── generate.js
│ │ ├── server.js
│ │ └── ...and more files
│ ├── static
│ ├── build-files.js
│ ├── copy-examples.js
│ ├── generate-feed.js
│ ├── publish-gh-pages.js
│ ├── rename-version.js
│ ├── start-server.js
│ ├── versions.js
│ └── write-translations.js
ここでの重要なファイルは、build-files.jsとstart-server.jsです。これら2つのファイルには多くの類似点があります。build-files.jsは、外部Webサーバーが提供するための物理的なアーティファクトを構築するために使用されます。start-server.jsは、Docusaurusサーバーを実行し、サイトをローカルでテストするために使用されます。どちらも、すべてのMarkdownと構成を取得して実行可能なWebサイトを作成するために、次の一般的なプロセスを実行します。
siteConfig.jsでWebサイトの設定を処理します。- docsディレクトリにあるすべてのMarkdownファイルに存在するドキュメントメタデータを読み取ります。
- メタデータから抽出されたIDに基づいて、ドキュメントの目次を作成します。
- リンクの置換を含め、MarkdownをHTMLに変換します。
- これらのファイルは、コンパイルされたサイトのbuild/docsディレクトリに配置され、翻訳されたバージョンはbuild/docsフォルダー内の言語固有のフォルダーに配置されます。
- ブログ投稿に対して1〜3を繰り返します。
- ブログファイルは、コンパイルされたサイトのbuild/blogディレクトリに配置されます。
- main.cssファイルを読み取り、ユーザー定義のcssをコンパイルされたサイトのbuild/cssディレクトリにあるマスターcssファイルに連結します。
- 画像をコンパイルされたサイトのbuild/imgディレクトリにコピーします。
- サイトのpagesフォルダーに追加されたカスタムページを取得し、それらをコンパイル/コピーして、コンパイルされたサイトのルートbuildディレクトリに配置します。翻訳されたバージョンは、build内の言語固有のフォルダーに配置されます。
- CNAMEおよびsitemap.xmlファイルを作成し、buildに追加します。
このプロセスでは、翻訳やバージョン管理の仕組みが完全には考慮されていないことに注意してください。これらの機能の詳細は、今後のブログ記事で説明します。
コンパイルされたサイトの最終的な構造は、次のようになります。
build
├── website
│ ├── CNAME
│ ├── blog
│ ├── css
│ ├── docs
│ ├── en
│ ├── help.html # custom page
│ ├── img
│ ├── index.html # landing page
│ ├── sitemap.xml
│ └── users.html # custom page
コミュニティ
Docusaurusへの貢献を歓迎します。ご自身のサイトで使用する場合でも、Docusaurusコアに貢献する場合でも、質問がある場合でも構いません。GitHubとTwitterでフォローしてください。
謝辞
Docusaurusは、Docusaurusコアチームの他のメンバーの努力なしには存在しませんでした。Eric Nakagawa氏、Hector Ramos氏、Eric Vicenti氏、そしてコア技術と機能を実装したFacebookの元インターンであるFrank Li氏です。
Docusaurusの初期の導入者の方々にも感謝いたします。
彼らがウェブサイトをプラットフォームに作成または移行することに尽力してくれたおかげで、私たちは今日のような立場になることができました。