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

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