How to configure the theme

Theme options

You can configure the theme by modifying the html_theme_options dictionary in the Sphinx configuration file conf.py.

nav_include_hidden

By default, the toctree directive includes the content and prints a list of links in the content area. A toctree directive with the :hidden: option includes the content, but doesn’t print the list of links in the content area. This can be useful if navigation links are elsewhere on the page. Printing the same list of links in the content area would be redundant.

If you don’t want to include elements from a hidden toctree directive in the navigation menu on the left, set:

python File: conf.py

# This option is `True` by default
html_theme_options = {"nav_include_hidden": False}

When using the toctree directive without the :hidden: option, insert a headline or provide a caption with the :caption: option. For example:

rst

.. toctree::
   :caption: Contents

show_nav

By default, the navigation links are shown in a navigation menu on the left side. If you want to hide the navigation menu completely, add:

python File: conf.py

# This option is `True` by default
html_theme_options = {"show_nav": False}

show_breadcrumbs

By default, “breadcrumbs” navigation links are shown at the top of the content area. They show the position of this document relative to the top level. If you want to hide the breadcrumbs navigation links, add:

python File: conf.py

# This option is `True` by default
html_theme_options = {"show_breadcrumbs": False}

breadcrumbs_separator

If you want to select a different separator for the breadcrumbs navigation links, set:

python File: conf.py

# The default separator is `/`
html_theme_options = {"breadcrumbs_separator": "CHAR"}

Replace CHAR with a character or HTML entity of your choice.

show_prev_next

If you want to show links to the previous and next pages, set:

python File: conf.py

# This option is `False` by default
html_theme_options = {"show_prev_next": True}

In most cases, documentation isn’t read from beginning to end. That’s why this option is turned off by default.

show_scrolltop

For longer pages, scrolling to the top can be a hassle. If you want to show a button, that scrolls to the top of the page when clicked, set:

python File: conf.py

# This option is `False` by default
html_theme_options = {"show_scrolltop": True}

extra_header_links

If you want to add extra links to the header of your documentation, for example, similar to what you can see on this page, set:

python File: conf.py

# This option is `False` by default
html_theme_options = {
  extra_header_links = {
    "link1": "/url1",
    "link2": "/url2",
  }
}

The keys of the extra_header_links dictionary are the link texts. The values are the absolute URLs to the pages you want to link.

Extension options

This theme also enables a few internal extensions that enhance the user experience. The following configuration values are set at the top level in the Sphinx configuration file conf.py:

html_collapsible_definitions

Set this option to True to make code references, such as classes, methods, and other objects, collapsible and expandable. By default, this option is turned off.

python File: conf.py

# This option is `False` by default
html_collapsible_definitions = True

html_awesome_headerlinks

Set this option to False to restore Sphinx’s default behavior for headerlinks. Using this theme, clicking a headerlink immediately copies the URL to the clipboard.

python File: conf.py

# This option is `True` by default
html_awesome_headerlinks = False