Web assets (CSS/JS/Fonts)#
This theme includes several web assets to ease development and design.
The configuration for our asset compilation is in
Compile and bundle assets#
When assets are compiled, static versions are placed in various places in the theme’s static folder:
For many assets, a
<hash> is generated and appended to the end of its reference in the HTML templates of the theme.
This ensures the correct asset versions are served when viewers return to your
site after upgrading the theme.
To compile the assets and bundle them with the theme, run this command:
$ nox -s compile
Styles (SCSS) and Scripts (JS)#
There are two relevant places for CSS/JS assets:
src/pydata_sphinx_theme/assets/styleshas source files for SCSS assets. These will be compiled to CSS.
src/pydata_sphinx_theme/assets/scriptshas source files for JS assets. These will be compiled to JS and import several vendored libraries (like Bootstrap).
src/pydata_sphinx_theme/theme/pydata_sphinx_theme/statichas compiled versions of these assets (e.g. CSS files). This folder is not tracked in
.githistory, but it is bundled with the theme’s distribution.
We vendor several packages in addition to our own CSS and JS.
For example, Bootstrap, JQuery, and Popper.
This is configured in the
webpack.config.js file, and imported in the respective
JS file in our assets folder.
Three “styles” of the FontAwesome 6 Free
icon font are used for icon links and admonitions, and is
It is managed as a dependency in
Copied directly into the site statics at compilation, including licenses
Partially preloaded to reduce flicker and artifacts of early icon renders
Our Webpack build generates a collection of Jinja macros in the
These macros are imported in the main
layout.html file, and then inserted at various places in the page to link the static assets.
Some of the assets are “preloaded”, meaning that the browser begins requesting these resources before they’re actually needed.
<head>, and the scripts are actually loaded at the end of