Configurable MathJax Support

[podsvirov]

Plan:

• Keap MathJax 2 Support
• Add Configurable MathJax 3 Support
• Update documentation
• Embedded MathJax copy for offline use

Just add few lines to your book.toml:

[output.html.mathjax]
enable = true

I'd be grateful if someone could help me update the documentation (perhaps in the next pull request).

[podsvirov]

MathJax 3 was release in 2020 ear. Currently MathJax 4 alpha also available.

Anybody, please, review this PR. May be I suggest some useful changes...

[ehuss]

Changing the config structure is a breaking change, so you'll need to find a different short-term solution.

Can you say what the differences are between mathjax 2 and 3? Why would someone want to stay with 2?

Why use jsdelivr.net instead of the existing cloudflare cdn?

Why make the source URL configurable instead of embedding the source?

[podsvirov]

Changing the config structure is a breaking change, so you'll need to find a different short-term solution.

You are wrong here. I didn't break anything. I have proposed new functionality that does not conflict with existing configurations.

Can you say what the differences are between mathjax 2 and 3? Why would someone want to stay with 2?

MathJax version 3 is a complete rewrite from the ground up, with the goal of modernizing MathJax’s internal infrastructure, bringing it more flexibility for use with contemporary web technologies, making it easier to use with NodeJS for pre-processing and server-side support, and making it faster to render your mathematics.

Upgrading is everyone's choice. It may or may not be updated. My changes are backward compatible and don't force anyone to update.

Why use jsdelivr.net instead of the existing cloudflare cdn?

This is recommended in the getting started example on the MathJax 3 site.

Why make the source URL configurable instead of embedding the source?

This allows you to select your preferred source. See your previous question.
It also allows you to use the embedded copy of the MathJax 3 as part of your book without external links.

[ehuss]

You are wrong here. I didn't break anything. I have proposed new functionality that does not conflict with existing configurations.

Ah, apologies, I saw that mathjax-support was removed in the first file and misunderstood.

My question about version 2 is about what would happen if mdbook just started to always use version 3? Is the syntax different? What would break?

As for the embedded source, I'm asking about whether or not it would be possible to fix #46 by always using a local copy of mathjax instead of using a CDN. That would allow books to be used offline and to simplify the config (so you don't need to specify a source). How difficult would that be?

[podsvirov]

I think, all is possible.

More from documentation about 2 and 3 version difference:

Some features from version 2 are still being ported to version 3. MathJax version 2 is still available, and you can continue to use that until version 3 includes the features that you need. We will make updates to version 2 until version 3 is complete.

On the other hand, it is a single file (unlike in version 2, where multiple files needed to be loaded), so there should not be the delays associated with establishing multiple connections to a server. If you use the async attribute on the script that loads MathJax, that allows the browser to put off loading MathJax until the rest of the page is ready, so that can help speed up your initial page loading as well.

In the documentation changes, I described how to manually make and use the embedded version of MathJax 3.

More infor about Hosting Your Own Copy of MathJax.

[podsvirov]

@ehuss, review again, please.

[expikr]

would this be able to accommodate the use cases in #2069 ?