Support dollar math syntax

[jeanas]

Letting MathJax scrape the output HTML for math delimiters makes it awkward to write complex formulas because characters with a special meaning in Markdown must be escaped. This commit implements a new output.html.math option that uses the support for parsing $...$ and $$...$$ in Markdown introduced in pulldown-cmark 0.11.0. The old option output.html.mathjax-support is left for backwards compatibility.

pulldown-cmark renders formulas into <span> tags with special classes, so we have to configure MathJax to look for these instead of textual delimiters. The code for this was helpfully provided by David Cervone on https://groups.google.com/g/mathjax-users/c/6cMuCH2dgmQ.

The latest version of MathJax 4 is used rather than MathJax 2.7.1 like the mathjax-support option, because the way to do this configuration has changed between MathJax 2 and MathJax 3, I'm not sure how to do it on MathJax 2, and it is an old version anyway. The Cloudflare CDN doesn't seem to work for MathJax 4, so it uses the jsdelivr.net one recommended by the MathJax documentation. In the future, it would be good to use a bundled version of MathJax by default and/or make the CDN URL configurable.

Fixes #1402, fixes #662, fixes #400

[jeanas]

Gentle ping? @ehuss

[jeanas]

Ping?

[GuillaumeGomez]

Hi, we created a new mdbook team to take over and I came across your PR. So a few questions: can this completely replace mathjax? Can you add some before/after differences (ie, how you would do it with this PR vs with mathjax)?

That would help a lot for the review.

[jeanas]

@GuillaumeGomez Depends on what you mean by “completely replace MathJax”. In all cases, MathJax is being used in the reader's browser to render the math. The difference is that with the old option (which is still kept for compatibility), the author writes \\( ... \\), the Markdown renderer doesn't recognize this as math or process it in any special way, this ends up as \( ... \) in the HTML, and then MathJax scrapes the whole HTML page on load to look for \( ... \) delimiters in text elements and replace them with rendered math in the DOM. On the other hand, with the new option, the author writes $ ... $, the Markdown renderer recognizes this as math and produces special HTML tags like <span class="math math-inline">...</span>, and then MathJax looks for these special tags.

The main benefit is that because this has support on the Markdown parser level, characters with a special meaning in Markdown are automatically escaped in $...$, so you can write e.g. $\frac{u_n}{v_n}$ and not \\(\\frac{u\_n}{v\_n}\\) (and since \ starts every LaTeX command and subscripts are used very often in formulas, this gets annoying quickly).

(There might also be a marginal benefit, which I didn't benchmark, from the fact that MathJax doesn't have to look for math delimiters through all text nodes in the HTML page anymore, it can use the browser's DOM APIs to just get all span tags identified by special CSS classes, which should be much faster, although it probably doesn't matter much in the grand scheme of things because that's usually not the most expensive step of math rendering.)

[rustbot]

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[GuillaumeGomez]

Sounds quite close to rust-lang/rfcs#3958. If it's what you're trying to achieve (sorry if I misunderstood), then we might want to get mdbook and rustdoc as close as possible for this feature.

cc @notriddle

[jeanas]

(I rebased on master and made a tweak: after all there is no reason to prevent from using both the new support and the legacy one at the same time (might be useful to convert an existing book piecewise).)

[GuillaumeGomez]

That's why I thought it was a complete replacement since it was an else if condition.

[jeanas]

Sounds quite close to rust-lang/rfcs#3958. If it's what you're trying to achieve (sorry if I misunderstood), then we might want to get mdbook and rustdoc as close as possible for this feature.

cc @notriddle

Interesting. I didn't know there were mature enough LaTeX to MathML renderers implemented in Rust, and that does sound like a superior option to me over MathJax (for error messages, avoiding flashes of raw syntax and readability in environments without JS), so I could update this PR to use the same library as rustdoc would with this proposal. Would you be happy with that?

[GuillaumeGomez]

Yes, but maybe wait until the rustdoc side is implemented so you don't do work for nothing.

EDIT: Saying that because once RFC is merged, we might encounter unexpected issues in the implementation and might change a few things with some back and forth, and I don't want you to have to keep up.

[notriddle]

I think, if this PR was changed to use math-core, I’d be happy to merge it now. Most of the discussion around rustdoc is about how it should be configured, which isn’t directly applicable to mdBook anyway, so waiting doesn’t buy you much.

[GuillaumeGomez]

Just found out about #2069 too.