Docusaurus を Astro Starlight に移行

Docusaurus から Astro Starlight に移行する理由

Docusaurus は React ドキュメントエコシステムに大きく貢献してきました。チームはバージョニング、検索、MDX サポートを備えたドキュメントサイトを素早くセットアップできました。しかし、すべての訪問者にフル React ランタイムを配信しており、その重さはすべての Lighthouse 監査に反映されます。

Astro Starlight はドキュメント用に特別に構築されています。デフォルトで静的 HTML をレンダリングし、明示的にオプトインしない限りゼロ JavaScript を配信し、組み込みの検索、サイドバーナビゲーション、多言語対応がボックスから出ています。MDX ファイルは直接転送できます。Astro チーム自体は移行パスをよくドキュメント化しています。

Docusaurus サイトが モバイルで遅く感じる場合、ドキュメントが増えるにつれてビルド時間が増加する場合、または静的コンテンツであるべき React のハイドレーション問題に疲れている場合 — Starlight はこれらすべてを修正します。

Docusaurus のスケール時の本当の問題

クライアント側 JavaScript のオーバーヘッド

Docusaurus は React をブラウザに配信します。すべてのページロードには React ランタイム、React DOM、クライアント側ルーティングレイヤーが含まれます。99% のページが静的テキストとコードブロックであるドキュメントサイトの場合、これは不要な重みです。モバイル Lighthouse スコアは通常 45-65 の間に落ち着きます。

ビルドパフォーマンスの低下

ドキュメントコレクションが数百ページを超えると、Docusaurus のビルドが顕著に遅くなります。Webpack バンドルはそれを悪化させます。500 ページ以上のドキュメントを持つチームは 5 分を超えるビルド時間を報告しており、これは CI/CD フィードバックループを壊します。

プラグインエコシステムのロック

Docusaurus プラグインはその内部アーキテクチャに密結合しています。カスタム remark プラグインが必要ですか？それらは機能しますが、構成層は複雑さを追加します。検索プロバイダーを交換したいですか？Docusaurus のプリセットシステム内で作業していて、可能な範囲を制限しています。

サイドバー構成の硬直性

Docusaurus サイドバー構成は category、items、type フィールドを含む特定の JSON/JS スキーマを使用します。機能しますが、深いネストを伴う大規模なドキュメントツリーの場合、構成は扱いづらくなります。セクションを並べ替えるには、構成ファイルを編集するのではなく、ファイルを移動します。

React コンポーネント依存関係

Docusaurus のカスタムコンポーネントはクライアント上でハイドレートする React コンポーネントです。対話型の例、タブ付きコンテンツ、またはカスタム警告を構築している場合、相互作用が最小限の場合でも、すべて React ハイドレーションコストを負担します。

Astro Starlight が提供するもの

デフォルトでゼロ JS

Starlight は純粋な静的 HTML と CSS を生成します。明示的に対話型アイランドを追加しない限り、フレームワークランタイムはブラウザに配信されません。ドキュメントページは 3G 接続で 200 ミリ秒以内に読み込まれます。Lighthouse スコアは一貫して 95-100 に達します。

MDX 互換性

Starlight にはデフォルトで Astro の MDX 統合が含まれています。既存の .mdx ファイルはすぐに機能します。フロントマターフィールドはクリーンにマップされます — title、description、sidebar_label はすべて Starlight に相当します。Remark と rehype プラグインは変更なしで適用されます。

組み込み Pagefind 検索

Starlight には、構築された HTML にインデックスを付けてブラウザ内で完全に実行される静的検索エンジン Pagefind が付属しています。外部サービス、API キー、Algolia クロール遅延はありません。検索はオフラインで機能し、バンドルに約 10KB を追加します。特に Algolia が必要なチームの場合、Starlight 用の公式プラグインがあります。

ファイルベースのサイドバー生成

Starlight はファイル構造からサイドバーを自動生成できます。MDX ファイルをフォルダーにドロップすると、サイドバーに表示されます。明示的な構成でまだオーバーライドできますが、デフォルトの動作はほとんどのサイドバー構成メンテナンスを削除します。

タイプセーフティを備えたコンテンツコレクション

Starlight は Astro のコンテンツコレクションを使用し、Zod スキーマに対してビルド時にフロントマターを検証します。フロントマターフィールドの誤植はデプロイ前に検出され、ユーザーに検出されません。

当社の移行プロセス

フェーズ 1: 監査と計画

Docusaurus サイトのインベントリを開始します — ページ数、カスタムコンポーネント、プラグイン使用状況、サイドバー構造、バージョニングセットアップ、カスタムテーマ。すべての Docusaurus 機能を Starlight 相当物にマップし、カスタムソリューションが必要なギャップをフラグします。

フェーズ 2: Starlight スキャフォルディング

yarn create astro --template starlight を使用して新しい Starlight プロジェクトをスピンアップし、既存サイトの構造と一致するように構成します。コンテンツコレクションをセットアップし、astro.config.mjs を構成し、現在の URL 構造をミラーリングするフォルダーヒエラルキーを確立します。

フェーズ 3: コンテンツ移行

MDX ファイルは最小限の変更で転送されます。以下を処理します:

• フロントマターのリマッピング: sidebar_position、sidebar_label、slug のような Docusaurus 固有フィールドは Starlight のフロントマタースキーマに変換されます
• インポートステートメントの更新: コンポーネントインポートは Docusaurus パスから Astro コンポーネントパスに変更されます
• 警告構文: Docusaurus は :::note 構文を使用します。Starlight は <Aside> コンポーネントまたは独自の警告構文を使用します
• タブコンポーネント: Docusaurus からの <Tabs> と <TabItem> は Starlight の組み込みタブコンポーネントに置き換えられます

フェーズ 4: サイドバー構成のリマッピング

category/items パターンを使用する Docusaurus サイドバー構成は Starlight のサイドバー構成形式に変換されます。可能な限り、ファイル構造で駆動されるサイドバーを自動生成することに切り替え、構成メンテナンスをゼロに削減します。

// Docusaurus sidebars.js
module.exports = {
  docs: [
    { type: 'category', label: 'Getting Started', items: ['intro', 'installation'] },
  ],
};

// Starlight astro.config.mjs
starlight({
  sidebar: [
    { label: 'Getting Started', autogenerate: { directory: 'getting-started' } },
  ],
})

フェーズ 5: プラグインと統合マッピング

Docusaurus プラグインを Astro 統合に置き換えます:

• @docusaurus/plugin-google-gtag → Astro の @astrojs/partytown とインライン gtag
• @docusaurus/plugin-sitemap → @astrojs/sitemap
• Algolia DocSearch → Pagefind（組み込み）または starlight-docsearch プラグイン
• @docusaurus/plugin-client-redirects → Astro 構成のリダイレクトまたは astro-redirect
• カスタム remark/rehype プラグイン → 直接転送、同じプラグインエコシステム

フェーズ 6: 検索移行

Algolia DocSearch を使用している場合、デフォルトで Pagefind に移行します。Pagefind はビルド時にインデックスを付け、外部サービスは不要で、あいまい一致によって即座検索を実現します。チームが特に Algolia を必要とする場合 — 分析や AI を活用した回答のため — 代わりに公式の starlight-algolia プラグインを構成します。

フェーズ 7: QA とローンチ

古いサイトと新しいサイト間の完全クロール比較を実行し、すべての URL が解決されることを確認し、検索機能をテストし、モバイルレンダリングを検証し、Lighthouse スコアが目標を満たしていることを確認します。

SEO 保存戦略

ドキュメントサイトは検索当局を蓄積しています。私たちはそのすべてを保護します:

• URL パリティ: 既存の URL 構造と完全に一致させます。Docusaurus が /docs/getting-started を提供した場合、Starlight は同じパスを提供します
• 301 リダイレクト: URL を変更する必要がある場合、Vercel または Cloudflare でサーバーレベルのリダイレクトを構成します
• 正規タグ: すべてのページは適切な正規 URL を取得します
• サイトマップ生成: @astrojs/sitemap は Search Console に送信される更新されたサイトマップを生成します
• メタ保存: タイトルタグ、メタ説明、Open Graph タグは既存のフロントマターから転送されます
• 構造化データ: 該当する場合、ドキュメント固有の JSON-LD を追加します

タイムラインと価格

ほとんどの Docusaurus から Starlight への移行は、サイトの複雑さに応じて 1～3 週間 で完了します:

• 小規模サイト（50 ページ未満、最小限のカスタムコンポーネント）: 1 週間、$3,000 から開始
• 中規模サイト（50～200 ページ、カスタムコンポーネント、バージョニング）: 2 週間、$6,000 から開始
• 大規模サイト（200 ページ以上、大規模なカスタマイズ、複数のロケール）: 3 週間以上、$10,000 から開始

すべてのプロジェクトは、特定の Docusaurus セットアップを評価し、正確なスコープとタイムラインを提供する無料の移行監査から開始されます。