sphinx-rtd-dark-mode

What it is and what it does

This is a Sphinx extension that layers dark mode functionality onto the Read the Docs theme. When installed and added to your Sphinx conf.py, it injects a toggle button in the bottom right corner of your documentation site, letting readers switch between light and dark color schemes. The reader's choice is saved in their browser's local storage, so their preference persists across visits.

The extension is lightweight—it has only one runtime dependency, sphinx-rtd-theme—and requires minimal configuration. You can set a default mode (dark or light) for first-time visitors, but after that, the user's stored preference takes over. The package is marked Production/Stable and has been dormant since late 2023, suggesting it is feature-complete rather than actively developed.

Use it for:

• Enable dark mode for technical documentation sites to reduce eye strain for readers working at night or in low-light environments.
• Provide accessibility-conscious documentation by offering both light and dark viewing modes without requiring server-side theme switching.
• Add a polished UX touch to Sphinx-based project documentation with minimal setup overhead.
• Let readers with visual sensitivity or preference for dark interfaces control their viewing experience without site configuration changes.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Adds a toggleable dark mode interface to Sphinx documentation built with the Read the Docs theme, letting readers switch between light and dark viewing modes with a button in the corner.

Yes, if you use Sphinx with the Read the Docs theme and want to offer dark mode to your readers. Installation is straightforward, maintenance burden is minimal, and the permissive MIT license poses no legal risk. The dormant status is not a concern for a feature-complete extension; however, verify compatibility with your current sphinx-rtd-theme version before deploying to production.

Install

sphinx-rtd-dark-mode on PyPI

pip install sphinx-rtd-dark-mode

uv add sphinx-rtd-dark-mode

poetry add sphinx-rtd-dark-mode

Installing sphinx-rtd-dark-mode

Before you install

Low friction install with a single runtime dependency on sphinx-rtd-theme. Maintenance is dormant—last release was 2023-09-19 and no commits since 2023-09-22—but the package is marked Production/Stable and has received no security reports.

License in practice

MIT license is permissive; you can use this in commercial or private projects without restriction, though you must retain the license notice.

Quickstart

pip install sphinx-rtd-dark-mode

# In conf.py:
extensions = ["sphinx_rtd_dark_mode"]
default_dark_mode = True  # optional: users start in dark mode

Requires Python 3.4 or higher and the sphinx-rtd-theme package to be installed and active in your Sphinx configuration.

Verify before relying

• Whether the dark mode toggle works correctly with recent versions of sphinx-rtd-theme, given the last commit was 2023-09-22.
• Whether browser local storage persistence of user preference works across all modern browsers.

Package facts

Evidence: sphinx_rtd_dark_mode-1.3.0-py3-none-any.whl

Tags

More Sphinx packages