Docusaurus中同时支持$$与\[数学公式语法的实现方案

问题原因 #

默认情况下，remark-math仅将$$作为块级数学公式的识别标记，\[包裹的内容不会被解析为公式，反而会被MDX当作普通文本处理。其中的x_1这类写法会被MDX误判为未定义的JS变量，从而抛出x_1 is not defined的运行时错误。

解决方案 #

通过配置remark-math的blockMath参数，同时启用$$和\[两种块级公式语法：

1. 修改docusaurus.config.js配置
   找到项目根目录下的docusaurus.config.js，定位到presets中的docs配置项，给remark-math添加自定义参数：

const remarkMath = require('remark-math');
const rehypeKatex = require('rehype-katex');

module.exports = {
  // 其他配置...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          // 修改remarkPlugins的配置，添加blockMath参数
          remarkPlugins: [
            [remarkMath, {
              blockMath: [
                ['$$', '$$'], // 保留原有的$$语法
                ['\\[', '\\]'] // 启用\[ \]语法
              ]
            }]
          ],
          rehypePlugins: [rehypeKatex],
          // 其他docs配置...
        },
        // 其他preset配置...
      },
    ],
  ],
  // 其他配置...
};

2. 清除缓存并重启项目
   Docusaurus的缓存可能导致配置不立即生效，执行以下命令清除缓存后重启：

# npm用户
npm run clear && npm start

# yarn用户
yarn clear && yarn start

3. 验证两种语法
   现在在KNN example.mdx中同时使用两种语法都能正常渲染：

• 使用$$的公式：

$$
d(x, x_i) = \sqrt{(x_1 - x_{i1})^2 + (x_2 - x_{i2})^2}
$$

• 使用\[的公式：

\[
d(x, x_i) = \sqrt{(x_1 - x_{i1})^2 + (x_2 - x_{i2})^2}
\]

额外注意事项 #

• 确保remark-math和rehype-katex的版本与Docusaurus 3.1.1兼容，推荐使用最新的稳定版本；
• 如果仍有问题，检查是否有其他remark插件与remark-math冲突，暂时禁用其他插件排查问题。

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