Docusaurus 3.1

我們很高興地宣布推出 Docusaurus 3.1。

升級應該很容易：正如我們在 版本流程文件 中說明的一樣，次要版本遵守 語意化版本管理。

亮點

損壞錨點檢查

在 #9528 中，我們改進了內建的損壞連結檢查程式，以便也能偵測損壞的錨點。

快速失敗

新的 onBrokenAnchors 選項，出於回溯相容性原因，預設為 warn。

我們建議將其改為 throw，在部署故障的定位標記到製作環境之前，先讓 CI 建置失敗。

注意

針對會實作自訂 <Heading> 和 <Link> 元件的使用者和外掛作者，我們提供了一個新的 useBrokenLinks React hook API。

大部分 Docusaurus 使用者都不必理會這個 API，內建元件（docusaurus/Link 和 @theme/Heading）已經內部使用此 API。

parseFrontMatter hook

在 #9624 中，我們新增了一個 siteConfig.markdown.parseFrontMatter 函數 hook。

這使得可以實作方便的前置元資料轉換、捷徑，或透過 Docusaurus 外掛不支援的前置元資料與外部系統整合。

docusaurus.config.js

export default {
  markdown: {
    parseFrontMatter: async (params) => {
      // Reuse the default parser
      const result = await params.defaultParseFrontMatter(params);

      // Process front matter description placeholders
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');

      // Create your own front matter shortcut
      if (result.frontMatter.i_do_not_want_docs_pagination) {
        result.frontMatter.pagination_prev = null;
        result.frontMatter.pagination_next = null;
      }

      // Rename an unsupported front matter coming from another system
      if (result.frontMatter.cms_seo_summary) {
        result.frontMatter.description = result.frontMatter.cms_seo_summary;
        delete result.frontMatter.cms_seo_summary;
      }

      return result;
    },
  },
};

閱讀 前置元資料指南 和 parseFrontMatter API 參考文件 以取得更多資訊。

其他變更

其他主要的變更包括

• #9674：加入 siteConfig.markdown.remarkRehypeOptions 以將選項傳遞給 remark-rehype，讓你可以自訂事項，例如 MDX 註腳標籤
• #9671：為 (Visual) Basic/批次檔/Fortran/COBOL/ML 加入程式碼區塊 MagicComments 支援
• #9610：啟用透過 PORT 環境變數設定 CLI 埠
• #9477：完成巴西葡萄牙語 (pt-BR) 翻譯

查看3.1.0 變更記錄條目取得變更的完整清單。