Gatsby博客gatsby-remark-katex插件无法正常渲染数学公式排查

配置问题核查 #

• gatsby.config.js 插件顺序配置无逻辑错误，但存在依赖缺失问题。从 gatsby-remark-katex@4 版本开始，remark-math被调整为对等依赖，不会随插件自动安装，你在初始安装步骤中仅安装了3个相关包，缺少remark-math依赖，这是公式被原样输出的核心原因。
• gatsby.browser.js 是引入 KaTeX 样式文件的正确位置，该配置没有错误，之前样式未生效本质是公式内容没有被KaTeX解析渲染，和CSS引入路径、位置无关。

修复操作步骤 #

• 安装缺失的依赖：
  执行命令 npm install remark-math，使用yarn的话执行 yarn add remark-math。
• 确认插件顺序：保持gatsby-remark-katex在gatsby-transformer-remark的子插件数组的第一位，避免后续代码高亮、目录生成、锚点生成类插件提前转义$符号，破坏公式标记。你当前的插件顺序符合要求，无需调整。
• 清除缓存重启服务：删除项目根目录下的.cache和public文件夹，再执行npm run develop重启本地服务，避免旧编译缓存导致配置不生效。

公式书写规范 #

配置生效后，按以下规则书写即可同时支持行内、展示两种模式：

• 行内公式：用单个$包裹公式内容，注意$和公式内容之间不要加空格，示例：
  书写内容：勾股定理的表达式为 $a^2 + b^2 = c^2$，是直角三角形的核心边长关系
• 展示模式（块级公式）：公式单独占一行，用两个$包裹，示例：

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

注意：如果行内公式的$和内容之间加了空格，公式会被识别为普通文本，无法正常渲染。

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