Documenter.jl: Switch to KaTeX

[MikeInnes]

KaTeX is much nicer and faster than MathJax and it might be good to switch over. I suspect it's not missing many important features vs mathjax at this point, but if there are downsides we care about it might be good to list them out.

Mentioned in #626.

[mortenpi]

We can probably default to KaTeX, although it would be good to know how their features compare. But it would be nice to be able to configure this, so that people could still keep using MathJax if they need to, so this is slightly blocked by #982.

[tlienart]

Re feature comparison, there's this nice site that gathers what does and doesn't work with KaTeX: https://utensil-site.github.io/available-in-katex/ it may be relevant if for instance using KaTeX by default and suggesting a way for users who would want some of the few non-supported feature to switch to MathJax.

[briochemc]

I wholeheartedly support this! KaTeX looks so much nicer. It would make all math-intensive documentations a lot more attractive. Without KaTeX I am tempted to replace all the math with code, e.g., I'll prefer to display f(x,y) = 0 rather than a misaligned, wrongly-sized (using codecogs in this case). And looking at that list of things that don't render with KaTeX, I would say most are either rare or have workarounds...

Anyway, I don't know if this is helpful but I saw that JuDoc.jl uses KaTeX to generate documentation. Maybe @tlienart has some useful advice on how to get this done?

Also is there any projected timeframe for this? 🙂

[tlienart]

Given the label just before your message it looks like this is on the todo list for the google summer of code.

In terms of insight, I doubt the guys here really need a hand. My only insights from JuDoc are firstly that katex's auto-render script is very useful to get all the math blocks rendered in one shot and secondly that all math elements can be pre-rendered to HTML using katex+node which removes the need for loading the javascript library on all pages containing maths.

Pre-rendering is really nice I think with the downside that it requires users to have node installed on their machine.

[mortenpi]

COMING THIS SUMMER™

[mortenpi]

The switch itself would not be very hard at all, really. But we definitely want to keep supporting MathJax as well, so it should be done properly (i.e. #982), which is planned for the GSoC.

katex's auto-render script is very useful to get all the math blocks rendered in one shot

I think we definitely want this, so I need to take a closer look at this. You use it in JuDoc I presume?

all math elements can be pre-rendered to HTML using katex+node which removes the need for loading the javascript library on all pages containing maths

I was reading JuDoc's code just yesterday and I noticed that. Pre-rendering would be neat, but I am not too keen on having Documenter depend on a Node.js installation. It could make a nice plugin though, which math-heavy docs could opt in to.

[tlienart]

I think we definitely want this, so I need to take a closer look at this. You use it in JuDoc I presume?

Yes, basically unless the user applies the pre-rendering step, this is appended at the foot of generated pages which contain maths:

<script src="/libs/katex/katex.min.js"></script>
<script src="/libs/katex/auto-render.min.js"></script>
<script>renderMathInElement(document.body)</script>

which is all you need (along with the stylesheets in the header).