How to add custom css file to Sphinx?

Question

How I can add custom css file? The following config does not work for me:

# conf.py
html_static_path = [\'_static\']
html_theme = \'default\'
html_theme_opti         


        

Answer 1

I'm using Sphinx 3.2.

I was able to add some simple custom CSS by doing the following:

• add this line in conf.py right under html_static_path = ['_static']:

html_css_files = ['css/custom.css']

• go to docs/_static/ and add css/custom.css

• add custom css to your file then $ make html

Source

Answer 2

The options that you can configure via html_theme_options are theme-dependent. Check out the [options] section of your theme’s theme.conf to find out what is available.

On a global basis, though, you can define html_context in your conf.py to override the settings for css_files (and, for that matter, script_files too):

html_context = {
    'css_files': ['_static/custom.css'],
}

(For reference, have a look at Sphinx’s builders.html.StandaloneHTMLBuilder.prepare_writing() and see how self.globalcontext gets populated there.)

Answer 3

A simpler way is to add this to your conf.py:

def setup(app):
    app.add_css_file('css/custom.css')  # may also be an URL

Then put the file into the _static/css/ folder.

Answer 4

You should be able to include custom css by extending the default sphinx theme. In your conf.py you would specify where your extension to the theme would be, such as.

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

Then in _templates you would create a extension to the default theme named 'layout.html' that would include your cssfiles such as.

{# layout.html #}
{# Import the layout of the theme. #}
{% extends "!layout.html" %}

{% set css_files = css_files + ['_static/style.css'] %}

See sphinx's documentation on templating for more information.