Math Equations Display - From MathJax to Docutils

Somthing about MathJax

I’ve got people asking me how was I able to make math equations to display on a web page. The key is MathJax_, it’s basically takes math written in latex and renders to HTML5/CSS with appropriate font. The math equations are selectable and zoomable.

Being dumb with plaintext math

I started this blog mainly to take notes from my classes with my laptop and to live publish them as I type. In the begining, I didn’t know about any tool that allows me to display math on html, so I just typed them in plain text, something like x^2+3x=3. For short and simple equations, it worked perfectly. But as I started to get to type long equations, matrices from my linear algebra class, this method bacome a nightmare. Then I accidentally found out about Mathjax on the Math StackExchange_; that was where all the goodies begin with.

Amic’s guide to mathjax+pelican, it works, but…

The first article I found out about how to use MathJax with Pelican was on Amic Frouvelle’s website_. (Our website looks alike because we both use the same blog engine and our themes share the same ancester) He modified the base.html from the theme to include MathJax bootstraping script. This method worked and I’ve been using it for the past six month. But there was a minor usability glitch that kept bothering me: I had to use double back slash on all my equations. It means, instead of having this::

1 2

to display the fraction 1/2, I had to double backslash it::

\frac 1 2

It was very annoying, especially when I needed to copy paste a large equation. Amic wrote that he was going to write a script to do that automatically, but my problem was with live typesetting, where I could not use a tool to bulk replace these backslashes.

Unfortunately, the problem didn’t stop with the need of double backslashing – I also needed to convert from rst_ to latex and then generate pdf. This way I could distribute my class notes in pdf form so people could read them offline. The rst2latex_ tool from docutils treated the math equations as paragraphs of text rather than as actual equations. So I needed to hack docutils to make it treat math equations as is. During the process, I discovered that rst actually had a math directive_ as docutils 0.8!

Native math directive in ReST!

With the new math directives_, I simply need to type :math:`the math equation here` and rst will automatically generate mathjax compatible equations. It can also generate output in mathml format so compatible webbrowsers can display them directly without the need of external javascript libraries. Math directive is also supported in rst2latex, I can easily convert my notes from rst to latex then to pdf. Moreover, I don’t have to backslash twice!

I’ll be converting the old mathjax equations to the new math directive for my notes in the next few days using a conversion script I created. Script will be posted after all notes have been successfully converted.

Finally I want to thank Amic Frouvelle_ for writing an awesome MathJax+Pelican guide!

.. _MathJax: http://www.mathjax.org .. _website: http://www.ceremade.dauphine.fr/~amic/blog/mathjax-and-pelican-en.html .. _Amic Frouvelle: http://www.ceremade.dauphine.fr/~amic/home.html .. _rst2latex: http://docutils.sourceforge.net/docs/user/tools.html .. _math directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html\#math .. _math directives: http://docutils.sourceforge.net/docs/ref/rst/directives.html\#math .. _math StackExchange: http://math.stackexchange.com/ .. _rst: http://docutils.sourceforge.net/rst.htm