Changing sidebar elements¶
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.
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.
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.
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
The scrollable region in the sidebar is determined by
sidebar/scroll-end.html. Any elements that fall between them can be scrolled.
There are two main ways to customise Furo’s sidebar:
override the content of the default templates with your own templates, using
change the entire sidebar structure, using
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.
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", ]
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.
If you’re hosting your documentation on ReadTheDocs, please make sure that
sidebar/ethical-ads.html is included in the sidebar. This helps keep ReadTheDocs sustainable.