準備你的網站迎接 Docusaurus v3

2023 年 9 月 29 日 ·閱讀時間 14 分鐘

Sébastien Lorber

Docusaurus 維護者，This Week In React 編輯

警告

這篇部落格文章撰寫於 Docusaurus v3 仍處於測試階段時。如果你要升級到 Docusaurus v3 當前穩定版本，有下列依賴項版本和升級步驟的變更你需要注意。請使用升級指南取得最新的遷移步驟。

Docusaurus v3 現已 進入 Beta 版，而官方版本也即將推出。這是為您的網站做好準備迎接這個新的大版本更新的最佳時機。

Docusaurus v3 有一些重大變更，其中許多變更Docusaurus v2 中都可以處理。提前為您的網站做好準備可以逐步進行，並讓升級至 v3 更加容易。

主要重大變更為將 MDX v1 升級至 MDX v3。有關詳細資訊，請閱讀 MDX v2 和 MDX v3 的版本說明。MDX 現在將更嚴謹地編譯您的 Markdown 內容，並且會有一些微妙的差異。

本文將主要關注如何為這個新的 MDX 版本準備您的內容，並且也會列出一些您今天就可以處理的其他重大變更。

警告

本文提及了大多數的 Docusaurus v3 重大變更，但並非所有。請閱讀 v3.0.0-beta.0 版本說明以取得詳細的清單。

請勿畏懼

這篇部落格文章中包含許多內容，但許多 Docusaurus v2 網站只需稍加變更即可升級。

如果您的網站規模較小，僅有一些自訂內容，那麼您可能可以立即升級到 Docusaurus v3。

準備工作

在準備 Docusaurus v3 升級之前，我們建議先升級到最新的 Docusaurus v2 版本。

根據您網站的複雜程度，採用我們最近發布的視覺回歸測試工作流程可能會是一個好方法。這有助於您在 Docusaurus v3 升級期間發現意外的視覺副作用。

我們也建議在 Markdown 檔案中使用 JSX、import 或 export （即 MDX 功能）時使用 .mdx 副檔名。在語意上，這更加正確，並且能改善與外部工具（IDE、格式化程式、清除程式等）的相容性。在未來的 Docusaurus 版本中，.md 檔案將被解析為標準 CommonMark，它不支援這些功能。在 Docusaurus v3 中，.md 檔案仍會被編譯為 MDX 檔案，但可以選擇採用 CommonMark。

為 MDX v3 準備內容

MDX 是 Docusaurus 的主要依賴項，負責編譯您的 .md 和 .mdx 檔案至 React 元件。

MDX v3 出色許多，但隨之而來的是修改，這可能會要求您稍做重構您的內容。MDX v3 較嚴格，有些在 v1 下編譯良好的元件現在可能無法在 v3 下編譯，最有可能的原因是 { 和 < 字元。

升級 MDX 會帶來 MDX v2 和 MDX v3 發佈部落格文章中記載的所有重大變更。大部分重大變更來自於 MDX v2。MDX v2 移轉指南針對如何更新 MDX 檔案有說明，而這對我們來說特別切中關鍵。也請務必閱讀 MDX 疑難排解頁面，該頁面可以協助您解釋常見 MDX 錯誤訊息。

請務必也閱讀我們已更新的 MDX 與 React 文件頁面。

尋求協助

我們有一個專用的 MDX v3 - 升級支援討論。

使用 MDX 遊樂場

MDX 遊樂場是您的新朋友。允許您瞭解您的內容是如何 編譯成 React 元件，以及單獨解決編譯或呈現問題。

每個 MDX 版本都有自已的遊樂場

設定 Docusaurus 的 MDX 遊樂場選項

要獲得類似於 Docusaurus v2 所使用的編譯行為，請在 MDX 遊樂場上啟用這些選項

使用 MDX
使用 remark-gfm
使用 remark-directive

Screenshot of the MDX playground's options panel, with only the "Use MDX", "Use remark-gfm", and "Use remark-directive" options checked

同時使用兩個 MDX 遊樂場，您很快會注意到一些內容在 v3 中以不同的方式編譯，或無法編譯。

讓你的內容永不過時

目標是重構有問題的內容，以便在兩個版本的 MDX 中都能正常運作。這樣一來，當你升級到 Docusaurus v3 時，此內容將直接在開箱情況下運作。

使用 MDX checker CLI

我們提供了docusaurus-mdx-checker CLI，可協助你輕鬆找出有問題的內容。現在在你的 Docusaurus v2 站台執行此命令，以取得在 MDX v3 下編譯失敗的檔案清單。

npx docusaurus-mdx-checker

對於每個編譯問題，CLI 將記錄檔案路徑和待檢視的行號。

Screenshot of the terminal showing an example MDX checker CLI output, with a few error messages

提示

使用此 CLI 來估計讓你的內容與 MDX v3 相容所需的工作量。

警告

此 CLI 是盡力而為，只會報告編譯錯誤。

它不會報告不會產生錯誤，但可能會影響你的內容顯示的細微編譯變化。為了發現這些問題，我們建議使用視覺回歸測試。

常見的 MDX 問題

我們將幾個 Docusaurus 站台升級至 Docusaurus v3 和 MDX v3

這些升級讓我們能彙整最常見的內容問題，並記錄最佳處理方式。

不當使用 `{`

{ 字元用於開啟JavaScript 表達式。如果你放入 {expression} 中的不是有效的表達式，MDX 現在會失敗。

example.md

The object shape looks like {username: string, age: number}

錯誤訊息

無法使用 acorn 解析表達式：表達式後有意外內容

如何準備

可用的選項來修正此錯誤

使用內聯程式碼：{username: 字串, age: 數字}
使用 HTML 程式碼：{
跳脫它：\{

錯誤使用 `<`

< 字元用於開啟 JSX 標籤。MDX 現在會在認為 JSX 無效時失敗。

example.md
Use Android version <5

You can use a generic type like Array<T>

Follow the template "Road to <YOUR_MINOR_VERSION>"

錯誤訊息

名稱之前出現意外字元 5 (U+0035)，應預期為可以作為名稱開頭的字元，如字母、$ 或 _

預期 <paragraph> 結束標籤之前有 <T> (1:6-1:9) 的關閉標籤 end-tag-mismatch mdast-util-mdx-jsx

預期 <paragraph> 結束標籤之前有 <YOUR_MINOR_VERSION> (134:19-134:39) 的關閉標籤

如何準備

可用的選項來修正此錯誤

使用內聯程式碼：Array<T>
使用 HTML 程式碼：< 或 <
跳脫它：\<（很不幸地，\ 會顯示在 MDX v1 下）

錯誤使用 GFM 自動連結

Docusaurus 支援 GitHub 格式 Markdown (GFM)，但 MDX 不再支援使用 <link> 語法的自動連結。

example.md
<[email protected]>

<https://127.0.0.1:3000>

錯誤訊息

名稱中出現意外字元 @ (U+0040)，應

找不到「 / 」（U+002F）字元，本機名稱前應為字元開頭，例如：字母、$ 或 _（注意：如需在 MDX 中建立連結，請使用 [文字](網址)）

如何準備

請使用一般的 Markdown 連結，或移除 < 和 >。MDX 和 GFM 可以自動連結文字。

example.md
[email protected]
[[email protected]](mailto:[email protected])

https://127.0.0.1:3000
[https://127.0.0.1:3000](https://127.0.0.1:3000)

小寫 MDXComponent 對應

如使用者提供自訂 MDXComponent 對應，元件現已「沙盒化」

h1 的 MDXComponent 對應僅用於 # hi，而不用於 <h1>hi</h1>
小寫的自訂元素名稱不會再由其 MDXComponent 元件取代

視覺差異

您的 MDXComponent 元件對應可能無法套用，且自訂元件可能不再可用。

如何準備

對於原生 Markdown 元素，您可以保留小寫：p、h1、img、a...

對於其他元素，請使用大寫字元。

src/theme/MDXComponents.js
 import MDXComponents from '@theme-original/MDXComponents';

 export default {
   ...MDXComponents,
   p: (props) => <p {...props} className="my-paragraph"/>
-  myElement: (props) => <div {...props} className="my-class" />,
+  MyElement: (props) => <div {...props} className="my-class" />,
 };

意外的多段落

在 MDX 中，現在可以更輕易將 JSX 和 Markdown 交錯，而不必額外換行。在多行上撰寫內容也會產生預期的 <p> 標籤。

視覺差異

請查看 MDX v1 和 v3 如何呈現不同的內容。

example.md
<div>Some **Markdown** content</div>
<div>
  Some **Markdown** content
</div>

MDX v1 輸出結果
<div>Some **Markdown** content</div>
<div>Some **Markdown** content</div>

MDX v3 輸出結果
<div>Some <strong>Markdown</strong> content</div>
<div><p>Some <strong>Markdown</strong> content</p></div>

如何準備

如果您不想要額外的 <p> 標籤，請針對每個案例重構內容，以使用單行 JSX 標籤。

 <figure>
   <img src="/img/myImage.png" alt="My alt" />
-  <figcaption>
-    My image caption
-  </figcaption>
+  <figcaption>My image caption</figcaption>
 </figure>

如果您的內容包含「Markdown 內嵌」（**、*、_、[連結](/路徑)），您可能無法事先重構，必須與 Docusaurus v3 升級一起進行。

意外使用指令

Docusaurus v3 現在使用 Markdown 指令集 (remark-directive 實作)，作為提供告警和其他 Docusaurus 即將推出的功能的通用的方式。

example.md
This is a :textDirective

::leafDirective

:::containerDirective

Container directive content

:::

視覺變更

指令集被解析，目的是要交給其他 Remark 外掛加以處理。未處理的指令集會被忽略，且其原始形式會被呈現在渲染的結果中。

example.md

The AWS re:Invent conf is great

由於 :Invent 被解析為一段文字指令，現在會呈現在渲染的結果中

The AWS re
conf is great

如何準備

使用 HTML 代碼：:
在 : 之後加上空白（如果合理）：: text
轉譯字元：\:（很遺憾的，在 MDX v1 中，\ 會被顯示出來）

不支援的縮排程式碼區塊

MDX 不再將縮排文字轉換為程式碼區塊。

example.md

    console.log("hello");

視覺變更

升級後通常不會產生新的 MDX 編譯錯誤，但可能會導致內容以意外的方式被渲染，因為不存在程式碼區塊。

如何準備

請使用一般的程式碼區塊語法，而不是縮排字元

example.md
```js
console.log('hello');
```

MDX 外掛

MDX 生態系統中的所有官方套件 (Unified, Remark, Rehype...) 現在僅限 ES 模組，不再支援 CommonJS。

在實作中，這意謂著你無法再執行 require("remark-plugin")。

如何準備

Docusaurus v3 現在支援 ES 模組 設定檔。建議你將你的設定檔轉換為 ES 模組，這能讓你輕鬆導入 Remark 外掛

docusaurus.config.js
import remarkPlugin from 'remark-plugin';

export default {
  title: 'Docusaurus',
  /* site config using remark plugins here */
};

如果你想要持續使用 CommonJS 模組，可以使用動態導入，作為讓你在 CommonJS 模組中導入 ES 模組的折衷辦法。很幸運的，Docusaurus 設定檔支援使用非同步函式讓你得以如此執行。

docusaurus.config.js
module.exports = async function () {
  const myPlugin = (await import('remark-plugin')).default;
  return {
    // site config...
  };
};

針對外掛作者

如果您建立了客製化 Remark 或 Rehype 外掛程式，您可能需要對它們進行重組，或最終完全重寫，因為新的 AST 是如何建構的。我們建立了專屬支援討論區來協助外掛程式作者升級他們的程式碼。

其他重大變更

除了 MDX，還有其他重大變更，您已經可以為您的網站做好準備，特別是重要相依項的主要版本升級。

Node.js 18.0

Node.js 16 已屆使用期限，而且 Docusaurus v3 現在需要 Node.js >= 18.0。

如何準備

在升級至 Docusaurus v3 之前，將您的 Docusaurus v2 網站升級至 Node.js 18。

React 18.0

Docusaurus v3 現在需要 React >= 18.0。

React 18 附帶其自己的重大變更，根據您為您的網站建立的客製化 React 程式碼的數量，這些變更處理起來應該相對簡單。

僅使用我們官方佈景主題程式碼且未變更的簡單 Docusaurus 網站並不需要做任何事。

如何準備

閱讀官方 React v18.0 和如何升級至 React 18，並查看您的第一方 React 程式碼以找出哪些元件可能會受此 React 18 升級影響。

我們建議特別尋找

非狀態元件的自動批次處理
新的 React hydration 錯誤報告於主控台

TypeScript 5.0

Docusaurus v3 現在需要 TypeScript >= 5.0。

如何準備

在升級至 Docusaurus v3 之前，將您的 Docusaurus v2 網站升級至 TypeScript 5。

TypeScript 基礎設定

官方 Docusaurus TypeScript 設定已從外部套件 @tsconfig/docusaurus 內部化至我們的新的 monorepo 套件 @docusaurus/tsconfig。

此新套件會與所有其他 Docusaurus 核心套件一同進行版本控管，並且會用於確保 TypeScript 的向後相容性，以及主要版本升級的重大變更。

如何準備

新的 Docusaurus v3 TypeScript 設定與以前的 Docusaurus v2 TypeScript 設定一樣合理。如果您已升級至 TypeScript 5，那麼在 v2 網站上使用 Docusaurus v3 設定是可行的。

package.json
 {
   "devDependencies": {
-    "@tsconfig/docusaurus": "^1.0.7",
+    "@docusaurus/tsconfig": "^3.0.0-beta.0",
   }
 }

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

警告標示

出於歷史因素，我們支援未記錄的標示 :::warning 其會以紅色呈現。

警告

這是 Docusaurus v2 的 :::warning 標示。

然而，此顏色和圖示過去曾錯誤使用。Docusaurus v3 正式重新引入 :::warning 標示，同時加以記錄並修正顏色和圖示。

警告

這是 Docusaurus v3 的 :::warning 標示。

如何準備

如果你先前使用未記錄的 :::warning 標示，請務必確認每處使用的情形，判斷現在是否適合使用黃色。如果你想維持紅色，請以 :::danger 取代。

Docusaurus v3 也已棄用 :::caution 標示。請重新調整 :::caution （黃色）至 :::warning （黃色）或 :::danger （紅色）。

版本化旁側欄

此重大變更僅影響在 v2.0.0-beta.10（2021 年 12 月）之前已將文件設定為版本的 Docusaurus v2 早期使用者。

在建立 v1.0.0 版本時，旁側欄檔案包含一個字首 version-v1.0.0/，Docusaurus v3 已不再支援此字首。

versioned_sidebars/version-v1.0.0-sidebars.json
{
  "version-v1.0.0/docs": [
    "version-v1.0.0/introduction",
    "version-v1.0.0/prerequisites"
  ]
}

如何準備

你的 Docusaurus v2 網站能夠以類似的方式處理這兩種旁側欄格式。

你可以從你的版本化旁側欄移除無用的版本化字首。

versioned_sidebars/version-v1.0.0-sidebars.json
{
  "docs": ["introduction", "prerequisites"]
}

立即試用 Docusaurus v3

Docusaurus v3 現在處於 beta 階段，並已在React-Native、Jest，以及我們自己的網站上實際使用。

我們認為這個新的 Docusaurus 版本健全且已經可以實際部署。預計收到我們社群早期使用者的正面回饋後，將會很快正式發布。

如果你願意升級並回報在3.0.0-beta.0 發布討論串中遇到的問題，我們會非常感謝。

對多數網站來說，升級應該很簡單。如果你已按照此處文件中的說明事先準備好你的網站，升級以下相依關係應該就已足夠

package.json
 {
   "dependencies": {
-    "@docusaurus/core": "2.4.3",
-    "@docusaurus/preset-classic": "2.4.3",
-    "@mdx-js/react": "^1.6.22",
+    "@docusaurus/core": "3.0.0-beta.0",
+    "@docusaurus/preset-classic": "3.0.0-beta.0",
+    "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^1.3.5",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.4.3"
+    "@docusaurus/module-type-aliases": "3.0.0-beta.0"
   }
 }

尋求協助

我們將透過下列支援管道幫助您升級

另外，您可以找付費的 Docusaurus 服務供應商替您執行這項升級。如果您的網站是開放原始碼，您也可以向我們的社群索取免費的善意協助。

結論

Docusaurus v3 已準備好試用，並將很快釋出。本文已經讓您大致了解升級所需的所有重大變更。

首次釋出的 3.0 版本著重在相依性項與基礎架構的升級，這將使我們能夠實作令人興奮的新功能。它也附帶了一些實用的功能，我們將在最終釋出的注意事項中詳細說明。

準備工作​

為 MDX v3 準備內容​

使用 MDX 遊樂場​

使用 MDX checker CLI​

常見的 MDX 問題​

不當使用 {​

錯誤使用 <​

錯誤使用 GFM 自動連結​

小寫 MDXComponent 對應​

意外的多段落​

意外使用指令​

不支援的縮排程式碼區塊​

MDX 外掛​

其他重大變更​

Node.js 18.0​

React 18.0​

TypeScript 5.0​

TypeScript 基礎設定​

警告標示​

版本化旁側欄​

立即試用 Docusaurus v3​

尋求協助​

結論​

準備工作

為 MDX v3 準備內容

使用 MDX 遊樂場

使用 MDX checker CLI

常見的 MDX 問題

不當使用 `{`

錯誤使用 `<`

錯誤使用 GFM 自動連結

小寫 MDXComponent 對應

意外的多段落

意外使用指令

不支援的縮排程式碼區塊

MDX 外掛

其他重大變更

Node.js 18.0

React 18.0

TypeScript 5.0

TypeScript 基礎設定

警告標示

版本化旁側欄

立即試用 Docusaurus v3

尋求協助

結論