How to modify Sphinx theme?#

Tech writers should write. Delivering documentation in a visually appealing manner is almost the same important as the content itself, however. Sphinx themes are “skins” that define look & feel of documentation when outputted to HTML format. In this post, you will learn how to customize existing or create a new theme from scratch.

Creating or customizing Sphinx theme requires at least basic web design skills and an understanding of how Sphinx theme works. The latter you will learn in here.

Custom CSS#

Custom CSS stylesheet is the most common way how to modify the existing Sphinx theme.

You will create custom CSS that will be placed as <link rel="stylesheet"> after theme’s main CSS giving you the opportunity to overwrite styles you don’t like.

Open your conf.py and search for html_static_path option. This option is the list of paths to folders and files that will be copied during the build to the output. There are big changes it will contains at least or only the _static folder (html_static_path = ['_static']). If not, append _static to the option. Ensure this folder actually exist (at the level of conf.py file). For example:
```
_static/
_templates/
getting-started/
installation/
theming/
conf.py
index.rst
second.rst
third.rst
```
Still in conf.py: create or update the html_css_files option to contain custom.css. For example:
```
html_css_files = ["custom.css"]
```
Create custom.css inside _static/ folder. (You can choose whatever filename you like.)

Write your custom styles or override existing. For example:

@import "https://fonts.googleapis.com/css?family=Saira+Extra+Condensed:700&amp;subset=latin-ext";

h1, h2, h3, h4, h5, h6 {
    margin-top: 0;
    font-weight: 700;
    font-family: "Saira Extra Condensed", Arial, sans-serif;
}

h1, h2, h3 {
    text-transform: uppercase;
}

/* ... */

Delete output folder (usually build, _build, etc.), build Sphinx project, open and check generated HTML files.

Modify favicon#

Favicons are small icons displayed on the page tab in the browser. Setting custom favicon is a must customization that is very easy to follow.

Put your favicon (probably named favicon.ico) to _static folder.
Set value of conf.py html_favicon option to path to this file. E.g.:
```
html_favicon = "_static/favicon.ico"
```

Explore theme options#

Themes often has a collection of theme options <themes-options> for fine-tuning the theme features. Theme options are usually used for setting font family, hiding logo, hiding prev/next buttons, etc. Have a look at your theme documentation what options you can modify.

Advantage of theme options is they are easy customizable in project’s conf.py html_theme_options. For example:

html_theme = 'mytheme'

html_theme_options = {
    'motto': 'A picture is worth a thousand words.',
    'display_gitlab': True
}

Previous: Sphinx Themes Next: CSS to remove document title from Sphinx local ToC

TechWriter at work blog

How to modify Sphinx theme?#

Custom CSS#

Modify favicon#

Explore theme options#

Comments