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.

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

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

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