DocusaurusからDocsbookへの段階的な移行

Docusaurusは、次のメジャー移行が始まるまでは素晴らしいツールです。そして、プロダクトのリリースではなく、その対応に1スプリントを費やすことになります。このガイドでは、現実的な移行パスを順を追って説明します。

私たちはDocsbookを開発しています。また、移行する価値がない場合についてもお伝えします。

移行すべきでない場合#

次に該当する場合は、この移行を見送ってください：

DocusaurusサイトでReactコンポーネントの埋め込み（インタラクティブなデモやカスタムプラグインなど）を多用している場合。DocsbookはMarkdownを中心に構成されています。
業務の一部としてDocusaurusを担当する専任のドキュメントエンジニアがいる場合。その担当者の手にかかれば、このプラットフォームには大きな強みがあります。
高度にカスタマイズされたReactテーマが必要な場合。Docsbookで提供されるのは、カラートークン、フォント、レイアウトの切り替え、ヘッダー／フッター設定などであり、テーマ全体のスウィズル機能ではありません。

いずれかに該当する場合は、Docusaurusを使い続け、このガイドの残りの部分は後でお読みください。

要約#

MDX固有の構文を標準的なMarkdownに変換する
GitHubリポジトリにプッシュする（すでに1つあります）
Docsbookに接続する
カスタムドメインを設定する
リダイレクトを移行する
CIパイプラインとホスティング料金をなくす

ステップ1：MDX から Markdown へ#

Docusaurus は MDX（Markdown + JSX）を使用します。Docsbook は拡張機能付きの標準 Markdown を使用します。

処理が必要な MDX は 3 種類あります：

インポートとReactコンポーネント#

import Foo from '@site/src/components/Foo';
 
<Foo />

解決策:

静的なビジュアルの場合: ホストされた画像とライブデモへのリンクに置き換える
インタラクティブな要素の場合: アプリへのリンクを設定する
タブや注意書きの場合: Docsbookのネイティブブロックを使用する（以下を参照）

注意事項#

Docusaurus:

:::note Title
Content
:::

Docsbook（GitHub-flavored markdown）:

> [!NOTE]
> Content

検索と置換:

find . -name "*.mdx" -exec rename 's/\.mdx$/\.md/' {} \;
find . -name "*.md" -exec sed -i.bak -E 's/:::note/> [!NOTE]/g; s/:::tip/> [!TIP]/g; s/:::warning/> [!WARNING]/g; s/:::caution/> [!CAUTION]/g; s/:::info/> [!NOTE]/g; s/^:::$//' {} \;

タブとコードグループ#

Docsbook は標準構文でタブをサポートしています。

<Tabs>
  <Tab title="npm">npm install foo</Tab>
  <Tab title="pnpm">pnpm add foo</Tab>
</Tabs>

ほとんどの Docusaurus のタブは 1 対 1 で変換されます。

Docusaurusでは、sidebars.jsを使用してナビゲーションを定義します。Docsbookでは、フォルダー構造とフロントマターからナビゲーションを構築します。

特定の順序にしたい場合：

---
title: "Quick Start"
order: 1
---

順序を指定しない場合、Docsbookはアルファベット順に並べ替えます。明示的なグループ化が必要な場合は、ファイルを順序付きフォルダーに移動してください。

移行後は、sidebars.js、docusaurus.config.js、babel.config.js、およびsrc/ディレクトリを削除できます。

ステップ3: Docsbookを接続#

ドキュメントはすでにdocs/にあります。リポジトリを接続します:

docsbook.io → GitHubでサインイン
github.com/yourorg/yourrepoを貼り付ける
サイトはdocsbook.io/yourorg/yourrepoで公開されます

ステップ 4: カスタムドメイン#

Docsbook は自動 SSL で docs.yourcompany.com を提供します。

Docsbook ダッシュボード → 設定 → ドメイン
docs.yourcompany.com を入力
DNS を更新: CNAME docs → cname.vercel-dns.com
SSL のために 5 分待ちます

ステップ 5: URL の保持#

Docusaurus の URL は通常、次のようになります:

docs.yourcompany.com/docs/intro
docs.yourcompany.com/docs/category/guides/getting-started

Docsbook の URL はファイルパスと一致します:

docs.yourcompany.com/intro.md → docs.yourcompany.com/intro
docs.yourcompany.com/guides/getting-started.md → docs.yourcompany.com/guides/getting-started

Docusaurus に /docs/ プレフィックスがあり、同じ形式を維持したい場合:

オプション A: ローカルの docs/ フォルダーの名前を変更して、URL にプレフィックスを保持します（Docsbook は別のパスから提供されます）。

オプション B: CDN または DNS レイヤーで、古い /docs/* URL から新しい /* URL へのリダイレクトを追加します。

ステップ 6: CI/CDをやめる#

Docsbookがトラフィックを処理するようになったら:

# Files you can delete
rm -rf .docusaurus/
rm -rf build/
rm -rf node_modules/
rm docusaurus.config.js
rm sidebars.js
rm babel.config.js
rm -rf src/
rm -rf static/
# Keep docs/ — it is your source

Docusaurusのデプロイ用GitHub Actionsワークフローファイルも削除します。

結果: CIの分数を一切使わず、すべての git push で main にドキュメントがデプロイされます。

得られるもの#

	Docusaurus	Docsbook
ビルド時間	プッシュごとに30～120秒	セットアップ全体で5秒
ホスティングコスト	Vercel/Netlifyのプロティア	含まれる
AIチャット	プラグイン作業	組み込み
翻訳	ロケールごとの設定＋翻訳パイプライン	組み込み、15言語対応
メジャーバージョンの移行	18か月ごと	不要
テーマのメンテナンス	Swizzleの差分	カラートークン、メンテナンス不要

失うもの#

ドキュメント内へのReactコンポーネントの埋め込み（別の場所でホストし、リンクを追加してください）
テーマの完全なスウィズル制御（色／フォント／レイアウトのトークンを利用できます）
プラグインエコシステム（ほとんどの場合、すでに組み込まれています）

エッジケース#

Algolia DocSearch#

Docsbook では引き続き Algolia DocSearch を使用できます（新しいドメインを指定してください）。または、無料で利用できる Docsbook 内蔵の検索機能を使用してください。

カスタムランディングページ#

Docusaurusには、Reactで構築されたカスタムランディングページが/に用意されていることがよくあります。Docsbookは/でREADME.mdを提供します。マーケティング向けのランディングページが必要な場合は、それを別途ホスティングし、yourcompany.comではなくdocs.yourcompany.comを参照するようDocsbookを設定してください。

バージョン管理#

Docusaurus の docs/versioned_docs/version-1.0/ パターンは直接サポートされていません。選択肢：

バージョンごとに個別の Docsbook ワークスペースを使用する（docsbook.io/yourorg/yourrepo-v1）
Git ブランチを使用し、インデックス対象のブランチを切り替える
古いバージョンを削除する（ほとんどのチームは、習慣で維持していたことに気づきます）

所要時間#

OSSプロジェクト、約80ページ、最小限のMDX：2時間
スタートアップ、約300ページ、中程度のMDX：半日
成長段階、約1000ページ、大量のMDX：1～2日

移行を決定する前にテストしてください。同じリポジトリから2つ目のサイトを公開しても費用はかからず、読者に引き続き提供されるDocusaurusのデプロイにも何も変更はありません。結果が同等に達しなかったとしても、失うのはそれにかかった5秒だけです。

無料で始める — クレジットカード不要

次のステップ#

2026年にDocusaurusから移行すべきか？ — まだ決めていない場合の判断
2026年のDocusaurus代替：9つのプラットフォームを比較 — より広い選択肢
ドキュメント用のカスタムドメイン — この移行におけるDNSとリダイレクトの部分
Docs as codeとマネージドプラットフォームの比較 — 移行の背景にある原則

Updated Sep 3, 2026