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. While this theme inherits some options from the built-in basic Sphinx theme, only the ones documented here are supported.

light_css_variables / dark_css_variables

Added in version 2020.08.14.beta5.

Changed in version 2020.11.01.beta14: Support for dark mode involved replacing css_variables with 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

Added in version 2022.06.04.

Deprecated since version 2024.05.06: This will be removed after 2024-11-01. Use top_of_page_buttons instead.

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",
}

top_of_page_buttons

Added in version 2024.05.06.

Controls which buttons are shown on the top of the page. This is a list which can be empty or contain one-or-more of the following values:

  • "edit"

  • "view"

html_theme_options = {
    "top_of_page_buttons": ["view", "edit"],
}

announcement

Added in version 2020.12.28.beta22.

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

Added in version 2020.08.14.beta5.

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.