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?

Backwards

While you pointed to all the instructions you are trying to follow, you didn't tell us what you actually did. Therefore it is a little hard to see what you missed. – Skiba

Also, I would suggest staying clear of that mathjax extension. I just looked at it closely for the first time and it has many issues: 1) it has no license, 2) it outputs invalid html, 3) the install process is ridiculous (not the recommended way to install Python-Markdown extensions), 4) its using deprecated features of Python-Markdown that will stop working in the next release, and 5) it doesn't appear to be maintained any more. – Skiba

@Skiba Could you suggest an alternative? – Luci

@Luci try this one: github.com/mitya57/python-markdown-math – Skiba

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

Skiba

Great, thanks, and thanks for your work on mkdocs! When I mentioned readthedocs I was actually talking about the site, readthedocs.org (which is a server which I think supports mkdocs), I'm not sure if it supports this...? – Carat

Worth mentioning that you pushed to pypi since posting this. Thanks! (I still think the question of getting it working on readthedocs is open, would be great to hear your thoughts.) – Carat

I don't use readthedocs.org myself, so not real familiar with their requirements. However, if the above is not working, the I suspect you would need to download and copy into your docs for the MathJax JavaScript library. The MathJax docs explain how to do that. MkDock should just copy the files on build. – Skiba

I have mathjax working though the method I describe below (in my answer). It just doesn't work with the above, with no feedback. – Carat

Note from the future: cdn.mathjax.org is nearing its end-of-life, check mathjax.org/cdn-shutting-down for migration tips. – Vermilion

Thanks @PeterKrautzberger for the warning. I've updated the answer to reflect the URL for the new recommended CDN (https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?...). – Skiba

enable_dollar_delimiter: True #for use of inline $..$ – Cockeyed

It looks great, thanks. Is there any way to get those equations in a PDF via github.com/zhaoterryy/mkdocs-pdf-export-plugin ? – Norrie

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

Microbicide

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.

Beginner

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.

Carat

some of the characters used in the equations might be mistaken as Markdown markup by the parser. Therefore, you still need the Markdown extension to ensure that the Markdown parser will not muck up the equations. Otherwise, I expect your example will work. – Skiba

I'm not sure I follow what may go wrong here, could you give a failing example? – Carat

An extreme edge case was reported here. I know I've seen other (more likely to be encountered) examples, but I can't find them now. It may be in general practice, you will not get collisions most of the time, but why risk it? Any equation which uses the Markdown escape characters is a potential collision. – Skiba

Actually, the simple example in my answer (to the OP question) won't work as the backslashes before the parentheses are striped out by Markdown. See Babelmark for an example of the output without a math specific extension. – Skiba

Answer 5

Here is a way to get LaTeX in MkDocs with the extension arithmatex.

I'm answering again because I want to document a solution that doesn't link to third party sites like Cloudflare and Google.

I'm going the way with the theme named mkdocs-material but you can replace theme: ...school with theme: readthedocs.

First install MkDocs and create a project: https://www.mkdocs.org/#installation.

Then install mkdocs-material and MathJax as follows. Say the project is called my-project. Use downloads and not pip because you want to change the CDN to Cloudflare and the link to google.

cd my-project
git clone https://github.com/squidfunk/mkdocs-material.git
git clone https://github.com/mathjax/MathJax.git MathJax

Edit mkdocs.yml like described under "Usage", for example:

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

You can insert some TeX in index.md, build the site (mkdocs build) and open the index.html to check that MathJax works. Because it doesn't work with mkdocs serve I uploaded the MathJax folder and linking to it instead of the link to the local path.

extra_javascript:
    - https://mysite/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML

To activate TeX inline with $...$ you have to create an extra JS-file

cd docs
mkdir assets
touch extra.js

Insert the following text into 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"
};

and link to it in mkdocs.yml. Finaly the extra_javascript section can like this:

extra_javascript:
    - https://mysite/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML
    - assets/extra.js

Because we don't want to use CDN you can edit mkdocs-material/material/base.html and delete/uncomment the line with <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>. Font-awesome and material-icons are already on board within mkdocs-material.

Barbet

Answer 6

This is the simplest solution I found. Just add the following content into mkdocs.yml:

markdown_extensions:
  - pymdownx.arithmatex

extra_javascript:
  - https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML

And then $f(x)$ and $$f(x)$$ will all work fine.

Grenadines