How to get LaTeX in GitHub README files and GitHub pages

This is a very brief blog post about something I found very useful, and I suppose others might benefit from it if they are doing a lot of math and also using GitHub or hosting a website with GitHub pages.

Github’s flavour of markdown doesn’t support LaTeX, which is rather frustrating.

However, there is a work around. One possible way to do this automatically is to use readme2tex. It is incredibly useful. What it does is converts all the LaTeX math into svg images. These images are then used to replace the LaTeX in a new markdown file. They are included into the markdown file using HTML image tags.

To install

pip install readme2tex

To use simply type the following into the terminal

python -m readme2tex  --username nouser --project noproject --nocdn --readme INPUT.md --output OUTPUT.md

A few notes

You may not need to use all the flags that I have used, but that is what worked for me. The first 2 flags were used because it cried foul when they were not given despite the documentation saying they are optional. I simply gave dummy values and it worked just fine. The —nocdn flag will use relative paths for the output images. The —readme flag is followed by the markdown file that is to be processed. The —output flag is followed by the desired name of the processed markdown file, which will have the LaTeX replaced with images.

Also GitHubs flavour of markdown can be little more sensitive to blank lines, so if you have inline equations you should be mindful of blank lines. In particular, you should check that your lists are tight, i.e., no blank lines between items. Otherwise you may get unwanted line breaks around your math images for apparently no reason. However, if all else fails to remove these unwanted line breaks I found that using the aside HTML tag can be useful, as the element does not render as anything special in a browser.