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
Include Mathjax.js on per-page basis #6241
Comments
executablebooks/sphinx-panels#28 (comment) An idea for a Sphinx plugin that does what's been requested here. |
Thinking about possible plugin implementations, would hooking into In order to not change the order of libraries and stylesheets included, I think conditionally removing js would work better, and the plugin configuration could specify a doctree node selector that is required to keep a js/css file. |
Yup -- that's exactly what I had in mind -- filtering the JS files "out" based on some conditional for them. Something like "only remove if there's no The exact design is 100% in the air though -- I imagine callable functions maybe nice in the spirit of extensibility but that's complexity and so on. :) |
Thinking about sphinx design, I'd say using any condition accepted by |
I think the pattern you suggested to remove files would work. I just tried adding an Here's the code I used in case it's helpful: def remove_thebe_if_not_needed(app, pagename, templatename, context, doctree):
if not doctree:
return
if not doctree.traverse(ThebeButtonNode):
# Remove thebe JS files
new_script_files = []
for ii in context["script_files"]:
if ii not in ["_static/sphinx-thebe.js", "https://unpkg.com/thebelab@latest/lib/index.js"]:
new_script_files.append(ii)
context["script_files"] = new_script_files
# Remove thebe CSS files
new_css_files = []
for ii in context["css_files"]:
if ii not in ['_static/thebelab.css', '_static/sphinx-thebe.css']:
new_css_files.append(ii)
context["css_files"] = new_css_files |
Sweet! Now the real question is if it's even worth an extension of its own—the amount of code is minimal. It would potentially make sense to make it a part of sphinx itself by allowing js and css files also specify a doctree selector for themselves to be included. |
Not sure what would be a good interface. The obvious option is to allow html_js_files = [
'js/custom.js', # included unconditionally
('js/large_optional_library.js', library_selector), # only if selector isn't empty
] This is backwards compatible, but ugly. |
hmmmm, I will think about it a bit more...another option is something like:
Then extension authors could do whatever they want with |
I'd use boolean values instead, but otherwise I like it. If we're willing to be a bit... uhm... YOLO about this, we could even have the |
Does Also: should the condition take all arguments passed to |
What if we substituted
for
That would provide the page name, and then the check could dive into whether that page has math tags? |
I am prototyping this over here, if any others have thoughts or contributions: https://github.com/executablebooks/sphinx-conditional-asset/blob/main/sphinx_conditional_asset/__init__.py#L11 My plan is to release it as an extension once we have a pattern that makes sense, and then if Sphinx core thinks it'd be good to have, upstream it. |
…c page Allow to add JS/CSS files to the specific page when an extension calls `app.add_js_file()` or `app.add_css_file()` on `html-context-page` event.
I posted #8631 to support JS/CSS files for the specific page. Please take a look and let me know your opinion for the change. |
…c page Allow to add JS/CSS files to the specific page when an extension calls `app.add_js_file()` or `app.add_css_file()` on `html-context-page` event.
…c page Allow to add JS/CSS files to the specific page when an extension calls `app.add_js_file()` or `app.add_css_file()` on `html-page-context` event.
…c page Allow to add JS/CSS files to the specific page when an extension calls `app.add_js_file()` or `app.add_css_file()` on `html-page-context` event.
…c page Allow to add JS/CSS files to the specific page when an extension calls `app.add_js_file()` or `app.add_css_file()` on `html-page-context` event.
…c page Allow to add JS/CSS files to the specific page when an extension calls `app.add_js_file()` or `app.add_css_file()` on `html-page-context` event.
…c page Allow to add JS/CSS files to the specific page when an extension calls `app.add_js_file()` or `app.add_css_file()` on `html-page-context` event.
Close #6241: html: Allow to add JS/CSS files to the specific page
(Original reporter here). Thank you very much! |
Is your feature request related to a problem? Please describe.
Currently in a documentation project we have many pages, of which only a very small subset needs mathjax. However, enabling the sphinx.ext.mathjax extension causes mathjax.js to be included in every page. This is a bit unfortunate since mathjax is huge.
Describe the solution you'd like
Mathjax.js is included in only the pages which need it, and not every page.
Describe alternatives you've considered
Current system works, but makes all pages that don't need mathjax bigger and slower than they need to.
Additional context
I mentioned this as a comment in #5497 , where it was suggested that I open a new issue.
The text was updated successfully, but these errors were encountered: