sphinx-conditional-asset¶
Conditionally add assets (JS and CSS) to your Sphinx build.
This package allows you to choose certain pages on which to load conditional assets, rather than forcing you to load assets for all pages. This allows you to avoid loading scripts and CSS on pages that do not need them. It is meant primarily for Sphinx developers, but can be used as a part of any Sphinx build.
Install¶
To install sphinx-conditional-asset
run the following command:
pip install git+https://executablebooks/sphinx-conditional-asset
and activate the extension via conf.py
:
extensions = [
...
"sphinx_conditional_asset",
]
Use¶
This package adds two new methods to the instance of sphinx.Application
that
is provided by setup(app)
, app.add_js_file_conditional
and app.add_css_file_conditional
. They take the same arguments as app.add_js_file
and app.add_css_file
, along with an additional condition
argument.
The condition
argument: takes a function that accepts the same arguments as the html-page-context
Sphinx event.
When each page is loaded, the function will be called with the html-page-context
arguments. If it returns True
then the asset will be loaded onto the page.
Examples¶
For example, let’s say we only wanted to load thebe
on pages that start with
thebe_
. To do so, we’d add this to our setup(app)
function:
def only_on_some_pages(app, pagename, templatename, context, doctree):
if pagename.startswith("thebe_"):
return True
def setup(app):
app.add_js_file_conditional(
"https://unpkg.com/thebelab@latest/lib/index.js",
only_on_some_pages
)
Here’s an example that checks for an admonition
node in the page’s doctree:
from sphinx_theme import ThebeButtonNode
def only_when_node_present(app, pagename, templatename, context, doctree):
if doctree.traverse(ThebeButtonNode):
return True
def setup(app):
app.add_js_file_conditional(
"https://unpkg.com/thebelab@latest/lib/index.js",
only_when_node_present
)