How to include MathJax in an epub3 file to work with iBooks (and possibly others)13 Jan 2013
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.
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…).
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
- 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.
This text is available as an epub3 file which includes MathJax and should run on iOS devices.
- Lila Roberts, 2013/01/15
I’d like to try to create an epub file–I must admit the opf file is quite intimidating. pandoc looks nice; but I do have inDesign and BlueGriffon. I’ll keep you posted. Thanks, Peter!
- Peter, 2013/01/15 yes, creating opf files is a pain. For experiments, you can just hack the sample file from the post. iBooks doesn’t complain if the opf is incomplete, so you can just add jsxgraph etc to the file, too.
- AndrewMcDermott, 2013/01/25
Great post, I’ll give this a go in the next week or so hopefully, if things calm down a little on our project. Will let you know how I get on!
- Peter, 2013/01/25 great! let me know how it goes.
- Peter, 2013/02/14 Hi Andrew. I think this was caught in moderation — sorry. Great to hear it works for you. I hope we can get HTML output running again since that behaves better wrt to CSS. You can of course include both images and MathML and have MathJax replace the images with its rendering. That way you can support all systems using the same file.
- Johannes Wilm, 2013/05/04
The other way one could go would be to try to convert the rendered SVG to a canvas element and from there to an img, which could be saved within the epub. I haven’t tried it, but was thinking of something like https://code.google.com/p/canvg/.
Are there any other recommentations you have?
- Peter, 2013/05/05 Hi Johannes, sorry that this was stuck in the moderation queue. Somehow I didn’t get the notification… This warrants a longer reply, as your comment is hitting on many problems and misconceptions at once 😀 (not you personal, just the way the comment can be misunderstood).
- Johannes Wilm, 2013/05/05
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:
- 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>
- Peter, 2013/05/05 As I wrote, ideally, you would produce some kind of image fallback and use the epub-switch element. Unfortunately, very few epub3 reading systems support it. Even worse, they often react the wrong way to it: using MahtML instead of the image :( Unfortunately, your “once there’s MathML support everywhere” makes me cry a little as I just replied to https://groups.google.com/forum/?fromgroups=#!topic/mozilla.dev.platform/96dZw1jXTvM. There’s currently zero development going into browsers. I hope we can change that, but this will be a while. Anyway, yes, MathJax can easily replace images by rendering embedded code. Case in point: bookmarklets for doing that on Wordpress.com and Wikipedia https://gist.github.com/pkra You can use SVG – both canvas and SVG are part of epub3. Grabbing MathJax output is certainly possible, but with constraints. Making MathJax work also outside the DOM (with those constraints) is in our backlog, but has been for a while. You might find https://github.com/agrbin/svgtex interesting.