MathTex compatibility for in-browser markdown using MathJax, MathML, and/or images
Have delimited math formulas in your markdown? If you're fortunate enough to have control over the webpage containing your markdown, pretty math displays are just one script
tag away, using MathJax. If otherwise, you're in a fix. This is where MDC comes in: pip install and with just one command, you'll have your math display ready to go in a jiffy. Math can be converted into one of the following alternatives:
- MathML: a native markup language supported by Safari and Firefox
- Images: All math is converted into images and saved to your local disk. You can configure a custom URL prefix, should you host the images on Github or elsewhere. (Automatic Imgur upload support coming soon)
To get started, download the package via pip
.
pip install mathdowncompat
After installation, use the mdcompat
command to process any markdown file's math excerpts. For example, consider the following sample file sample.md
.
# Hello World
This is some $\frac{1}{n} \sum_{i=1}^n x_i$ average math. ;)
$$\int e^{xy} dude$$
Run the following on the sample.md
above. By default, MDC will search for all math environments delimited by $
and $$
, replacing all with paths to images. By default, these paths are relative to your current working directory.
mdcompat sample.md
With that one command, you are now done. Your output at sample.md.converted
will match the following.
# Hello World
This is some ![1](assets/1.png) average math. ;)
![2](assets/2.png)
Want to share this markdown file online? Say we upload all images to alvinwan.com/static
. Then, we specify that as our image URL prefix.
mdcompat sample.md --image-url-prefix alvinwan.com/static
This gives us the following markdown file that we can then host online.
# Hello World
This is some ![1](alvinwan.com/static/assets/1.png) average math. ;)
![2](alvinwan.com/static/assets/2.png)
You can use the options below to specify a host URL or convert to MathML instead of images. (In the future, you can specify an option to automatically upload images to Imgur) The output file is then the following
usage: mdcompat [-h] [--converter {mathml,image}] [--out OUT] [--verbose]
[--image-assets IMAGE_ASSETS]
[--image-url-prefix IMAGE_URL_PREFIX]
path
positional arguments:
path path to markdown file
optional arguments:
-h, --help show this help message and exit
--converter {mathml,image}
math converter to apply
--out OUT path to output markdown file
--verbose
--image-assets IMAGE_ASSETS
path to assets
--image-url-prefix IMAGE_URL_PREFIX
prefix for all image urls