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.
gulpfile.js– for Gulp.
noxfile.py– for nox.
package.json– for NPM.
pyproject.toml– for Python Packaging.
Theme build process¶
Furo’s build process uses Gulp. Running
gulp build in the repository root will compile the theme’s CSS and JS assets (
src/furo/assets/) into the correct final files (inside
When building the distributions for upload,
gulp build is run once and the
src/furo/assets/ directory is excluded for the final distribution. Thus, both the source distribution and wheel distribution do not contain the original source code for Furo and only contain the compiled SCSS and JS files.
It is not ideal that the version-controlled source tree is not installable using pip directly. There is a need for a
gulp build command to be run between the clone and installation.
Things are set up this way due to the lack of a “build” step support in Flit. There is an open issue for enhancement with a proposal awaiting feedback.
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.