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构建命令添加-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 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

Answer 3

看起来这个扩展名不是必需的：

文档/ 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 4

以下是使用扩展名 arithmatex 在MkDocs中获取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。然后执行以下操作：

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


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

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

我会承认我不是专家，实际上只关心有效的方法。我花了几个小时才弄清楚.yml和mathjaxhelper.js文件中的哪些组合可以使$和$$都起作用。希望这对其他人有帮助。

MkDocs和MathJax

5 个答案:

文档/ mathjaxhelper.js

mkdocs.yml