Change the colors of the Sphinx Read The Docs theme?

Question

I'm building documentation for my API library and I'm having readthedocs.io host the documentation, and is backed with Sphinx. I have the Read The Docs theme installed for Sphinx using pip install, and the Read the Docs website currently has the documentation running.

I would like to change the colors of my documentation. I have done some searching through their GitHub repository GitHub.com and have seen some talk that editing the sass files. However, I can't seem to find where these files are located.

Example of a Read The Docs with other colors

score 29 · Accepted Answer · answered Jan 16 '18 at 12:52

I believe the canonical way is to create a _static folder, include CSS files in that, and then reference that CSS in your templates with an include in the _templates folder.

To demonstrate this, you can try a simple override of the layout.html file: first, create _templates in your docs folder if it doesn't already exist, then create a file there named layout.html.

Populate that with the following:

{% extends "!layout.html" %}
  {% block footer %} {{ super() }}

  <style>
    /* Sidebar header (and topbar for mobile) */
    .wy-side-nav-search, .wy-nav-top {
      background: #00ff00;
    }
    /* Sidebar */
    .wy-nav-side {
      background: #ff0000;
    }
  </style>
{% endblock %}

Once you've rebuilt your docs, you should see a garish side-bar and header. (I used a similar technique with our Sphinx / Read The Docs theme implementation. View source etc. to see which bits we override.)

If you just want to change the simplest colors of the theme, this answer works perfectly. Thanks. — Lex Li, Aug 09 '18 at 22:11
If it wasn't clear (i.e. if you're a noob like me) you can replace the ` — Luke Davis, Nov 17 '19 at 12:18

score 13 · Answer 2 · edited Feb 10 '22 at 11:45

13

You can change the theme colors by adding a custom CSS file to _static. To actually have Sphinx use that file, add this to your conf.py:

def setup(app):
    app.add_css_file('custom.css')

Sample CSS (custom.css) to change the sidebar color to dark-green (based on @afit's answer):

.wy-side-nav-search, .wy-nav-top {
    background: #0b750a;
}

edited Feb 10 '22 at 11:45

bad_coder

11,289
20
44
72

answered Jan 22 '19 at 09:23

Gustavo Bezerra

9,984
4
40
48

1

didn't work for me – Gonzalo Garcia Apr 30 '22 at 03:40
1

@GonzaloGarcia: you may need to run `make clean`, `make html`. The sample CSS was useful for me. However, i replaced the `def setup(app)...` part by Azmisovs answer. – Martin Ellguth Sep 21 '22 at 08:56
@GonzaloGarcia What Sphinx version are you on? I just checked again using Sphinx 5.2.2 and it still works fine for me. The `html_css_files` approach also works fine by the way. – Gustavo Bezerra Sep 28 '22 at 08:24

score 8 · Answer 3 · answered Mar 15 '19 at 23:51

8

If you only want to change the color of the navigation header, you can do that by using the html_theme_options variable in conf.py. There is parameter called 'style_nav_header_background'.

https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#theme-options

answered Mar 15 '19 at 23:51

Daniel Ching

443
5
9

1

getting `preparing documents... WARNING: unsupported theme option 'style_nav_header_background' given` – Gonzalo Garcia Apr 30 '22 at 03:33
@GonzaloGarcia yep, this didn't work for me either. – david May 19 '22 at 11:55
@david adding a custom css worked for me. You just have to force using the color you want with `!important;` at the end of each line – Gonzalo Garcia May 20 '22 at 16:48

score 7 · Answer 4 · answered Sep 28 '20 at 17:25

An easier way to add CSS files is to set html_css_files in your conf.py:

# custom.css is inside one of the html_static_path folders (e.g. _static)
html_css_files = ["custom.css"]

See: https://docs.readthedocs.io/en/latest/guides/adding-custom-css.html

Change the colors of the Sphinx Read The Docs theme?

4 Answers4

Linked