Configure the theme

Configure the Awesome Theme.

Note

If you’re not using version 5 of the Awesome Theme, read Configure the theme (version 4).

Bundled extensions

The Awesome Theme bundles two Sphinx extensions that let you enhance your documentation. They’re independent from each other, so you can load them separately or together.

sphinxawesome_theme.docsearch

Replaces the built-in search with Algolia DocSearch for showing instant search results as you type. For more information, see Algolia DocSearch.

sphinxawesome_theme.highlighting

Adds the following highlighting options to Sphinx’s code-block directive:

• :emphasize-added: LINES: highlight lines to be added.

• :emphasize-removed: LINES: highlight lines to be removed.

• :emphasize-text: TEXT: highlight a placeholder word or phrase.

See also

Code blocks, extensions

Note

In version 5, many configuration options changed. To help you with finding and upgrading deprecated options, add the sphinxawesome.deprecated extension. For more information, see Upgrade to version 5.0

Logos

You can use the html_logo option to set a path to your logo. If you’re using a logo that works well in dark mode, you only need to declare one logo.

If you want to use different logos for light and dark mode, add them to your theme options:

File: conf.py

html_theme_options = {
    "logo_light": "path/to/light/logo",
    "logo_dark": "path/to/dark/logo"
}

Sidebars

The Awesome Theme uses the html_sidebars setting to configure the sidebar.

The default setting is:

html_sidebars = {
  "**": ["sidebar_main_nav_links.html", "sidebar_toc.html"]
}

This includes a sidebar on every page. The sidebar includes the main navigation links (from the header) on small screens, and the links to your documentation pages.

You can change the sidebar for individual pages. For example, to hide the sidebar on large screens, but still show the header navigation links on an about page:

html_sidebars = {
  "/about": ["sidebar_main_nav_links.html"]
}

To hide the sidebar completely, use html_sidebars = {"**": []}.

Theme options

You can configure the Awesome Theme with the html_theme_options dictionary. To benefit from code completion and documentation when editing your Sphinx configuration, you can use the ThemeOptions class:

File: conf.py

from dataclasses import asdict
from sphinxawesome_theme import ThemeOptions

theme_options = ThemeOptions(
   # Add your theme options. For example:
   show_breadcrumbs=True,
   main_nav_links={"About", "/about"},
)

html_theme_options = asdict(theme_options)

You can still configure the theme using a regular dictionary:

File: conf.py

html_theme_options = {
   # Add your theme options. For example:
   "show_breadcrumbs": True,
   "main_nav_links": {
      "About": "/about",
   }
}

class ThemeOptions

Helper class for configuring the Awesome Theme.

Each attribute becomes a key in the html_theme_options dictionary.

awesome_external_links: bool = False

If True, the theme includes an icon after external links and adds rel="nofollow noopener" to the links’ attributes.

awesome_headerlinks: bool = True

If True, clicking a headerlink copies its URL to the clipboard.

breadcrumbs_separator: str = '/'

The separator for the breadcrumbs links.

extra_header_link_icons: dict[str, LinkIcon]

A dictionary with extra icons to include on the right of the search bar.

The keys are labels for the link’s title attribute. The values are themselves LinkIcon.

globaltoc_includehidden: bool = True

If True, the theme includes entries from hidden toctree directives in the sidebar.

The toctree directive generates a list of links on the page where you include it, unless you set the :hidden: option.

This option is inherited from the basic theme.

logo_dark: str | None = None

A path to a logo for the dark mode. If you’re using separate logos for light and dark mode, you must provide both logos.

logo_light: str | None = None

A path to a logo for the light mode. If you’re using separate logos for light and dark mode, you must provide both logos.

main_nav_links: dict[str, str]

A dictionary with links to include in the site header.

The keys of this dictionary are the labels for the links. The values are absolute or relative URLs.

show_breadcrumbs: bool = True

If True, the theme includes breadcrumbs links on every page except the root page.

show_prev_next: bool = True

If True, the theme includes links to the previous and next pages in the hierarchy.

show_scrolltop: bool = False

If True, the theme shows a button that scrolls to the top of the page when clicked.

LinkIcon reference

class LinkIcon(*args, **kwargs)

A link to an external resource, represented by an icon.

icon: str

An SVG icon as a string.

link: str

The absolute URL to an external resource.

Algolia DocSearch

DocSearch provides search for open source projects and technical blogs for free. You can apply and receive your credentials.

To replace the built-in search with DocSearch, Add the theme to your Sphinx configuration and add the sphinxawesome_theme.docsearch extension:

File: conf.py

extensions += ["sphinxawesome_theme.docsearch"]

How does DocSearch work?

Algolia indexes your content with a crawler. You’ll add the DocSearch UI component to your layout. Now, on every keystroke, DocSearch looks for matching results on Algolia’s servers and updates the view instantly.

DocSearch credentials

Algolia provides you with three credentials for DocSearch. You must add the application ID and search API key to your site to authenticate and authorize search requests. Keep the write API key a secret. You can find your credentials in the Algolia dashboard.

Application ID

The identifier for your project on Algolia. It’s used to route search requests from your site to your Algolia index.

Search API key

An API key that allows search requests from your site.

Write API key

An API key that allows writing to your index. Since Algolia indexes your content automatically with a crawler, you don’t have to use this key. Don’t use the write API key in your site.

Configure DocSearch

To configure DocSearch, declare the docsearch_* options as regular Python variables:

File: conf.py

docsearch_app_id = "YOUR_APP_ID"
docsearch_api_key = "YOUR_API_KEY"
docsearch_index_name = "YOUR_INDEX_NAME"

Use environment variables

Instead of exposing your credentials in your Sphinx configuration file, you can load them from environment variables. For example, you can store them in a in a .env file. To do this, add the python-dotenv package to your project and add the following code to your Sphinx configuration:

File: conf.py

import os
from python_dotenv import load_dotenv

# Load environment variables from a .env file
load_dotenv()

docsearch_app_id = os.getenv("DOCSEARCH_APP_ID")
docsearch_api_key = os.getenv("DOCSEARCH_API_KEY")
docsearch_index_name = os.getenv("DOCSEARCH_INDEX_NAME")

In the same directory as your conf.py file, create a .env file with these variables:

File: .env

DOCSEARCH_APP_ID=YOUR_APP_ID
DOCSEARCH_API_KEY=YOUR_API_KEY
DOCSEARCH_INDEX_NAME=YOUR_INDEX_NAME

To avoid uploading this file to your repository, add .env to your .gitignore file.

The DocSearchConfig helper

To make it easier to configure DocSearch with code completion and hover help, the Awesome Theme provides a DocSearchConfig helper class. If you’re okay with (ab)using Python’s dynamic character, you can add the following code:

File: conf.py

import os
from python_dotenv import load_dotenv
from dataclasses import asdict
from sphinxawesome_theme.docsearch import DocSearchConfig

# This gets you code completion and documentation for your configuration options
config = DocSearchConfig(
   docsearch_app_id=os.getenv("DOCSEARCH_APP_ID")
   docsearch_api_key=os.getenv("DOCSEARCH_API_KEY")
   docsearch_index_name=os.getenv("DOCSEARCH_INDEX_NAME")
)

vars = locals()
for key, value in asdict(config).items():
   vars.__setitem__(key, value)

DocSearch configuration options

docsearch_app_id

Your Algolia DocSearch application ID. (Required)

docsearch_api_key

Your Algolia DocSearch search API key. (Required)

Caution

Don’t use your write API key.

docsearch_index_name

Your Algolia DocSearch index name. (Required)

docsearch_container

A CSS selector where the DocSearch UI component should be added. The default is: #docsearch.

docsearch_placeholder

The placeholder for the search box.

docsearch_initial_query

A query for an initial search if you want to show search results as soon as the user opens the search menu.

docsearch_search_parameter

Any Algolia search parameter you want to add.

docsearch_missing_results_url

If specified, DocSearch adds a message to the “No results found” screen with the link to the URL you specified, for users to report issues with missing search results. You can include the current search query as parameter ${query}. For example:

docsearch_missing_results_url = "https://github.com/example/docs/issues/new?title=${query}"

See also

DocSearch API reference