Dark mode toggle

[choldgraf]

Description

We should implement the ability to toggle between a "dark mode" that makes the background dark and the text light colored.

Benefit

This is an accessibility feature and is also more generally just something that many people find useful to help with readability.

Implementation

We should be able to do this by controlling CSS variables. @bollwyvl even has a nice PR implementation (not quite finished) here: #273

[flying-sheep]

the default state should be derived from the system theme via media query like in the furo theme:

• js: https://github.com/pradyunsg/furo/blob/9534e33cec40f5e004eb625285e1e902b8b8a752/src/furo/assets/scripts/furo.js#L84-L107
• css: https://github.com/pradyunsg/furo/blob/9534e33cec40f5e004eb625285e1e902b8b8a752/src/furo/assets/styles/base/_theme.sass#L16-L38

cc @bollwyvl

[choldgraf]

@flying-sheep check out the PR that is implementing this here: #540 I think that one is getting close, reviews / suggestions are welcome!

[flying-sheep]

ah neat! #540 is definitely the way to go, very comprehensive.

[12rambau]

@choldgraf do you thing this could be closed now that #540 has been merged or is there still work to do ?

[choldgraf]

Closed in #540 by @12rambau - thanks so much for this awesome PR!

[damianavila]

Indeed, awesome PR (and patience with us) @12rambau. Thank you very much!!

[freddyaboulton]

Thank you all for implementing this feature + providing this great theme.

How can I set the default value of this toggle to light mode? We have some plots/logos in our documentation that look better in light mode.

[choldgraf]

hmmm I seem to remember us discussing this but I don't remember the conclusion. @12rambau do you remember?

[12rambau]

@freddyaboulton to force the theme you can follow the instruction from the documentation: (https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/configuring.html#configure-default-mode) and set the default theme in the conf.py file:

html_context = {
   # ...
   "default_mode": "light"
}

To help you tuning your documentation, there also an entire section about dark mode tricks:
https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/customizing.html#manage-light-and-dark-themes

[deepaksirohiwal]

Hi @choldgraf, how can I add the switch to my doc page? By default, it is using the system setting but I want to add the switch.

[drammock]

@deepaksirohiwal https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/light-dark.html#configure-default-theme-mode

By default the light/dark mode switcher appears in the header bar among the "navbar end items":

pydata-sphinx-theme/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/theme.conf

Line 33 in 88296e5

navbar_end = theme-switcher.html, navbar-icon-links.html

Make sure in your conf.py you're either not specifying navbar_end at all or you're including theme-switcher in navbar_end:

html_theme_options = {
    # various other entries...
    "navbar_end": ["theme-switcher", "navbar-icon-links"],
    # ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑ this is the crucial bit
}

[deepaksirohiwal]

Thanks a lot @drammock !

[seanlaw]

@drammock Are you aware of any way to completely disable dark mode (i.e., only allow light mode)? Currently, I am using:

html_context = {"default_mode": "light"}

but this doesn't disable dark mode.

[12rambau]

@seanlaw, you cannot really disable it but you can make it unreachable by removing the theme switcher from the header navbar:

# conf.py

html_theme_options = {
    "navbar_end": ["navbar-icon-links"],
}

[flying-sheep]

Why would you want to reduce accessibility for your site?

[12rambau]

some sites are using lots of images and third party libs that are not (yet) supporting the dark theme. In order to avoid breaking all their display, they prevent the switch.

[wowone]

I'd like to disable dark mode completely too. The reason is that originally I created a doc for a light theme. At some point I realised that I also need to tune the doc so it could suit dark theme as well. And currently I have no resources for it. So it would be easier to me to disable it everywhere.

[flying-sheep]

As an alternative that doesn’t compromise accessibility, you could consider adding a white background or filter: hue-rotate(.5turn) invert(100%); to images in dark mode.

[12rambau]

@flying-sheep the white background is already automatically added to any all image:

pydata-sphinx-theme/src/pydata_sphinx_theme/assets/styles/variables/_color.scss

Line 121 in 13d4692

.bd-content img:not(.only-dark):not(.dark-light) {

[flying-sheep]

Ah, but doesn’t that mean there’s no actual problem?

[12rambau]

for some specific extensions the rendering is not yet very satisfying (jupyterlite, graphviz... etc) so if you perfectly tuned everything for the light one, it's easier to drop the dark one altogether.