Customisation#

Furo supports customisation of the theme’s overall look and feel (through theme options) as well as a few per-page tweaks.

This section serves to guide the user with customising Furo-based documentation. This page lists all the theme-specific customisations, as provided by this theme. Other pages in this section provide guidance for making specific customisations when using Sphinx with Furo.

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.

Note

Note that only the configuration options listed here are supported (not the ones inherited from the built-in basic Sphinx theme).

light_css_variables/dark_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. Changing colors contains important details of how these variables are used.

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

html_theme_options = {
    "light_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.

top_of_page_button#

Controls which button is shown on the top of the page. The only supported values are "edit" (the default) and None.

html_theme_options = {
    "top_of_page_button": "edit",
}

announcement#

Add a site-wide announcement, to the top of every page when set. See Adding an announcement banner for the details.

Page specific tweaks#

File-Wide metadata is used for per-page customisation, primarily 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, see Injecting code.