Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Dark mode toggle #458

Closed
choldgraf opened this issue Aug 28, 2021 · 21 comments
Closed

Dark mode toggle #458

choldgraf opened this issue Aug 28, 2021 · 21 comments
Labels
kind: enhancement New feature or request needs: discussion Needs discussion before an implementation can be made tag: CSS CSS and SCSS related issues tag: design Items related to design tasks or improvements

Comments

@choldgraf
Copy link
Collaborator

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

@choldgraf choldgraf added tag: CSS CSS and SCSS related issues tag: design Items related to design tasks or improvements kind: enhancement New feature or request impact: medium needs: discussion Needs discussion before an implementation can be made labels Aug 28, 2021
@flying-sheep
Copy link
Contributor

flying-sheep commented Feb 23, 2022

@choldgraf
Copy link
Collaborator Author

@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
Copy link
Contributor

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

@12rambau
Copy link
Collaborator

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

@choldgraf
Copy link
Collaborator Author

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

@damianavila
Copy link
Collaborator

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

@freddyaboulton
Copy link

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
Copy link
Collaborator Author

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

@12rambau
Copy link
Collaborator

@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
Copy link

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
Copy link
Collaborator

@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":

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
Copy link

Thanks a lot @drammock !

@seanlaw
Copy link

seanlaw commented Oct 4, 2022

@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
Copy link
Collaborator

12rambau commented Oct 4, 2022

@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
Copy link
Contributor

Why would you want to reduce accessibility for your site?

@12rambau
Copy link
Collaborator

12rambau commented Oct 4, 2022

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
Copy link

wowone commented Jan 5, 2023

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
Copy link
Contributor

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
Copy link
Collaborator

12rambau commented Jan 5, 2023

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

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

@flying-sheep
Copy link
Contributor

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

@12rambau
Copy link
Collaborator

12rambau commented Jan 6, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: enhancement New feature or request needs: discussion Needs discussion before an implementation can be made tag: CSS CSS and SCSS related issues tag: design Items related to design tasks or improvements
Projects
None yet
Development

Successfully merging a pull request may close this issue.

9 participants