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, it may be quicker to skip the packaging and to load the theme from a 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 both includes the content as well as prints a list of links in the content area, where the directive is included. 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, and 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 the list of links in the content area. 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 to 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, so that this option is disabled 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, methods, and so on.

html_collapsible_definitions = True