はじめに
⚡️ Docusaurus は、美しく、かつ短時間でドキュメントサイトを構築するのに役立ちます。
💸 カスタムの技術スタックを構築するには費用がかかります。代わりに、コンテンツに集中し、Markdown ファイルを書くだけで済みます。
💥 もっと活用したいですか？ バージョン管理、国際化、検索、テーマのカスタマイズなどの高度な機能を使用できます。
💅 インスピレーションを得るために最高の Docusaurus サイトをチェックし、お客様の声をご覧ください。
🧐 Docusaurus は静的サイトジェネレーターです。高速なクライアントサイドナビゲーションを備えたシングルページアプリケーションを構築し、React のフルパワーを活用してサイトをインタラクティブにします。すぐに使えるドキュメント機能を提供しますが、あらゆる種類のサイト（個人ウェブサイト、製品、ブログ、マーケティングランディングページなど）を作成するために使用できます。
クイックスタート ⏱️
遊んで Docusaurus を5 分で理解しましょう！
新しい Docusaurus サイトを作成し、非常に短い組み込みチュートリアルに従ってください。
Node.js をインストールし、新しい Docusaurus サイトを作成します
npx create-docusaurus@latest my-website classic
サイトを開始します
cd my-website
npx docusaurus start
http://localhost:3000 を開き、チュートリアルに従ってください。
docusaurus.new を使用して、ブラウザで Docusaurus をすぐにテストしてください！
または、5 分間のチュートリアルをオンラインで読んでください。
Docusaurus: ドキュメント作成を簡単に
Algolia Community Event でのこのプレゼンテーションでは、Meta Open Source チーム が Docusaurus の簡単なウォークスルーを共有しました。プロジェクトの開始方法、プラグインの有効化方法、ドキュメントやブログなどの機能の設定方法について説明しました。
v1 からの移行
Docusaurus v2+ は、完全に近代化されたツールチェーンを活用して、Docusaurus v1 から完全に書き直されました。v2 の正式リリース後、Docusaurus v1 は非推奨になったため、Docusaurus v1 よりも Docusaurus v2+ を使用することを強くお勧めします。
すでに多くのユーザーが Docusaurus v2+ を使用しています（トレンド）。
以下の場合に Docusaurus v2+ を使用します
- ✅最新の Jamstack ドキュメントサイトが必要な場合
- ✅クライアントサイドルーティングを備えたシングルページアプリケーション (SPA) が必要な場合
- ✅React と MDX のフルパワーを活用したい場合
- ✅IE11 のサポートが必要ない場合
以下の場合にDocusaurus v1 を使用します
- ❌シングルページアプリケーション (SPA) が不要な場合
- ❌IE11 のサポートが必要な場合（...本当に必要ですか？ IE はすでにサポート終了に達しており、公式にはサポートされていません）
v2+ へのアップグレードを検討している既存の v1 ユーザーは、移行ガイドに従うことができます。
機能
Docusaurus は、開発者と貢献者のエクスペリエンスを重視して構築されています。
- ⚛️ 💚 と React で構築
- React で拡張およびカスタマイズ
- 独自の React コンポーネントを提供することで、サイトのブラウジングエクスペリエンスを完全に制御できます
- 🔌 プラグイン可能
- 基本テンプレートでサイトをブートストラップし、高度な機能とプラグインを使用します
- プラグインをオープンソース化してコミュニティと共有します
- ✂️ 開発者エクスペリエンス
- すぐにドキュメントの記述を開始できます
- 貢献者による保守を容易にするためのユニバーサル設定エントリポイント
- 変更時の超高速インクリメンタルビルドによるホットリロード
- ルートベースのコードとデータ分割
- GitHub Pages、Netlify、Vercel、その他のデプロイメントサービスに簡単に公開できます
私たちの共通の目標は、ユーザーが必要な情報をすばやく見つけ、製品をよりよく理解できるようにすることです。ドキュメントサイトを正しく適切に構築できるよう、ベストプラクティスを共有しています。
- 🎯 SEO フレンドリー
- 考えられるすべてのパスに対して HTML ファイルが静的に生成されます。
- ページ固有の SEO により、ユーザーが目の前の問題に直接関連する公式ドキュメントにアクセスできるようになります。
- 📝 MDX 搭載
- Markdown に埋め込まれた JSX と React を介してインタラクティブなコンポーネントを作成します。
- ライブエディターでコードを共有して、ユーザーがその場で製品を気に入るようにします。
- 🔍 検索: サイト全体を検索できます。
- 💾 ドキュメントのバージョン管理: ドキュメントをプロジェクトのリリースと同期させるのに役立ちます。
- 🌍 国際化 (i18n): サイトを複数のロケールに翻訳します。
Docusaurus v2+ は、すべてのユーザーが思いやりを持ってアクセスでき、超高速であるように設計されています。
- ⚡️ 超高速。Docusaurus v2+ は、コンテンツが非常に高速にロードされるようにするPRPL パターンに従います。
- 🦖 アクセスしやすい。アクセシビリティに配慮し、すべてのユーザーがサイトに平等にアクセスできるようにします。
設計原則
- 学ぶことは少ない。API が非常に小さいため、Docusaurus は学習と使用が簡単です。ユーザーがより多くのコードと時間をかけて記述する必要がある場合でも、ほとんどのことは依然として達成可能です。抽象化を持たないことは、間違った抽象化を持つよりも優れており、ユーザーが間違った抽象化をハックする必要はありません。必見の講演 - 最小限の API サーフェスエリア。
- 直感的。ユーザーは、Docusaurus プロジェクトのプロジェクトディレクトリを見たり、新しい機能を追加したりするときに、圧倒されることはありません。使い慣れた方法を使用して、直感的に構築できるように見えるはずです。
- 階層型アーキテクチャ。スタックの各層 (コンテンツ/テーマ/スタイリング) 間の関心の分離は明確で、適切に抽象化され、モジュール化されている必要があります。
- 適切なデフォルト。一般的で人気のあるパフォーマンスの最適化と構成はユーザー向けに実行されますが、ユーザーはそれらをオーバーライドするオプションがあります。
- ベンダーロックインなし。ユーザーはデフォルトのプラグインや CSS を使用する必要はありませんが、強くお勧めします。React Loadable や React Router など、特定のコアインフラストラクチャは、デフォルトのパフォーマンス最適化を実行するためスワップできませんが、上位レベルのインフラストラクチャはスワップできます。Markdown エンジン、CSS フレームワーク、CSS 方法論、その他のアーキテクチャの選択は、完全にユーザー次第です。
私たちは、開発者として、ライブラリの仕組みを知ることで、ライブラリをより効果的に使用できるようになると考えています。したがって、アーキテクチャと Docusaurus のさまざまなコンポーネントを説明することに尽力しており、それを読むユーザーがツールをより深く理解し、ツールをより効果的に使用できるようになることを願っています。
他のツールとの比較
すべての静的サイトジェネレーターの中で、Docusaurus はドキュメントサイトに独自の焦点を当てており、すぐに使える多くの機能を備えています。
また、他の主要な静的サイトジェネレーターも調査しており、比較に関する洞察を共有することで、多様な選択肢の中から最適なものを選択するのに役立つことを願っています。
Gatsby
Gatsby には多くの機能が満載されており、豊富なプラグインエコシステムがあり、Docusaurus が行うすべてのことを実行できます。当然のことながら、学習曲線が急になるという犠牲が伴います。Gatsby は多くのことをうまくこなし、多くのタイプの Web サイトの構築に適しています。一方、Docusaurus は 1 つのことを非常にうまく行うことに重点を置いています。それは、コンテンツを記述および公開するための最良のツールになることです。
GraphQL は Gatsby の中核でもありますが、Gatsby サイトを構築するために必ずしも GraphQL が必要というわけではありません。静的 Web サイトを構築する場合、ほとんどの場合、GraphQL が提供する柔軟性は必要ありません。
Docusaurus v2+ の多くの側面は、Gatsby の最も優れた点に触発されており、優れた代替手段です。
Docz は、ドキュメント Web サイトを構築するための Gatsby テーマです。現在、Docusaurus よりも機能が少なくなっています。
Next.js
Next.js は、もう一つの人気の高いハイブリッド React フレームワークです。優れたドキュメント Web サイトを構築するのに役立ちますが、ドキュメントのユースケースに特化しているわけではなく、Docusaurus が標準で提供する機能を実装するには、より多くの作業が必要になります。
Nextra は、Next.js をベースに構築された、独自の静的サイトジェネレーターです。現時点では、Docusaurus よりも機能が少ないです。
VitePress
VitePress は Docusaurus と多くの類似点があります。どちらもコンテンツ中心の Web サイトに重点を置いており、ドキュメントに特化した機能を標準で提供しています。ただし、VitePress は Vue を使用しているのに対し、Docusaurus は React を使用しています。Vue ベースのソリューションが必要な場合は、VitePress が適切な選択肢となります。
MkDocs
MkDocs は、Docusaurus と同様の価値提案を持つ、人気のある Python 静的サイトジェネレーターです。
シングルページアプリケーションが不要で、React を活用する予定がない場合は、良い選択肢となります。
Material for MkDocs は、美しいテーマです。
Docsify
Docsify は、ドキュメント Web サイトの作成を容易にしますが、静的サイトジェネレーターではなく、SEO にも適していません。
GitBook
GitBook は、非常にクリーンなデザインで、多くのオープンソースプロジェクトで使用されてきました。しかし、オープンソースツールではなく、商用製品に重点を移したことで、その要件の多くは、オープンソースプロジェクトのドキュメントサイトのニーズに合わなくなりました。その結果、多くが他の製品に移行しています。Redux が Docusaurus に移行した経緯については、こちらをご覧ください。
現在、GitBook はオープンソースおよび非営利団体のみ無料で利用できます。Docusaurus はすべての人が無料で利用できます。
Jekyll
Jekyll は、最も成熟した静的サイトジェネレーターの 1 つであり、優れたツールです。実際、Docusaurus 以前は、Facebook のオープンソース Web サイトのほとんどは Jekyll で構築されていました。非常に簡単に使い始めることができます。私たちは、Jekyll で静的サイトを構築するのと同じような開発者エクスペリエンスを提供したいと考えています。
静的に生成された HTML に <script /> タグを使用してインタラクティブ性を追加する方法と比較して、Docusaurus サイトは React アプリです。最新の JavaScript エコシステムツールを使用して、ドキュメントサイトのパフォーマンス、アセット構築パイプラインと最適化、セットアップの容易さについて、新しい基準を設定したいと考えています。
最新情報の入手
不足しているものがありますか？
ドキュメントに問題がある場合、またはドキュメントやプロジェクト全般の改善に関する提案がある場合は、Issue を報告するか、@docusaurus Twitter アカウントをメンションしてツイートを送信してください。
新機能のリクエストについては、機能リクエストボード (Canny)に投稿を作成できます。これはロードマッピングに便利なツールであり、賛成票でソートできるため、コアチームは、トリアージが難しい GitHub の Issue と比較して、どの機能の需要が高いかをよりよく把握できます。新機能（特に大規模なもの）のプルリクエストの作成は控えてください。既に誰かが作業しているか、ロードマップの一部になる可能性があるためです。まずはご相談ください。