{{ message }}

# sphinx-doc / sphinx Public

Closed
opened this issue Jul 14, 2021 · 7 comments
Closed

opened this issue Jul 14, 2021 · 7 comments
Labels
Milestone

### cpitclaudel commented Jul 14, 2021

 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 
added a commit to cpitclaudel/MyST-Parser that referenced this issue Jul 19, 2021
 [draft] Remove option mathjax_classes 
 53cfef5 
The global approach in 395 isn't really sustainable: it requires all-ways
cooperation between all projects that want to customize MathJax.  Additionally,
when processing a MyST document without Sphinx, the MathJax configuration
changes are not performed (part of executablebooks#347).  And, of course, this approach of
overriding the MathJax object causes issues down the line for projects that need
to customize MathJax (the setting in Sphinx isn't sufficient, see sphinx-doc/sphinx#9450)

The following two approaches would not cause these issues:

something like this, essentially:

js
var MathJax = window.MathJax || MathJax;
MathJax.options = MathJax.options || {};
MathJax.options.processHtmlClass = (MathJax.options.processHtmlClass || "")
+ "|math";
""")


- Don't touch MathJax_config at all; instead, add an explicit mathjax_process
class on all math nodes, either by changing docutils_renderer (this PR) or by
adding a Docutils transform to processes all math nodes:

python
class ActivateMathJaxTransform(Transform):
default_priority = 800

@staticmethod
def is_math(node):
return isinstance(node, (math, math_block))

def apply(self, **kwargs):
for node in self.document.traverse(self.is_math):
node.attributes.setdefault("classes", []).append("mathjax_process")


This PR isn't ready for merging; it's just to start a discussion.
mentioned this issue Jul 19, 2021
added this to the 4.2.0 milestone Jul 23, 2021

### tk0miya commented Jul 23, 2021

 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.

removed this from the 4.2.0 milestone Sep 12, 2021
added this to the 4.3.0 milestone Sep 12, 2021

### cpitclaudel commented Sep 13, 2021

 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 commented Nov 8, 2021

 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.

mentioned this issue Nov 8, 2021
closed this in  4cd19b8  Nov 9, 2021
added a commit that referenced this issue Nov 9, 2021
 Merge pull request #9829 from tk0miya/9450_load_mathjax_as_defer 
 563936b 
Close #9450: mathjax: Load MathJax via "defer" strategy`

### raphaeltimbo commented Nov 12, 2021

 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 commented Nov 17, 2021

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

mentioned this issue Nov 18, 2021

### raphaeltimbo commented Nov 18, 2021

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

### tk0miya commented Nov 18, 2021

 Thanks!

bot locked as resolved and limited conversation to collaborators Dec 19, 2021