如何在没有 CDN 的情况下将 MathJax 包含在本地 Sphinx 构建中？

Question

我正在尝试将 MathJax 包含在本地

_static

Sphinx 目录中，以避免在本地开发时在重建时下载它的开销。我按照 的说明进行操作，并在

mathjax_path

中设置 conf.py，如下所示，已将 tex-mml-chtml.js 复制到

docs/_static/MathJax/tex-mml-chtml.js

，如 Sphinx 文档中所述：

html_static_path = ["_static"]
mathjax_path = "MathJax/tex-mml-chtml.js"
mathjax3_config = {
    'loader': {'load': ['[tex]/mathtools']},
    'tex': {'packages': {'[+]': ['mathtools']}}
}

如果我

不设置

make html并让Sphinx使用其默认值（从CDN下载MathJax），则通常的

mathjax_path

构建可以工作。所以使用这个例子：

.. math::
    \begin{array}{l}
    f = \underbrace{x^3}_\textrm{text 1} + \underbrace{2}_\textrm{text 2}
    \end{array}

与

conf.py

中的注释行：

# mathjax_path = "MathJax/tex-mml-chtml.js"
mathjax3_config = {
    'loader': {'load': ['[tex]/mathtools']},
    'tex': {'packages': {'[+]': ['mathtools']}}
}

给出了预期的结果：

如果我不指定

mathjax_path

，这将包含在 HTML 中并且可以正常工作：

<script>window.MathJax = {"loader": {"load": ["[tex]/mathtools"]}, "tex": {"packages": {"[+]": ["mathtools"]}}}</script>
<script defer="defer" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>

---

---

但是如果我取消注释

# mathjax_path = "MathJax/tex-mml-chtml.js"

MathJax 就不再工作了，只需给出

:math:

指令的损坏内容而不渲染它：

这包含在 HTML 中：

<script>window.MathJax = {"loader": {"load": ["[tex]/mathtools"]}, "tex": {"packages": {"[+]": ["mathtools"]}}}</script>
<script defer="defer" src="_static/MathJax/tex-mml-chtml.js?v=cadf963e"></script>

我做错了什么？我比较了 CDN 分发和本地文件的哈希值，它们是相同的。我应该包含除

tex-mml-chtml.js

之外的其他文件吗？我是否应该包含更多文件，例如 MathJax 中的

loader.js

？因为查看 Sphinx 文档，路径似乎没问题，我检查了构建，文件位于 _static

...我还在 Sphinx 存储库中搜索了有关此功能的已报告错误，但似乎没有。

Answer 1

检查 Firefox 控制台是否存在 JS 错误后，我注意到 MathJax 无法在本地加载某些组件。为了让它在本地与 Sphinx 一起工作，我通过浏览器从 GitHub

下载了整个 MathJax 库（还有其他方法来获取 MathJax），并指出 mathjax_path

到 MathJax 在我的用例中选择的特定脚本（请参阅问题中的源 HTML 片段），从 CDN 运行时即 es5/tex-mml-chtml.js。

使用绝对路径，值得在

conf.py

 中展示适用于我的 Windows 语法：

mathjax_path = "file:///C:/MathJax-master/es5/tex-mml-chtml.js"