How to use the theme

Use one of the following methods to configure Sphinx to use the awesome theme.

Load the theme from a Python package

Add the html_theme configuration option to the Sphinx configuration file

html_theme = "sphinxawesome_theme"

If you install and load the theme as a Python package, the extension sphinxawesome.sampdirective as well as all internal extensions are installed and loaded automatically.

Load the theme from a local directory

If you want to make many changes to the theme, you can also skip the packaging. It may be quicker to load the theme from a local directory.

Follow these steps to load a local version of the theme from a directory:

  1. Create a local copy of the theme

  2. Add the src/ directory to the Sphinx configuration.

    import os
    import sys
  3. Add this directory to the exclude_patterns list to prevent Sphinx from searching this path for reStructuredText files:

    exclude_patterns = ["sphinxawesome-theme", "..."]
  4. Add the theme both as an extension and as a theme:

    extensions = ["sphinxawesome_theme", "..."]
    html_theme = "sphinxawesome_theme"

Theme and extension options

You can configure the theme by modifying the html_theme_options dictionary in the Sphinx configuration file The options and their default values are shown below.

html_theme_options = {
      "nav_include_hidden": True,
      "show_nav": True,
      "show_breadcrumbs": True,
      "breadcrumbs_separator": "/",
      "show_prev_next": False,
      "show_scrolltop": False

Theme options


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:

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:

.. toctree::
   :caption: Contents

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:

html_theme_options = {"show_nav": False}

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:

html_theme_options = {"show_breadcrumbs": False}

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

html_theme_options = {"breadcrumbs_separator": "CHAR"}

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


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

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.


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:

html_theme_options = {"show_scrolltop": True}

Extension options

This theme also enables a few internal extensions that enhance the user experience. The following additional configuration value is set at the top level in the Sphinx configuration file


Set this option to True to enable collapsible object definitions, such as command line options, classes, or methods.

html_collapsible_definitions = True