Material for MkDocs---数学公式

本文最后更新于 2025年8月5日中午

知识库里面的内容涉及安培定律公式，发现无法渲染，也就是不支持数学公式，去必应搜索，出来的Material for MkDocs中文文档。其中的数学公式配置无法生效，可能是由于其调用的polyfill.io被封了，所以无效。阴差阳错才找到了原版官网，才找到正确方法。

操作

详细内容：Material for MkDocs官方文档中配置数学公式

这里记录一下MathJax进行配置，没有使用KaTeX，KaTex不知道有没有我下面遇到的问题

在项目根目录起中新建docs/javascripts/mathjax.js文件。然后写入如下内容：

window.MathJax = {
  tex: {
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processEscapes: true,
    processEnvironments: true
  },
  options: {
    ignoreHtmlClass: ".*|",
    processHtmlClass: "arithmatex"
  }
};

document$.subscribe(() => { 
  MathJax.startup.output.clearCache()
  MathJax.typesetClear()
  MathJax.texReset()
  MathJax.typesetPromise()
})

然后在项目的mkdocs.yml配置中写入如下内容：

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

这里的unpkg.com国内可以正常访问

我按照官方文档中的MathJax配置后，发现公式结构\[ \]无法渲染。于是修改docs/javascripts/mathjax.js文件代码如下：

window.MathJax = {
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']],
    displayMath: [['$$', '$$'], ['\\[', '\\]']],
    packages: {'[+]': ['ams']} // 仅保留必要AMS扩展
  },
  startup: {
    typeset: false // 必须禁用自动渲染
  }
};

// 单独提取渲染控制（关键！）
document$.subscribe(() => {
  if (window.MathJax?.typesetPromise) {
    MathJax.typesetPromise();
  }
});