Primary sidebar and navigation#
The primary sidebar generally contains the site navigation and logo. By default it is on the left side of the site. This page describes ways that you can control and customize the primary sidebar.
Control the left sidebar items#
You can control what kind of content goes underneath the logo and name of your website in the top left.
To do so, use the html_sidebars
variable in your conf.py
file. This takes a dictionary of filename patterns as keys, and a list of sidebar elements as values. Any files that match a key will have the corresponding sidebar elements placed in that page’s sidebar.
For example, the following configuration would include only the footer on pages under the posts/
folder:
html_sidebars = {
"posts/*": ["sbt-sidebar-nav.html"]
}
You can also use **
to apply a set of sidebars to all pages of your book. For example:
html_sidebars = {
"**": ["sbt-sidebar-nav.html"]
}
See the Sphinx HTML sidebars documentation for more information.
Default sidebar elements#
By default, this theme comes with these theme-specific sidebar elements enabled on all pages:
navbar-logo.html
: Displays the logo and site title.icon-links.html
: Displays icon linkssearch-button-field.html
: A bootstrap-based search bar (from the PyData Sphinx Theme)sbt-sidebar-nav.html
: A bootstrap-based navigation menu for your book.
Add a header to your Table of Contents#
If you’d like to add a header above a section of TOC links, use :caption: My header text
in your toctree
directive for that section.
Add the home page to your table of contents#
By default, your table of contents will begin with the first file that you add to a toctree
. You can also configure the theme to show the landing page of the theme in your navigation bar as well.
To add the landing page of your site to the table of contents, use the following configuration:
html_theme_options = {
...
"home_page_in_toc": True
...
}
Control the depth of the left sidebar lists to expand#
You can control the level of toc items in the left sidebar to remain expanded,
using the following configuration in conf.py
:
html_theme_options = {
...
"show_navbar_depth": <level>,
...
}
The default value is 1
, which shows only top-level sections of the documentation (and is used in this documentation).
Control the maximum depth of the left sidebar lists#
You can control the level of toc items included in the left sidebar,
using the following configuration in conf.py
:
html_theme_options = {
...
"max_navbar_depth": <level>,
...
}
The default value is 4
.
Turn off expandable left sidebar lists#
You can turn off the sidebar expanding,
using the following configuration in conf.py
:
html_theme_options = {
...
"collapse_navbar": True,
...
}
The default value is False
, which allows the navbar to be expanded.