Configure the theme

Configure the Awesome Theme.

Syntax highlighting

This theme lets you configure different color themes for syntax highlighting code blocks using these configuration options:

File: conf.py
# Select theme for both light and dark mode
pygments_style = "PYGMENTS_THEME"
# Select a different theme for dark mode
pygments_style_dark = "PYGMENTS_THEME"

If you only set the pygments_style option, the same style will be used in both light and dark modes. If you specify a pygments_style_dark option, different colors will be used in light and dark modes.

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"
}

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[source]

Helper class for configuring the Awesome Theme.

Each attribute becomes a key in the html_theme_options dictionary.

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

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

breadcrumbs_separator: str = '/'

The separator for the breadcrumbs links.

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.

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)[source]

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

icon: str

An SVG icon as a string.

The absolute URL to an external resource.

Algolia DocSearch

If you want to replace Sphinx’s built-in search with DocSearch, use the sphinx-docsearch extension.