Tech update

This site is nearing its 11th anniversary and the past year has not been kind to my writing around here. I can't even say there are a lot of drafts or some such, just a lot of emptiness after lots of hours in ICU waiting rooms and then straight into covid19.

I've been trying to get back to writing here and as these things tend to go, it took spare time over a few months to upgrade the underlying tech instead. A large part of this was playing around with MathJax, which migh seem somewhat silly since I don't write mathematics much anymore. However, I use MathJax a lot for work and it was time to implement a few things I had wanted to dogfood.

The basics

Two years ago, I switched from Jekyll (to which I had at some point added a travis build to run mathjax-node) to eleventy. The primary reason was that I wanted more control over my build and since I work primarily with (vanilla) JavaScript, eleventy was (and continues to be) a very good choice. But I didn't find time to work out a proper integration of mathjax-node so I went back to client-side MathJax (naturally with its accessibility extension active by default).

So obviously I upgraded eleventy which went as smooth as can be - just some minor plugin changes.

the new stuff

The step back to client-side MathJax was supposed to get me two steps forward towards testing my new tech here. But shit hit the fan and here we are two years later.

Since my last significant piece of writing around here, I've been continuing to work on accessible and explorable server-side MathJax rendering (and beyond that more generally "complex" content). I favor MathJax's SVG output for both technical and philosophical reasons but a key problem for the (now retired) mathjax-sre-walker had been that MathJax v2 dropped some internal structure in its SVG output (to get smaller SVGs), which in particular meant that any table construction failed to become explorable.

So really rolling out these exploration ideas meant upgrading to MathJax v3 - which was a bit of a pain, to be honest. I have many (many) feelings about MathJax v3 and should do a post on it at some point. But for now let's just say that I ran into many small bugs, some fixed but not released, others not yet fixed when I found them. All in all, maybe a dozen bugs that just dragged things out.

At the same time, my exploration tooling continued to evolve and mathjax-sre-walker has now been retired in favor of aria-tree-walker as well as sre-to-tree.

Aria-tree-walker is a tiny (<1kb zipped) walker for ARIA trees with a fairly specific markup structure: the tree is marked up via aria-owns and each tree item is named by an aria-label. Sre-to-tree translates SRE's structural information to just such a suitable tree. Rolling out the walker led to me finding several minor bugs found in speech-rule-engine, thus more delay. (But don't get me wrong, Davide and Volker have been super responsive as always when it came to these bugs.)

So 3-4 moving pieces for equations, lots of bugs, lots of growing pains. Fun stuff really and the main point why I wanted to test these technologies here.

markdown

The third part was to integrate these moving pieces back into eleventy. Fortunately, I found an existing markdown+mathjax plugin that was designed to not just ignore TeX content but render it server-side. Unfortunately, markdown-it-mathjax3 wasn't quite flexible enough to let me do my thing. But it helped me solve a major problem: hooking into markdown(-it) processing. So I forked it to hook into my custom MathJax v3 setup.

As a side effect, a ton of markdown content broke because markdown-it-mathjax follows pandoc's TeX-in-markdown rules and my old writing didn't adhere to that. Which took me through a fun romp of my content, fixing lots of stuff, including more errors from previous rewrites (embarassing) and also bugs in the tooling (awesome). Some posts hold up rather well, others not so much; I should maybe write about that some time (ahaha, listen to yourself, man).

Finally, some CSS and JS updates were in order: adding the aria-tree-walker when necessary and styling the exploration - which led to yet more bug reports (yay). After teasing myself on mathstodon I was finally ready to push it out last week. In the end, the setup isn't the most efficient but it's ok for now; a 1 min build time is bareable and yet probably enough pressure to optimize later.

Coda

No next steps as life gets in the way too much these days. Ping me if you have any questions on the setup. For good measure, here's an equation which should - final piece - also render in the atom/rss feed (though exploration will probably fail as most feed readers won't run JavaScript). As described in the aria-tree-walker docs AT users will get the full text in browse mode but can switch to focus mode to explore with arrow keys; visual users can focus the equation (e.g., tab to it or left-click it) and then explore.