Furo’s internals contain an interesting mix of stupid-things-that-work and all kinds of bodges. Most of this project was built slowly over the span of a few weeks, as a part of an attempt to take a break from working on Python packaging stuff.
The repository layout is pretty standard for a Python project, with a few quirks due to the need for compiling Sass and JS files.
.nox/– Generated by nox.
dist/– Generated as part of the release process.
docs/– Sources for the documentation.
furo/– actual source code for the package
__init__.py– Handles interaction with Sphinx and some configuration.
navigation.py– Generates the sidebar navigation HTML.
sphinxext.py– Defines the internal-only
assets/– contains Sass and JS source code.
theme/– the folder that Sphinx adds to template lookup.
furo/– main Sphinx theme folder
static/– contains compiles CSS and JS code.
everything else here – the underlying HTML templates.
noxfile.py– for nox.
package.json– for NPM.
pyproject.toml– for Python Packaging.
webpack.config.js– for Webpack.
Theme build process#
Furo’s build process uses sphinx-theme-builder and Webpack. Running
webpack in the repository root will compile the theme’s CSS and JS assets (
src/furo/assets/) into the correct final files (inside
When generating a wheel (eg: for upload, or for installing from a source distribution),
sphinx-theme-builder will use nodeenv to create an isolated NodeJS installation (using the system NodeJS version if it matches the requirements).
Thus, the source distribution does not contain the compiled JS artifacts and wheel distribution does. Both contain the original SASS/JS source code for Furo. Using the SASS/JS source code of Furo is consider “unstable” under the stability policy.
How stuff works#
CSS variables for customisation#
This is pretty much the “USP” of this theme. In
src/furo/theme/furo/partials/_head_css_variables.html, the user provided CSS variables are translated and written into each page’s HTML. This is set up, such that these declarations overrides any other declarations made in the CSS of the theme.
This essentially allows the user to control the values of the CSS variables, and hence control how the theme looks.
This directive was written to make it easier to write the examples used in the Reference section. The way it works is pretty straightforward really:
It only works in MyST documents, since it performs an in-place substitution.
It takes the contents of the block, splits it at “+++” into Markdown and reStructuredText snippets.
For both of these, it renders a tab that has a code block containing the snippet followed by the actual code itself.
This is carefully crafted to ensure that things are evaluated correctly.
This approach has significant limitations however, since the A/B comparision format means that it is not directly usable to showcase functionality that is different between the two.
For that, we keep one of the snippets empty, which thanks to a conditional, results in the tab for that language (MyST or reST) not being rendered.