Migrate Docusaurus to Astro Starlight

Docusaurus has served the React documentation ecosystem well. Teams could spin up docs sites with versioning, search, and MDX support pretty quickly. But it ships a full React runtime to every visitor, and that weight shows up in every Lighthouse audit.

Astro Starlight is built specifically for documentation. It renders static HTML by default, ships zero JavaScript unless you explicitly opt in, and includes built-in search, sidebar navigation, and i18n out of the box. Your MDX files transfer directly. Astro's own team keeps the migration path well-documented.

If your Docusaurus site feels sluggish on mobile, if build times keep creeping up as your docs grow, or if you're tired of fighting React hydration issues on what should be static content — Starlight fixes all of that.

從 Docusaurus 遷移的真實問題

客戶端 JavaScript 開銷

Docusaurus 向瀏覽器傳送 React。每個頁面載入都包括 React runtime、React DOM 和客戶端路由層。對於 99% 的頁面都是靜態文字和程式碼區塊的文件網站，這是無用的重量。行動 Lighthouse 分數通常因此落在 45-65 之間。

建置效能降級

當您的文件集合增長到數百頁以上時，Docusaurus 的建置速度會明顯減慢。Webpack 捆綁使其更糟。擁有 500+ 文件頁面的團隊報告建置時間超過 5 分鐘，這會破壞 CI/CD 回饋迴圈。

外掛生態系統鎖定

Docusaurus 外掛與其內部架構緊密耦合。需要自訂 remark 外掛？它們有效，但配置層增加了複雜性。想要交換搜尋提供者？您在 Docusaurus 的預設系統中工作，這限制了可能性。

邊欄配置剛性

Docusaurus 邊欄配置使用特定的 JSON/JS 綱要，包含 category、items 和 type 欄位。它有效，但對於深層嵌套的大型文件樹，配置會變得難以管理。重新排序部分意味著編輯配置檔案，而不是簡單地移動檔案。

React 元件依賴

Docusaurus 中的自訂元件是在客戶端進行水合的 React 元件。如果您建置了互動式範例、索引標籤內容或自訂警告，它們都會承擔 React 水合成本 — 即使互動性最少。

Astro Starlight 提供的功能

預設零 JS

Starlight 生成純靜態 HTML 和 CSS。除非您明確新增互動式孤島，否則不會將任何框架 runtime 傳送到瀏覽器。文件頁面在 3G 連線上的載入時間不到 200ms。Lighthouse 分數一致地達到 95-100。

MDX 相容性

Starlight 預設包括 Astro 的 MDX 整合。您現有的 .mdx 檔案立即有效。Frontmatter 欄位清晰對應 — title、description、sidebar_label 都有 Starlight 等效項。Remark 和 rehype 外掛無需變更即可轉移。

內建 Pagefind 搜尋

Starlight 隨附 Pagefind，一個靜態搜尋引擎，可以索引您建置的 HTML 並完全在瀏覽器中執行。沒有外部服務、沒有 API 金鑰、沒有 Algolia 爬蟲延遲。搜尋可離線運作，並為您的套件增加約 10KB。對於特別需要 Algolia 的團隊，有針對 DocSearch 的官方 Starlight 外掛。

基於檔案的邊欄生成

Starlight 可以根據您的檔案結構自動生成邊欄。在資料夾中放置 MDX 檔案，它會出現在邊欄中。您仍然可以使用明確配置進行覆寫，但預設行為消除了大多數邊欄配置維護。

具有型別安全性的內容集合

Starlight 使用 Astro 的內容集合，它在建置時根據 Zod 綱要驗證您的 frontmatter。Frontmatter 欄位中的拼寫錯誤在部署前被捕獲，而不是由使用者發現。

我們的遷移流程

階段 1：稽核和規劃

我們從盤點您的 Docusaurus 網站開始 — 頁面計數、自訂元件、外掛使用、邊欄結構、版本控制設定和任何自訂主題。我們將每個 Docusaurus 功能對應到其 Starlight 等效項，並標記需要自訂解決方案的間隙。

階段 2：Starlight 構建

我們使用 yarn create astro --template starlight 建立新的 Starlight 專案，並將其配置為與現有網站的結構相符。我們設定內容集合、配置 astro.config.mjs，並建立與現有 URL 結構相符的資料夾階層。

階段 3：內容遷移

MDX 檔案以最小變更轉移。我們處理：

• Frontmatter 重新對應：Docusaurus 特定欄位如 sidebar_position、sidebar_label 和 slug 轉換為 Starlight 的 frontmatter 綱要
• 匯入語句更新：元件匯入從 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：品質保證和啟動

我們執行新舊網站之間的完整爬蟲比較，驗證每個 URL 都能解析，測試搜尋功能，驗證行動端呈現，並確認 Lighthouse 分數達到我們的目標。

SEO 保護策略

文件網站積累了大量搜尋權限。我們保護每一位：

• URL 同位：我們完全匹配您現有的 URL 結構。如果 Docusaurus 提供 /docs/getting-started，Starlight 提供相同的路徑
• 301 重新導向：對於必須變更的任何 URL，我們在 Vercel 或 Cloudflare 上配置伺服器層級重新導向
• 規範標籤：每個頁面都獲得正確的規範 URL
• 網站地圖生成：@astrojs/sitemap 生成提交給 Search Console 的更新網站地圖
• 中繼保護：標題標籤、中繼描述和 Open Graph 標籤從現有 frontmatter 轉移
• 結構化資料：我們在適用的地方新增文件特定的 JSON-LD

時間表和定價

大多數 Docusaurus 至 Starlight 遷移在 1-3 週內完成，取決於網站複雜性：

• 小型網站（50 頁以下，最少自訂元件）：1 週，起價 $3,000
• 中型網站（50-200 頁、自訂元件、版本控制）：2 週，起價 $6,000
• 大型網站（200+ 頁、大量自訂、多個地區）：3+ 週，起價 $10,000

每個專案開始時都進行免費遷移稽核，我們評估您特定的 Docusaurus 設定並提供確切的範圍和時間表。