Skip to main content

はじめに

⚡ Docusaurusを使えば、美しいドキュメントサイトをあっという間に作成できます。

💸 個別の技術スタックの構築は手間が掛かるものです。 それよりも内容に集中し、Markdownを書くだけにしましょう。

💥 もっと知りたいですか？ バージョン管理や国際化、検索、テーマのカスタマイズなどの高度な機能を使ってみましょう。

💅 インスピレーションの源として、Docusaurusの優れたサイト集 をご覧ください。

🧐 Docusaurusは静的サイトジェネレータです。 Reactをフル活用してサイトをインタラクティブにし、高速なクライアントサイドナビゲーションを備えた単一ページアプリケーションを構築します。 Docusaurusは、すぐに使えるドキュメンテーション機能を提供しますが、 どんな種類のサイトの作成にも使用することができます（個人のウェブサイト、製品、ブログ、マーケティングのランディングページなど）。

お急ぎコース⏱️​

手を動かしながらDocusaurusを5分で理解しましょう！

新しいDocusaurusサイトを作成し、そこに組み込まれたごく短いチュートリアルに従ってください。

Node.jsをインストールし、次のコマンドで新しいDocusaurusサイトを作成します。

npx create-docusaurus@latest my-website classic

以下のコマンドでサイトを起動します。

cd my-website
npx docusaurus start

http://localhost:3000を開き、チュートリアルに従ってください。

ヒント

手元のブラウザーですぐにDocusaurusを試すには、docusaurus.new を使いましょう！

または 5分間のチュートリアル をオンラインで読んでください。

Docusaurus: ドキュメント作成を簡単に​

Algoliaコミュニティイベントで行われたこのプレゼンテーションで、Metaオープンソースチームは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 コンポーネントを提供することで、サイトのブラウジング体験を完全に制御できます
  • 🔌 プラグイン可能：
    • 基本のテンプレートでサイトを初期設定したのち、高度な機能とプラグインを使用できます
    • プラグインをオープンソース化してコミュニティと共有しましょう
  • ✂️ 開発者体験：
    • すぐにドキュメントを書き始められる
    • Contributor によるメンテナンス性を高めるために、ユニバーサルな設定を行なえるエントリーポイントが用意されています。
    • ソースに変更があった際に稲妻のごとき高速ビルドを行うホットリロード機能も付属
    • Route-based なコードとデータの分割を実装しています。
    • GitHub Pages、Netlify、Vercel や、その他のデプロイサービスに簡単に公開できます。

私たちの共通の目標は、ユーザーが必要なものを素早く見つけ、製品をより深く理解できるようにすることです。 私たちは、あなたがドキュメントサイトを適切に構築できるように、最善の方法を共有します。

  • 🎯 SEOに優しい：
    • HTML ファイルは、可能なすべてのパスに対して静的に生成されます。
    • ページに特化した SEO で、ユーザーが手元にある問題を直接関連づけて公式ドキュメントにアクセスできるようにします。
  • 📝 MDX採用：
    • Markdown に組み込まれた JSX と React を介してインタラクティブなコンポーネントを記述します。
    • あなたの製品がユーザーに即座に気に入ってもらえるように、ライブエディターであなたのコードを共有しましょう。
  • 🔍 検索：サイト全体が検索可能です。
  • 💾 ドキュメントのバージョン管理：ドキュメントをプロジェクトのリリースと同期させるのに役立ちます。
  • 🌍 国際化（i18n）：サイトを複数のロケールに翻訳しましょう。

Docusaurus v2 は、すべてのユーザーが快適にアクセスでき、驚くほど速く動作するように生まれました。

  • ⚡️ 超高速動作。 Docusaurus v2以降はPRPL Patternに従ってコンテンツを高速にロードします。
  • 🦖 アクセシビリティ対応。 すべてのユーザーがサイトに平等にアクセスできるようにするアクセシビリティも重視しています。

設計の原則​

  • 学ぶことが少ない。 Docusaurusは、APIが非常に小さいため、学びやすく、使いやすいでしょう。 たとえ時間をかけてたくさんのコードを書いたとしても、ほとんどのことはユーザが実現できるでしょう。 抽象化されないことは、間違った抽象化よりも良いことであり、ユーザーが間違った抽象化で解決策を誤魔化すことは避けたいです。 必須の要点—APIの公開面を最小限にすること。
  • 直感的。 Docusaurus プロジェクトのプロジェクトディレクトリを見るときや、新しい機能を追加するときに、ユーザの気が遠くなるようなことはありません。 直感的で、慣れ親しんだアプローチで簡単に構築できなければなりません。
  • 階層型アーキテクチャ。 スタックの各レイヤー（コンテンツ／テーマ／スタイリング）間の関心事の分離は、明確で、すなわち十分に抽象化かつモジュール化されていなければなりません。
  • 合理的な初期設定。 一般的でよく使われるパフォーマンスの最適化や設定は、ユーザー向けに行われますが、それを上書きする選択肢が与えられています。
  • ベンダーロックインなし。 ユーザーはデフォルトのプラグインやCSSを使用することが強く推奨されているものの、必須ではありません。 React LoadableやReact Routerのような特定のコアインフラは、デフォルトのパフォーマンス最適化を行うため、差し替えができませんが、より高いレベルのものは差し替えできます。 Markdownエンジン、CSSフレームワーク、CSSメソッド、その他のアーキテクチャの選択は、完全にユーザー側に委ねられています。

私たちは、開発者の立場から、ライブラリの仕組みを知ることが、そのライブラリの使い方をより良くすることにつながると信じています。 そのため、Docusaurusのアーキテクチャや様々なコンポーネントを説明することに力を注ぎ、それを読んだユーザがこのツールをより深く理解し、さらに使いこなせるようになることを願っています。

他のツールとの比較​

すべての静的サイトジェネレータの中で、Docusaurusはドキュメントサイトに独自の焦点を当て、多くのすぐに使える機能を持っています。

私たちは、他の主要な静的サイトジェネレーターも調査しており、その比較に関する私たちの見解を共有することで、世の中にある多彩な選択肢を見極める一助となればと考えています。

Gatsby​

Gatsbyには多くの機能が詰め込まれており、豊富なプラグインのエコシステムがあり、Docusaurusができることはすべて行うことができます。 それは当然ながら、より高い学習曲線に従うコストを支払うことにもつながります。 結局のところ、Gatsby は多くのことをうまくやってくれるという点で、様々なタイプのウェブサイトを構築するのに適しています。 一方で Docusaurus は、コンテンツを書き公開するツールとして、そのことを非常に上手に行います。

また、GraphQL も Gatsby の中核をなすものですが、必ずしも Gatsby サイトを構築するために GraphQL が必要というわけではありません。 静的なウェブサイトを構築する際のほとんどの場合では、GraphQL が提供する柔軟性は必要ありません。

Docusaurus v2以降の多くの部分は、Gatsbyの良いところから着想を得ており、優れた代替ソリューションとなっています。

Doczはドキュメントサイトを構築するためのGatsbyテーマです。 現時点ではDocusaurusより機能が少ないです。

Next.js​

Next.jsも非常に人気が高いハイブリッドReactフレームワークです。 Next.jsは、優れたドキュメントサイトを構築するのに役立つかもしれませんが、ドキュメントの用途に特化しておらず、Docusaurusではすぐに使えるものを実装するには、ずっと多くの手間がかかります。

Nextraは、Next.jsを基盤として構築された、制約の強い（opinionatedな）静的サイトジェネレーターです。 現時点ではDocusaurusより機能が少ないです。

VitePress​

VitePressはDocusaurusと多くの類似点があります。どちらもコンテンツ中心のウェブサイトに重点を置いており、すぐに使える個々に合ったドキュメント機能を提供します。 しかし、DocusaurusはReactで動いているのに対し、VitePressはVueで動いています。 Vueを基盤としたソリューションが必要な場合、VitePressは適切な選択肢となるでしょう。

MkDocs​

MkDocsは、Docusaurusに似た価値観を持つ、人気のPython製静的サイトジェネレータです。

シングルページアプリケーションを必要とせず、Reactを活用する予定もないのであれば、良い選択肢となるでしょう。

Material for MkDocsは美しいテーマです。

Docsify​

Docsifyはドキュメントサイトを簡単に作ることができますが、静的サイトジェネレータではなく、SEOにも対応していません。

GitBook​

GitBookは非常にスッキリとしたデザインで、多くのオープンソースプロジェクトで使用されてきました。 その主軸がオープンソースツールではなく、商用製品に移行したことで、その要件の多くが、オープンソースプロジェクトのドキュメントサイトのニーズに合わなくなりました。 その結果、多くの人が他の製品に目を向けるようになりました。 ReduxがDocusaurusに切り替えた経緯については、こちらで読むことができます。

現在、GitBookはオープンソースと非営利のチームに対してのみ無料で提供されています。 一方、Docusaurusは、誰でも無料で利用できます。

Jekyll​

Jekyllは、最も成熟した静的サイトジェネレータの一つであり、使用するのにふさわしいツールです。実際、Docusaurusの登場前は、FacebookのオープンソースサイトのほとんどがJekyllで構築されています/されていました！ 始めるのは非常に簡単です。 私たちは、Jekyllで静的サイトを構築するのと同様の開発者体験をもたらしたいのです。

静的に生成されたHTMLと<script />タグで追加されたインタラクティブ性に対して、DocusaurusのサイトはReactアプリです。 最新のJavaScriptエコシステムツールを使用し、ドキュメントサイトのパフォーマンス、アセットをビルドするパイプラインと最適化、セットアップの容易さについて新しい基準を打ち立てることを望んでいます。

Rspress​

RspressはRustベースのバンドラーであるRspackを土台にして作られた高速な静的サイトジェネレータです。 MDX（Reactコンポーネントを組み込んだMarkdown）によるコンテンツ作成・統合型テキスト検索機能・多言語対応（i18n）・プラグインによる拡張性に対応しています。 洗練されたドキュメントサイトや静的ウェブサイトの作成を目的として設計されており、デプロイが簡単な静的HTMLファイルを生成します。

RpressとDocusaurusは非常に似ています。 どちらも一長一短です。 Rspressはより新しく作られたものであり、現代的なインフラストラクチャによりサイトのビルド速度が速いという利点があります。 一方、Docusaurusはその成熟度・豊富な機能セット・高い柔軟性・強力なコミュニティサポートで突出しています。 また、パフォーマンス面での競争力を維持するために、インフラストラクチャの近代化を定期的に進めています。

最新情報を入手​

お探しのものが見つからないときは？ ​

もし、ドキュメントに問題があったり、ドキュメントやプロジェクト全般を改善するための提案があったりする場合は、私たちにissueを投稿するか、@docusaurusのXアカウントへのメンションを加えたツイートを送信してください。

新機能のリクエストについては、機能リクエストボード（Canny）に投稿してください。これはロードマップのための便利なツールで、投票数によるソートができるようになっています。トリアージが難しいGitHubでのIssueと比べて、開発コアチームにとってどのような機能に対する需要が高いのかよりわかりやすくなります。 誰かがすでにそれに取り組んでいるか、ロードマップの一部になる可能性があるため、新しい機能（特に大きなもの）の Pull Request を作成することは避けてください。 まずはご相談ください！