DocusaurusからDocsbookへの移行

Docusaurusは素晴らしいですが、次の大規模な移行が行われると、製品を出荷する代わりにスプリントをその作業に費やすことになります。このガイドでは、現実的な移行経路を説明します。

私たちはDocsbookを作っています。移行が価値がない場合についてもお知らせします。

移行すべきでない時#

次の場合はこの移行をスキップしてください:

• あなたのDocusaurusサイトが重いReactコンポーネントの埋め込み（インタラクティブデモ、カスタムプラグイン）を使用している場合。Docsbookはマークダウンファーストです。
• Docusaurusを含む仕事を部分的に担う専任のドキュメントエンジニアがいる場合。そのプラットフォームは彼らの手の中で本当の強みを持っています。
• 深くカスタムされたReactテーマが必要な場合。Docsbookは色トークン、フォント、レイアウトスイッチ、ヘッダー/フッターの設定を提供しますが、完全なテーマのスウィズルは提供しません。

これらのいずれかが当てはまる場合は、Docusaurusに留まることをお勧めし、このガイドの残りを後でお読みください。

要点#

1. MDX特有の構文を標準のマークダウンに変換する
2. GitHubリポジトリにプッシュする（すでに持っているもの）
3. Docsbookを接続する
4. カスタムドメインを設定する
5. リダイレクトを移行する
6. CIパイプラインとホスティング料金を削除する

ステップ 1: MDX からマークダウンへ#

Docusaurus は MDX を使用します。これはマークダウン + JSX です。Docsbook は拡張機能を持つ標準のマークダウンを使用します。

処理が必要な 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で翻訳されます。

ステップ 2: サイドバーとナビゲーション#

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: カスタムドメイン#

PRO ($150 生涯) または PRO+ ($59/月) にはカスタムドメインが含まれます。

• 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: 古い /docs/* URL から新しい /* URL へのリダイレクトを CDN または DNS レイヤーで追加します。

ステップ 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 ワークフローファイル: これも削除します。

結果: git push から main までのすべての docs がデプロイされ、CI 分は使用されません。

得られるもの#

あなたが放棄するもの#

• ドキュメント内に埋め込まれたReactコンポーネント（他の場所にホストし、リンクを貼る）
• 完全なスウィズルテーマ制御（色/フォント/レイアウトトークンを取得）
• プラグインエコシステム（ほとんどのケースはすでに組み込まれています）

エッジケース#

Algolia DocSearch#

新しいドメインに向けてAlgolia DocSearchをDocsbookで引き続き使用できます。また、無料で含まれているDocsbookの組み込み検索を使用することもできます。

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

Docusaurusは、/でReactで構築されたカスタムランディングページを持つことがよくあります。Docsbookは、README.mdを/で提供します。マーケティングスタイルのランディングページが必要な場合は、それを別にホストし、Docsbookをdocs.yourcompany.comにポイントして、yourcompany.comではなくしてください。

バージョン管理#

Docusaurusの docs/versioned_docs/version-1.0/ パターンは直接サポートされていません。オプション：

• バージョンごとに別々のDocsbookワークスペースを使用する (docsbook.io/yourorg/yourrepo-v1)
• Gitブランチを使用し、インデックスされたブランチを切り替える
• 古いバージョンを削除する（ほとんどのチームは習慣でそれらを維持していることがわかります）

タイミング#

• OSSプロジェクト、約80ページ、最小限のMDX：2時間
• スタートアップ、約300ページ、適度なMDX：半日
• 中期段階、約1000ページ、重いMDX：1〜2日

関連文献#

• 2026年のDocusaurusとDocsbook
• コードとしてのドキュメントと管理プラットフォーム
• ドキュメントのカスタムドメインの方法

まずは移行をテストしてください: あなたのリポジトリをdocsbook.ioに貼り付けます。サイトは5秒でビルドされます。Docusaurusのパリティと一致しない場合、何も失うことはありません。