インストール

Docusaurus は、npm パッケージの集まりで構成されています。

ヒント

お急ぎコース を利用して、Docusaurus を 5 分⏱で理解しましょう！

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

要件

• Node.js バージョン 18.0 以上（node -v を実行することで確認できます）。 nvm をインストール・使用すると、単一のコンピューター上で複数バージョンの Node を管理することができます。
  • Node.js をインストールする際、依存関係に関連するすべてのチェックボックスをチェックすることをお勧めします。

プロジェクトの足場作り

Docusaurusをインストールする最も簡単な方法は、骨格となるDocusaurusウェブサイトの足場作りを支援するコマンドラインツールを使用することです。 このコマンドは、新しい空のリポジトリ内でも、既存のリポジトリ内でも、どこでも実行でき、雛形ファイルを含む新しいディレクトリが作成されます。

npx create-docusaurus@latest my-website classic

すぐに始められるように、classicテンプレートをお勧めします。このテンプレートには、Docusaurus 1から搭載されている機能が含まれています。 classicテンプレートには、@docusaurus/preset-classicが含まれており、その中には標準ドキュメント、ブログ、カスタムページ、CSSフレームワーク（ダークモード対応）などが含まれています。 標準的（classic）なテンプレートを使えばすぐに使い始めて、Docusaurusに慣れてきた頃にはカスタマイズをすることができます。

また、--typescriptフラグを指定することで、テンプレートのTypeScript版を使用することができます。 詳しくはTypeScriptサポートをご覧ください。

npx create-docusaurus@latest my-website classic --typescript

Meta関係者専用

Metaオープンソースプロジェクトのために新しいDocusaurusウェブサイトをセットアップする場合、以下のコマンドを内部リポジトリ内で実行すると、Meta固有の便利な初期設定がいくつか付属してきます。

scarf static-docs-bootstrap

代替インストールコマンド

また、お好みのプロジェクトマネージャを使用して新しいプロジェクトを初期化することもできます。

npm

npm init docusaurus

Yarn

yarn create docusaurus

pnpm

pnpm create docusaurus

利用可能なすべてのフラグの詳細については、npx create-docusaurus@latest --helpを実行するか、APIドキュメントを参照してください。

プロジェクト構造

標準テンプレートを選択し、サイト名をmy-websiteとした場合、新しいディレクトリmy-website/の下に以下のファイルが生成されることが確認できます。

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

プロジェクト構造の概要

• /blog/ - ブログのMarkdownファイルが格納されています。 ブログプラグインを無効にしている場合は、このディレクトリを削除できます。また、pathオプションを設定した後は、その名前を変更することができます。 詳細はブログガイドに記載されています。
• /docs/ - ドキュメントのMarkdownファイルが格納されています。 sidebars.jsでドキュメントのサイドバーの並び順をカスタマイズできます。 ドキュメントプラグインを無効にしている場合は、このディレクトリを削除できます。また、pathオプションを設定した後は、その名前を変更することができます。 詳細はドキュメントガイドに記載されています。
• /src/ - ページやカスタムReactコンポーネントのようなドキュメンテーション以外のファイルです。 ドキュメント以外のファイルを厳密にここに置く必要はありませんが、一元化されたディレクトリの下に置くことで、何らかのリントまたは処理を行う必要がある場合に指定しやすくなります。
  • /src/pages - このディレクトリ内のJSX/TSX/MDXファイルは、ウェブサイトページに変換されます。 詳細はページガイドに記載されています。
• /static/ - 静的ディレクトリです。 この中にあるコンテンツは、最終的にはbuildディレクトリのルートにコピーされます。
• /docusaurus.config.js - サイトの設定を含む設定ファイルです。 Docusaurus v1で言うところのsiteConfig.jsに相当します。
• /package.json - Docusaurusのウェブサイトは、Reactアプリです。 その中に好きなnpmパッケージをインストールして使うことができます。
• /sidebars.js - サイドバーのドキュメントの順序を指定するためにドキュメントで使用されます。

単一リポジトリ（Monorepo・モノレポ）

既存のプロジェクトのドキュメント作成にDocusaurusを使用している場合、モノレポが解決策になるかもしれません。 モノレポは、類似のプロジェクト間で依存関係を共有することを可能にします。 例えば、ウェブサイトでは、リリースされたバージョンに依存する代わりに、ローカルパッケージを使用して最新の機能を紹介することができます。 そうすれば、コントリビューターは機能を実装するたびにドキュメントを更新することができます。 モノレポのフォルダー構造の例を以下に示します。

my-monorepo
├── package-a # 別パッケージ（本体プロジェクト）
│   ├── src
│   └── package.json # パッケージAの依存関係
├── website   # Docusaurusのルート
│   ├── docs
│   ├── src
│   └── package.json # Docusaurusの依存関係
├── package.json # モノレポ内で共有された依存関係

この場合、./my-monorepoフォルダ内でnpx create-docusaurusを実行する必要があります。

NetlifyやVercelなどのホスティングプロバイダを使用している場合は、サイトのBase directoryをDocusaurusのルートがある場所に変更する必要があります。 この場合、./websiteとなります。 無視コマンドの設定については、デプロイドキュメントを参照してください。

モノレポについてはYarnのドキュメントを参照してください（モノレポを構築する手段はYarnだけではなく、一般的なソリューションです）。また、DocusaurusとJestの実例もご覧ください。

開発サーバーの実行

ファイルを編集しながら変更点を確認するには、Webサイトを配信し、最新の変更点を反映させるローカル開発サーバーを実行するとよいでしょう。

npm

cd my-website
npm run start

Yarn

cd my-website
yarn run start

pnpm

cd my-website
pnpm run start

初期設定では、http://localhost:3000を開くブラウザ画面が起動します。

おめでとうございます！ 最初のDocusaurusサイトを作成できました！ サイト内を閲覧して何があるかを確認しましょう。

ビルド

Docusaurusは最新の静的ウェブサイトジェネレータなので、ウェブサイトを静的コンテンツのディレクトリ内にビルドし、ウェブサーバに置いて閲覧できるようにする必要があります。 ウェブサイトをビルドするには以下のコマンドを実行します。

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build

すると、/buildディレクトリ内にコンテンツが生成されます。このディレクトリはGitHub pagesやVercel、Netlifyなどの静的ファイルホスティングサービスにコピーすることができます。 デプロイに関するドキュメントをご覧ください。

Docusaurusバージョンの更新

Docusaurusのバージョンアップには、様々な方法があります。 確実な方法の1つとしては、package.json内のバージョン番号を手動で目的のバージョンに変更することが挙げられます。 ただし、@docusaurus/で始まる名前空間のパッケージはすべて同じバージョンを使用する必要があることに注意してください。

情報

未リリースバージョンのドキュメントを参照しています。未リリースの機能を使用したい場合は、 @canary リリース を使用できます。

package.json

{
  "dependencies": {
    "@docusaurus/core": "current",
    "@docusaurus/preset-classic": "current",
    // ...
  }
}

次に、package.jsonのあるディレクトリで、以下のようなパッケージマネージャのinstallコマンドを実行します。

npm

npm install

Yarn

yarn install

pnpm

pnpm install

アップデートが正常に行われたことを確認するために、以下のコマンドを実行します。

npx docusaurus --version

出力として正しいバージョンが表示されるはずです。

また、Yarnを使っている場合は、以下のようにすることもできます。

yarn add @docusaurus/core @docusaurus/preset-classic

ヒント

Docusaurusの未リリースの新機能を@canary npm distタグで使用することができます。

お困りですか？

Stack Overflow、GitHubリポジトリ、Discordサーバー、またはTwitterで質問してください。