Depressed musician vintage drawing

Productive Failure: MathJax and Pressbooks

As an OER specialist and accessibility advocate, I feel double pressure that when we create openly licensed materials, we have to hold ourselves towards the highest standards of accessibility. That’s not easy when we are talking about STEM, but it’s a responsibility I don’t take lightly.

Online, when you have accessible math displayed in a browser, typically there are two tools that are doing that work MathJax or KaTeX. By far, the most common is MathJax, a javascript library that transforms what would typically be inaccessible math markup languages like LaTeX and Asciimath into the visual typeset display and the assistive MathML that is required for screenreaders and other accessibility tools like braille displays.

Mathjax makes math accessible
Mathjax converts multiple inaccessible math markup language into beautiful typeset math, plus the assistive MathML to make it readable by a screenreader.

This works great for web books and HTML documents. In fact, the web based materials we create are probably among the most accessible math materials if we build them with accessibility in mind from the beginning. Pressbooks is a great application for building web books that can be exported into multiple formats, but to be able to use MathJax for both the live web version, and the exports we have to run our own MathJax microservice on our Pressbooks server.

I spent two days attempting to get a MathJax microservice running on Reclaim Cloud, so that we can transition SUNY’s server from shared hosting, into a modern, scalable system that can absorb web traffic and future proof our OER efforts. On Reclaim Cloud the server has the ability to scale up and down in computing power according to current server usage which is great. For me this was a good opportunity to explore working with this new setup.

As you might have gathered from my title productive failure, I was not entirely successful in my goals, but the work was still important. There just are not that many people who are doing this type of work. When my installations failed, 1, 2, 3…. 9 times, I started documenting the problems, and communicating with the developers of Pressbooks. Hopefully by communicating what was failing, sharing error messages, and documenting the problems the developers can make the program stronger for all open source users.

As a non-coder in an open-source community, that’s often how I feel I can contribute to the community. A good error report can save the developers time if we can identify exact what is broken. I can play detective for them so that they can fix the problem. I opened up issues on GitHub about the PB-MathJax installation process, and shared the error messages when it fails to install with the current versions of NodeJS. While I eventually got MathJax to successfully install, and I started the microservice, I was also able to start a conversation about mixed media errors happening in the Pressbooks browser that the developers can look at.

I was pretty disappointed I wasn’t 100% successful today, but after a few conversations with Steel Wagstaff at Pressbooks and some bug reports on Github, I feel like I have contributed to the community. I was also able to document the installation for Reclaim Hosting, who had previously had a hard time troubleshooting MathJax.

Leave a Reply