How to add custom css file to Sphinx?

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

# conf.py
html_static_path = ['_static']
html_theme = 'default'
html_theme_options = {
  'cssfiles': ['_static/style.css']
}

Result:

C:temptest-docsdocs>make html
Running Sphinx v1.2.2
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [ 50%] help
reading sources... [100%] index

looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents...
Theme error:
unsupported theme option 'cssfiles' given

Answers:

Thank you for visiting the Q&A section on Magenaut. Please note that all the answers may not help you solve the issue immediately. So please treat them as advisements. If you found the post helpful (or not), leave a comment & I’ll get back to you as soon as possible.

Method 1

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.

Method 2

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.

Method 3

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.)

Method 4

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

All methods was sourced from stackoverflow.com or stackexchange.com, is licensed under cc by-sa 2.5, cc by-sa 3.0 and cc by-sa 4.0