{"id":7741,"library":"sphinx-rtd-dark-mode","title":"Sphinx RTD Dark Mode","description":"sphinx-rtd-dark-mode is a Sphinx extension that adds a toggleable dark mode to the Read the Docs Sphinx theme. Currently at version 1.3.0, it receives periodic updates to enhance styling, fix visual bugs across various Sphinx elements, and improve user experience.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/MrDogeBro/sphinx_rtd_dark_mode","tags":["sphinx","theme","dark mode","documentation","read the docs"],"install":[{"cmd":"pip install sphinx-rtd-dark-mode","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core documentation generator","package":"sphinx","optional":false},{"reason":"This extension is designed specifically for and requires the Read the Docs Sphinx theme. It will automatically set this theme if not already configured.","package":"sphinx-rtd-theme","optional":false}],"imports":[{"note":"Sphinx extensions are activated by adding their module name to the 'extensions' list in conf.py, not via direct Python imports.","wrong":"import sphinx_rtd_dark_mode","symbol":"sphinx_rtd_dark_mode","correct":"extensions = ['sphinx_rtd_dark_mode']"}],"quickstart":{"code":"# conf.py\n\nimport os\nimport sys\n# Add your project's path if necessary\n# sys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\nversion = '0.1'\nrelease = '0.1.0'\n\nhtml_theme = 'sphinx_rtd_theme'\nextensions = [\n    'sphinx_rtd_dark_mode',\n]\n\n# Optional: Set the default mode (True for dark, False for light)\ndefault_dark_mode = True\n\n# To build:\n# sphinx-build -b html . _build","lang":"python","description":"To enable sphinx-rtd-dark-mode, first ensure you have `sphinx` and `sphinx-rtd-theme` installed. Then, add `'sphinx_rtd_dark_mode'` to the `extensions` list in your `conf.py` file. Optionally, set `default_dark_mode = False` if you prefer the light theme on the first load."},"warnings":[{"fix":"Ensure `html_theme = 'sphinx_rtd_theme'` is set, or be aware the extension will set it for you.","message":"This extension is exclusively designed for the 'sphinx_rtd_theme'. If you have a different `html_theme` set in `conf.py`, the extension will override it to `sphinx_rtd_theme` to function correctly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `default_dark_mode = False` in `conf.py` if you prefer users to start in light mode.","message":"The `default_dark_mode` configuration option (boolean) controls whether users see dark mode or light mode on their *first* visit to the documentation. If not explicitly set, the default is `True` (dark mode first). User preferences are stored in local storage thereafter.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to version 1.1.1 or later (`pip install --upgrade sphinx-rtd-dark-mode`).","message":"Older versions (prior to 1.0.1 and 1.1.1) had issues with static CSS files not being included during installation, leading to the dark mode not appearing or being partially broken.","severity":"breaking","affected_versions":"<1.0.1, <1.1.1"},{"fix":"Ensure you are using the latest version (1.3.0+) for the most comprehensive styling fixes: `pip install --upgrade sphinx-rtd-dark-mode`.","message":"Various styling issues, such as unreadable text on certain elements (e.g., `guilabel`, admonitions, code blocks, navigation, tables) or incorrect fonts, were present in older versions.","severity":"gotcha","affected_versions":"<1.3.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install sphinx-rtd-dark-mode` in the correct Python environment. If using `venv`, ensure it's activated.","cause":"The package `sphinx-rtd-dark-mode` was not installed or installed in a different Python environment.","error":"ModuleNotFoundError: No module named 'sphinx_rtd_dark_mode'"},{"fix":"1. Verify `'sphinx_rtd_dark_mode'` is in the `extensions` list in `conf.py`. 2. Ensure `html_theme = 'sphinx_rtd_theme'`. 3. Upgrade to the latest version: `pip install --upgrade sphinx-rtd-dark-mode`.","cause":"The extension might not be correctly added to `conf.py`'s `extensions` list, or an old version with static file inclusion bugs is being used. Alternatively, `html_theme` might be set to a non-RTD theme, leading to unexpected behavior (though the extension attempts to correct this).","error":"Sphinx build completes, but dark mode toggle or styling is missing/broken."},{"fix":"Upgrade to the latest version (1.3.0+) of `sphinx-rtd-dark-mode` which includes fixes for these styling issues: `pip install --upgrade sphinx-rtd-dark-mode`.","cause":"This is a known bug in older versions of the extension where specific element styles were not correctly converted for dark mode.","error":"Some text elements (e.g., function names, admonitions, inline code) are unreadable in dark mode (dark text on dark background)."}]}