search

jbms / sphinx-immaterial

Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system
https://jbms.github.io/sphinx-immaterial/
Other
177 stars 28 forks source link

Enabling MathJax extensions breaks it completely #279

Closed matrach closed 10 months ago

matrach commented 10 months ago

Enabling any MathJax extension (for instance, Accessibility) makes the library request modules from a11l and sre directories. The script errors out and aborts processing because these directories are not present in the local cache:

https://github.com/jbms/sphinx-immaterial/blob/57224a3b05ea5750f4cdb341463a803b87cf9bce/tools/build/index.ts#L138-L143

According to the CDN docs:

Reducing the Size of the Components Directory Since the es5 directory contains all the component files, so if you are only planning one use one configuration, you can reduce the size of the MathJax directory by removing unused components. For example, if you are using the tex-chtml.js component, then you can remove the tex-mml-chtml.js, tex-svg.js, tex-mml-svg.js, tex-chtml-full.js, and tex-svg-full.js configurations, which will save considerable space. Indeed, you should be able to remove everything other than tex-chtml.js, and the input/tex/extensions, output/chtml/fonts/woff-v2, adaptors, a11y, and sre directories. If you are using the results only on the web, you can remove adaptors as well.

If you are not using A11Y support (e.g., speech generation, or semantic enrichment), then you can remove a11y and sre as well (though in this case you may need to disable the assistive tools in the MathJax contextual menu in order to avoid MathJax trying to load them when they aren't there).

But according to my quick research, there is no configuration option to disable fetching those files at all.

How to repreduce

  1. Visit https://jbms.github.io/sphinx-immaterial/additional_samples.html#math
  2. Right click on the math expression -> Accessibility -> Activate
  3. Reload the page

Now the math is not rendered and there is a 404 error from a failed fetching of a11y/sre.js.

How to recover

I had to clear the Local Storage for a given site, because the MathJax context menu is no longer accessible...

2bndy5 commented 10 months ago

Thanks for the detailed report! I'm guessing the fix is to adjust the list of patterns that are copied to the theme's dist (as you noted in OP). Would you like to submit a PR?

2bndy5 commented 10 months ago

Using SVG renderer causes a similar problem: image in web console:

Loading failed for the Githubissues.

  • Githubissues is a development platform for aggregating issues.