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

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

然后你需要告诉 Mkdocs 你正在使用这个 Python Markdown 扩展。你可以通过在你的 mkdocs.yaml 中有这样一行来做到这一点： markdown_extensions: [mathjax]

YAML 配置文档位于：

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

Answer 2

好像不需要这个扩展：

docs/mathjaxhelper.js

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

mkdocs.yml

markdown_extensions:
  - extra
  - tables
  - fenced_code
extra_javascript:
  - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML
  - mathjaxhelper.js

似乎可以解决问题。

Answer 3

这实际上比我预期的要容易。首先我安装了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 Extension 的创建者）合作，因为他是两个人之一其他对 Python-Markdown 具有提交访问权限的开发人员，我是 MkDocs 的贡献者（其中一个贡献是支持 Python-Markdown 扩展）。

Answer 4

这是一种在 MkDocs 中使用扩展名 arithmatex 获取 LaTeX 的方法。

我再次回答是因为我想记录一个不链接到 Cloudflare 和 Google 等第三方网站的解决方案。

我将使用名为 mkdocs-material 的主题，但您可以将 theme: ...school 替换为 theme: readthedocs。

首先安装 MkDocs 并创建一个项目： https://www.mkdocs.org/#installation.

然后安装mkdocs-material和MathJax如下。 假设项目名为 my-project。 使用下载而不是 pip，因为您想将 CDN 更改为 Cloudflare 并将链接更改为 google。

cd my-project
git clone https://github.com/squidfunk/mkdocs-material.git
git clone https://github.com/mathjax/MathJax.git MathJax

编辑mkdocs.yml，如描述under "Usage"，例如：

site_name: My Project
pages:
    - Home: index.md
theme:
    name: null
    custom_dir: 'mkdocs-material/material'
    palette:
        primary: amber
        accent: pink
    language: de
    feature:
        tabs: true
    font: false
    logo:
        icon: school
markdown_extensions:
    - pymdownx.arithmatex
extra_javascript:
    - ../MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML

您可以在 index.md 中插入一些 TeX，构建站点 (mkdocs build) 并打开 index.html 以检查 MathJax 是否有效。 因为它不适用于mkdocs serve，所以我上传了 MathJax 文件夹并链接到它而不是本地路径的链接。

extra_javascript:
    - https://mysite/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML

要使用$...$ 内联激活 TeX，您必须创建一个额外的 JS 文件

cd docs
mkdir assets
touch extra.js

将以下文本插入extra.js：

window.MathJax = {
  tex2jax: {
    inlineMath: [ ["$","$"], ["\\(","\\)"] ],
    displayMath: [ ["\\[","\\]"] ]
  },
  TeX: {
    TagSide: "right",
    TagIndent: ".8em",
    MultLineWidth: "85%",
    equationNumbers: {
      autoNumber: "AMS",
    },
    unicode: {
      fonts: "STIXGeneral,'Arial Unicode MS'"
    }
  },
  displayAlign: "center",
  showProcessingMessages: false,
  messageStyle: "none"
};

并在mkdocs.yml 中链接到它。最后 extra_javascript 部分可以这样：

extra_javascript:
    - https://mysite/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML
    - assets/extra.js

因为我们不想使用 CDN，您可以编辑 mkdocs-material/material/base.html 并删除/取消注释带有 <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin> 的行。 mkdocs-material 中已经包含了超棒的字体和材质图标。

Answer 5

我不是这方面的专家，但以下内容对我有用。我的一个需求是让 $...$ 表示法适用于内联 Latex，而不是 \(..\)，因为 $ 表示法直接在 Jupyter 笔记本中工作，您可以在不先运行 mkdocs 的情况下看到您的文本的外观.

要同时使用 $..$ 和 $$..$$ 样式，请先安装 pip install --upgrade python-markdown-math。然后执行以下操作：

1. 将一个名为 mathjaxhelper.js 的文本文件放在 /docs 文件夹中，它应该只包含以下内容：

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

1. project.yml 文件应包含以下内容。 （将 project.yml 替换为您的实际 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

我承认我不是专家，我真的只关心有效的方法。我花了几个小时才弄清楚 .yml 和 mathjaxhelper.js 文件中的哪些内容组合将使 $ 和 $$ 都能正常工作。希望这对其他人有帮助。