This is the changelog of the Awesome Theme.
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. You can add the Bundled extensions to enable more features.
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
extensions += ["sphinxawesome_theme.deprecated"]
The extension raises warnings if it finds deprecated options and upgrades them to their new values if possible.
The following two options don’t have any effect in version 5.0. You can remove them from your Sphinx configuration:
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
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-designextension with its
DocSearch is now an optional extension. This creates a better separation between the theme and additional features. The DocSearch-related options are deprecated.
Load the bundled
Instead of using keys in a single dictionary, use top-level configuration options instead. For more information, see Algolia DocSearch.
These options are now keys in the
instead of top-level configuration options:
Split into two options:
main_nav_linksfor text links in the header
extra_header_link_iconfor icon links on the right side of the header.
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-parserpackage 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.
Create a better visual hierarchy which makes the document easier to scan. Heavily inspired by the Material Design website.
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.