How to add custom css file to Sphinx?
Solution 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.
Solution 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.
Solution 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.)
Solution 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 underhtml_static_path = ['_static']
:
html_css_files = ['css/custom.css']
-
go to
docs/_static/
and addcss/custom.css
-
add custom css to your file then
$ make html
Related videos on Youtube
![ole](https://i.stack.imgur.com/puhlO.gif?s=256&g=1)
Comments
-
ole about 2 years
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:\temp\test-docs\docs>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
-
Louis Maddox almost 3 yearsRelated question: stackoverflow.com/questions/32079200/…
-
-
ole about 10 yearsCould you explain, what is symbol
!
means? -
Cole about 10 years"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.
-
ole about 10 yearsThx, one more question plz: You example work as expected after
make html
, but does not work on readthedocs.org with default theme(sphinx_rtd_theme). -
Cole about 10 yearsYou 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. 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.
-
ole about 10 yearsThx for the link,
add_stylesheet
solved my problem. -
reggie over 8 yearsI noticed that the css will not be rebuilt when I use sphinx-autobuild.
-
tterry almost 7 yearsThank you! Out of the answers provided, this is what helped me override annoying auto-hyphenation in the basic.css.
-
Anil almost 7 yearsadd javascript files via
app.add_javascript('file.js')
. -
Tony about 6 yearsAfter doing that, I still have to manually add a reference to the css in the html file... Anything more automatic?
-
Gringo Suave about 6 years@Tony been a while, but may be a function of the theme.
-
Admin about 6 yearsperhaps worthwhile to note that alabaster theme works out-of-the box with a
_static/custom.css
file in source folder soadd_styleshee('custom.css')
would not be needed for this theme. -
webknjaz about 3 yearsFTR the templating link is now 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.
-
Louis Maddox almost 3 yearsThis is the approach recommended by ReadTheDocs and Furo
-
fred.yu over 2 yearsThis works with this line: html_static_path = ['_static']
-
firebush over 2 yearsThe link is now dead.
-
igor over 2 yearsThank you for noticing @firebush, I updated the link.