How to add custom css file to Sphinx?

Question

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:

$ 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

Related question: https://stackoverflow.com/questions/32079200/how-do-i-set-up-custom-styles-for-restructuredtext-sphinx-readthedocs-etc/68394150#68394150 — Louis Maddox, Jul 15 '21 at 12:55

score 59 · Accepted Answer · edited Sep 14 '20 at 15:31

59

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.

edited Sep 14 '20 at 15:31

Hugo

27,885
8
82
98

answered Jun 23 '16 at 00:11

Gringo Suave

29,931
6
88
75

4

add javascript files via `app.add_javascript('file.js')`. – Anil Jul 26 '17 at 17:37
After doing that, I still have to manually add a reference to the css in the html file... Anything more automatic? – Tony May 25 '18 at 19:27
@Tony been a while, but may be a function of the theme. – Gringo Suave May 28 '18 at 17:28
5

perhaps worthwhile to note that [alabaster theme](https://alabaster.readthedocs.io/en/latest/) works out-of-the box with a `_static/custom.css` file in source folder so `add_styleshee('custom.css')` would not be needed for this theme. – Jun 20 '18 at 07:42
This works with this line: html_static_path = ['_static'] – fred.yu Oct 14 '21 at 06:42

score 25 · Answer 2 · edited Oct 02 '19 at 17:11

25

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.

edited Oct 02 '19 at 17:11

Gringo Suave

29,931
6
88
75

answered May 05 '14 at 06:53

Cole

1,699
1
17
21

Could you explain, what is symbol `!` means? – ole May 05 '14 at 14:12
3

"By prefixing the name of the overridden template with an exclamation mark, Sphinx will load the layout template from the underlying HTML theme." I've added a link to the sphinx documentation on templating above. Mainly that line is called to extend the default sphinx layout.html, or whatever theme you might have installed. – Cole May 05 '14 at 14:41
1

Thx, one more question plz: You example work as expected after `make html`, but does not work on [readthedocs.org](http://readthedocs.org) with default theme(sphinx_rtd_theme). – ole May 05 '14 at 15:03
1

You are correct. I just pulled the sphinx_rtd_theme down and tried to extend the theme with my custom css, and the sphinx_rtd_theme overrides that css. I searched the github issues and this seems to be a problem with other css as well. [github issue 117](https://github.com/snide/sphinx_rtd_theme/issues/117). I'll continue to play with it and see, if I can get it to work with the theme, but it seems to be a current limitation of sphinx_rtd_theme as mentioned in that issue. – Cole May 05 '14 at 16:39
2

Thx for the link, `add_stylesheet` solved my problem. – ole May 05 '14 at 18:15
I noticed that the css will not be rebuilt when I use sphinx-autobuild. – reggie Nov 16 '15 at 09:39
FTR the templating link is now https://www.sphinx-doc.org/en/master/templating.html. SO wouldn't let me suggest an edit to the answer for some reason so I'm pointing it here. – webknjaz -- Слава Україні Apr 29 '21 at 21:12

igor · Answer 3 · 2022-03-25T15:08:17.547

16

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

edited Mar 25 '22 at 15:08

answered Dec 22 '15 at 16:45

igor

2,090
20
32

2

Thank you! Out of the answers provided, this is what helped me override annoying auto-hyphenation in the basic.css. – tterry Jul 14 '17 at 01:18
The link is now dead. – firebush Mar 24 '22 at 14:45

score 13 · Answer 4 · edited Oct 23 '20 at 10:47

13

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

edited Oct 23 '20 at 10:47

tomerpacific

4,704
13
34
52

answered Oct 23 '20 at 08:53

moryama

149
1
4

1

This is the approach recommended by [ReadTheDocs](https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html) and [Furo](https://pradyunsg.me/furo/customisation/injecting/#injecting-code) – Louis Maddox Jul 15 '21 at 12:54

How to add custom css file to Sphinx?

4 Answers4

Linked

Related