pandocs

pandocs copied to clipboard

We have a couple of formulas in Pan Docs, especially when sound is involved: for example, X(t) = X(t-1) +/- X(t-1)/2^n in the "Channel 1 Sweep register" section.

I believe formulas typeset like this are hard to read, so I looked for alternatives, and found MathML (HTML5 spec), which is very nice... but doesn't work in Chrome besides version 24 (current is 92).

Another alternative would be Mathjax, which mdBook natively supports; however, the JS-less experience may be degraded, and the page layout may shift while the formulas are being rendered, likely more jarringly on the "single" page.

I finally found mdbook-katex, which pre-renders equations written in LaTeX format, probably in a similar fashion as MathJax, i.e. generating SVGs.

What should we go with?

mdbook-katex looks good, though, looking at its API, it doesn't seem to support changing font color? This would render it incompatible with our themes. MathML doesn't look like its widely adopted, although I'll admit that I'm not really aware of web standards (maybe I'm just ignorant, but it looks like its not supported on Android, for example).

If someone finds a way to change colors according to the theme, mdbook-katex is probably the better option, otherwise, Mathjax wins IMO

Since it [seems to] generate SVGs, I'd assume those are styled to follow the document's stylesheet via CSS variables (like our own diagrams do). Testing is in order, anyway.

Since it [seems to] generate SVGs, I'd assume those are styled to follow the document's stylesheet via CSS variables (like our own diagrams do). Testing is in order, anyway.

Any update on this? It looks promising

I'm working on other stuff, personally, so someone else would have to look into it, or I'll look into it once I'm done with the current items in progress.

We settled on MathML in #350; with the polyfill in place, and Chrome 109 re-adding native support, I think this cements it as our pick going forward. Therefore, closing this as a duplicate of #441.