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

If you don’t want to include entries from a hidden toctree directive in the sidebar, set nav_include_hidden to False.

python File: conf.py

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

By default, the toctree directive includes your content and generates a list of links in the content area of the page. With the hidden option, the content is still included, but no links are printed in the main content area.

show_nav

The Awesome Theme shows links to all your documentation pages in sidebar on the left side. If you want to hide the sidebar on all pages, set this option to False:

python File: conf.py

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

show_breadcrumbs

The Awesome Theme shows breadcrumbs links at the top of each page To hide the breadcrumbs, set this option to False:

python File: conf.py

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

breadcrumbs_separator

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

To show links to the previous and next pages, set this option to True:

python File: conf.py

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

show_scrolltop

To show a button that scrolls to the top of the page when clicked, set this option to True:

python File: conf.py

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

extra_header_links

To add extra links to the header of your documentation, set the following option:

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 absolute URLs.

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. In the Awesome 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

html_awesome_code_headers

By default, the Awesome Theme shows the programming language above code blocks in a header. To disable this behavior, set this option to False.

python File: conf.py

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

html_awesome_docsearch

Set this option to True to use Algolia DocSearch instead of the built-in search.

python File: conf.py

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

To configure DocSearch, add these environment variables:

DOCSEARCH_APP_ID

The id of your Algolia app

DOCSEARCH_API_KEY

The API key for searching your index on Algolia

DOCSEARCH_INDEX_NAME

The name of your Algolia index for your documentation project.

You can write them in a .env file in your Sphinx project directory or provide them on the command line.

Alternatively, you can also configure DocSearch via a docsearch_config dictionary in your Sphinx configuration file conf.py:

python File: conf.py

docsearch_config = {
  app_id: "",
  api_key: "",
  index_name: ""
}

Note

Algolia DocSearch is an external web service. You need to apply and receive your credentials before you can use it.