从Docusaurus V2升级至V3后Admonitions无法正常渲染问题

问题根源 #

Docusaurus V3 要求MDX版本升级至v3，当前项目使用的MDX v1无法正确解析原V2的Admonition语法，导致样式丢失；同时需确保V3的Markdown配置中Admonitions功能已启用。

解决步骤 #

1. 升级MDX依赖 #

执行以下命令升级到兼容V3的MDX版本：

npm install @mdx-js/react@^3.0.0 @mdx-js/esbuild@^3.0.0

若使用Yarn：

yarn add @mdx-js/react@^3.0.0 @mdx-js/esbuild@^3.0.0

2. 配置Docusaurus启用Admonitions #

在docusaurus.config.js中，更新@docusaurus/preset-classic的Markdown配置：

module.exports = {
  // 其他配置项
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        // 其他preset配置
        markdown: {
          mdx1Compat: false, // 关闭MDX1兼容模式，适配V3
          admonitions: true, // 显式启用Admonitions功能
        },
      },
    ],
  ],
};

3. 清理缓存并重启服务 #

清理旧缓存避免干扰：

npm run clear

重启开发服务：

npm run start

4. 排查第三方主题冲突 #

当前使用的docusaurus-theme-search-typesense@0.15.0需确认是否兼容Docusaurus V3，若存在版本适配问题，建议升级至最新兼容版本，防止主题干扰Markdown解析逻辑。

验证 #

完成上述操作后，原Admonition代码将恢复样式渲染：

内容的提问来源于stack exchange，提问作者Daria