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