CLI

Docusaurus は Web サイトの生成、サーブ、デプロイメントに役立つスクリプトのセットを提供しています。

Web サイトがブートストラップされると、Web サイトのソースにはパッケージマネージャーで呼び出すことができる Docusaurus スクリプトが含まれます。

package.json

{
  // ...
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy",
    "clear": "docusaurus clear",
    "serve": "docusaurus serve",
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids"
  }
}

Docusaurus CLI コマンド

Docusaurus CLI コマンドとその使用方法を以下に示します。

docusaurus start [siteDir]

Webpack Dev Server でローカルにサイトのプレビューをビルドして配信します。

オプション

名称	デフォルト	説明
--port	3000	開発用サーバーのポートを指定します。
--host	localhost	使用するホストを指定します。たとえば、サーバーを外部からアクセス可能にする場合は、--host 0.0.0.0 を使用できます。
--locale		使用するサイトのロケールを指定します。
--hot-only	false	Hot Module Replacement を有効にして、ビルドが失敗した場合の代替手段としてページを更新せずにファイルの自動リロードを行います。詳細 こちら。
--no-open	false	ページをブラウザで自動的に開かないでください。
--config	未定義	Docusaurus 設定ファイルへのパス。デフォルトは [siteDir]/docusaurus.config.js です。
--poll [optionalIntervalMs]	false	ウォッチングが機能しない環境の代替手段として、ライブリロードを待機するのではなくファイルのポーリングを使用します。詳細 こちら。
--no-minify	false	JS/CSS バンドルを最小化せずに Web サイトを構築します。

情報

一部の機能 (たとえば、アンカーリンク) は開発では動作しないことに注意してください。機能は本番環境では想定どおりに動作します。

ネットワーク上での開発

リモートサーバーまたは VM (例: GitHub Codespaces) からポート 3000 を転送する場合は、0.0.0.0 で dev server を実行してローカル IP でリッスンすることができます。

npm

npm run start -- --host 0.0.0.0

Yarn

yarn run start --host 0.0.0.0

pnpm

pnpm run start --host 0.0.0.0

HTTPS の有効化

証明書を取得する方法はいくつかあります。例として、mkcert を使用します。

1. localhost.pem + localhost-key.pem を生成するには、mkcert localhost を実行します。

2. トラストストアに証明書をインストールし、ブラウザを再起動するには、mkcert -install を実行します。

3. Docusaurus HTTPS 環境変数を使用してアプリケーションを開始します。

HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start

4. https://localhost:3000/ を開きます。

docusaurus build [siteDir]

本番環境用にサイトをコンパイルします。

オプション

名称	デフォルト	説明
--dev		完全な React エラーメッセージを含む dev モードで Web サイトを構築します。
--bundle-analyzer	false	webpack バンドル アナライザー でバンドルを分析します。
--out-dir	ビルド	現在のワークスペースを基準とした新しい出力ディレクトリの絶対パス。
--config	未定義	Docusaurus 設定ファイルへのパス。デフォルトは [siteDir]/docusaurus.config.js です。
--locale		指定した言語でサイトを構築します。指定しないと、既知の言語はすべて構築されます。
--no-minify	false	JS/CSS バンドルを最小化せずに Web サイトを構築します。

情報

CSS バンドルの高度な最小化には、高度な cssnano プリセット (いくつかの追加的な PostCSS プラグインと併せて) と、clean-css のレベル 2 最適化 を使用します。この高度な CSS 最小化の結果、破損した CSS が見つかった場合は、環境変数 USE_SIMPLE_CSS_MINIFIER=true でウェブサイトを構築して、既定の cssnano プリセット で CSS を最小化します。**CSS 最小化バグが発生した場合は、問題を記入してください。**

環境変数 SKIP_HTML_MINIFICATION=true で HTML の最小化を省略できます。

docusaurus swizzle [themeName] [componentName] [siteDir]

Swizzle でカスタマイズするテーマコンポーネント。

npm

npm run swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
npm run swizzle @docusaurus/theme-classic Footer -- --eject

Yarn

yarn swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
yarn swizzle @docusaurus/theme-classic Footer --eject

pnpm

pnpm run swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
pnpm run swizzle @docusaurus/theme-classic Footer --eject

swizzle CLI はインタラクティブであり、swizzle プロセス全体をガイドします。

オプション

名称	説明
themeName	swizzle 元のテーマの名前。
componentName	swizzle するテーマコンポーネントの名前。
--list	スウィズリングに利用可能なコンポーネントを表示
--eject	取り外しテーマコンポーネント
--wrap	ラップテーマコンポーネント
--danger	内部の提供変更による差分のないコンポーネントを、ただちにスウィズリング
--typescript	TypeScript バリアントコンポーネントをスウィズリング
--config	docusaurus config ファイルへのパス。既定では [siteDir]/docusaurus.config.js

警告

内部の再構築 duetoによる重大な変更のリスクが高い、非推奨コンポーネント

docusaurus deploy [siteDir]

サイトを GitHub Pages でデプロイします。詳細についてはデプロイメントのドキュメントを参照してください。

オプション

名称	デフォルト	説明
--locale		指定されたロケールでサイトをデプロイします。指定しない場合、すべての既知のロケールがデプロイされます。
--out-dir	ビルド	現在のワークスペースを基準とした新しい出力ディレクトリの絶対パス。
--skip-build	false	構築せずにWebサイトをデプロイします。これはカスタムデプロイスクリプトを使用する場合に便利です。
--target-dir	.	デプロイするターゲットディレクトリへのパス。
--config	未定義	Docusaurus 設定ファイルへのパス。デフォルトは [siteDir]/docusaurus.config.js です。

docusaurus serve [siteDir]

ローカルでビルドされたWebサイトを提供します。

名称	デフォルト	説明
--port	3000	指定されたポートを使用
--dir	ビルド	現在のワークスペースに関連する出力ディレクトリの完全なパス
--build	false	提供する前にWebサイトを構築します
--config	未定義	Docusaurus 設定ファイルへのパス。デフォルトは [siteDir]/docusaurus.config.js です。
--host	localhost	使用するホストを指定します。たとえば、サーバーを外部からアクセス可能にする場合は、--host 0.0.0.0 を使用できます。
--no-open	ローカルではfalse、CIではtrue	サーバーの場所にブラウザのウィンドウを開きません。

docusaurus clear [siteDir]

Docusaurusサイトの生成されたアセット、キャッシュ、ビルドアティファクトをクリアします。

バグを報告する前、バージョンのアップグレード後、またはDocusaurusサイトで問題が発生したときにこのコマンドを実行することをお勧めします。

docusaurus write-translations [siteDir]

翻訳する必要があるJSON翻訳ファイルを記述します。

既定では、ファイルはwebsite/i18n/<defaultLocale>/...に書き込まれます。

名称	デフォルト	説明
--locale	<defaultLocale>	翻訳したJSONファイルを書き込むローカルフォルダを定義します
--override	false	既存の翻訳メッセージを上書きします。
--config	未定義	Docusaurus 設定ファイルへのパス。デフォルトは [siteDir]/docusaurus.config.js です。
--messagePrefix	''	翻訳されていない文字列を強調表示するために、各翻訳メッセージにプレフィックスを追加できます

docusaurus write-heading-ids [siteDir] [files]

明示的な見出しIDをサイトのMarkdownドキュメントに追加します。

名称	デフォルト	説明
files	プラグインで使用されるすべてのMDファイル	見出しのIDを書き込むファイル。
--maintain-case	false	見出しのケースを維持します。それ以外はすべて小文字にします。
--overwrite	false	既存の見出し ID を上書きする。