Techwriter at work blog.

Living and writing documentation at Documatt, small team of programmers that do write documentation too.

How to modify Sphinx theme?

Do you like your current HTML theme for Sphinx documentation project, but want only to change font family, increase the font size, change colors, and similar minor customizations? Learn common ways to customize and modify Sphinx themes.

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.

  1. Open your 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 file). For example:

  2. Still in create or update the html_css_files option to contain custom.css. For example:

    html_css_files = ["custom.css"]
  3. Create custom.css inside _static/ folder. (You can choose whatever filename you like.)

  4. Write your custom styles or override existing. For example:

    @import ";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;
    /* ... */
  5. 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.

  1. Put your favicon (probably named favicon.ico) to _static folder.

  2. Set value of 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 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 html_theme_options. For example:

html_theme = 'mytheme'

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


comments powered by Disqus