Update mkdocs-material
We are using an ancient version of mkdocs-material, and therefore are missing a bunch of bugfixes and performance improvements. We're also risking that the whole contraption collapses due to software rot. Additionally, we're using a hacky way to execute inline code (a separate script that copies all the files outside of the mkdocs build process.
The upgrade is involved, and requires solving a lot of entangled issues. Below I outline these, mostly for myself to keep track of what there is to do.
-
Implement execution as a function hook
plugin- Fix the "link to a missing file" warning by creating "virtual files"
- Double-check handling of non-image outputs (plotly)
- Update the source for mathjax to render properly: it expects blocks to be separated by newlines.
- Add CSS workaround for formula vertical scrollbars here
- Fix plotly rendering and separate loading the data. This might remove the requirejs dependency that doesn't play nicely with mkdocs.
- Check if single page app works: this will require hooking plotly rendering to page transitions.
-
Plotly relies on mathjax2, while mkdocs-material uses mathjax3, so we need to fix this by using one alternative below or both.
- Switch to server-side rendering of math. This requires adding a node app, along the lines shown here.
- Introduce a compatibility layer, outlined in mathjax docs. This may be tricky because plotly wants an SVG renderer and we want chtml one for the rest.
-
As a fallback we could avoid latex in plotly entirely (it doesn't work in 3D plots anyway).
- Update/rebuild the docker image and CI.
- Reenable thebe. This is a stretch goal, and will probably deserve an issue of its own.