MathJax, Markdown, and Instapaper

Last month, I got an email from reader and occasional commenter Alan Schmitt who told me that my posts with equations didn’t display well in Instapaper. The problem was that an equation like1

Φ(x)=12πxeξ2/2dξ\Phi(x) = \frac{1}{\sqrt{2\pi}} \int_{-\infty}^x e^{-\xi^2/2} d\xi

would appear in Instapaper as


which, while true, isn’t very informative.

I dashed off a quick reply with a promise to look into fixing it. The promise was delayed by, you know, things and stuff, but the fix—to the extent I can make one—is finally in place. The version of PHP Markdown Extra Math (PHPMEM) in the GitHub repository has the changes.

Originally, PHPMEM would generate this HTML for the equation above:

<span class="MathJax_Preview">[math]</span><script type="math/tex; mode=display">\Phi(x) = \frac{1}{\sqrt{2\pi}} \int_{-\infty}^x e^{-\xi^2/2} d\xi</script>

As the page loads, the “[math]” appears. When MathJax is done processing the LaTeX in the <script>, it displays the rendered equation and hides the <span> that precedes it. This serves two purposes:

  1. It gives you something to look at if the MathJax processing is lengthy. On fast machines, MathJax is usually so quick you never see this; but on my iBook G4, I see it all the time.
  2. It works around a display bug in Internet Explorer.

As it turned out, the “[math]” also became the replacement for the equation in Instapaper.

My fix, such as it is, is to replace the “[math]” placeholder with the LaTeX code:

<span class="MathJax_Preview">[\Phi(x) = \frac{1}{\sqrt{2\pi}} \int_{-\infty}^x e^{-\xi^2/2} d\xi]</span><script type="math/tex; mode=display">\Phi(x) = \frac{1}{\sqrt{2\pi}} \int_{-\infty}^x e^{-\xi^2/2} d\xi</script>

which now displays

[\Phi(x) = \frac{1}{\sqrt{2\pi}} \int_{-\infty}^x e^{-\xi^2/2} d\xi]

as the placeholder. It’s certainly not as good as the rendered equation, but it’s somewhat readable if you speak LaTeX. Simpler equations, like E=mc2E = mc^2, are easily readable in their raw LaTeX form: [E = mc^2].

It makes perfect sense that the placeholder text appears in Instapaper instead of the rendered equation. Instapaper’s mission is to strip away a page’s extra fluff and display the text content in a pleasing way. MathJax, being written in JavaScript, is taken to be part of the fluff.

Which is unfortunate, because the formatting of an equation really is part of its content—reading it as LaTeX code just isn’t the same. And pages with equations often require longer reading time and more thoughtful consideration, which is what Instapaper is all about.

I’ve emailed Marco Arment about this and asked if there was a way he could get Instapaper to handle MathJax. It strikes me as being quite difficult. Not only would Instapaper have to incorporate MathJax itself, it would also have to read the site’s MathJax configuration file to understand how the equation code is to be interpreted.

I’m not holding my breath, but I am holding out hope. Marco is an extraordinarily smart programmer.

  1. In case you’ve forgotten your statistics, this is the standard normal cumulative distribution function, one of those nasty integrals that can’t be done analytically.