Upgrading the plugin to MathJax v3

[liffiton]

Pull request #36 contributes some changes that make the plugin work with MathJax v3 instead of v2. v3 has a slightly different way to insert MathJax into a page, and it's not compatible with v2. To upgrade the plugin cleanly, then, we have to be careful about not breaking things for any existing users with customized setups using v2.

Auto-detecting the version feels way too fragile, and it's not feasible in some cases (e.g., self-hosting the libraries with no version in the path). Adding a configuration option to choose between the two versions sounds nice, but the default value should be to use 3.x, and that would make any existing plugin users have that setting. I don't know how to add a new configuration option to the plugin with a default that only applies for a new install and not an upgrade...

One option would be to create a new configuration option like 'url_v3' or similar and set its default to be a CDN URL for Mathjax v3. Then set the existing 'url' option's default to be an empty string. The plugin could do v2-compatible things if the existing 'url' option is set (meaning the user customized it); otherwise, do v3-compatible things. I think the same thing would have to be done for the 'config' option as well. This ends up being unwieldy for the common case, though, with confusing leftover configuration options that aren't used in most cases.

If there are no good options here, it might be best to just release a mathjax3 plugin separately and direct people to it instead of this one. I don't see any critical improvements in v3 for the use case of this plugin, so letting existing installs linger on v2 doesn't cause any harm. (Correct me if I'm wrong, but the only v3 change I see that's relevant to the use here is that it renders faster.)

Ideas are welcome.

[greneholt]

You could use a combination of options. You could try to auto-detect the version from the URL, and if that fails, fall back to a configuration setting that would default to use V2.

So there would be two options: the URL, which defaults to V3, and a select box that asks "MathJax Version to use if URL-based auto-detection fails", which defaults to V2.

If you make the version detection conservative, this should avoid breaking any existing users, while still supporting locally hosted files. One way to do the version detection would be if the URL ends in MathJax.js?config=*, it is V2, whereas if it ends in one of the following, it is V3:

• tex-chtml.js
• tex-chtml-full.js
• tex-svg.js
• tex-svg-full.js
• tex-mml-chtml.js
• tex-mml-svg.js.
• mml-chtml.js.
• mml-svg.js
• startup.js

Alternatively, the auto-detection could look at the configuration syntax. V2 starts with MathJax.Hub.Config, whereas V3 being MathJax = .

One other potential problem is if they haven't modified the default configuration, but have modified the URL. If DokuWiki only saves modified settings (I'm not sure how it handles this), the user could get a V2 manually entered URL with the default settings for V3.