--- title: "Docusaurusとは：ドキュメントサイトの構築手順とバージョン管理・多言語・検索の設定【3.10対応】" url: "https://www.issoh.co.jp/tech/details/18707/" published: 2026-10-21 updated: 2026-10-21 categories: ["開発"] publisher: "株式会社一創" --- # Docusaurusとは：ドキュメントサイトの構築手順とバージョン管理・多言語・検索の設定【3.10対応】 Docusaurusは、Markdownで書いた原稿からドキュメントサイトとブログを生成する、Meta製のオープンソースツールです。npm registryで2026年10月21日に確認した`@docusaurus/core`のlatestは3.10.2（2026年7月10日公開）で、ライセンスはMIT、動作要件はNode.js 20.0以上でした。この記事では、Docusaurusの立ち位置と新規作成からビルドまでの手順、バージョニングと国際化（i18n）の仕組み、検索の付け方、3.10系とv4に向けた準備、VitePressやMkDocsとの使い分けまでを、公式ドキュメントの記述をもとに実装目線で整理します。 ## まとめ：Docusaurusを選んでよい条件とVitePress・MkDocsへ回す線引き 結論から書きます。製品の版ごとに説明書を出し分けたい。英語と日本語など複数言語で同じ構成のサイトを持ちたい。この2つのどちらかが要件にあるなら、Docusaurusは第一候補です。バージョンの切り出しはコマンド1本、翻訳ファイルの置き場所も規約で決まっているため、作り込まずに運用へ乗せられます。 反対に、1言語・1版で数十ページの社内マニュアルを作るだけなら過剰です。React製のSPAとしてビルドされるぶん、依存パッケージもビルド時間も重くなります。Vueで組んでいる現場ならVitePress、Pythonの開発チームならMkDocsのほうが保守の負担は軽くなります。もう1つ見落としやすいのが検索で、Docusaurusは標準では検索が動きません。AlgoliaのDocSearchへ申請するか、コミュニティ製のプラグインを入れる作業が別に要ります。 ## Docusaurusの定義｜Reactで動くMeta製のドキュメント特化型静的サイト生成 まず、Docusaurusが何を自動化し、何を利用者に任せているのかを押さえます。 ### MDXの原稿をReactのSPAとして静的出力する仕組みと出力先 Docusaurusは、`docs/`と`blog/`に置いたMarkdownやMDXを読み込み、Reactのコンポーネントとして描画したうえで、`build`ディレクトリへHTMLとJavaScriptを書き出します。出力はページごとのHTMLを持つ静的ファイルなので、表示自体にサーバー処理は要りません。初回表示の後はSPAとして画面を切り替えるため、ページ遷移はページ全体の再読み込みを伴わない動きになります。 MDXはMarkdownの中にJSXを書ける形式です。注意書きの枠やタブ切り替えをReactコンポーネントとして原稿に埋め込めるのが、Markdownだけの生成ツールとの差になります。静的サイト生成という方式そのものの利点と制約は、[静的サイトジェネレーターの仕組みと企業サイトでの採用判断](https://www.issoh.co.jp/column/details/17699/)で整理しています。 ### docs・blog・pagesの3プラグインで組むclassicプリセットの範囲 公式の[インストール手順](https://docusaurus.io/docs/installation)が推奨する`classic`テンプレートは、ドキュメント、ブログ、独立ページの3つのプラグインとテーマをひとまとめにしたプリセットです。`src/pages/`に置いたJSX・TSX・MDXはそのままページになり、`static/`の中身は`build`の直下へ複写されます。 ドキュメント部分の左メニューは`sidebars.js`で順序を決めます。ディレクトリ構成から自動生成させることもできるので、最初は自動生成で始め、章立てが固まった段階で手書きへ切り替える進め方が無理のない順番です。 ## create-docusaurusでの新規作成からローカル起動・ビルドまでの手順 ここからは手を動かす部分です。Node.jsは20.0以上が要件で、`node -v`で先に確認しておきます。npm registryの記録では、3.8.1までは`engines`が`node >=18.0`、2025年9月25日公開の3.9.0から`node >=20.0`に上がっています。 ### npx create-docusaurusで雛形を作り3000番で確認する4ステップ 公式手順どおりに進めると、作成から本番用ビルドまでは次のコマンドで済みます。TypeScriptで設定を書きたい場合は、作成時に`--typescript`を付けます。 ``` # 1. classicテンプレートで雛形を作る（TypeScript版） npx create-docusaurus@latest my-website classic --typescript # 2. 開発サーバーを起動する（http://localhost:3000 が開く） cd my-website npm run start # 3. 本番用にビルドする（成果物は build/ に出力される） npm run build # 4. ビルド結果をローカルで確認する npm run serve ``` 開発サーバーは原稿の保存を検知して画面を更新します。一方、`npm run serve`はビルド済みの`build/`を配信するだけなので、原稿を直した後は`npm run build`からのやり直しが必要です。リンク切れはビルド時に検出されるため、公開前の確認は必ず`build`で行います。 ### 公開先のurl・baseUrl・trailingSlashを決める設定条件 公開先が決まったら、設定ファイルの`url`と`baseUrl`を最初に埋めます。[デプロイのドキュメント](https://docusaurus.io/docs/deployment)によると、`https://my-org.com/my-project/`に置くなら`url`は`https://my-org.com`、`baseUrl`は末尾スラッシュ付きの`/my-project/`です。ここを誤ると、CSSや画像が404になった画面が出ます。 GitHub Pagesへ出す場合は`organizationName`と`projectName`を加え、`GIT_USER= yarn deploy`で`gh-pages`ブランチへ送ります。同じページによると、GitHub PagesがURLの末尾にスラッシュを足すため`trailingSlash`を`true`か`false`で明示するのが推奨設定です。未指定のままだと、サイト内のURLとGitHub Pagesが返すURLの末尾がずれます。 ## docs:versionで切るバージョニングの仕組みと10版未満に抑える運用 Docusaurusを選ぶ理由として最も大きいのがバージョニングです。製品の1.x系と2.x系を並べて公開し、利用者に自分の版の説明書を読ませる仕組みが最初から入っています。 ### versioned\_docsとversions.jsonが生成される版の切り出し手順 [バージョニングのドキュメント](https://docusaurus.io/docs/versioning)では、`npm run docusaurus docs:version 1.1.0`を実行すると3つの処理が走ると説明されています。`docs/`の中身を`versioned_docs/version-1.1.0/`へ複写し、その時点のサイドバー設定を`versioned_sidebars/version-1.1.0-sidebars.json`に保存し、`versions.json`に版番号を追記するという流れです。 切り出した後も、`docs/`は「次の版」の原稿として編集を続けます。リリースの直前に`docs:version`を打ち、その版の説明を凍結する。この順番を手順書に書いておかないと、未リリースの機能説明が公開中の版へ混ざります。 ### 版を増やしすぎるとビルドが重くなる失敗パターンとonlyIncludeVersions 版の切り出しは全文の複写なので、版の数だけページ数が増えます。公式ドキュメントで示されている版の数の目安は、10未満です。パッチ版ごとに`docs:version`を打つ運用は、この上限をすぐに超えるため、避けるべき運用です。版を切るのは、利用者の手順が変わるメジャー版やマイナー版だけで足ります。 古い版を消さずにビルド対象だけ絞りたいときは、ドキュメントプラグインの`onlyIncludeVersions`で配信する版の部分集合を指定します。`/docs`の既定表示をどの版にするかを決める設定項目は`lastVersion`です。プレビュー環境では最新の2版だけをビルドし、本番は全版を出すという使い分けがこの2項目でできます。 ## i18n設定とwrite-translationsで進める多言語サイトの翻訳手順 多言語化もDocusaurusの得意分野です。ただし翻訳そのものは人か翻訳サービスの仕事で、Docusaurusが受け持つのはファイルの置き場所とビルドの切り分けです。 ### defaultLocaleとlocalesの設定と翻訳ファイルを置くi18nディレクトリ [i18nのチュートリアル](https://docusaurus.io/docs/i18n/tutorial)に沿うと、設定ファイルの`i18n`に`defaultLocale`と`locales`を書き、`npm run write-translations -- --locale ja`でReactコード内の文言を`code.json`へ抜き出します。この処理はソースコードを静的解析して翻訳対象の呼び出しを集めるものです。 ドキュメント本文の翻訳は、`docs/`のMarkdownを`i18n/ja/docusaurus-plugin-content-docs/current/`へ複写して書き換えます。バージョニングと組み合わせると、版ごと・言語ごとにファイルが掛け算で増える点は、事前の見積もりで考慮すべき事項です。国際化とローカライズの用語の違いは[i18nとl10nの違いを整理した記事](https://www.issoh.co.jp/tech/details/8884/)が参考になります。 ### 開発サーバーは1言語ずつしか起動できない制約と多言語版の確認手順 チュートリアルには、すべてのロケールを同時に起動することはできないと明記されています。各ロケールが独立したSPAとしてビルドされるためです。日本語版を確認するには`npm run start -- --locale ja`で起動し直し、`http://localhost:3000/ja/`を開きます。 言語切り替えのメニューまで含めて確かめたいときは、`npm run build`で全言語をビルドしてから`npm run serve`で開きます。開発サーバーで別の言語のページが開けないのは1言語ずつ起動する仕様によるもので、設定の誤りではありません。チーム内で共有しておくと無駄な調査を減らせます。 ## 検索の付け方｜Algolia・Typesense・ローカル検索の選び分けと設定 Docusaurusの[検索のドキュメント](https://docusaurus.io/docs/search)に、最初から動く組み込み検索は書かれていません。挙がっている選択肢は、公式対応のAlgolia DocSearch、コミュニティ保守のTypesenseとローカル検索プラグイン、そして`SearchBar`コンポーネントを差し替える自作の4つです。 ### Algolia DocSearchの申請条件とthemeConfigに書く設定値 DocSearchは、開発者向けのドキュメントと技術ブログであれば無料で使えると案内されています。ただし利用には申請が要り、社内向けの非公開サイトは無料枠の対象になりません。採用された後は、Algoliaから受け取った値を設定ファイルに書くだけで検索窓が出ます。 ``` // docusaurus.config.ts（抜粋） export default { url: 'https://docs.example.co.jp', baseUrl: '/', trailingSlash: false, i18n: { defaultLocale: 'ja', locales: ['ja', 'en'], }, themeConfig: { algolia: { appId: 'YOUR_APP_ID', apiKey: 'YOUR_SEARCH_ONLY_API_KEY', // 検索専用の公開キー indexName: 'YOUR_INDEX_NAME', contextualSearch: true, // 表示中の言語と版に絞って検索する }, }, }; ``` `apiKey`は検索専用の公開キーで、公式もリポジトリにコミットしてよいと書いています。管理用キーを入れる誤りだけは避けます。`contextualSearch`は既定で有効で、表示中の言語と版に合う結果だけを返すため、バージョニングや多言語化と組み合わせても検索結果が混ざりません。 ### 非公開の社内ドキュメントでDocSearchを使えない場合の代替 社内ポータルや閉域網のマニュアルでは、DocSearchの無料枠に乗りません。このときの第1候補はローカル検索プラグインで、ビルド時に索引を作ってブラウザ内で検索します。外部サービスへの申請も通信も不要な点が利点です。公式も、索引が小さいサイト向けの選択肢として位置付けています。 ページ数が数千規模に増えたら、TypesenseやAlgoliaの有償プランで自前の検索基盤を組みます。検索サービス自体の比較は[CloudSearch・OpenSearch・Algolia・Kendraを比べた検索サービスの選び方](https://www.issoh.co.jp/column/details/2687/)が判断材料になります。 ## 3.10系の現在地とv4に向けたfuture.v4フラグ・Node要件の確認 いま入れるなら、v3系の最終版とv4の準備状況を知っておく必要があります。 ### 3.10がv3系の最終リリースとされた理由とfuture.v4フラグ [3.10のリリースブログ](https://docusaurus.io/blog/releases/3.10)は、このリリースをv3.x系の最後とし、v4への準備を助けるものと位置付けています。v4で入る破壊的変更は`future.v4: true`でまとめて先取りでき、個別には`localStorage`のキーにサイト単位の名前空間を付ける`siteStorageNamespacing`、ビルド基盤の切り替えを既定にする`fasterByDefault`、MDX v1互換を外す`mdx1CompatDisabledByDefault`の3項目です。 同じブログで、Rspack・SWC・LightningCSSを使うビルド基盤「Docusaurus Faster」が安定版になり、設定名が`experimental_faster`から`faster`へ変わったと告知されています。v4ではReact 18の対応を外すとも明記されました。3.10.2の`peerDependencies`はReact 18と19の両方を許していますが、新規に作るならReact 19で始めておくのが移行の手戻りを減らす選び方です。 ### v4 canaryのNode要件から逆算するCIイメージの更新計画 npm registryの`canary`タグは2026年10月21日時点で`4.0.0-canary-6985`（10月16日公開）で、`engines`欄は`node >=24.21`でした。latestの`node >=20.0`から大きく上がっています。canaryの値は正式版で変わる可能性がありますが、v4への移行がパッケージの更新だけでは済まない可能性は高いと見ておくべきです。 実務での判断は単純です。新規サイトは3.10.2で作り、`future.faster`を有効にしてビルドを確かめておく。CIとDockerイメージのNodeをv24系へ上げる予定を先に立てる。v4の正式版が出た時点で`future.v4: true`を試し、警告を潰してから上げる。修正内容の詳細は[GitHubの3.10.2リリースノート](https://github.com/facebook/docusaurus/releases/tag/v3.10.2)で追えます。 ## VitePress・MkDocsとの違いと受託開発で採用してよい条件・見送る場面 同じ「Markdownからドキュメントサイトを作る」ツールでも、土台の言語とフレームワークが違えば、保守できる人の顔ぶれが変わります。並べたうえで、採用の線を引きます。 ### Docusaurus・VitePress・MkDocsの土台・多版対応・保守者の比較 | ツール | 土台 | 版の出し分け | 向いている保守者 | | ---------- | ------------- | -------- | ------------- | | Docusaurus | React・Node.js | 標準機能で対応 | Reactを書けるチーム | | VitePress | Vue・Vite | 標準機能には無い | Vueを書けるチーム | | MkDocs | Python | 外部ツールで対応 | Pythonを書けるチーム | 3者の差は機能の多寡より、カスタマイズするときに書く言語にあります。DocusaurusはReactコンポーネント、VitePressはVueコンポーネント、MkDocsはテーマとPythonの拡張がカスタマイズの対象です。自前でビルドせず配信基盤ごと任せるホスト型の選択肢は[Mintlifyとは：docs.jsonとOpenAPIでAPIドキュメントを公開する手順と料金・注意点](https://www.issoh.co.jp/tech/details/18709/)で比べています。MkDocsの設定と日本語検索の扱いは[Material for MkDocsの設定とGitHub Pages公開の手順](https://www.issoh.co.jp/tech/details/3675/)にまとめています。 ### 製品ドキュメントでDocusaurusを採用してよい条件と見送る3つの場面 採用してよいのは、版の出し分けか多言語のどちらかが要件にあり、Reactを触れる担当者が保守に残るときです。この条件が揃えば、`docs:version`と`i18n`の規約に乗るだけで、自作すると数週間かかる仕組みが手に入ります。 見送る場面も具体的に書きます。第一に、1言語・1版の社内手順書。依存パッケージとビルド時間の負担に見合いません。第二に、原稿を書く人がGitを使えない組織。Markdownをリポジトリへコミットする前提を崩すと、更新が止まります。第三に、閉域網で全文検索が必須なのに、検索の自前構築に工数を割けない案件。この3つでは、既存のWikiやヘッドレスCMSのほうが総コストは下がります。ドキュメントを書き続ける体制づくりの論点は[エンジニアがドキュメントを書かない理由と回る仕組み](https://www.issoh.co.jp/column/details/2578/)で扱っています。 ### ドキュメントサイトと技術ブログを外部に委託する際の進め方と相談先 Docusaurusを外部に作らせる場合は、着手前に3点を決めておくと引き継ぎで揉めません。どの単位で版を切るか、翻訳を誰が担うか、検索をDocSearchで申請するか自前で持つか、の3点です。どれも後から変えると、URLの構造か運用の手順が変わります。 技術ブログやお知らせも同じサイトで出す、デザインを自社ブランドに合わせる、といった要件が重なると、設定の調整だけでは収まりません。当社では記事サイトや情報発信サイトの構築を[オウンドメディアサイト制作](https://www.issoh.co.jp/service/web/media/)として受託しており、ツール選定から公開後の運用設計まで含めて相談いただけます。 ## よくある質問 Docusaurusの導入検討でよく挙がる論点を、公式ドキュメントとnpm registryの記録をもとに整理します。 ### Docusaurusを使うのにReactの知識は必要ですか？ Markdownで原稿を書いて公開するだけなら、Reactの知識は要りません。`classic`テンプレートのまま、`docs/`と`blog/`にファイルを置けばサイトになります。トップページを作り込む、テーマの部品を差し替える、といった段階でReactを書ける人が要ります。 ### Docusaurusは無料で商用利用できますか？ できます。[npm registryの@docusaurus/core](https://www.npmjs.com/package/@docusaurus/core)に記載されたライセンスはMITで、商用サイトでの利用や改変に制約はありません。費用が発生しうるのはツールの外側で、公開先のホスティングや、DocSearchの無料枠に当てはまらない場合の検索サービス料金が該当します。 ### Docusaurusで作ったサイトはどこに公開できますか？ `npm run build`で出力される`build/`は静的ファイルなので、静的ホスティングならどこでも置けます。公式のデプロイ手順はGitHub Pages向けの`deploy`コマンドを用意しており、NetlifyやVercelなどのサービスも対応先です。AWSで自社の管理下に置くなら、[CloudFrontとS3で静的サイトを公開する手順](https://www.issoh.co.jp/tech/details/18064/)がそのまま使えます。 ### DocusaurusとVitePressはどちらを選ぶべきですか？ 判断軸は、製品の版を出し分ける必要があるかと、チームが書けるフレームワークです。版の出し分けや多言語を標準機能で済ませたいならDocusaurus。Vueで開発していて、1版のドキュメントを軽く作りたいならVitePressが向きます。MDXに埋め込んだReactコンポーネントは、そのままでは移せません。 ### Docusaurus v2からv3へ上げるときに何が変わりますか？ 大きいのはMDXの版が上がったことで、v2で通っていた原稿がv3ではビルドエラーになる場合があります。3.10ではMDX v1互換の設定が残っていますが、v4で既定から外れる予定です。Node.jsも20.0以上が必要になったため、CI環境の更新も合わせて行います。v4を見据えるなら、移行の際に`future.v4`のフラグも試しておくと、二度手間を避けられます。 ## 関連記事 - [MkDocsの使い方｜Material for MkDocsの設定・日本語検索・GitHub Pages公開と2.0の注意](https://www.issoh.co.jp/tech/details/3675/) - [SSGとは？静的サイトジェネレーターの仕組みと企業サイト採用の判断基準](https://www.issoh.co.jp/column/details/17699/) - [i18n（国際化）とは？読み方・l10nとの違いとAngularでの実装手順](https://www.issoh.co.jp/tech/details/8884/) - [CloudFrontとS3で静的サイトを公開する手順：OAC・独自ドメイン・デプロイまでCLIで構築](https://www.issoh.co.jp/tech/details/18064/) - [ドキュメント化とは？エンジニアが書かない理由と開発現場で回る仕組み](https://www.issoh.co.jp/column/details/2578/) --- 出典: [Docusaurusとは：ドキュメントサイトの構築手順とバージョン管理・多言語・検索の設定【3.10対応】]()（株式会社一創）