Changing sidebar elements¶

Added in version 2020.11.15.beta17.

Furo supports customising the elements that show up in the navigational sidebar (left). This is to provide documentation authors who are willing to work with HTML/CSS to change and tweak how the sidebar looks.

Unstable

This customisation considered “unstable” under Furo’s Stability Policy.

Furo is not designed to accommodate for all potential custom sidebar designs. It is also possible to get suboptimal results (or even break the layout!) when overriding the default sidebar.

Expectations¶

It is expected that users who override the sidebar would also carefully consider how their documentation looks across various platforms (i.e. not take a “looks OK on my machine” approach) and would be willing to override Furo’s styles to make it work with their sidebar design.

Some things to consider when doing this are:

different OSs/browsers handle scrollbars and their widths differently, with different effects on the layouting
end users can customise the look of their default scrollbars at an OS level(like overlay, hidden, visible-and-takes-space and maybe more?)
different viewport heights will differ across devices
“user interaction flows”, such as looking for a certain page in the sidebar or via search.

Default design¶

The following code snippet lists the fragments (HTML files from Furo’s theme folder) that are used for the default sidebar design.

sidebars =
  sidebar/brand.html,
  sidebar/search.html,
  sidebar/scroll-start.html,
  sidebar/navigation.html,
  sidebar/ethical-ads.html,
  sidebar/scroll-end.html,
  sidebar/variant-selector.html

Hint

The scrollable region in the sidebar is determined by sidebar/scroll-start.html and sidebar/scroll-end.html. Any elements that fall between them can be scrolled.

Making changes¶

There are two main ways to customise Furo’s sidebar:

override the content of the default templates with your own templates, using templates_path.
change the entire sidebar structure, using html_sidebars.

Using `templates_path`¶

This is useful when you want to change a specific element of the sidebar. A good example for when you might want to use this: adding a tagline after your project’s name/logo.

This is done by setting templates_path in the conf.py and correctly adding files within the configured paths.

templates_path = ["_templates"]

For the above example – adding a tagline after the name/logo – you’d want to add an _templates/sidebar/brand.html file, that overrides the appropriate content. For more information on how to do so, Sphinx’s templating documentation.

Using `html_sidebars`¶

This is useful when you want to make drastic or major changes to the design of Furo’s sidebar.

As an example, to make the entire sidebar scrollable, it is possible to set sidebar/scroll-start.html as the first fragment and sidebar/scroll-end.html as the last fragment.

html_sidebars = {
    "**": [
        "sidebar/scroll-start.html",
        "sidebar/brand.html",
        "sidebar/search.html",
        "sidebar/navigation.html",
        "sidebar/ethical-ads.html",
        "sidebar/scroll-end.html",
    ]
}

Warning

sidebar/scroll-start.html and sidebar/scroll-end.html must be included in the sidebar. Ensure that the “non-scrollable” elements (i.e. that don’t occur between these two) do not go beyond the height of the viewport.

Tip

If you’re hosting your documentation on Read the Docs, please make sure that sidebar/ethical-ads.html is included in the sidebar. This helps keep Read the Docs sustainable.

Changing sidebar elements¶

Expectations¶

Default design¶

Making changes¶

Using templates_path¶

Using html_sidebars¶

Using `templates_path`¶

Using `html_sidebars`¶