sphinx-book-theme
sphinx-book-theme copied to clipboard
executablebooks
Add a dark mode
Description
Many themes have at least two options for their CSS: light and dark mode. Dark mode is a common feature to help reduce strain on the eyes. We should offer something like this in the sphinx-book-theme, perhaps as a toggle.
Dark modes can help people parse some content more easily, so this is partially an accessibility issue. Maybe others (@pradyunsg ?) have experience w/ this too.
Here's a blog post that describes how dark modes can work w/ minimal CSS changes: https://prudhvirampey.com/blog/colours/jekyll/css/fastpages/2020/10/30/hello-dark-mode.html
Another option would be to fix this in the pydata theme (in fact, @bollwyvl already has a shot at implementation). This would solve the problem for both themes! Here's a link to the issue: https://github.com/pydata/pydata-sphinx-theme/issues/458
Actions
Here are the actions needed to do this:
- [x] pydata theme release is made: https://github.com/pydata/pydata-sphinx-theme/releases/tag/v0.9.0
- [ ] update the dependency in the book theme
- [ ] make any adjustments needed to support the new pydata theme html structures, css classes, etc
- [ ] make the necessary adjustments to support dark mode in the book theme
- [ ] decide where the dark mode toggle should be in the book theme
- [ ] merge that in here and make a release of the book theme
One of the things that’s tricky with this, is that user’s content needs to be written such that it works under both schemes.
https://github.com/pradyunsg/furo/issues/28 has a bit more context. In general though, it’ll also make the css a little tricky to work with (if you’re doing anything with colours).
All that said, I do think this would be a nice improvement. I just don’t know what needs to be done to make it happen smoothly. :)
This is being worked on in the parent theme of this one, and we should be able to inherit it once it is merged. See:
- https://github.com/pydata/pydata-sphinx-theme/pull/540
@OlivierCodol I believe it has not yet been merged, here's the PR:
- https://github.com/pydata/pydata-sphinx-theme/pull/540
I believe this is now merged https://github.com/pydata/pydata-sphinx-theme/commit/454918d43c9a9d10764aeccccfb1a7aca4918cfd
Hey! Now that this is merged on pydata-sphinx-theme, what has to be done from sphinx-book-theme side to leverage dark mode?
I believe the next steps are:
- pydata theme release is made
- update the dependency in the book theme
- make any adjustments needed to support the new pydata theme html structures, css classes, etc
- make the necessary adjustments to support dark mode in the book theme
- decide where the dark mode toggle should be in the book theme
- merge that in here and make a release of the book theme
pydata theme is released! that's one item down: https://github.com/pydata/pydata-sphinx-theme/releases/tag/v0.9.0
I added that list to the top comment so others can help out, and so we can track progress
Maybe you all know about this but it hasn't been mentioned yet : the Furo theme, which Book cites as an inspiration, has a dark mode already. Maybe looking into how they did that could help ? Also, I'm getting a bit ahead I guess but as for the location of the dark mode toggle, I think it should probably be placed at the top of the page near the "fullscreen" and "download" buttons. That's where Furo put it, too.
I've updated the top comment with the current Actions list - we are getting close! Agreed we still need to figure out where that button should be. I'm thinking either the content header (as you suggest), or just under the logo in the primary sidebar.
Hi everyone, I'm new to jupyterbooks. I love this so much, I was reading through this thread and now I'm curious. How long until a toggle able dark mode is available in Jupyter Books? Or if possible, is there a way to have it default to the user's system preferences? If it is already available, how do I use it in my book?
