# How to include MathJax in an epub3 file to work with iBooks (and possibly others)

At the Joint Mathematics Meetings Present and Future of Mathematics on the Web session, Lila Roberts presented an excellent demo of the good stuff you can do with iBooks author. The demo included MathJax and jsxgraph, and combined both with iBooks Author’s easy, pretty layout tools. Of course, the drawback is that iBooks Author is

• a proprietary format
• restricted to iPads (not just iOS)
• you’re not allowed to sell an iBooks Author file except through iTunes.
• iBooks Author is not transparent about how its formula editor produces SVGs out of TeX but pastes MathML directly into a page, leading to inconsistent renderings of equivalent mathematics
• MathML support of iBooks on iOS5 devices is severly broken (and will likely never be fixed) thanks to a mobile Safari bug that screws up the use of STIX fonts.

Anyway, I mentioned in the session that you can actually include MathJax in epub3 files directly to get much of the same. Well, you have to do the pretty layouts yourself and you’ll depend on a javascript-enabled epub3 reading software (like iBooks) but at least you’re using an open standard and retain your rights.

## Let’s get started!

If you’re lazy, grab the file at the end of the post and hack from there. But I’ll walk you through it.

• If you want to learn something, grab a copy of MathJax
• slim it down as described here
• I went all the way and restricted output to SVG – to minimize things and to make it work. HTML output should work on iOS5, but last I checked Apple changed something on iOS6 that I couldn’t track down for lack of devices.

Alright, that’s the basics. You now have a copy of MathJax that works on any reasonably recent webkit browser, including most Android and iOS versions.

You have all inputs (LaTeX, asciimath, MathML) available but only SVG output (well, and native MathML but if that worked we wouldn’t be here…).

## What’s next?

Create your document. That’s actually hard if you don’t have a workflow already and don’t want to afford InDesign, Blue Griffon etc.

Personally, I will always try pandoc first. It’s the most versatile tool there is and John McFarlane is just fantastic. Its TeX implementation is enough if you are writing TeX with HTML/epub output in mind, I’m sure you won’t run into trouble.

If you can, consider to go through the Haskell-cabal-pain of installing the current development version – see the instructions at the pandoc github wiki. That will get you the new epub3 writer and things should be easy.

Of course, you can hack the example file below and just use a current version of pandoc or whatever you like to generate some xHTML5 (yes, xhtml, not html if you want your file to validate). You’ll have to modify the manifest etc by hand.

Anyway, let’s daringly assume you have an epub3 with your xhtml+mathml content.

• add the slim down version of MathJax to your epub file using your favoriate tool for adding content to a zip file. (Don’t unzip/rezip unless you know what epub needs when zipping…)
• Assuming you’re using the copy as in the attachement, add the following to your manifest (modify paths and id’s if needed)
`

`

• To each xhtml file that contains MathML, add
```<script type="text/x-mathjax-config"> MathJax.Hub.Config({ jax: ["input/TeX","input/MathML","output/SVG"], extensions: ["tex2jax.js","mml2jax.js","MathEvents.js"], TeX: { extensions: ["noErrors.js","noUndefined.js","autoload-all.js"] }, MathMenu: { showRenderer: false }, menuSettings: { zoom: "Click" }, messageStyle: "none" }); </script> <script type="text/javascript" src="../mathjax/MathJax.js"> </script>```
• I have not activated automatic linebreaking because there’s currently a bug in MathJax on iOS6. If MathJax detects the need to break the line, you’ll get Math Processing errors instead.
• For each xhtml file with the above we’ll have to modify the `properties`-part in the manifest to have both `mathml scripted`, e.g., in the sample file you’ll see
• `<item id="c3" media-type="application/xhtml+xml" href="xhtml/ch1.html" properties="mathml scripted"/>`
• And then you can include wonderful MathML and even webkit deficiencies or the horrible iOS5 Safari+STIX bug will be meaningless to your epub file and you can actually publish a mathematical epub file to be read on iBooks. $\stackrel{^}{x}+\stackrel{^}{xy}+\stackrel{^}{xyz}.$

This text is available as an epub3 file which includes MathJax and should run on iOS devices.

• Johannes Wilm, 2013/05/05 I see. The epub with mathjax in it worked fine in IBooks, while in Adobe Digital Editings (installed via Wine) and my Nook Glow Light, it just doesn’t run the Javascript. It seems to crash the ebook reading app that comes with Calibre. Epubs themselves may have a limited lifespan, as ebook readers will get fullblown browsers with time, and once there is MathML support everywhere, we may just need a smaller script of some kind to translate Tex-based maths to MathML… The point is that the landscape is changing rapidly and that one needs to adjust one’s solutions quite a lot over the next few years. So, I was thinking: To get smething that is working with today’s devices, instead of this: `$X=Y^2$` which is rendered fine on only some devices, have something like this:   Then the ebook readers that cannot run jaascript will show the image and those that can (IBooks) can calculate the mathjax formula. Of course, mathjax has to be run manually with some javascript, as it cannot find the equation it should render as easily, but I’m sure this can be done. As for SVG vs. IMG – I didn’t look enough at the svg-canvas library, but assuming that it permits me to copy an already rendered SVG to a canvas, that should mean that I should be able to create a canvas which easily can be converted to an IMG and then saved inside the epub. But you would maybe argue that it is preferable to just include the SVG directly? For that I assume I would copy the SVG code from the DOM, copy the extra style information that has been added to the header, and find the fonts that have been added through some other trick (cannot find them in hte header) and add those to the mix as well. Right?
• Johannes Wilm, 2013/05/05 Ah, this system ate most of my code examples. let me try again: So, I was thinking: To get something that is working with today’s devices, instead of this: `<span class="equation"><MATH>X=Y^2</MATH></span>` which is rendered fine on only some devices, have something like this: `<span class="equation" data-equation="X=Y^2"><IMG src="..." alt="an equation showing X=Y^2"/></span>`