宣佈 Docusaurus 3.0

2023 年 10 月 31 日 ·閱讀 11 分鐘

Docusaurus 維護人員、This Week In React 編輯

今天，我們很高興地宣佈推出 Docusaurus 3.0！ 🥳

在 Meta Open Source，我們相信 Docusaurus 能協助您輕鬆建置最佳的文件網站，讓您專注在最重要的部分：撰寫內容。

這是 Docusaurus 的全新主要版本，附帶令人興奮的新功能和升級的依賴項。

根據 語意化版本號 原則，這個版本包含重大變更，我們已在 v3 升級指南 中詳細編制說明。重大變更的確會造成困擾，但它們是設定 Docusaurus 全新功能的必要基礎，而我們計畫實作這些功能。

我們最初計劃發布更多頻繁的主要版本，但 Docusaurus v3 耗費的時間比預期的要長。在我們累積的重大變更中，升級到 MDX v3可能是採用此新版本的主要挑戰。我們付出了額外的努力，讓此升級盡可能的容易，特別是透過增加MDX v1 的相容性選項。

最簡單的網站只需要升級一些 npm 相依性即可。對於更複雜的網站，我們提出了一些策略，可以幫助你更有信心地升級

預先準備好你的網站，在 Docusaurus v2 上逐步執行。
設定視覺回歸測試，以便在升級期間捕獲意外發生的視覺變更

關於 Docusaurus v2

根據我們的發布流程，Docusaurus v2 已進入維護模式。它將只對重大安全問題提供為期 3 個月的支援，直到 2024 年 1 月 31 日。建議在此時間範圍內升級到 v3。

重大變更

此部分僅提供快速瀏覽。所有的重大變更都在v3 升級指南中得到徹底的文件化。

Docusaurus v3 升級了一些相依性到新的主要版本，每個版本都伴隨著自己的重大變更

Node.js v16 ➡️ v18
React v17 ➡️ v18
MDX v1 ➡️ v3
TypeScript v4 ➡️ v5
prism-react-renderer v1 ➡️ v2
react-live v2 ➡️ v4
Mermaid v9 ➡️ v10
import-fresh v3 ➡️ jiti v1
remark-emoji v2 ➡️ v4

一般典型的 package.json 相依性升級如下

package.json
 {
   "dependencies": {
     // upgrade to Docusaurus v3
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
+    "@docusaurus/core": "3.0.0",
+    "@docusaurus/preset-classic": "3.0.0",
     // upgrade to MDX v3
-    "@mdx-js/react": "^1.6.22",
+    "@mdx-js/react": "^3.0.0",
     // upgrade to prism-react-renderer v2.0+
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
     // upgrade to React v18.0+
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
     // upgrade Docusaurus dev dependencies to v3
-    "@docusaurus/module-type-aliases": "2.4.3",
-    "@docusaurus/types": "2.4.3"
+    "@docusaurus/module-type-aliases": "3.0.0",
+    "@docusaurus/types": "3.0.0"
   }
   "engines": {
     // require Node.js 18.0+
-    "node": ">=16.14"
+    "node": ">=18.0"
   }
 }

除了 MDX v3 之外，那些已升級相依性所伴隨的大部分重大變更已內部處理好，你大部分時間都不需執行任何操作。在相依性之外，唯一明確來自 Docusaurus 程式碼庫的功能性重大變更為

#9189：新的預設部落格 RSS 摘要上限為 20 則
#9308：修正並重新引入 :::warning 告示，棄用 :::caution
#9310：移除舊的版本側欄 ID 前置字元，用於版本在 v2.0.0-beta.10 之前的網站（2021 年 12 月）
#7966：重構文件主題元件，最終要求您重新組合它們

重點

下方列出此新版本附帶的新有用功能，但清單並非詳盡。所有功能均列於 Docusaurus v3.0.0 發行說明 中。

Markdown

Docusaurus v3 已從 MDX v1 升級至 MDX v3

在 #8288 中，我們已升級至 MDX v2（遷移指南）
在 #9451 中，我們已升級至 MDX v3（遷移指南）

此新版 MDX 對內容撰寫人員和外掛程式作者來說要好得多，並奠定實作令人興奮的新 Markdown 功能的基礎。

MDX v3 - 主要挑戰

從 MDX v1 到 MDX v3 的過渡是採用 Docusaurus v3 的主要挑戰。

在 Docusaurus v2 下編譯成功的部分文件現在可能會在 Docusaurus v3 下編譯失敗，而其他文件可能會呈現不同的內容。

大部分重大變更源自於 MDX v2，而 MDX v3 是一個相對較小的版本。 MDX v2 遷移指南包含一個關於如何更新 MDX 檔案的章節，這個章節對我們來說特別有幫助。另外，請務必參閱 MDX 疑難排解頁面，這個頁面能幫助您判斷常見的 MDX 錯誤訊息。

不要被嚇到了。大多數問題都很容易修復，而且通常都與現在你必須轉義的 { 與 < 字元有關。不過，依據你網站的大小，你可能需要編輯許多檔案且覺得不知所措。因此，我們提供一個指令 npx docusaurus-mdx-checker，協助你估算要完成的工作量，我們建議您事先準備好你的網站。

如果你建立自訂 MDX 外掛程式 (Remark/Rehype)，其 AST 稍有不同，你可能需要重新編排它們。

這尤其能讓我們新增一個 CommonMark 模式，這應能讓現有的文件更容易採用 Docusaurus。目前須選用，且仍為實驗性質，且有限 (部份 Docusaurus 功能將無法運作)。在 Docusaurus v3 中，所有檔案仍會詮釋為 MDX，但我們計畫在未來的主要版本中將 .md 檔案詮釋為 CommonMark，並建議對使用 JSX 或 ES 模組的任何檔案都採用 .mdx 副檔名。

我們還新增一個新的方式來為網站整體設定 Markdown，並計畫在日後新增更多彈性的選項。

docusaurus.config.js
export default {
  markdown: {
    format: 'mdx',
    mermaid: true,
    preprocessor: ({filePath, fileContent}) => {
      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
    },
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

Docusaurus 現已採用 remark-directive 外掛程式來支援勸告。這也能讓你建立自己的 Remark 外掛程式，以自己的自訂指令來擴充 Markdown，例如 :textDirective、::leafDirective 或 :::containerDirective。

ESM 和 TypeScript 組態

在 #9317 中，我們新增了對 ES 模組和 TypeScript 組態檔的支援，包括網站組態、文件側邊欄、外掛程式和預設值。

以下是 2 個 TypeScript 範例，讓你擁有 IDE 自動完成的現代體驗

docusaurus.config.ts
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'My Site',
  favicon: 'img/favicon.ico',
  // your site config ...
  presets: [
    [
      'classic',
      {
        // your preset config ...
      } satisfies Preset.Options,
    ],
  ],
  themeConfig: {
    // your theme config ...
  } satisfies Preset.ThemeConfig,
};

export default config;

sidebars.ts
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  docs: ['introduction'],
};

export default sidebars;

未列出的內容

Docusaurus 早已支援在我們的 3 個內容外掛程式 (文件、部落格、頁面) 中使用 draft: true 的前端設定選項，可讓你從產品版本中移除一些頁面。

在 #8004 中，我們新增一個新的 unlisted: true 的前端設定選項，會讓你的頁面繼續顯示在產品版本中，同時「隱藏」起來，並讓你不具備 URL 時找不到。這能讓你在最終發布之前輕鬆徵求對內容的回饋，進而便利工作流程。

未列出的內容會

從 sitemap.xml 中排除
運用 <meta name="robots" content="noindex, nofollow" /> 將內容排除於 SEO 結果之外
從部落格 RSS 饋送中排除
從 Algolia DocSearch 結果中排除
從網站導覽列項目、文件側欄、部落格側欄、部落格文章歸檔、標籤頁面... 中過濾

未列出的內容也將顯示一個橫幅，提醒你在內容準備好公開後記得將其關閉。以下是未列出的部落格文章範例

/tests/blog/unlisted-post

React 18

在 #8961 中，我們將版本升級到 React 18。這非常重要，特別是為了漸進採用並行 React 功能，以及即將推出的令人興奮的功能，例如建置時間 React 伺服器元件。

這個新版的 React 對於大部分的 Docusaurus 網站來說應為可取代的。新版附有中斷性變更，這些變更已由我們在 Docusaurus 程式碼庫內部處理。如果你的網站使用了許多自訂 React 程式碼，我們建議你查看官方文章如何升級到 React 18，特別是新的自動批次處理行為。

React 18 功能的實驗性支援

React 18 附有新功能

<Suspense>
React.lazy()
startTransition()

他們的 Docusaurus 支援都被視為實驗性的。我們可能需要在未來調整整合作業，導致不同的執行時期行為。

自動 JSX 執行時期

Docusaurus 現在使用「自動」JSX 執行時期。

不再需要在不使用任何 React API 的 JSX 檔案中匯入 React。

src/components/MyComponent.js
- import React from 'react';

  export default function MyComponent() {
    return <div>Hello</div>;
  }

除錯建置

現在可以在開發模式下建置你的靜態網站。

docusaurus build --dev

偵錯 React 相關問題

Docusaurus 會將更多錯誤記錄在主控台上，特別是透過新的 onRecoverableError 呼叫回函來記錄 React 18 水化錯誤。

這種新的建置模式特別有助於解決 React 問題。Docusaurus 將會使用 React 的開發版本建置，因此會產生詳細且易讀的錯誤訊息，而不是連結到 React 錯誤解碼器頁面的縮寫訊息。

TypeScript

Docusaurus v3 現在需要 TypeScript 5.0 的最低版本。

我們重新將推薦的基本 TypeScript 組態內部化到一個新的官方套件

tsconfig.json
 {
-  "extends": "@tsconfig/docusaurus/tsconfig.json",
+  "extends": "@docusaurus/tsconfig",
   "compilerOptions": {
     "baseUrl": "."
   }
 }

我們也清除了 Docusaurus 核心類型、外掛程式和預設選項的輸出，你可以使用這些輸出在全新的 TypeScript 組態檔案

docusaurus.config.ts
import type {Config} from '@docusaurus/types';
import type {Options, ThemeConfig} from '@docusaurus/preset-classic';
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

程式碼區塊

在 #9316，我們改進了語法高亮，這要歸功於 prism-react-renderer v2 更新。例如，bash 參數 --save 現在會著色

npm install --save some-package

此外，互動式程式碼編輯器也升級到 react-live v4，並採用了新的 sucrase 編譯器。此編譯器速度更快、更精簡，並且支援現代化特色，特別是 TypeScript 類型的註解。

即時編輯器

function Hello() {
  const name: string = 'World';
  return <div>Hello {name}</div>;
}

結果

載入中...

在 #8982 和 #8870，我們也新增了魔術註解，支援 TeX 類型、Haskell 類型和 WebAssembly 註解語法。

haskell.hs
stringLength :: String -> Int
stringLength [] = 0
stringLength (x:xs) = 1 + stringLength xs

matlab.m
function result = times2(n)
  result = n * 2;
end
x = 10;
y = times2(x);

Mermaid 圖表

在 #9305，我們更新到 Mermaid v10.4，並新增了對非同步圖表渲染的支援。Docusaurus 現在可以渲染新型態的圖表。

心智圖

象限圖

查詢字串資料屬性

在 #9028 中，我們透過 docusaurus-data-x 查詢字串參數讓設定自訂 HTML 資料屬性變得可行。這能更輕鬆地在其他網站上嵌入 Docusaurus iframe，並讓你可以用 CSS 自訂嵌入版本的樣式。

/src/css/custom.css
html[data-navbar='false'] .navbar {
  display: none;
}

html[data-red-border] div#__docusaurus {
  border: red solid thick;
}

/docs/?docusaurus-data-navbar=false&docusaurus-data-red-border

其他功能

其他值得一提的新功能

#9189：新的部落格 feedOptions.limit 選項
#9071：為頁面外掛程式新增正規化 SEO front matter 支援
#9171：client-redirects 外掛程式現在支援目的地網址中的完全限定網址和查詢字串/雜湊
#9171：新的 ESLint 規則 no-html-links
#8384：新的 ESLint 規則 prefer-docusaurus-heading

請閱讀 Docusaurus v3.0.0 發行說明 以取得所有變更的詳盡清單。

結論

此版本附有少數幾個功能，但更重要的是升級了 Docusaurus 基礎架構中的許多部份。

今年我們花費許多時間在 MDX 升級 上，並且努力讓所有人都能更輕鬆地進行這個重要的升級。

現在我們趕上基礎架構的進度後，我們將會很快在後續的小版本中提供更多實用的文件功能。

感謝各位多年來使用 Docusaurus。文件架構領域現在競爭越來越激烈，而我們會盡全力確保 Docusaurus 仍然是一個有競爭力的解決方案，並以其高度的彈性而備受推崇。

重大變更​

重點​

Markdown​

ESM 和 TypeScript 組態​

未列出的內容​

React 18​

自動 JSX 執行時期​

除錯建置​

TypeScript​

程式碼區塊​

Mermaid 圖表​

查詢字串資料屬性​

其他功能​

結論​