MkDocs and MathJax

Question

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/

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

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?

Answer 1

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 

Then I created a new MkDocs project:

mkdocs new test_math 

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}.$$ 

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 

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

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:

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.

Finally, the Bounty is...

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

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).

Answer 2

You will need to install the extension as indicated in the github README. It sounds as if you have already done that.

Then you need to tell Mkdocs that you are using this Python Markdown extension. You would do this by having a line such as this in your mkdocs.yaml: markdown_extensions: [mathjax]

The YAML configuration documentation can be found at:

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

Answer 3

I am no expert on any of this but the below is what worked for me. One of my needs was to have the $...$ notation work for inline Latex, instead of \(..\) because the $ notation works directly in Jupyter notebooks and you can see what your text will look like without first running mkdocs.

For both $..$ and $$..$$ styles to work, first install pip install --upgrade python-markdown-math. Then do the following:

1. Put a text file called mathjaxhelper.js in the /docs folder, and it should contain only the following:

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

2. The project.yml file should contain the following. (replace project.yml with your actual yml file)

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

I will admit I am no expert and really only cared about what worked. It took me several hours to figure out what combination of things in the .yml and the mathjaxhelper.js file will get both $ and $$ to work. Hope this helps someone else.

Answer 4

It looks like be that this extension is not required:

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

Seems to do the trick.