Closed 2bndy5 closed 1 year ago
I found this upstream comment that explains how the mermaid.js lib is used in the theme's JS bundle.
So, I can add the mermaid.js lib to this theme's external resources ext (on build-init if the mermaid ext is enabled), but I'm not sure this fits into the consolidated bundle because the bundled JS is written to load the script from a separate file (only when there are <div class="mermaid">
elements present).
https://github.com/jbms/sphinx-immaterial/blob/f04bc71a5a205dff7884146caf9d3a0e53462d36/src/assets/javascripts/components/content/code/mermaid/index.ts#L72
What I think I need to do is somehow read the contents of the mermaid.min.js dist and create a <script>
element with the contents as children -- this would be extra bloat if not using mermaid. I'm not sure if there is a TS function in the inherited codebase to do that because the watchScript()
function is only designed to create <script src="path/to/min.js"></script>
elements.
Alternatively, I can just add the mermaid.js dist from cache to built docs' _static
folder and simply change the path specified in the watchScript()
arg. In this scenario, we would have to exclude the mermaid.min.js contents from the bundled JS though.
I have yet to look into how we could exclude the theme's mermaid-related JS code from the bundle. It definitely won't be needed when the mermaid ext is not enabled. This bit seems like a separate issue because there is other JS code that could be conditionally be excluded (eg not using all available html_theme_options["features"]
).
This should be much easier since the upstream implementation is basically just telling the user to add the mathjax lib themselves. Sphinx already ships with mathjax support, so we may just need to document how the user can build docs that self-host the mathjax dist.
TBH, I'm not really sure there's anything in the inherited codebase that is specific to mathjax (aside from some CSS). So, I don't think mathjax support in our external resources ext is needed, rather it may be better managed by the doc project's author(s).
Agreed, and also for MathJax. But that could be deferred for a separate PR.
Originally posted by @jbms in https://github.com/jbms/sphinx-immaterial/issues/144#issuecomment-1218796196