MkDocs MathJax 公式渲染经验总结¶

日期： 2026-05-05
问题： 4G/5G 数学原理页面中的 LaTeX 公式未渲染
状态： ✅ 已解决

一、问题描述¶

现象¶

• 站点：http://101.132.106.49/
• 页面：/references/4g5g-math-principles/10-均衡算法/
• 问题：公式显示为原始 LaTeX 代码（如 $\frac{1}{h}$），未渲染为数学公式

影响范围¶

• 4G/5G 数学原理系列（12 个章节）
• 4G/5G 协议教程系列（12 个章节）
• 所有包含 LaTeX 公式的页面

二、错误原因分析¶

根本原因¶

mkdocs.yml 中虽然配置了 pymdownx.arithmatex 和 MathJax，但存在两个关键配置错误：

错误 1：MathJax 3 默认不识别 $...$ 行内公式¶

原始配置：

1
2
3

extra_javascript:
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

问题： MathJax 3 默认只识别 $$...$$ 块级公式和 \[...\] 语法，不识别 $...$ 行内公式。

错误 2：ignoreHtmlClass 配置阻止公式渲染¶

原始配置（mkdocs.yml 中的 pymdownx.arithmatex）：

1
2

- pymdownx.arithmatex:
    generic: true

问题： pymdownx.arithmatex 扩展会将公式包装在 <span class="arithmatex"> 中，但 MathJax 默认配置中的 ignoreHtmlClass: /arithmatex/ 会跳过这个 class，导致公式不渲染。

三、解决方案¶

步骤 1：创建 MathJax 配置文件¶

文件： docs/assets/mathjax-config.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// MathJax 3 配置 - 支持 $...$ 和 $$...$$ 语法
window.MathJax = {
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']],
    displayMath: [['$$', '$$'], ['\\[', '\\]']],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    skipHtmlTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
  }
};

关键配置说明： - inlineMath: 添加 $...$ 和 \(...\) 作为行内公式分隔符 - displayMath: 添加 $$...$$ 和 \[...\] 作为块级公式分隔符 - processEscapes: 允许使用 \$ 转义美元符号 - processEnvironments: 处理 LaTeX 环境（如 \begin{equation}...\end{equation}） - 移除 ignoreHtmlClass: 允许 MathJax 处理 arithmatex class 的元素

步骤 2：更新 mkdocs.yml¶

1
2
3

extra_javascript:
  - assets/mathjax-config.js  # 先加载配置
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js  # 再加载 MathJax

注意： 配置必须在 MathJax 之前加载，因为 MathJax 3 使用 window.MathJax 对象读取配置。

步骤 3：重新构建站点¶

1
2

cd /home/admin/.openclaw/workspace/chip-project
mkdocs build

四、成功经验总结¶

1. 正确的配置顺序¶

1
2
3
4
5
6
7
8

1. pymdownx.arithmatex (Markdown 扩展)
   ↓ 将 LaTeX 代码转换为 <span class="arithmatex"> 标签

2. mathjax-config.js (MathJax 配置)
   ↓ 配置 MathJax 识别公式分隔符

3. MathJax 3 (渲染引擎)
   ↓ 渲染 arithmatex 标签中的公式

2. 关键配置项¶

3. 验证方法¶

1
2
3
4
5
6
7

# 1. 检查配置文件是否正确复制
cat site/assets/mathjax-config.js

# 2. 检查 HTML 是否包含 MathJax 脚本
grep -r "mathjax" site/

# 3. 浏览器访问公式页面验证渲染效果

五、避免再次犯错的检查清单¶

部署前检查¶

• mkdocs.yml 中 pymdownx.arithmatex 已配置
• docs/assets/mathjax-config.js 存在且配置正确
• extra_javascript 中配置在 MathJax 之前加载
• ignoreHtmlClass 已移除或不包含 arithmatex
• inlineMath 包含 $...$ 分隔符

部署后验证¶

• 访问包含公式的页面
• 检查公式是否正确渲染
• 检查行内公式（$...$）是否正常
• 检查块级公式（$$...$$）是否正常
• 检查复杂公式（矩阵、积分、求和）是否正常

六、相关文档¶

• MkDocs 文档： https://squidfunk.github.io/mkdocs-material/reference/math/
• MathJax 文档： https://docs.mathjax.org/
• pymdownx.arithmatex： https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/

七、经验教训¶

1. 不要假设默认配置正确¶

• MathJax 3 默认不识别 $...$，需要显式配置
• 默认配置可能包含阻止渲染的设置（如 ignoreHtmlClass）

2. 配置顺序很重要¶

• MathJax 配置必须在 MathJax 库之前加载
• window.MathJax 对象必须在 MathJax 初始化前设置

3. 测试要覆盖所有公式类型¶

• 行内公式：$E=mc^2$
• 块级公式：$$\int_0^\infty e^{-x} dx = 1$$
• 复杂公式：矩阵、求和、积分、分式等

4. 文档化成功经验¶

• 将配置模板保存到项目中
• 记录常见错误和解决方案
• 建立部署检查清单

最后更新：2026-05-05
下次检查：部署新站点时参考此文档