HTML theme development — Sphinx documentation

Added in version 0.6.
This document provides information about creating your own theme. If you simply wish to use a pre-existing HTML themes, refer to HTML theming.
Sphinx supports changing the appearance of its HTML output via themes. A theme is a collection of HTML templates, stylesheet(s) and other static files. Additionally, it has a configuration file which specifies from which theme to inherit, which highlighting style to use, and what options exist for customizing the theme’s look and feel.
Themes are meant to be project-unaware, so they can be used for different projects without change.
See Sphinx API for more information that may be helpful in developing themes.
Themes take the form of either a directory or a zipfile (whose name is the theme name), containing the following:
Either a theme.toml file (preferred) or a theme.conf file.
HTML templates, if needed.
A static/ directory containing any static files that will be copied to the output static directory on build. These can be images, styles, script files.
The theme.toml file is a TOML document, containing two tables: [theme] and [options].
The [theme] table defines the theme’s settings:
inherit (string): The name of the base theme from which to inherit settings, options, templates, and static files. All static files from theme ‘ancestors’ will be used. The theme will use all options defined in inherited themes. Finally, inherited themes will be used to locate missing templates (for example, if "basic" is used as the base theme, most templates will already be defined).
If set to "none", the theme will not inherit from any other theme. Inheritance is recursive, forming a chain of inherited themes (e.g. default -> classic -> basic -> none).
stylesheets (list of strings): A list of CSS filenames which will be included in generated HTML header. Setting the html_style config value will override this setting.
Other mechanisms for including multiple stylesheets include @import in CSS or using a custom HTML template with appropriate <link rel="stylesheet"> tags.
sidebars (list of strings): A list of sidebar templates. This can be overridden by the user via the html_sidebars config value.
pygments_style (table): A TOML table defining the names of Pygments styles to use for highlighting syntax. The table has two recognised keys: default and dark. The style defined in the dark key will be used when the CSS media query (prefers-color-scheme: dark) evaluates to true.
[theme.pygments_style.default] can be overridden by the user via the pygments_style config value.
The [options] table defines the options for the theme. It is structured such that each key-value pair corresponds to a variable name and the corresponding default value. These options can be overridden by the user in html_theme_options and are accessible from all templates as theme_<name>.
Added in version 7.3: theme.toml support.
Exemplar theme.toml file:
The theme.conf file is in INI format [1] (readable by the standard Python configparser module) and has the following structure:
The inherit setting gives the name of a “base theme”, or none. The base theme will be used to locate missing templates (most themes will not have to supply most templates if they use basic as the base theme), its options will be inherited, and all of its static files will be used as well. If you want to also inherit the stylesheet, include it via CSS’ @import in your own.
The stylesheet setting gives a list of CSS filenames separated commas which will be referenced in the HTML header. You can also use CSS’ @import technique to include one from the other, or use a custom HTML template that adds <link rel="stylesheet"> tags as necessary. Setting the html_style config value will override this setting.
The pygments_style setting gives the name of a Pygments style to use for highlighting. This can be overridden by the user in the pygments_style config value.
The pygments_dark_style setting gives the name of a Pygments style to use for highlighting when the CSS media query (prefers-color-scheme: dark) evaluates to true. It is injected into the page using add_css_file().
The sidebars setting gives the comma separated list of sidebar templates for constructing sidebars. This can be overridden by the user in the html_sidebars config value.
The options section contains pairs of variable names and default values. These options can be overridden by the user in html_theme_options and are accessible from all templates as theme_<name>.
Added in version 1.7: sidebar settings
Changed in version 5.1: The stylesheet setting accepts multiple CSS filenames
INI-style theme configuration files (theme.conf) can be converted to TOML via a helper programme distributed with Sphinx. This is intended for one-time use, and may be removed without notice in a future version of Sphinx.
The required argument is a path to a directory containing a theme.conf file. The programme will write a theme.toml file in the same directory, and will not modify the original theme.conf file.
Added in version 7.3.
As a way to distribute your theme, you can use a Python package. This makes it easier for users to set up your theme.
To distribute your theme as a Python package, please define an entry point called sphinx.html_themes in your pyproject.toml file, and write a setup() function to register your theme using the add_html_theme() API:
If your theme package contains two or more themes, please call add_html_theme() twice or more.
Added in version 1.2: ‘sphinx_themes’ entry_points feature.
Deprecated since version 1.6: sphinx_themes entry_points has been deprecated.
Added in version 1.6: sphinx.html_themes entry_points feature.
The stylesheets setting can be used to add custom CSS files to a theme.