Configure the theme

Configure the Awesome Theme.

Bundled extensions

The Awesome Theme bundles one Sphinx extension for better code blocks.

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.

Note

If you don’t add this extension, the spacing in code blocks might appear off. You can Add custom CSS with extra padding to pre elements.

See also

Code blocks, extensions

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.