Customisation

Furo supports customisation of the overall theme’s look and feel.

Theme options

html_theme_options in conf.py is used for customisations that affect the entire documentation. This is for stuff like fonts and colors.

css_variables

Furo makes extensive use of CSS variables. These can be overridden by the user and are used for stylizing nearly all elements of the documentation.

Setting css_variables is the recommended mechanism to override Furo’s default values for these variables.

html_theme_options = {
    "css_variables": {
        "color-brand-primary": "red",
        "color-brand-content": "#CC3333",
        "color-admonition-background": "orange",
    }
}

Caution

Typos in the css_variables dictionary are silently ignored, and do not raise any errors or warnings. Double check that your spellings and values are correct and valid.

Page specific tweaks

File-Wide metadata is used for per-page customisation, usually for controlling which UI elements are presented.

hide-toc

The “Contents” sidebar is automatically hidden for any pages that don’t have any inner headings. It is possible to hide it even when a page has inner headings, by setting hide-toc at the page level. See Hiding Contents sidebar for an example.

Custom CSS files

If you want more control than what is provided by the above theme options, you can add custom stylesheets to your documentation.

ReadTheDocs has an excellent explanation on how to add custom CSS files to Sphinx-based documentation.