Add a way to defer loading of MathJax

[cpitclaudel]

Is your feature request related to a problem? Please describe.

It is quite tricky to configure MathJax to work with Sphinx currently.

Sphinx loads MathJax asynchronously since #3606 and #5005. While this was fine for MathJax 2, because of the special kind of <script> blocks mentioned in #5616 , it doesn't work well with MathJax 3.

Indeed, in MathJax 3, MathJax expect a config <script> block to be present before MathJax is loaded. Sphinx 4 added mathjax3_config parameter:

        if app.config.mathjax3_config:
            body = 'window.MathJax = %s' % json.dumps(app.config.mathjax3_config)
            app.add_js_file(None, body=body)

This assumes that the config is a simple dictionary, which isn't sufficient: that configuration should be able to contain functions, for example.

The only possibility at the moment is to add a separate script file containing a MathJax configuration and to load it with app.add_js_file.

Describe the solution you'd like

There are three possibilities:

• Allow arbitrary strings for mathjax3_config, and in that case don't JSON-serialize them.

• Change async to defer when loading MathJax.

• Make it possible for users to change async to defer themselves. At the moment this isn't possible because the async flags is unconditionally added:

      if app.registry.html_assets_policy == 'always' or domain.has_equations(pagename):
        # Enable mathjax only if equations exists
        options = {'async': 'async'}
        if app.config.mathjax_options:
            options.update(app.config.mathjax_options)
  

The latter two are preferable because they would allow individual pages to use different MathJax config by using a .. raw:: block to override the default MathJax configuration on a given page (the script in that raw block will run before MathJax loads thanks to the defer option).

CC @jfbu , the author of #5616.

Thanks!

[tk0miya]

I'm not good at loading JS. Could you let me know the impact of changing async to defer? Are there any incompatible change for users? If not, we can change the loading option for MathJax to defer in the next version.

[cpitclaudel]

I don't think it's an incompatible change. For MDN:

• If the async attribute is present, then the script will be executed asynchronously as soon as it downloads.
• If the async attribute is absent but the defer attribute is present, then the script is executed when the page has finished parsing.

So changing async to defer just rules out certain behaviors (the script starts executing before the whole page is parsed), it shouldn't add any new ones.

[tk0miya]

I found an explanation for this topic:

Note that here we use the defer attribute on both scripts so that they will execute in order, but still not block the rest of the page while the files are being downloaded to the browser. If the async attribute were used, there is no guarantee that the configuration would run first, and so you could get instances where MathJax doesn’t get properly configured, and they would seem to occur randomly.
https://docs.mathjax.org/en/latest/web/configuration.html#using-a-local-file-for-configuration

I believe using defer option instead is a good alternative.

[raphaeltimbo]

Is there a way to have the option to choose async instead of defer?
I am using plotly in my docs and, as discussed in #9563, plotly uses mathjax v2, so I have to force sphinx to also use mathjax v2.
The problem is that with 'defer' plotly graphs stopped rendering.

[tk0miya]

@raphaeltimbo Could you file a new issue, please? I'll fix it soon.

[raphaeltimbo]

@tk0miya, I have filed a new issue as requested. Let me know if you need additional information.
Thank you!

[tk0miya]

Thanks!