版本： 3.5.2

升級到 Docusaurus v3

此文件將協助您將您的網站從 Docusaurus v2 升級到 Docusaurus v3。

Docusaurus v3 是一款新的主要版本，包含重大變更，需要您相應調整您的網站。我們會在過程中提供指引，另外也會提及一些建議的選項。

這並非大規模重寫，且重大變更都相對好處理。最簡單的網站最後只要更新他們的 npm 相依性即可升級。

主要的重大變更為從 MDX v1 升級到 MDX v3。請參閱 MDX v2 和 MDX v3 的說明文件取得詳細說明。MDX 現在會以更嚴格且略有不同的方式來編譯您的 Markdown 內容。

升級前

在升級前，我們建議為您的網站準備 Docusaurus v3。您已經可以在 Docusaurus v2 的情況下逐步處理一些變更。這樣可以減少最後升級到 Docusaurus v3 所需的工作量。

對於複雜的網站，我們還建議設定視覺回歸測試，這是確保您的網站保持視覺相同的良好方法。Docusaurus v3 主要升級依賴關係，預期不會產生任何視覺變更。

注意

查看 Docusaurus v3.0.0 的發佈筆記，並瀏覽拉取要求以取得其他有用的資訊，以及此處所述每個變更背後的動機。

升級依賴關係

升級至 Docusaurus v3 不僅需要升級 Docusaurus 核心依賴關係 (@docusaurus/name)，還需要升級其他相關封裝。

Docusaurus v3 現在使用下列依賴關係

Node.js v18.0+
React v18.0+
MDX v3.0+
TypeScript v5.1+
prism-react-renderer v2.0+
react-live v4.0+
remark-emoji v4.0+
mermaid v10.4+

升級社區外掛

如果您的網站使用第三方社區外掛和佈景主題，您可能需要升級它們。

在嘗試升級之前，請確定這些外掛與 Docusaurus v3 相容。

一般的 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"
   }
 }

針對 TypeScript 使用者

package.json
 {
   "devDependencies": {
     // swap the external TypeScript config package for the new official one
-    "@tsconfig/docusaurus": "^1.0.7",
+    "@docusaurus/tsconfig": "3.0.0",
     // upgrade React types to v18.0+
-    "@types/react": "^17.0.69",
+    "@types/react": "^18.2.29",
     // upgrade TypeScript to v5.1+
-    "typescript": "~4.7.4"
+    "typescript": "~5.2.2"
   }
 }

升級 MDX

MDX 是 Docusaurus 一項重要相依性，負責將你的 .md 和 .mdx 檔案編譯成 React 元件。

從 MDX v1 轉換至 MDX v3 是 Docusaurus v3 採用的主要挑戰。大部分重大變更來自於 MDX v2，而 MDX v3 是個較小的版本。

一些在 Docusaurus v2 下編譯成功的文件，現在在 Docusaurus v3 下可能會編譯失敗。

及早找出有問題的內容

在你網站上執行 npx docusaurus-mdx-checker，取得清單中將在 Docusaurus v3 下編譯失敗的檔案。

此指令也很好估計將你的內容調整為相容時需要做的工作量。記住，這些工作大部分可以透過為你的內容準備 Docusarus v3 在升級之前完成執行。

其他文件也有可能會顯示不同。

使用視覺回歸測試

對於需要手動檢視所有頁面會很複雜的大型網站，我們建議你設定視覺回歸測試。

升級 MDX 會帶來 MDX v2 和 MDX v3 版本部落格文章中所有記載的重大變更。大部分重大變更來自於 MDX v2，而 MDX v3 是個較小的版本。MDX v2 遷移指南有個區段關於如何更新 MDX 檔案，這對我們來說特別實用。另外也要確認閱讀 MDX 疑難排解頁面，可以幫助你解釋常見的 MDX 錯誤訊息。

也別忘了閱讀我們更新的 MDX 與 React 文件頁面。

使用 MDX 遊樂場

MDX 遊戲場是您最好的朋友。它允許您瞭解您的內容是如何編譯成 React 組件的，並孤立地解決編譯或呈示問題。

設定 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 遊樂場，您很快會注意到某些內容已以不同的方式編譯，或在 v2 中無法編譯。

讓您的內容永保不敗

目標是重新整理您有問題的內容，讓它在 MDX 的兩個版本上都能正常執行。這樣一來，當您升級到 Docusaurus v3 時，這個內容已經可以立即使用。

使用 MDX 檢查器 CLI

我們提供一個 docusaurus-mdx-checker CLI，可以輕鬆發現有問題的內容。在您的網站上執行此命令，即可取得一份在 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 無法詳盡記錄 MDX 帶來的所有變更。那是 MDX v2 和 MDX v3 遷移指南的責任。

然而，通過升級一些 Docusaurus 網站，我們注意到大多數問題都歸結為我們為您記錄的一些案例。

`{` 使用不當

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

example.md

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

錯誤訊息

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

如何升級

可以修正此錯誤的可用選項

使用內嵌程式碼：{username: string, age: number}
使用 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) 的關閉標籤，否則會產生段落結束標籤不匹配錯誤

paragraph 結束標籤前應出現 <YOUR_MINOR_VERSION> (134:19-134:39) 的關閉標籤

如何升級

可以修正此錯誤的可用選項

使用內嵌程式碼：Array<T>
使用 HTML 程式碼：< 或 <
跳脫字元：\<

GFM 自動連結錯誤用法

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

example.md
<[email protected]>

<https://127.0.0.1:3000>

錯誤訊息

名稱出現意外字元 @ (U+0040)，應為名稱字元，例如字母、數字、$ 或 _；屬性前有空白；或標籤結束（注意：要建立 MDX 連結，請使用 [text](url)）

本機名稱前出現意外字元 / (U+002F)，應為可開始名稱的字元，例如字母、$ 或 _（注意：要建立 MDX 連結，請使用 [text](url)）

如何升級

使用一般 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 v3 中，現在可以更簡單地在 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>

您也可以使用 { 和 } 包住這些內容，以避免額外的 <p> 標籤，如果您尚未打算在那邊使用 Markdown 語法。

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

意外使用指令

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 代碼：:
在 : 之後加入空格（如果合理）：: 文字
跳脫它：\:

不支援縮排程式碼區塊

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

example.md

    console.log("hello");

外觀變更

升級通常不會產生新的 MDX 編譯錯誤，但可能會導致內容以意想不到的方式呈現，因為不再有程式碼區塊。

如何升級

使用正常的程式碼區塊語法，而非縮排

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

其他 Markdown 不相容性

以一個空白或標點開頭或結尾的語法重點

自 v0.14 之後，新的 MDX 剖析器現在嚴格符合 CommonMark 規範。CommonMark 規範針對空白和標點前後的語法重點引入了規則，這與不使用空白來分隔字詞的語言不相容。

日語和中文受此影響最大，但也會影響其他語言 (例如泰語和高棉語)，例如嘗試在內嵌程式碼或連結中加入語法重點時。使用空白分隔字詞的語言受其影響較少。

以下範例中 ** (除了 `**`) 在 Docusaurus 2 中會按照預期剖析，但現在在 Docusaurus 3 中不會。

example.md
**Do not end a range of emphasis with a space. **Or `**` will not work as intended.

<!-- Japanese -->
**「。」の後に文を続けると`**`が意図した動作をしません。**また、**[リンク](https://docusaurus.dev.org.tw/)**や**`コード`**のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

查看詳細條件以及升級方式

如果 * 或 ** 符合以下條件中的任何一個，它將不再作用於語法重點標記的開頭

下一個字元是一個空白 (例如 word* word)
上一個字元是一個標點字元，下一個字元是一個字母 (不是空白或標點字元) (例如 文**（文）)

相反地，如果 * 或 ** 符合以下條件中的任何一個，它將不再作用於語法重點標記的結尾

上一個字元是一個空白 (例如 word *word)
下一個字元是一個標點字元，上一個字元是一個字母 (例如 文。**文)

「標點字元」包括非 ASCII 字元、括號、引號和一些符號，包括 % 和 @。更嚴格地說，Unicode 類別以 P 為開頭的 2 個字母的字元在此視為標點字元。

如何升級

如果導致問題的語法重點標記在一個空白旁邊，請將空白移出語法重點的範圍

english.md
**Do not end a range of emphasis with a space.** Or `**` will not work.

如果導致問題的語法重點標記被標點字元和字母包圍，您可以透過下列方式修正，而不用修改內容

如果只是一個傳統 Markdown，則將文件轉換為 MDX。
改以原始 HTML 標籤 (<em> 或 <strong>) 取代導致問題的語法重點標記

japanese.mdx

<strong>「。」の後に文を続けると`**`が意図した動作をしません。</strong>また、<strong>[リンク](https://docusaurus.dev.org.tw/)</strong>や<strong>`コード`</strong>のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

雖然不是一個理想的解決方案，您也可以在不將文件轉換為 MDX 的情況下採取以下任一方法

將最外面的標點字元移出語法重點標記。

japanese.md
**「。」の後に文を続けると`**`が意図した動作をしません**。また、[**リンク**](https://docusaurus.dev.org.tw/)や・・・

在導致問題的 * 或 ** 外部放置一個空白。這個解決方案不強迫您將文件轉換為 MDX。

japanese.md
**「。」の後に文を続けると`**`が意図した動作をしません。** また、**[リンク](https://docusaurus.dev.org.tw/)** や **`コード`** のすぐ外側に`**`、そのさらに外側に句読点以外がある場合も同様です。

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 的結構方式不同，你可能需要改寫這些外掛程式，甚至完全重寫。我們建立了專屬支援討論，協助外掛程式開發者升級他們的程式碼。

格式化工具

最常見的格式化工具 Prettier，僅支援舊版的 MDX v1，在 Docusaurus v3.0.0 中，仍不支援 v3。你可以在程式碼中與 Prettier 不相容的部分前面，新增 {/* prettier-ignore */}，使其搭配 Prettier 使用。

{/* prettier-ignore */}
<SomeComponent>Some long text in the component</SomeComponent>

如果你對過多的 {/* prettier-ignore */} 註解感到厭倦，可以考慮在 .prettierignore 檔案中將 MDX 格式化停用，直到 Prettier 開始支援 MDX v3。

.prettierignore

*.mdx

其他重大變更

除了 MDX v3 升級外，以下是 Docusaurus v3 所含的重大變更清單。

Node.js v18.0

Node.js 16 已停止支援，Docusaurus v3 現在需要 Node.js >= 18.0。

如何升級

在你的電腦上安裝 Node.js 18.0+。

最後，設定你的持續整合、CDN 或主機，以使用此新的 Node.js 版本。

你也可以更新網站的package.json，避免使用較舊的不支援版本

package.json
 {
   "engines": {
-     "node": ">=16.14"
+     "node": ">=18.0"
   }
 }

升級 Docusaurus v2 網站至 Node.js 18，然後再升級至 Docusaurus v3。

React v18.0+

Docusaurus v3 現在需要React >= 18.0。

React 18 自行附帶重大變更，可能會相當容易處理，端視您為網站建立的 React 自訂程式碼數量。官方佈景主題和外掛程式與 React 18 相容。

升級方法

閱讀官方 React v18.0 和如何升級至 React 18，並檢視您自己的 React 程式碼，找出此升級可能影響哪些元件。

我們建議特別留心

狀態元件的自動批次處理
回報給主控台的新 React 注入錯誤

React 18 功能的實驗性支援

React 18 附帶新功能

<Suspense>
React.lazy()
startTransition

它們的 Docusaurus 支援被視為實驗性。我們日後可能必須調整整合，導致執行時期行為不同。

Prism-React-Renderer v2.0+

Docusaurus v3 升級 prism-react-renderer 至 v2.0+。此程式庫用於程式碼區塊語法醒目顯示。

升級方法

這是包含重大變更的新主程式庫版本，我們無法保證嚴格的後向相容性。prism-react-renderer v2 發行說明沒有非常詳盡，但 Docusaurus 使用者需要了解 3 個重大變更。

應升級相依性

package.json
 {
   "dependencies": {
-    "prism-react-renderer": "^1.3.5",
+    "prism-react-renderer": "^2.1.0",
 }

更新在 Docusaurus 組態檔中匯入佈景主題的 API

docusaurus.config.js
- const lightTheme = require('prism-react-renderer/themes/github');
- const darkTheme = require('prism-react-renderer/themes/dracula');
+ const {themes} = require('prism-react-renderer');
+ const lightTheme = themes.github;
+ const darkTheme = themes.dracula;

以前，react-prism-render v1 預設會包含更多語言。從 v2.0+ 開始，預設會包含的語言變少了。你可能需要額外在 Docusaurus 設定中新增語言

docusaurus.config.js
const siteConfig = {
  themeConfig: {
    prism: {
      additionalLanguages: ['bash', 'diff', 'json'],
    },
  },
};

React-Live v4.0+

如果使用者使用 @docusaurus/theme-live-codeblock 套件，Docusaurus v3 會將 react-live 升級到 v4.0+。

升級方法

理論上，你不需要做任何事，而且現有互動式程式碼區塊應該還是能像以前一樣運作。

不過，這是包含重大變更的新版核心函式庫，而且我們無法保證嚴格的向後相容性。如果遇到問題，請參閱 v3 和 v4 變更日誌。

remark-emoji v4.0+

Docusaurus v3 將 remark-emoji 升級到 v4.0+。此函式庫是用來支援 Markdown 中的 :emoji: 快捷鍵。

升級方法

多數 Docusaurus 使用者都不用做任何事。表情符號快捷鍵的使用者應該參閱變更日誌並仔細檢查他們的表情符號是否仍如預期般呈現。

重大變更 將 node-emoji 從 v1 更新到 v2。這項變更新增了對許多新表情符號的支援，並移除不再於 GitHub 上有效的舊版表情符號快捷鍵。

Mermaid v10.4+

如果使用者使用 @docusaurus/theme-mermaid 套件，Docusaurus v3 會將 mermaid 升級到 v10.4+。

升級方法

理論上，你不需要做任何事，而且現有圖表應該還是能像以前一樣運作。

不過，這是包含重大變更的新版核心函式庫，而且我們無法保證嚴格的向後相容性。如果遇到問題，請參閱 v10 變更日誌。

TypeScript v5.1+

現在，Docusaurus v3 需要使用 TypeScript >= 5.1。

升級方法

升級您的依賴項以使用 TypeScript 5+

package.json
 {
   "devDependencies": {
-    "typescript": "~4.7.4"
+    "typescript": "~5.2.2"
   }
 }

TypeScript 基礎設定

官方 Docusaurus TypeScript 組態已從外部套件 @tsconfig/docusaurus 重新內部化到我們新的單一儲存庫套件 @docusaurus/tsconfig。

此新套件版本與所有其他 Docusaurus 核心套件相同，且將用於確保 TypeScript 向後相容性和重大版本升級時的重大變更。

升級方法

將外部 TypeScript 組態套件換成新的官方套件

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

在你的 tsconfig.json 檔案中使用它

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

新的組態載入器

Docusaurus v3 將其內部組態載入程式庫從 import-fresh 改為 jiti。它負責載入檔案，例如 docusaurus.config.js 或 sidebars.js，以及 Docusaurus 外掛程式。

升級方法

理論上，你什麼事都不用做，現有的組態檔應會像以前一樣持續運作。

然而，這是一個主要的依賴項交換，可能會發生細微的行為變化。

警告提醒

由於歷史因素，我們支援未記錄的 :::warning 警告提醒，以紅色呈現。

警告

這是 Docusaurus v2 :::warning 警告提醒。

不過，顏色和圖示一直有問題。Docusaurus v3 正式重新推出 :::warning 警告提醒，並記錄在案，且修正了顏色和圖示。

警告

這是 Docusaurus v3 :::warning 警告提醒。

升級方法

如果你之前使用了未記錄的 :::warning 警告提醒，請務必針對每個用法確認黃色現在是否為適當的顏色。如果你想要保留紅色，請使用 :::danger。

Docusaurus v3 也將 :::caution 警告提醒設定為不建議使用。請將 :::caution（黃色）重構為 :::warning（黃色）或 :::danger（紅色）。

如果你想要保留「注意」這個標題，你可能想要將它重構成 :::warning[caution]（黃色）。

版本分類側欄

此破壞性變更僅會影響在 v2.0.0-beta.10 (2021 年 12 月) 之前版本化文件的人員，也就是 Docusaurus v2 早期採用者。

在建立 v1.0.0 版本時，其中欄文件包含了 Docusaurus v3 不再支援的前置詞 version-v1.0.0/。

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

升級方法

從版本化其中欄中移除無用的版本前置詞。

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

部落格饋送限制

預設情況下，@docusaurus/plugin-content-blog 現已將 RSS 饋送限制為最後 20 則項目。對於大型的 Docusaurus 部落格，這是比較合理的預設值，可避免 RSS 檔案過於龐大。

升級方法

如果您不喜歡這種新的預設行為，可以使用新的 limit: false 饋送選項，恢復到以前的「無限制饋送」行為

docusaurus.config.js
const blogOptions = {
  feedOptions: {
    limit: false,
  },
};

文件佈景主題重構

對於那些在 docs 相關佈景主題元件（例如 @theme/DocPage）中作弊的使用者而言，這些元件已被大幅重構，讓自訂變得更為容易。

從技術上來說，這並非一個破壞性變更，因為這些元件被 標示為不安全的作弊行為，然而許多 Docusaurus 網站都排除了與 docs 相關的元件，因此他們會很想知道自己的自訂功能可能會破壞 Docusaurus。

升級方法

刪除所有您作弊的元件，重新在他們上面作弊，並重新套用您的自訂功能至新更新的元件。

或者，您可以查看 pull-request 說明，來了解新的佈景主題元件樹狀結構，最後再嘗試手動修補您作弊的元件。

選用變更

有些變更並非強制性的，但若要明確地利用 Docusaurus v3，仍然需要認識它們。

自動 JSX 執行環境

Docusaurus v3 現已使用 React 18 「自動」JSX 執行環境。

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

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

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

ESM 和 TypeScript 組態

Docusaurus v3 支援 ESM 和 TypeScript 組態檔案，建議採行這些新選項。

docusaurus.config.js
export default {
  title: 'Docusaurus',
  url: 'https://docusaurus.dev.org.tw',
  // your site config ...
};

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',
  presets: [
    [
      'classic',
      {
        /* Your preset config here */
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    /* Your theme config here */
  } satisfies Preset.ThemeConfig,
};

export default config;

使用 `.mdx` 延伸功能

當你在 Markdown 檔案中使用 JSX、import 或 export（即 MDX 功能）時，我們建議使用 .mdx 副檔名。這在語意上更正確，並提升與外部工具（IDE、格式化程式、程式檢查工具等）的相容性。

在後續的 Docusaurus 版本中，.md 檔案將會被解析為標準的 CommonMark，而不支援這些功能。在 Docusaurus v3 中，.md 檔案仍會先編譯成 MDX 檔案，但你可以選擇加入 CommonMark。

升級 Math 套件

如果你使用 Docusaurus 來呈現數學方程式，你應該升級 MDX 外掛。

請確定對 Docusaurus v3（使用 MDX v3）使用 remark-math 6 和 rehype-katex 7。我們無法保證其他版本能正常運作。

{
-  "remark-math": "^3.0.0",
+  "remark-math": "^6.0.0",
-  "rehype-katex": "^5.0.0"
+  "rehype-katex": "^7.0.0"
}

hast-util-is-element 在 Docusaurus v3 中已不再必要。如果你已經安裝了它，但沒有在其他地方使用到，你可以執行 npm uninstall hast-util-is-element 來卸載它。

關閉 MDX v1 相容性

Docusaurus v3 自帶 MDX v1 相容性選項，預設為開啟。

docusaurus.config.js
export default {
  markdown: {
    mdx1Compat: {
      comments: true,
      admonitions: true,
      headingIds: true,
    },
  },
};

`comments` 選項

這個選項允許在 MDX 中使用 HTML 註解，儘管 HTML 註解已不再被官方支援。

對於 MDX 檔案，我們建議逐步使用 MDX {/* comments */} 來取代 HTML ，然後關閉這個相容性選項。

部落格截斷標記

現在預設的部落格截斷標記同時支援  和 {/* truncate */}。

`admonitions` 選項

這個選項允許使用 Docusaurus v2 的警告標題語法

:::note Your Title

content

:::

Docusaurus 現在是以 Markdown 指令（以 remark-directive 實作）來實作警告，而提供指令標籤的語法需要方括號

:::note[Your Title]

content

:::

我們建議逐步使用新的 Markdown 指令標籤語法，然後關閉這個相容性選項。

`headingIds` 選項

此選項允許使用 Docusaurus v2 明確標題 ID 語法

### Hello World {#my-explicit-id}

此語法現在是無效的 MDX，且需要跳脫 { 字元：\{#my-explicit-id}。

我們建議現在保持此相容性選項，直到我們提供與較新版本 MDX 相容的新語法為止。

疑難排解

在任何升級問題中，首先嘗試下列事項

確認您的所有文件皆已在 MDX 暫存區編譯，或使用 npx docusaurus-mdx-checker
刪除 node_modules 及 package-lock.json，然後再次執行 npm install
執行 docusaurus clear 以清除快取
移除可能不支援 Docusaurus v3 的協力廠商外掛程式
刪除您的所有已調換組件

嘗試過上述事項後，您可以透過下列支援管道尋求支援

請考慮我們的時間很寶貴。為了確保您的支援請求不會被忽略，我們懇切地請求您

提供我們可以輕鬆執行的最小重現，理想情況下是以 docusaurus.new 建立的
提供顯示問題作用中的真實部署網址（如果您的網站可以建置）
清晰地說明問題，遠遠多於模棱兩可的「它不作用」
包括儘可能多的相關資訊：程式碼片段、儲存庫網址、git 分支網址、完整的堆疊追蹤、螢幕截圖和影片
清晰、簡潔地提出您的請求，讓我們知道您已經付出努力協助我們為您提供協助

或者，您可以尋找已付費的 Docusaurus 服務提供者為您執行此升級。如果您的網站是開放原始碼的，您也可以請我們社群提供免費的仁慈協助。

升級依賴關係​

升級 MDX​

使用 MDX 遊樂場​

使用 MDX 檢查器 CLI​

常見 MDX 問題​

{ 使用不當​

< 使用不當​

GFM 自動連結錯誤用法​

小寫 MDXComponent 映射​

意外增加段落​

意外使用指令​

不支援縮排程式碼區塊​

其他 Markdown 不相容性​

以一個空白或標點開頭或結尾的語法重點​

MDX 外掛程式​

格式化工具​

其他重大變更​

Node.js v18.0​

React v18.0+​

Prism-React-Renderer v2.0+​

React-Live v4.0+​

remark-emoji v4.0+​

Mermaid v10.4+​

TypeScript v5.1+​

TypeScript 基礎設定​

新的組態載入器​

警告提醒​

版本分類側欄​

部落格饋送限制​

文件佈景主題重構​

選用變更​

自動 JSX 執行環境​

ESM 和 TypeScript 組態​

使用 .mdx 延伸功能​

升級 Math 套件​

關閉 MDX v1 相容性​

comments 選項​

admonitions 選項​

headingIds 選項​

疑難排解​

升級依賴關係

升級 MDX

使用 MDX 遊樂場

使用 MDX 檢查器 CLI

常見 MDX 問題

`{` 使用不當

`<` 使用不當

GFM 自動連結錯誤用法

小寫 MDXComponent 映射

意外增加段落

意外使用指令

不支援縮排程式碼區塊

其他 Markdown 不相容性

以一個空白或標點開頭或結尾的語法重點

MDX 外掛程式

格式化工具

其他重大變更

Node.js v18.0

React v18.0+

Prism-React-Renderer v2.0+

React-Live v4.0+

remark-emoji v4.0+

Mermaid v10.4+

TypeScript v5.1+

TypeScript 基礎設定

新的組態載入器

警告提醒

版本分類側欄

部落格饋送限制

文件佈景主題重構

選用變更

自動 JSX 執行環境

ESM 和 TypeScript 組態

使用 `.mdx` 延伸功能

升級 Math 套件

關閉 MDX v1 相容性

`comments` 選項

`admonitions` 選項

`headingIds` 選項

疑難排解