MkDocs和MathJax [英] MkDocs and MathJax

问题描述

我是MkDocs的新手，正在写一些需要乳胶的技术文档.我已经成功建立了一个带有MkDocs主题之一的小型网站，但是该网站无法正确显示乳胶方程式.我按照以下指示进行操作:

I'm new to MkDocs and am writing some technical documentation that requires latex. I've successfully built a small website with one of the MkDocs themes, however it won't properly display the latex equations. I followed the instructions at:

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

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

as well as the instructions following the python-markdown-mathjax link from that page. I have also tinkered with adding appropriate lines to my mkdocs.yaml file, similar to:

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

但是，发出命令"mkdocs build"仍然会导致站点无法呈现等式.我还尝试了在mkdocs build命令中添加-x mathjax标志.

However, issuing the command 'mkdocs build' still results in a site that doesn't render the equations. I've also tried adding a -x mathjax flag with the mkdocs build command.

我已经在网上进行搜索，并且已经花了很多时间进行修补.谁能阐明我要让这两个人一起玩需要做什么?

I've scoured the web and have been tinkering for quite a bit of time now. Can anyone shed light on what I need to do to get these two playing together?

推荐答案

这实际上比我预期的要容易.首先，我安装了 Python-Markdown-Math扩展:

This is actually easier than I expected. First I installed the Python-Markdown-Math Extension:

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

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

Then I created a new MkDocs project:

mkdocs new test_math

接下来，我将test_math/docs/index.md文件编辑如下(从

Next I edited the test_math/docs/index.md file to be as follows (sample borrowed from the 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文件编辑如下:

Finally, I edited the test_math/config.yaml file to be as follows:

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

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

I was unsure if this would work, but I ran the test server to see:

mkdocs serve

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

I then opened my browser and loaded http://127.0.0.1:8000/. The page displayed with the sample equations properly formatted:

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

Then I remembered that the OP asked for this to work with ReadTheDocs, so I added the following line to the config:

theme: readthedocs

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

My browser reloaded and the following (properly formatted equations) displayed:

我应该注意，关于fontawesome无法加载，我遇到了一些奇怪的错误.以MkdDocs为主题，等式在一分钟后消失(当错误出现在浏览器的控制台中时).但是，在ReadTheDocs主题中，即使出现错误，方程也可以正确显示.无论哪种方式，我都认为此错误与本地计算机上的其他问题有关.

I should note that I'm getting some weird error about fontawesome not loading. With the MkdDocs' theme, the equations disappear after a minute (when the error appears in the browser's console). However, in the ReadTheDocs theme, the equations display properly, even with the error. Either way, I believe this error is related to some other issue on my local machine.

最后，赏金是...

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

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

我通常不做广告，但是由于您的询问，我是Python-Markdown的首席开发人员，我经常与mitya57(Python-Markdown-Math Extension的创建者)合作，因为他是以下两个人之一其他开发人员具有对Python-Markdown的提交访问权限，我是MkDocs的贡献者(其中之一是对Python-Markdown扩展的支持).

I don't normally advertise this, but since you asked, I am the lead developer of Python-Markdown, I work regularly with mitya57 (the creator of Python-Markdown-Math Extension) as he is one of two other developers with commit access to Python-Markdown, and I am a contributor to MkDocs (one of those contributions being support for Python-Markdown Extensions).

这篇关于MkDocs和MathJax的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！