Managing theme assets#

The sphinx-theme-builder intentionally separates asset source files from the compiled assets that are bundled with your theme. These generally fall into two folders:

  • “Asset sources” in src/my_awesome_theme/assets

    The source files used for generating the theme’s actual stylesheet/JavaScript files (e.g. .scss files, .ts files).

  • “Compiled static assets” in src/my_awesome_theme/theme/my-awesome-theme/static

    These are the files that will be used by Sphinx (e.g. .css files generated from .scss, .js files after transpiling and bundling).

Compiling assets#

As described in the Build Process document, themes are expected to compile assets through a NodeJS-based build system with npm run-script build being the entrypoint for it.

During theme development, it is expected that theme authors will not need to invoke npm manually. Instead, when you want to compile the theme’s assets, you’ll run:

$ stb compile

This will handle all the details of fetching NodeJS, the npm dependencies and other running the build via npm.

When previewing documentation using stb serve, this command will run prior to rebuilding the documentation. This means that your theme development workflow will not require manually invoking the rebuild. The live-reloading server ignores assets in the static folder, so generating files there does not trigger a re-build loop.

Example: Webpack-based asset generation#

For an example, we’ll use Furo’s 2022.06.21 release. That version of the Furo theme uses a Webpack based asset generation pipeline, for compiling Sass and JS source assets into generated CSS and JS assets.

The relevant files for this setup are: