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

最后赏金是..。

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

我通常不会宣传这一点，但既然你问了，我是Python-Markdown的首席开发人员，我经常与mitya57 ( Python-Markdown-Math扩展的创建者)合作，因为他是另外两个可以提交Python-Markdown的开发人员之一，我是MkDocs的贡献者(其中一个贡献是支持Python-Markdown扩展)。

Answer 2

您需要按照github自述文件中的说明安装该扩展。听起来你好像已经这么做了。

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

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

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

Answer 3

我不是这方面的专家，但以下是对我有效的方法。因为$ notation直接在Jupyter notebooks中工作，您可以在不先运行mkdocs的情况下看到文本的外观。

要使$..$和$$..$$样式都正常工作，首先要安装pip install --upgrade python-markdown-math。然后执行以下操作：

MathJax.Hub.Config({
  config: ["MMLorHTML.js"],
  jax: ["input/TeX", "output/HTML-CSS", "output/NativeMML"],
  extensions: ["MathMenu.js", "MathZoom.js"]
});

1. project.yml文件应包含以下内容。(用实际的yml文件替换project.yml )

markdown_extensions:
    - extra
    - tables
    - mdx_math:
        enable_dollar_delimiter: True
    - fenced_code
theme: readthedocs
extra_javascript: 
    - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-AMS-MML_HTMLorMML

我承认我不是专家，我只关心什么是有效的。希望这对其他人有帮助。