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.
Edited by Anton Akhmerov