Adding additional stylesheets or scripts¶

If your custom stylesheet is _static/css/custom.css, you can add that CSS file to the documentation using the Sphinx option html_css_files:

## conf.py

# These folders are copied to the documentation's HTML output
html_static_path = ['_static']

# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
    'css/custom.css',
]

A similar approach can be used to add JavaScript files:

html_js_files = [
    'js/custom.js',
]

That’s it! You don’t need to create a Sphinx extension anymore to add a bit of custom CSS or JavaScript.

Customizations supported by your theme¶

I should also note that depending on the theme you’re using and what you’re hoping to accomplish, you may not even need to add custom CSS or JavaScript. Many themes support a number of “theme options” for customizing their look and feel without having to write custom code. For example, here are all the options for the Read the Docs theme and the Alabaster theme which are the two most popular themes on Read the Docs itself.

Both themes, for example, support the addition of Google Analytics to documentation by setting the analytics_id option:

## conf.py

html_theme_options = {
    'analytics_id': 'UA-XXXXXXX-1',  #  Provided in your GA dashboard
}

In summary¶

To recap, it only takes a few additions to your conf.py to add custom CSS or JavaScript. However, it’s also worth taking a look at your theme’s docs or Sphinx’s built-in HTML options to see if what you’re trying to do is already supported.

Happy documenting!