メインコンテンツへスキップ
バージョン: 3.5.2

インストール

Docusaurus は npm パッケージのセットで構成されています。

ヒント

ファストトラックを利用して、Docusaurus を 5分 ⏱で理解しましょう！

docusaurus.new を使用して、ブラウザですぐに Docusaurus を試してみましょう！

要件​

  • Node.js バージョン 18.0 以上 (node -v を実行して確認できます)。単一のマシンに複数の Node バージョンをインストールする場合は、nvm を使用できます。
    • Node.js のインストール時に、依存関係に関連するすべてのチェックボックスをオンにすることをお勧めします。

プロジェクトWebサイトの足場を作る​

Docusaurus をインストールする最も簡単な方法は、Docusaurus Web サイトのスケルトンを足場にするのに役立つコマンドラインツールを使用することです。このコマンドは、新しい空のリポジトリ内または既存のリポジトリ内の任意の場所で実行でき、足場となるファイルを含む新しいディレクトリが作成されます。

npx create-docusaurus@latest my-website classic

classic テンプレートを使用すると、すぐに開始でき、Docusaurus 1 に見られる機能が含まれているため、お勧めします。classic テンプレートには、標準ドキュメント、ブログ、カスタムページ、および CSS フレームワーク (ダークモードサポート付き) を含む @docusaurus/preset-classic が含まれています。classic テンプレートを使用すると、非常に迅速に立ち上げて実行でき、Docusaurus に慣れてきたら、後でカスタマイズできます。

--typescript フラグを渡すことで、テンプレートの TypeScript バリアントを使用することもできます。詳細については、TypeScript サポート を参照してください。

npx create-docusaurus@latest my-website classic --typescript
Meta専用

Meta オープンソースプロジェクト用に新しい Docusaurus Web サイトを設定する場合は、内部リポジトリ内でこのコマンドを実行してください。便利な Meta 固有のデフォルト設定が付属しています。

scarf static-docs-bootstrap
代替インストールコマンド

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

npm init docusaurus

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

プロジェクト構造​

classic テンプレートを選択し、サイトに 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 コンポーネントなどのドキュメント以外のファイルです。ドキュメント以外のファイルをここに厳密に配置する必要はありませんが、集中的なディレクトリの下に配置すると、linting/処理が必要な場合に指定しやすくなります。
    • /src/pages - このディレクトリ内の任意の JSX/TSX/MDX ファイルは、Web ページに変換されます。詳細については、ページガイド をご覧ください。
  • /static/ - 静的ディレクトリ。ここにあるすべてのコンテンツは、最終的な build ディレクトリのルートにコピーされます。
  • /docusaurus.config.js - サイト設定を含む設定ファイル。これは、Docusaurus v1 の siteConfig.js と同等です。
  • /package.json - Docusaurus Web サイトは React アプリです。任意の npm パッケージをインストールして使用できます。
  • /sidebars.js - ドキュメントで使用され、サイドバー内のドキュメントの順序を指定します。

モノレポ​

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

my-monorepo
├── package-a # Another package, your actual project
│   ├── src
│   └── package.json # Package A's dependencies
├── website   # Docusaurus root
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies

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

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

モノレポの詳細については、Yarn ドキュメント (Yarn はモノレポを設定する唯一の方法ではありませんが、一般的な解決策です) をお読みください。または、現実世界の例として Docusaurus と Jest を確認してください。

開発サーバーの実行​

ファイルを編集するときの変更をプレビューするには、Web サイトを提供し、最新の変更を反映するローカル開発サーバーを実行できます。

cd my-website
npm run start

デフォルトでは、ブラウザウィンドウが http://localhost:3000 で開きます。

おめでとうございます！最初の Docusaurus サイトを作成しました！サイトを閲覧して、利用可能なものを確認してください。

ビルド​

Docusaurus は最新の静的 Web サイトジェネレーターであるため、Web サイトを静的コンテンツのディレクトリにビルドして、Web サーバーに配置して表示できるようにする必要があります。Web サイトをビルドするには

npm run build

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

Docusaurus バージョンの更新​

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

package.json
{
  "dependencies": {
    "@docusaurus/core": "3.5.2",
    "@docusaurus/preset-classic": "3.5.2",
    // ...
  }
}

次に、package.json を含むディレクトリで、パッケージマネージャーのインストールコマンドを実行します。

npm install

更新が正常に完了したことを確認するには、次を実行します。

npx docusaurus --version

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

または、Yarn を使用している場合は、次のように実行できます。

yarn add @docusaurus/core @docusaurus/preset-classic
ヒント

@canary npm dist タグを使用して、Docusaurus の新しい未リリース機能を使用します

問題？​

Stack Overflow、GitHub リポジトリ、Discord サーバー、または Twitter でお問い合わせください。