Docusaurus 2.4

我們很高興宣布Docusaurus 2.4。

升級應該很輕鬆：正如我們的版本流程文件中所述，微小版本遵守語意化版本控制。

亮點

側邊欄項目說明

在 #8236 中，我們讓使用者可以針對類型為 連結和 類別的 doc 側邊欄項目提供新的 說明屬性。

sidebars.js

[
  {
    type: 'link',
    label: 'Link with description',
    href: 'https://docusaurus.dev.org.tw',
    description: 'Some link description',
  },
  {
    type: 'category',
    label: 'Category with description',
    description: 'Some category description',
    items: [],
  },
];

這些說明會用在類別所產生的索引頁面中。

佈景主題字串

在 #8708 中，我們新增了一個功能，能夠透過新的查詢字串參數 `docusaurus-theme` 強制 Docusaurus 以 light 或 dark 模式初始化。

這對於當把現有的 Docusaurus 頁面嵌入到 iframe 或 WebView 中時，可以確保主題的一致性。

/文件/?docusaurus-theme=light

/文件/?docusaurus-theme=dark

Remark 外掛 npm2yarn 升級

在 #8690 中，我們升級了 Remark 外掛 @docusaurus/remark-plugin-npm2yarn，修復了許多轉換錯誤，對 pnpm 提供了一流的支援，並具備註冊產生新索引標籤的客製化轉換器的能力。

Run these commands!

```bash npm2yarn
npm install
npm run build
npm run myCustomScript -- --some-arg
```

https://127.0.0.1:3000

npm

npm install
npm run build
npm run myCustomScript -- --some-arg

Yarn

yarn install
yarn build
yarn myCustomScript --some-arg

pnpm

pnpm install
pnpm run build
pnpm run myCustomScript --some-arg

gtag 支援多重追蹤 ID

在 #8620 中，我們新增了 @docusaurus/plugin-google-gtag 外掛支援，以宣告多重追蹤 ID。

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        gtag: {
          trackingID: [
            'G-<YOUR-NEW-GA4-ID>',
            'UA-<YOUR-OLD-UA-ID>',
          ],
        },
      },
    ],
  ],
};

Google 即將終止 Universal Analytics 服務

Google 將於 2023 年 7 月 1 日 終止其 Universal Analytics 服務。

Docusaurus 使用者應轉移到 Google Analytics 4。Google 不允許將現有的 Universal Analytics 資料轉移到新的 Google Analytics 4 屬性。

為保持分析的連續性，我們建議暫時同時向 2 個追蹤 ID 報告事件：舊 ID（UA-*）和新 ID（G-*）。有關詳細資料，請參閱專屬議題。

開發人員體驗

在 #8736 中，我們改進了錯誤訊息的呈現方式，並新增了初步支援，以呈現錯誤的完整因果鏈（請參閱 ES2022 錯誤原因）。

提示

若要實際看到效果，請按一下這裡

在 #8735 中，我們也將導覽列相關錯誤訊息改得更清楚，協助使用者了解錯誤所在。

我們讓許多新元素可以翻譯

• #8677 引入了新的 process.env.DOCUSAURUS_CURRENT_LOCALE（實驗性質），讓您可以針對 config 檔案進行在地化，包括網站標題、標語、公告欄、baseUrl...
• #8616 可翻譯導覽列和頁尾標誌的替代文字

我們為預設主題增加了多種語言的翻譯支援

• #8668：匈牙利文
• #8631：挪威文（書面挪威話）

提示

完成主題翻譯是 持續進行的努力，也是對 Docusaurus 做出貢獻的簡單方式。我們會定期新增主題功能，我們經常 需要新的翻譯。

其他顯著的變更包括

• #8674：尊重 prefers-reduced-motion: reduce 媒體查詢
• #8712：在範本中使用 docSidebar 類型的導覽列項目
• #8801：允許標籤的子項目為假值
• #8757：讓搜尋頁面回應外接查詢字串變更
• #8803：修正RTL中程式碼區塊按鈕的位置
• #8615：修正使用深色導覽列時色彩模式切換的問題
• #8699：修正導覽列下拉式標籤的焦點錯誤

查看2.4.0 變更日誌項目，取得所有變更的完整清單。