The configuration format for MathJax v3 is changed

[bryanwweber]

Describe the bug
Pull request #7961 introduced MathJax v3, to be released in the next major version of Sphinx. However, there is not yet support for the new configuration format for MathJax. In particular, MathJax v3 no longer uses the nested MathJax.Hub.Config object, preferring instead to use simply MathJax.

To Reproduce

Include some mathjax_config values in conf.py and set mathjax_path to point to MathJax v3 (or use the main branch).

Following the conversion guide here: https://mathjax.github.io/MathJax-demos-web/convert-configuration/convert-configuration.html

This generated configuration using Sphinx 3 and MathJax v2:

MathJax.Hub.Config({

  "TeX": {"Macros": {"vector": ["\\vec{#1}", 1]}}, "tex2jax": {"inlineMath": [["\\(", "\\)"]], "displayMath": [["\\[", "\\]"]], "processRefs": false, "processEnvironments": false}

});

with this config parameter: MathJax.js?config=TeX-AMS-MML_HTMLorMML results in this new MathJax v3 configuration:

<script>
window.MathJax = {
  tex: {
    macros: {
      vector: ["\\vec{#1}", 1]
    },
    inlineMath: [["\\(", "\\)"]],
    displayMath: [["\\[", "\\]"]],
    processRefs: false,
    processEnvironments: false,
    autoload: {
      color: [],
      colorV2: ['color']
    },
    packages: {'[+]': ['noerrors']}
  },
  options: {
    ignoreHtmlClass: 'tex2jax_ignore',
    processHtmlClass: 'tex2jax_process'
  },
  loader: {
    load: ['[tex]/noerrors']
  }
};
</script>
<script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js" id="MathJax-script"></script>

The last line there is handled by the mathjax_path, but the rest of it can't be handled by the current mathjax_config option, which assumes that MathJax.Hub.Config should be present. See also: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax_config

Expected behavior
MathJax is configured properly.

Environment info

• OS: Tested on macOS, presumably any
• Python version: Tested on 3.8, presumably any
• Sphinx version: Currently, only master by default, but any version is mathjax_path is set to point to v3.
• Sphinx extensions: sphinx.ext.mathjax
• Extra tools: Tested on Firefox, presumably any browser

Additional context

• Found in the context of building a Jupyter Book: MathJax version 3 support executablebooks/jupyter-book#963

[mgeier]

Sphinx 4 is coming out in a bit more than a month, are there any news on this issue?

For starters, this should get the proper milestone assigned so that it isn't overlooked when the time comes ...

[tk0miya]

Thank you for the reminder. I perfectly missed this. And I still don't understand what we should do. Can anybody send a pull request for this issue?

[bryanwweber]

I'm happy to try a fix. Is there interest in supporting both MathJax 2 and 3? Or can a fix be specific for MathJax 3?

[asmeurer]

Is the default mathjax version going to change in Sphinx? Can the configuration be changed in a backwards compatible way, so that existing configuration will continue to work with mathjax 3 when upgrading?

[bryanwweber]

@asmeurer Yes, the default version is currently set to change (see #7961). It seems as though the configuration changes are non-trivial between v2 and v3 of MathJax, and trying to write a backwards compatible configuration format will be tricky. That's why I asked if there was interest in trying to support both.

I think the easier way to retain "backwards compatibility" is for end-users who don't want to update to MathJax v3 to change their mathjax_path to point to MathJax v2, as suggested in the documentation: https://www.sphinx-doc.org/en/master/usage/extensions/math.html?highlight=mathjax#module-sphinx.ext.mathjax This would require no other configuration changes.

That's a good point though, that configuration for MathJax 3 could probably happen with a different variable name (the current is mathjax_config).

[mgeier]

What about using mathjax2_config and mathjax3_config?

mathjax_config could then be an (at some point deprecated) alias for mathjax2_config.

[tk0miya]

I'm happy to try a fix. Is there interest in supporting both MathJax 2 and 3? Or can a fix be specific for MathJax 3?

I don't know how many users want to keep using old versions. But it would be better if we can support both for a while.

What's the difference in configurations between v2 and v3? If they are almost the same or very similar, it might be better to set up them via mathjax_config setting with introducing a new configuration mathjax_version = 2 | 3 (as a migration step). What do you think?

[asmeurer]

One way maintain backwards compatibility would be to maintain mathjax_config as @mgeier suggested, and use MathJax 2 if it is defined (but it can be deprecated in the meantime). That way existing users with configuration will continue to have that configuration applied until they upgrade it to mathjax3_config. The default if no configuration is defined can be MathJax 3.

[asmeurer]

What's the difference in configurations between v2 and v3?

Version 3 is a complete rewrite. See https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html. In particular, it completely changes the API for configuration, so it is not backwards compatible.

Also, from https://docs.mathjax.org/en/latest/upgrading/v2.html#v2-configuration-changes:

MathJax v3 is still a work in progress; not all features of version 2 have been converted to version 3 yet, and some may not be. MathJax v2 will continue to be maintained as we work to move more features into version 3, but MathJax v2 likely will not see much further development, just maintenance, once MathJax v3 is fully converted.

So it makes sense to continue to support both versions for the time being. There will probably be some users who cannot easily upgrade to version 3.

[bryanwweber]

What's the difference in configurations between v2 and v3? If they are almost the same or very similar, it might be better to set up them via mathjax_config setting with introducing a new configuration mathjax_version = 2 | 3 (as a migration step). What do you think?

As @asmeurer mentions, the configuration format is completely different. I also posted an example of the new configuration in the OP of this thread. So direct translation of v2 to v3 configuration is non-trivial, unfortunately.

I like the suggestion from @asmeurer to use MathJax v2 if mathjax_config is specified and issue a deprecation warning. That will give people who don't have time to change right away a little runway to deal with it. It will also avoid breaking anyone's website if they don't specify an upper version limit for Sphinx in their requirements (which is very common).

MathJax v3 will then be configured by mathjax3_config, and if neither is specified, MathJax v3 is used by default.

One slight modification of that approach would be to introduce a mathjax2_config variable instead of mathjax3_config, and let mathjax_config do the configuration for MathJax v3. Then the fix for people who want to stay on v2 is just to change the name of a configuration variable, and mathjax2_config can continue to be supported as an option until MathJax themselves drop support for v2, without a whole circle of deprecations of configuration variables. I can also try to do some introspection of mathjax_config to see if it looks like it's configuring for v2 and issue a warning. I think I like this approach better, although it is somewhat more disruptive, because sites which are currently working will break if they update to Sphinx 4 without making any other changes.

[asmeurer]

I like that my approach requires no changes to the config to continue working. Although if we can reliably detect the difference automatically that also sounds like it could be a good idea.

Another thing that should be fixed is the link to the MathJax docs at https://www.sphinx-doc.org/en/master/usage/extensions/math.html#confval-mathjax_config (unfortunately, MathJax 404ed all old docs links at some point).

[tk0miya]

I posted #8940 that introduces a new configuration value mathjax_version to choose the version of Mathjax. And it controls the form of mathjax_config. What do you think?
#8940

I prefer to keep using mathjax_config for v3 as in the past. So adding a new configuration for the version is better to me.

[mgeier]

@tk0miya I think the problem with mathjax_version is that now there are two ways to select the MathJax version: mathjax_path and mathjax_version.

What if they disagree?

@asmeurer

One way maintain backwards compatibility would be to maintain mathjax_config as @mgeier suggested, and use MathJax 2 if it is defined (but it can be deprecated in the meantime). That way existing users with configuration will continue to have that configuration applied until they upgrade it to mathjax3_config. The default if no configuration is defined can be MathJax 3.

This has the advantage that it will not be disruptive, but I fear that it might slow down adoption of MathJax 3.

I think it would be better to to raise a warning (or even an error?) if mathjax_config is set (and mathjax_path is unset). This way, people will be nudged towards changing their config and their users can enjoy the new MathJax version.
This will be a breaking change for people who use mathjax_config, but that's the whole reason why this is happening at a major version bump, isn't it?

[tk0miya]

I think the problem with mathjax_version is that now there are two ways to select the MathJax version: mathjax_path and mathjax_version.

Agreed. But, we need to configure both URL and configuration method (MathJax.Hub.Config vs window.MathJax). So there are two configurations if we'll add mathjax3_config instead.

And I suppose who want to control the version of mathjax via mathjax_path is rare. So the problem can be ignored, I think.

What if they disagree?

What do you mean? I think mathjax_version is one of the candidates for the new configuration. So I'm okay to withdraw my idea if it's not good. I will adopt the best one.

About mathjax3_config:

Personally, I prefer not to use a version number to the configuration name. It means we'll have to introduce mathjax4_config in the future (even if its format is not changed). But it's an advantage to be able to raise a warning.

[bryanwweber]

What if they disagree?

What do you mean?

I think @mgeier means what if the version set in mathjax_version and the version set in mathjax_path disagree. But it seems like you're advocating to remove the mathjax_path option, or maybe to rely on users to keep the path in sync with the version? I don't think it would be as rare as one might expect, for a few reasons. Perhaps people prefer to load from their own CDN or their local directory rather than a CDN, or perhaps people prefer to change the query parameters and use a larger or smaller subset of the MathJax suite. I think it would be best to keep mathjax_path as an option, if at all possible.

It means we'll have to introduce mathjax4_config in the future (even if its format is not changed). But it's an advantage to be able to raise a warning.

How would you feel about introducing a mathax2_config option instead? Then the default configuration for mathjax_config can be for v3 and it isn't necessary to have mathjax4_config in the future.

[tk0miya]

But it seems like you're advocating to remove the mathjax_path option, or maybe to rely on users to keep the path in sync with the version?

I don't think to deprecate mathjax_path at all. My idea is only adding a new configuration mathjax_version to modify both the default value of mathjax_path and the behavior of mathjax_config once.

Any contradiction will happen even if we don't introduce mathjax_version. What will happen if user gives v2 URL for mathjax_path and v3 option for mathjax_config (or mathjax3_config).

How would you feel about introducing a mathax2_config option instead?

Acceptable.

Note: minor concerns:

• In this case, users should set both mathjax_path and mathjax2_config to keep using v2.
• Additionally, it's difficult to raise a warning for v2 users (if they've configured mathjax_config)

[mgeier]

Any contradiction will happen even if we don't introduce mathjax_version. What will happen if user gives v2 URL for mathjax_path and v3 option for mathjax_config (or mathjax3_config).

The v3 configuration will be inserted into the HTML, and it will of course not work, as expected.
This is the fault of the user, because they have to use the right config mathjax2_config or mathjax3_config for whatever version they chose with mathjax_path.
This is no problem, because the user is actively choosing mathjax3_config, so they should see that it doesn't match their path setting.

If a user is already (pre-Sphinx-4) using mathjax_path and mathjax_config, it would be great if it could keep working.

If a user is using mathjax_config but no mathjax_path, a warning should inform them that the default MathJax version has been changed.

I think a mathjax_version setting just complicates things.

About mathjax3_config:

Personally, I prefer not to use a version number to the configuration name. It means we'll have to introduce mathjax4_config in the future (even if its format is not changed). But it's an advantage to be able to raise a warning.

I expect it will take many years until MathJax 4 comes out.
And then it is very likely that the config format will change again.

And if it doesn't change, there isn't really a problem with adding mathjax4_config as an alias to mathjax3_config.

How would you feel about introducing a mathjax2_config option instead? Then the default configuration for mathjax_config can be for v3 and it isn't necessary to have mathjax4_config in the future.

This would break all instances that are currently using mathjax_config, without any warning. It would be great if we could do better.

We haven't really talked about what should happen when both mathjax2_config (or its alias mathjax_config) and mathjax3_config are given.
I think that in this case both configs should be inserted into the HTML.

I think for a normal user that's fine, but how would a Sphinx extension be able to change the default MathJax settings for both versions?

For example, I'm changing the default MathJax settings in my nbsphinx extension: https://github.com/spatialaudio/nbsphinx/blob/31df9169555b31d663972507449a45937da5fbce/src/nbsphinx.py#L2258-L2266

How can I do this without always inserting two configs into the HTML file?

[bryanwweber]

This would break all instances that are currently using mathjax_config, without any warning. It would be great if we could do better.

@mgeier This is predicated on being able to detect differences between a dictionary meant to configure v2 and one meant to configure v3. In the former case, a warning would be issued and users should change the variable name to mathjax2_config (and using mathjax2_config can automatically trigger changing the mathjax_path to v2 if it isn't set). I really think this is a better option than introducing mathjax3_config because it simplifies long-term maintenance of the set of options.

I think for a normal user that's fine, but how would a Sphinx extension be able to change the default MathJax settings for both versions?

Why do you need to set config for both versions? IMO, you can upgrade nbsphinx to support v3 and put a note in your docs that if you want to keep using v2 you have to do X, Y, Z configuration in your conf.py file.

(Off topic, thank you for developing nbsphinx, I've used it in several projects and it has always worked wonderfully!)

[bryanwweber]

As it happens, there actually is a common way to configure both versions, at least in terms of the JavaScript assignment. So I don't think it's necessary to introduce two variables. The specific option names are different and can't really be converted (or at least, I don't want to try to do that), but it's easy enough to warn when something looks like v2. I made a PR this afternoon! #8971

[mgeier]

Why do you need to set config for both versions?

To avoid breakage.

Most nbsphinx users won't use any MathJax settings (neither URL nor config), but nbsphinx still uses a custom config (as mentioned above: https://github.com/spatialaudio/nbsphinx/blob/31df9169555b31d663972507449a45937da5fbce/src/nbsphinx.py#L2258-L2266).

If nbsphinx switches to MathJax 3 before Sphinx 4 comes out, the HTML rendering will be partially broken without warning.

If nbsphinx switches to MathJax 3 after Sphinx 4 comes out (or if some users don't upgrade to the latest nbsphinx release immediately), for a while, users will get a (for them) cryptic warning message about setting mathjax_path, which is really not what they should do.

IMO, you can upgrade nbsphinx to support v3 and put a note in your docs that if you want to keep using v2 you have to do X, Y, Z configuration in your conf.py file.

Even when assuming that the releases are perfectly timed (see above), this would still be very annoying for people who have selected MathJax v2 with mathjax_path.

Because those won't get any warning, but their equations will be broken (if they use single $ delimiters in cell outputs)!

(Off topic, thank you for developing nbsphinx, I've used it in several projects and it has always worked wonderfully!)

Thanks, that's nice to hear!

I've looked at #8971 and I didn't know that the window.MathJax approach works for both versions.
This is great to know!
This way, in the nbsphinx code I can indeed simply add both versions of the configuration to mathjax_config and it works.
But the warning is generated, which is bad.

[mgeier]

PS: in case you want to try it out, I've just created an experimental PR for nbsphinx: spatialaudio/nbsphinx#544

[bryanwweber]

@mgeier I was thinking about adding a configuration option for "don't warn me, I really know what I'm doing," but I couldn't come up with a good name. But adding the logic for that would be trivial, just an extra condition on the if leading to the warning. Maybe suppress_v2_warning?

[mgeier]

There is no need for a custom option for suppressing warnings, because Sphinx already has suppress_warnings.

If you add a warning type and subtype to your warning, it can be silenced without silencing all other warnings.

However, silencing this warning isn't really a solution for my use case.
I would like the settings added by nbsphinx not to raise the warning, but if at the same time a user defines mathjax_config with the wrong version's syntax, the warning should be raised!

[bryanwweber]

I would like the settings added by nbsphinx not to raise the warning, but if at the same time a user defines mathjax_config with the wrong version's syntax, the warning should be raised!

@mgeier I'm not sure how this could work using the suppress_warnings functions. What if I move the "suppress" option into the mathjax_config dictionary? That way, if you're updating a default value for the mathjax_config dictionary, and a user overrides that with their own mathjax_config, their version won't include the warning suppression unless they enable it.

[mgeier]

I'm not sure how this could work using the suppress_warnings functions.

I guess it wouldn't work.

What if I move the "suppress" option into the mathjax_config dictionary? That way, if you're updating a default value for the mathjax_config dictionary, and a user overrides that with their own mathjax_config, their version won't include the warning suppression unless they enable it.

This sounds very much like a hack. I hope there is a better way.

What about using mathjax2_config (or mathjax_config) and mathjax3_config?

This would be very simple, easy to use and no heuristics are needed to automatically detect the desired MathJax version.

And let me quote the Zen of Python:

• "Explicit is better than implicit." It would be good if the MathJax version is visible in the configuration variable.
• "In the face of ambiguity, refuse the temptation to guess." mathjax_config is ambiguous, so we shouldn't guess the actual version based on its contents.

[bryanwweber]

This sounds very much like a hack.

It doesn't to me... it sounds like a user is configuring their Sphinx build. In that sense, what you're already doing with nbsphinx could probably be considered a hack, and this seems like a reasonably elegant option. The only reason I didn't put it in the dictionary in the first place was because the other items in mathjax_config are put into the actual MathJax configuration JavaScript, they aren't configuring Sphinx like a warning suppression would. But I can see the value in your use case, and I think it's reasonable to support that.

What about using mathjax2_config (or mathjax_config) and mathjax3_config?

My personal preference is really to avoid version-specific configuration variables, especially ones that will be removed at some point in the future. It seems that @tk0miya also agrees with this perspective. If you feel very strongly that separate configuration variables are necessary, feel free to create your own pull request and the maintainers of the package can decide which they like.

FWIW, I also don't put very much stock in appeals to arbitrary authority which support one's viewpoint. If that is your viewpoint, then just flat out state it, it's fine we can have different opinions. The Zen of Python is ambiguous enough to be interpreted to support any viewpoint, e.g.,

Simple is better than complex. Complex is better than complicated.

One configuration variable is less complex and less complicated than two/three for a user.

There should be one-- and preferably only one --obvious way to do it.

One configuration variable is more obvious for a user than two/three.

[asmeurer]

Hi all. I'm catching up on this thread, and only skimmed things so I apologize if I am saying something that was already said.

This has the advantage that it will not be disruptive, but I fear that it might slow down adoption of MathJax 3.

I don't think this is a huge issue. The documentation can show how to configure MathJax 3, so that it becomes the default for new projects. I forget if there's a commented out section in conf.py, but if there is, that can be updated too.

Given that MathJax 2 is itself not yet deprecated (#8195 (comment)), I am -1 to warning or erroring if it is being used. I expect there are some corner cases of things that don't yet work in MathJax 3 that may prevent some projects from updating.

Regarding mathjax_path, It is not the same as mathjax_version. It can be used to set a custom path to the MathJax Javascript. For example, you may want to host the Javascript yourself to avoid hitting the CDN. As far as I understand mathjax_path is the only way to do that. If you want to add a mathjax_version as well to simplify the common configuration, I would suggest making it an error to specify both.

As I said before, please make it so existing projects do not break. This means the MathJax version should not change out from under a project so that its mathjax_config stops being valid. This would be especially bad if it didn't result in any warnings from Sphinx, only math that doesn't render like it used to. That sort of thing happened to me once and I went weeks before noticing that none of my math was actually rendering on the page (this can easily happen, e.g., if you reconfigure the default math delimiters).

If it's possible to automatically make the same config work with both versions, and a specific mathjax version isn't specified, I think it would be acceptable to automatically push a project to MathJax 3. It's not clear to me exactly, can one version's config be automatically translated to the other's or are they too different?

[bryanwweber]

Given that MathJax 2 is itself not yet deprecated (#8195 (comment)), I am -1 to warning or erroring if it is being used. I expect there are some corner cases of things that don't yet work in MathJax 3 that may prevent some projects from updating.

At least in my PR (#8971), a warning is only issued when MathJax v3 at the default URL is being used with something that looks like a v2 configuration dictionary. This seems appropriate, and will prompt people to either change the mathjax_path or update their configuration.

If it's possible to automatically make the same config work with both versions, and a specific mathjax version isn't specified, I think it would be acceptable to automatically push a project to MathJax 3. It's not clear to me exactly, can one version's config be automatically translated to the other's or are they too different?

The config is quite different between the versions. MathJax provides a page that will do the conversion if you copy in your JavaScript code, so I don't think it's something that Sphinx should try to do automatically. However, it is possible to set a single variable that will configure v2 and v3. In v2.3 and up it's possible to shove the configuration mapping into a JavaScript object (I'm not sure of the correct name for that) called window.MathJax before MathJax is loaded, and MathJax will look there to find configuration. Since v2.3 was released in 2013, I hope it's safe to assume that people are updated past that.

As it stands, since #7961 has already been merged, v3 will become the default version for all projects that haven't set a mathjax_path as of Sphinx 4.0, including existing projects. I'm not sure what the best way forward is to limit the fallout. As I've said in other comments, my personal preference is not to introduce versioned configuration arguments, and I think the implementation in #8971 is a decent compromise solution that allows people flexibility to continue using v2 as long as they set the mathjax_path to point to v2, without changing their configuration. People who have already set mathjax_path to a custom version should see no changes at all, as long as they're using MathJax 2.3 or higher. On the other hand, if you've been using the default mathjax_path, you'll get a warning that either your configuration needs to be updated or you need to set a mathjax_path pointing to v2.

[asmeurer]

As it stands, since #7961 has already been merged, v3 will become the default version for all projects that haven't set a mathjax_path as of Sphinx 4.0, including existing projects. I'm not sure what the best way forward is to limit the fallout. As I've said in other comments, my personal preference is not to introduce versioned configuration arguments, and I think the implementation in #8971 is a decent compromise solution that allows people flexibility to continue using v2 as long as they set the mathjax_path to point to v2, without changing their configuration. People who have already set mathjax_path to a custom version should see no changes at all, as long as they're using MathJax 2.3 or higher. On the other hand, if you've been using the default mathjax_path, you'll get a warning that either your configuration needs to be updated or you need to set a mathjax_path pointing to v2.

This sounds reasonable to me.

[mgeier]

This sounds very much like a hack.

It doesn't to me... it sounds like a user is configuring their Sphinx build.

You were talking about defining a "magic" dictionary key that causes a special behavior, while all others are systematically added to a JavaScript object.

That simply sounds like a hack, and not like what a user would normally want to do.

In that sense, what you're already doing with nbsphinx could probably be considered a hack,

Oh yes, very much so!
nbsphinx uses a very ugly hack to define its desired default settings for mathjax_config.

If you know a better (less hacky) way to implement this, please let me know!
I would really like to make nbsphinx less hacky, because currently it uses very many hacks.

and this seems like a reasonably elegant option.

Well you shouldn't take hacks in other projects (e.g. nbsphinx) as an excuse for adding a bad API to Sphinx.

And a hack in the implementation is much less bad than a hack that's exposed to the API surface (in form of a configuration value).

The only reason I didn't put it in the dictionary in the first place was because the other items in mathjax_config are put into the actual MathJax configuration JavaScript, they aren't configuring Sphinx like a warning suppression would.

Exactly.

What about using mathjax2_config (or mathjax_config) and mathjax3_config?

My personal preference is really to avoid version-specific configuration variables,

I agree.

But it still might be the least bad option ...

It seems that @tk0miya also agrees with this perspective. If you feel very strongly that separate configuration variables are necessary, feel free to create your own pull request and the maintainers of the package can decide which they like.

I think collaboration would be better than competition in this case.

And I don't feel strongly that separate configuration variables are necessary. I simply don't know yet. I don't have the feeling that they should be ruled out at this point. I have the feeling that there might be a better solution that hasn't been proposed yet.

The problem for my use case is that (AFAICT) just having separate configuration values doesn't solve my problem either.

FWIW, I also don't put very much stock in appeals to arbitrary authority which support one's viewpoint.

I'm not using the Zen of Python as an authority, and I don't think it has been created with that intention.

I'm using it to provide food for discussions, and I think it's great for that.

If that is your viewpoint, then just flat out state it, it's fine we can have different opinions.

I don't have a fully formed opinion yet.

My viewpoint is that there hasn't been a proposal that's clearly better than two separate configuration values for MathJax version 2 and 3.

I'm not saying the best solution will necessarily have those two configuration values, I'm just saying it would be good to stay open-minded and consider all suggestions that have been made in this discussion here.

The Zen of Python is ambiguous enough to be interpreted to support any viewpoint,

Yes, that's why it is so great!

e.g.,

Simple is better than complex. Complex is better than complicated.

One configuration variable is less complex and less complicated than two/three for a user.

One configuration variable that's used for different things in different circumstances is in fact more complex than two separate configuration variables that each do their own thing.

There should be one-- and preferably only one --obvious way to do it.

One configuration variable is more obvious for a user than two/three.

According to this, there should be one obvious way to configure MathJax v2 and one obvious way to configure MathJax v3.

I don't think this means that there should be one way to do two different things, depending on which Sphinx version is used (or some other non-obvious internal state).

[tk0miya]

It's difficult for me to decide which idea is better. But we need to choose one for v4.0 release. So I'd like to vote @mgeier 's idea. It's enough simple, and it helps the implementation of nbsphinx.

@mgeier Do you have time to create a PR? If possible, it would be helpful to me.

[mgeier]

The problem is that I don't know how to solve my problem mentioned above either way.

I've created a draft PR #9094 which mentiones the problem in a bit more detail.

In their current form, both #8971 and #9094 have the same problem.

[mgeier]

I just found a way to make #9094 work reasonably well with my nbsphinx problem, see spatialaudio/nbsphinx#558.

I don't think a similar solution would be possible with #8971.

[bryanwweber]

Thanks @mgeier and @tk0miya! I'll be excited to see this resolved and be able to use MathJax v3!

[tk0miya]

Now I merged #9094 into the 4.0.x branch. So Sphinx-4.0.0 will support MathJax v3 perfectly. Thank you for your support, @mgeier, and @bryanwweber!