MkDocs和MathJax

Question

我是MkDocs的新手,正在写一些需要乳胶的技术文档.我已成功建立了一个小型网站,其中包含一个MkDocs主题,但它无法正确显示乳胶方程式.我按照以下说明操作:

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扩展:

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

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

mkdocs new test_math

接下来我编辑了test_math/docs/index.md如下文件(从MathJax文档中借用的样本):

# 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主题中,方程式显示正确,即使出现错误.无论哪种方式,我相信这个错误与我本地机器上的其他问题有关.

最后,赏金是......

寻找可信和/或官方来源的答案

我通常不会宣传这个,但是既然你问我,我是Python-Markdown的首席开发人员,我经常与mitya57(Python-Markdown-Math Extension的创建者)合作,因为他是另外两个拥有提交访问权限的开发人员之一Python-Markdown,我是MkDocs的贡献者(其中一个贡献是支持Python-Markdown Extensions).

Answer 2

您需要按照 github README 中的指示安装扩展。听起来好像你已经这样做了。

然后你需要告诉 Mkdocs 你正在使用这个 Python Markdown 扩展。您可以通过在 mkdocs.yaml 中添加如下行来完成此操作： markdown_extensions: [mathjax]

YAML 配置文档可以在以下位置找到：

• http://www.mkdocs.org/user-guide/configuration/#formatting-options