New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
caching (locally) npm pkgs' dist at docs build stage #150
Comments
About mermaid.jsI 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 sphinx-immaterial/src/assets/javascripts/components/content/code/mermaid/index.ts Line 72 in f04bc71
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' 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 About mathjaxThis 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). |
In reference to #150, this uses the `external_resources` ext to cache the mermaid.js dist. Users can still use `html_static_path` if downloading the dist at build time proves problematic.
In reference to #150, this uses the `external_resources` ext to cache the mermaid.js dist. Users can use `html_static_path` if downloading the dist at build time proves problematic. BREAKING CHANGE: The `sphinx_immaterial.mermaid_diagrams` ext is now optional and must be enabled in conf.py to use the `md-mermaid` directive.
Agreed, and also for MathJax. But that could be deferred for a separate PR.
Originally posted by @jbms in #144 (comment)
The text was updated successfully, but these errors were encountered: