Sphinx RTD-Theme Dark Mode

A comprehensive dark mode implementation for the Sphinx Read the Docs theme that provides an elegant dark interface while maintaining excellent readability and accessibility. Theme used for this web site.

Features

πŸŒ™ Dark Mode Styling

  • Complete Dark Theme: Professional dark color scheme for all elements

  • High Contrast: Optimized text contrast for excellent readability

  • Eye-Friendly: Reduces eye strain during extended reading sessions

  • Consistent Design: Maintains RTD theme’s clean, professional appearance

🎨 Enhanced Visual Elements

  • Smooth Transitions: Animated hover effects and state changes

  • Custom Scrollbars: Dark-themed scrollbars that match the overall design

  • Improved Navigation: Enhanced sidebar and navigation styling

  • Code Block Optimization: Dark syntax highlighting for better code readability

πŸ”§ Responsive Design

  • Mobile Friendly: Optimized for all screen sizes

  • Print Compatibility: Maintains readability when printed

  • Accessibility: WCAG compliant color contrasts

  • Cross-Browser: Works across all modern browsers

Installation

Requirements

  • Sphinx documentation generator

  • Read the Docs theme (sphinx_rtd_theme)

  • Basic CSS customization support

Setup

  1. Copy the CSS file’s custom.css and code-block.css to your Sphinx project:

    Click on this link custom.css to download the custom.css file. Click on this link code-block.css to download the custom.css file.

    Copy the file custom.css and code-block.css to the source/_static/css directory.

    Tip

    Right click on the link, copy link address. Use a shell terminal and navigate to source/_static/css directory. Then use wget to download. This will download the custom.css and code-block.css files, without needing to copy from your Download directory.

  2. Update your conf.py to include the CSS:

    # Ensure static path is configured
html_static_path = ['_static']

# Add your custom CSS
html_css_files = [
    'css/custom.css',
    'css/code-block.css',
    # ... your other CSS files
]

  3. Build your documentation:

    make clean && make html

  4. Clear browser cache (important for seeing changes):

    • Hard refresh: Ctrl+F5 (Windows/Linux) or Cmd+Shift+R (Mac)

    • Clear cache: Use browser developer tools to clear site data

    • Incognito/Private mode: Test in a fresh browser session

CSS File Structure

The dark mode CSS is organized into logical sections:

custom.css
β”œβ”€β”€ Color Variables          # Global color definitions
β”œβ”€β”€ Body & Background        # Main page styling
β”œβ”€β”€ Navigation & Sidebar     # Left sidebar styling
β”œβ”€β”€ Content Area            # Main content styling
β”œβ”€β”€ Code Blocks             # Syntax highlighting
β”œβ”€β”€ Tables & Lists          # Data presentation
β”œβ”€β”€ Search & Forms          # Interactive elements
β”œβ”€β”€ Responsive Design       # Mobile adaptations
└── Print Styles           # Print-friendly overrides

Color Scheme

Primary Colors

Element

Light Mode

Dark Mode

Usage

Background

#ffffff

#1e1e1e

Main page background

Text

#404040

#e0e0e0

Primary text content

Sidebar

#f8f8f8

#2d2d2d

Navigation background

Code Blocks

#f8f8f8

#2d2d2d

Code background

Links

#2980b9

#4da6e0

Hyperlinks

Borders

#e1e4e5

#404040

Dividers and borders

Accent Colors

  • Success: #27ae60 β†’ #2ecc71 (Green)

  • Warning: #f39c12 β†’ #f1c40f (Orange/Yellow)

  • Error: #e74c3c β†’ #e67e22 (Red/Orange)

  • Info: #3498db β†’ #74b9ff (Blue)

Customization

Adjusting Colors

To modify the color scheme, edit the CSS variables at the top of the custom.css file:

:root {
  --bg-color: #1e1e1e;           /* Main background */
  --text-color: #e0e0e0;         /* Primary text */
  --sidebar-bg: #2d2d2d;         /* Sidebar background */
  --accent-color: #4da6e0;       /* Links and accents */
  --border-color: #404040;       /* Borders and dividers */
}

To modify the code block css see Code Block CSS - Syntax Highlighting Reference

Troubleshooting

Common Issues

Q: Dark mode not applying A: Ensure custom.css is in the correct path and listed in html_css_files

Q: CSS changes not visible A: Hard refresh your browser (Ctrl+F5 or Cmd+Shift+R) or clear browser cache. This is the most common issue when developing CSS.

Q: Navigation hover effects not working A: Try a hard refresh first. If still not working, check browser developer tools to see if CSS is loading properly.

Q: Some elements still show light colors A: Check for theme-specific CSS that may override the dark styles

Q: Text is hard to read A: Adjust contrast ratios in the color variables section

Q: Mobile layout issues A: Verify responsive breakpoints are working correctly

This dark mode CSS was developed to provide a professional, accessible, and visually appealing dark theme for Sphinx documentation while maintaining the excellent usability of the Read the Docs theme.