Upgrade MathJax and configurable url

[ickc]

Currently in https://github.com/getnikola/nikola/blob/8cc31e0230a7209cc0bca558a9d085b2e179fe8c/nikola/data/themes/base-jinja/templates/math_helper.tmpl#L30, it loads MathJax 2.7.

The feature request is to allow this url be configurable (similar to pandoc for example), and/or upgrade it to MathJax 3.1.

See upgrading the default MathJax version is backward incompatible, the path here may be just letting it configurable (user supplied URL) and let the user decide.

[Kwpolska]

This will be a very rarely-used feature. I don’t think we should make it a config option, you can just edit your templates if you want that change. Switching the version used by Nikola to 3.x is also something we could think about — we’ll accept a PR with that change, if it also includes proof that it’s compatible with typical usage.

[ickc]

Just notes to others than might need this:

the way to do it in Nikola without changes on their part is to disable the internal MathJax mechanism and setup on your own say in the header, conveniently available in conf.py.

This is working for me that I setup pandoc as the markdown compiler and use the --mathjax flag. I’m not sure if disabling Nikola mathjax with the default compiler would be working for math.

this means that has_math is not needed, a side effect that all your posts has mathjax loaded regardless.

a note on this being classified as rarely used: it is surprising to hear that especially when MathJax in Nikola is still 2.x. In MathJax 2 there are a lot of MathJax configuration to choose from, and it would be very rare that you think you should configure the MathJax without choosing an appropriate corresponding config file (those TeX…CHTML or SVG preconfigured file.) Since configuring MathJax is supported in Nikola, it is very weird that it wouldn’t allow you to change that file, corresponding to changing the url.

also, while MathJax 3 is backward incompatible, it shouldn’t be in the case of default configuration. If you upgrade MathJax to 3 without allowing people to configure URL, and if they have custom MathJax config (which is incompatible between 2 and 3) then you don’t have a good path pushing this update, you either break everyone’s config and force them to use MathJax 3, or let them choose the URL and default to 2.7 for backward compatibility.

Therefore I must say @Kwpolska’s judgement on the issue is rather strange, especially they think proof is needed to demonstrate it is “compatible”, and closing this so prematurely.

[Kwpolska]

0. Remember we are a volunteer-run open-source project, we aren’t paid for our work on Nikola, and do it on our free time. We reserve the right to say no due to a feature request introducing too much non-productive work for us, or if a feature request does not match our vision for Nikola, or for any other reason.
1. Adding yet another config option (I think we have too many) is mostly a burden on us. We (the maintainers) would be then expected to provide support for this option, to document it, to test it, etc.
2. To 99% of users, the MathJax version and specific configuration is an implementation detail.
3. If we expose MATHJAX_VERSION as a config variable, should we also expose KATEX_VERSION? Or BOOTSTRAP4_VERSION? In my mind, not everything should be a configuration variable. But users can still customize the behavior using template overriding. For example:
4. Users that do want a different MathJax version, can easily override math_helper.tmpl in their sites (nikola theme -c math_helper.tmpl + change the version there + maybe adjust mathjax.js if necessary).
5. We, as maintainers, test and verify the impact of PRs/contributions, but we expect the PR author to also help us with this. Since we’re dealing with a potentially incompatible change, we need to have proof it doesn’t break existing sites. A PR author would be expected to help provide this proof. If we don’t have this proof, then we can’t merge it.
6. Note that a large share of MathJax usage in Nikola comes from Jupyter Notebooks. I just fired up JupyterLab version 3.0.13, and it is using MathJax 2.7.9, which is an argument against upgrading Nikola’s version.

[ickc]

Remember we are a volunteer-run open-source project, we aren’t paid for our work on Nikola, and do it on our free time.

I stopped reading right there. I didn’t forget that.

Remember we are volunteer in filing issue as well. And there’s better way to manage open source project. The opening issue is a succinct description where anyone experienced enough with MathJax will immediately understand. If you don’t understand the benefits, you could have ask for more info. But you straight jump to conclusion that it is rarely used and closing it immediately is IMO the wrong way of managing open source software. Who said that I wasn’t about to create PR if you asked? But I also think instead of jumping right into a PR it should have been discussed and agreed it is a good direction first.

That said, your repo, your call. Feel free to maintain your repo and from now on I’ll not speak again here and it likely to be a waste of time.

[Kwpolska]

I have stated my reasons why we are not accepting a MATHJAX_VERSION config option and why we probably won’t upgrade to MathJax 3.x soon in the post you didn’t read.

[ickc]

I have stated the reason why this is needed in https://github.com/getnikola/nikola/issues/3551#issuecomment-832204301 that you didn't read clearly.

In any case, this is beyond this single issue. As I stated earlier, I have my solution before filing this issue. The intention was to have a better design for the community. Whether this is better is subjective, but the way it is handled is the main issue.

Anyway, your call. No hard feelings.

[ickc]

Also the argument that Jupyter is also using MathJax 2 is not really an argument. Any sane open source maintainer at least will leave the issue open when the times has come. That's why I emphasized this is your call, because only that would make sense.