Customisation - Furo

Furo is under active development, and this documentation is not written yet!

# 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.

Note

Note that only the configuration options list 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.

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.

### `sidebar_hide_name`

Controls whether you see the project’s name in the sidebar of the documentation. This is useful when you only want to show your documentation’s logo in the sidebar. The default is `False`.

    html_theme_options = {
        "sidebar_hide_name": True,
    }

### `navigation_with_keys`

Controls whether the user can navigate the documentation using the keyboard’s left and right arrows. The default is `False`.

    html_theme_options = {
        "navigation_with_keys": True,
    }

## 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.