Changelog

This is the changelog of the Awesome Theme.

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 use CSS grid. This leads to fewer container elements in the templates.