Configure the theme

Configure the Awesome Theme.

Syntax highlighting

You can choose any Pygments color scheme for syntax highlighting in code blocks. To use different color schemes for both light and dark modes, set both the pygments_style and pygments_style_dark parameters. To use the same color scheme in light and dark mode, only set the pygments_style parameter:

File: conf.py

# Select a color scheme for light mode
pygments_style = "PYGMENTS_THEME"
# Select a different color scheme for dark mode
pygments_style_dark = "PYGMENTS_THEME"

Permalinks icons

By default, Sphinx adds a link to each heading which allows you to link to each section of a page. Sphinx adds a ¶ icon by default.

Even if you want to use the default icon, it’s better to wrap it in a <span> element:

File: conf.py

html_permalinks_icon = "<span>¶</span>"

This makes the icon only show up when you hover over or focus the heading.

If you want to use the same icon as used in the documentation for the Awesome Theme, add the following code to your Sphinx configuration:

File: conf.py

from sphinxawesome_theme.postprocess import Icons

html_permalinks_icon = Icons.permalinks_icon

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

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.

Algolia DocSearch

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