python - MkDocs 和 MathJax

Question

我是 MkDocs 的新手，正在编写一些需要 latex 的技术文档。我已经成功地建立了一个带有 MkDocs 主题的小型网站，但是它不能正确显示 latex 方程。我按照以下说明操作:

http://www.vlfeat.org/matconvnet/developers/

以及该页面中 python-markdown-mathjax 链接后面的说明。我还尝试在我的 mkdocs.yaml 文件中添加适当的行，类似于:

https://github.com/EdyJ/vehicle-physics-docs/blob/master/mkdocs.yml

但是，发出“mkdocs build”命令仍会导致网站无法呈现方程式。我还尝试使用 mkdocs build 命令添加 -x mathjax 标志。

我已经搜索了网络并且已经修改了相当长的时间。谁能阐明我需要做些什么才能让这两个人一起玩？

Answer 1

这实际上比我预期的要容易。首先我安装了Python-Markdown-Math Extension :

pip install https://github.com/mitya57/python-markdown-math/archive/master.zip

然后我创建了一个新的 MkDocs 项目:

mkdocs new test_math

接下来我将 test_math/docs/index.md 文件编辑为如下(示例从 MathJax documentation 借用):

# MathJax Test Page

When \(a \ne 0\), there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$

最后，我将 test_math/config.yaml 文件编辑为如下:

site_name: Test Math

extra_javascript: 
    - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML

markdown_extensions:
    - mdx_math

我不确定这是否可行，但我运行了测试服务器来查看:

mkdocs serve

然后我打开浏览器并加载 http://127.0.0.1:8000/ .显示格式正确的示例方程的页面:

然后我记得 OP 要求它与 ReadTheDocs 一起使用，所以我在配置中添加了以下行:

theme: readthedocs

我的浏览器重新加载并显示以下(格式正确的方程式):

我应该注意到我收到了一些关于 fontawesome 未加载的奇怪错误。使用 MkdDocs 的主题，方程会在一分钟后消失(当错误出现在浏览器的控制台中时)。但是，在 ReadTheDocs 主题中，即使出现错误，方程式也会正确显示。无论哪种方式，我相信这个错误与我本地机器上的其他问题有关。

最后，赏金是……

Looking for an answer drawing from credible and/or official sources

我通常不做广告，但既然你问了，我是 Python-Markdown 的首席开发人员，我经常与 mitya57(Python-Markdown-Math Extension 的创建者)一起工作他是另外两位对 Python-Markdown 具有提交访问权限的开发人员之一，我是 MkDocs 的贡献者(其中一个贡献是支持 Python-Markdown 扩展)。