Brand Your Docs on ReadTheDocs: Custom CSS for the RTD Sphinx Theme

Problem: Docs that Don’t Match Your Brand

When your open‑source or internal documentation lives on ReadTheDocs, the default sphinx_rtd_theme gives you a clean, functional look but it’s hard to make it feel like part of your product. A mismatched logo, color palette, or typography can make the docs feel disjointed and reduce user confidence.

Thesis: Override the Theme with a Custom Stylesheet

ReadTheDocs lets you keep the theme’s structure while injecting your own CSS. The process is lightweight, survives theme upgrades, and works both locally and in the hosted build.

How the RTD Theme Loads Styles

The theme bundles a set of CSS files in the _static directory. Sphinx appends any files listed in html_css_files after the theme’s defaults, giving your styles the last word. Because the custom file is part of your repository, theme updates never overwrite it.

Practical Example

1. Create a custom.css in the docs source

   /* docs/source/custom.css */
   /* Replace the side‑bar background */
   .wy-side-nav-search {
       background-color: #004080;
       color: #ffffff;
   }
   /* Add your logo next to the title */
   .wy-side-nav-search .logo {
       background-image: url("_static/my_logo.png");
       background-size: contain;
       width: 120px;
       height: 40px;
       margin-right: 10px;
   }
   /* Override the primary heading color */
   .rst-content h1, .rst-content h2 {
       color: #003366;
   }
   

2. Reference the stylesheet in conf.py

   # docs/source/conf.py
   import os
   
   # Tell Sphinx where to find static files
   html_static_path = ["_static"]
   
   # Add the custom stylesheet after the theme’s CSS
   html_css_files = ["custom.css"]
   

   Run make html locally. Open _build/html/index.html and confirm the new colors and logo appear. The custom.css file will be copied into _build/html/_static and linked in the HTML head.

3. Push to ReadTheDocs

   Commit both custom.css and the updated conf.py. The RTD build system will use the same Sphinx configuration, so the custom stylesheet is automatically applied. Verify the live URL and inspect the page source to see custom.css loaded from /static/custom.css.

Trade‑offs & Maintenance Considerations

• Theme updates can change HTML markup. If you target a selector that disappears, your style will be ignored. Keep selectors as specific as possible (e.g., .wy-side-nav-search instead of .search).
• Using !important can force a rule but makes future overrides harder. Prefer specificity over !important.
• Large CSS files increase page load time. If the stylesheet grows, consider inlining critical rules or using a CDN for the static assets.
• The custom stylesheet is part of your repo, so accidental deletion or path changes break the build. Add tests that check the presence of custom.css in the build log.

Actionable Next Steps

1. Decide on the branding assets you need: logo, colors, fonts.
2. Create custom.css with minimal overrides; keep it under 2 KB for performance.
3. Update conf.py as shown and run make html to test locally.
4. Push to your Git repository and let ReadTheDocs rebuild.
5. Use browser dev tools to verify that the CSS file is loaded and that your selectors are not overridden by the theme.
6. Document the CSS changes in your repo (e.g., README or a dedicated branding.md) so future maintainers know why the overrides exist.

With these steps you can give your documentation a consistent look that matches your product, while keeping the process lightweight and future‑proof.