Changelog

This is the changelog of the Awesome Theme.

Version 6.0

Version 6.0 drops support for Python 3.8 and removes code that became deprecated in version 5.2. This version also removes the light mode/dark mode selector. Since dark mode is an operating-system setting, having to control this additionally for every website seems like an anti-pattern.

Version 5.2

Version 5.2 of the Awesome Theme deprecates the bundled sphinxawesome_theme.highlighting extension. Its functionality is now integrated and this extension will be removed with version 6.

Version 5.0

Version 5.0 of the Awesome Theme is almost a complete rewrite.

Better navigation: Version 5.0 has a clear separation between links to other pages (left sidebar), and links to sections on the current page (right sidebar).
Dark mode: The theme follows a consistent design in light and dark mode.
Simpler setup: You no longer need to load the theme as an extension. Like most other themes for Sphinx, it’s enough to load it as html_theme.
Redesign: Using the design from shadcn/ui.

Upgrade to version 5.0

If you want to upgrade the theme to version 5.0, you might need to update your Sphinx configuration. To help you find deprecated options, you can add the bundled sphinxawesome_theme.deprecated extension.

File: conf.py

extensions += ["sphinxawesome_theme.deprecated"]

The extension raises warnings if it finds deprecated options and upgrades them to their new values if possible.

Deprecated options

The following two options don’t have any effect in version 5.0. You can remove them from your Sphinx configuration:

html_collapsible_definitions: This option provided a terrible user experience. After all, references are meant to be scanned, not hidden. You can use the sphinx-design extension instead and place single references inside a dropdown.
html_awesome_code_header: In most cases, the programming language of a code sample is already clear from its context. If you want to make more annotations, you can use existing mechanisms that are built into Sphinx, such as captions or comments at the top of a code block. For code samples in multiple languages, you can use the sphinx-design extension with its tab-set-code directive.

DocSearch is now an external extension, available as sphinx-docsearch.

html_awesome_docsearch: Load the bundled sphinxawesome_theme.docsearch extension instead.

These options are now keys in the html_theme_options dictionary instead of top-level configuration options:

html_awesome_headerlinks

Changed to awesome_headerlinks

html_awesome_external_links

Split into two options:

main_nav_links for text links in the header
extra_header_link_icon for icon links on the right side of the header.

Version 4.0

Version 4.0 of the Awesome Theme includes these breaking changes:

Add support for Sphinx 6: Since Sphinx 6 is only supported with the latest version of the myst-parser package and Sphinx 6 drops support for Python 3.7, this release is a major version update.

Apart from that, this version is identical with version 3 of the Awesome Theme.

Version 3.0

Redesign: Create a better visual hierarchy which makes the document easier to scan. Heavily inspired by the Material Design website.
Restructure: All JavaScript is now using the Stimulus framework.

Version 2.0

Version 2.0 of the Awesome Theme includes these breaking changes:

Require Sphinx 4 or newer: Sphinx 4 depends on docutils 0.17, which creates more semantic HTML by default. This allows to reduce the amount of custom transformations.
Restructure several templates: The layout uses CSS grid. This leads to fewer container elements in the templates.