Repository navigation
Customization to select light/dark/dual mode #24
Description
Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
Currently, I think by default furo adapts to OS (or browser) settings to display light/dark mode. I'll be nice if we can choose to render only light mode, or only dark mode, or both like the present default.
Describe the solution you'd like
A clear and concise description of what you want to happen.
Something like a setting in conf.py for the preferred action?
html_theme_options = {
"theme-color": light/dark/dual,
}
Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.
Stick with the current default. :)
Activity
pradyunsg commentedon Oct 17, 2020
Sounds fair!
I'll note that I'd rather to make this configurable by the end-user; i.e. a part of the generated website and controlled by the user on a per-device-browser basis. That's more common and is usually what the users expect anyway.
pradyunsg commentedon Nov 8, 2020
Any bright ideas for where to put the toggle on the screen, on each resolution/breakpoint?
McSinyx commentedon Nov 9, 2020
pradyunsg commentedon Nov 9, 2020
pradyunsg commentedon Nov 27, 2020
In #44, the suggestion is to add it to the right sidebar.
Currently, Furo completely disables the right sidebar if there is no TOC to show, since that's... well, the only thing in the right sidebar, and an empty drawer is useless. :)
stonecharioteer commentedon Nov 28, 2020
I was going to say right side bar a la Docker, but @pradyunsg made the point I was about to make. How about give it as an option? Below the logo icon or at the bottom of the left sidebar
mlazag commentedon Dec 1, 2020
how about somewhere in the left sidebar (above or below the search box)? it's the kind of control that does not have to be visible when the left sidebar is not visible.
AWhetter commentedon Dec 12, 2020
This rust guide floats theirs in a bar at the top but we could make this button float in the top left of the content rather than in a bar? https://doc.rust-lang.org/book/ch04-01-what-is-ownership.html
Another option is at the bottom of the page with the footer.
pradyunsg commentedon Dec 15, 2020
The bar at the top only shows up on small resolutions, and is hidden on wider screens.
Aside from it not being clear where to position it in the top bar, I'm on board for that on small screens. Any thoughts on what to do on desktop resolutions?
adamgayoso commentedon Feb 9, 2021
any update on this? I'd like to use Furo, but we display a lot of jupyter notebooks that don't look good with the dark theme.
AWhetter commentedon Feb 9, 2021
I think that this is still pending the design decision about where to put the toggle and what it should look like. If you wanted to help progress this, assuming that @pradyunsg would be happy with the change, you could implement the mechanism that would allow for the user to override the decision about theme colour made by prefers-color-scheme. That way, until the decision about what it should look like in the theme has been made, users would have the flexibility to implement their own toggle.
adrn commentedon Feb 12, 2021
Just adding a +1 to this feature request -- I would love to have this option!
AdemFr commentedon Mar 1, 2021
+1 would love this feature :)
AWhetter commentedon Mar 1, 2021
If you want to see a feature implemented then it's best to give the issue a thumbs up, instead of leaving a comment, so that everyone watching the issue doesn't get a notification (See https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/).
j0yu commentedon Mar 15, 2021
There's also GoogleChromeLabs/dark-mode-toggle which might be worth looking into too, which can remembers per-user settings across the site and is fairly customisable.
It's is currently used on Google's https://v8.dev/ at the very bottom (see #proudly-used-on section for screenshots of comparison)
Edit: Made my own proof of concept which is fairly rough
johnthagen commentedon Mar 15, 2021
As prior art, Material for MkDocs supports three modes, a light, a dark, and a user preference.
And then their Insiders version also supports an additional toggle switch.
You can see this in action here: https://fastapi.tiangolo.com/
pradyunsg commentedon Mar 15, 2021
Thanks for sharing those links here!
At the cost of sounding a bit smug, I've seen them before I wrote this theme or within a week of them being publicly announced. They're definitely useful but knowledge about them isn't the blocker here. :)
The blockers to implementing this are:
html_theme_optionsoverrides)I don't know the answer to any of these, and haven't been super motivated to make time to explore them either. I think the best way to help move this forward would be to help figure out an answer to these questions. :)
sdabhi23 commentedon Apr 13, 2021
Hi guys, I have built a sample using pure HTML, SCSS, JS and Jinja. It also supports the
html_theme_optionsoverrides for the themes as well as colorsBasically I created 2 top level CSS classes (
darkandlight) and separated the color scheme related CSS into those classes (thanks to @j0yu's work, it was easy for me to locate all the color scheme specific CSS). Also loaded the relevant pygment CSS for each theme under the respective top level class.Then created a small JS function to assign the right class to the
<html>tag on page load and a function to toggle the class on button press. The theme value is also stored in localStorage to remember the user's color scheme choice across reloads.I have put a basic HTML button for toggling the color scheme in the left sidebar just above the search box for the time being. The toggle button is hidden using
display: nonewhen the author has fixed the color scheme fromhtml_theme_options. Have used only vanilla JS, so should work across most browsers.A demo is available on https://sdabhi23.github.io/furo/ and the code is available on https://github.com/sdabhi23/furo. Do share your thoughts about this approach @pradyunsg!
Can create a PR for this basic skeleton if the approach sounds good. More work needs to be done on thorough testing of all the functionalities and styling of the toggle button IMO.
pradyunsg commentedon Jul 26, 2021
Screen.Recording.2021-07-25.at.15.29.32.mov
This is now implemented, as a 3-state "toggle" between auto / dark / light. It only took refactoring a substantial portion of the colors-related styles in this theme, changing how CSS variables are handled in this theme, some duplication of the dark mode styles and completely working around how Sphinx generates
pygments.cssfile by overwriting it with a custom variant of that file.The overrides are JS-dependent. If you don't have JS enabled, you won't get the ability to override the colours.
I don't want to be adding a "force light mode" or anything like that -- there are
only-darkandonly-lightclasses that you can put on the elements to help with implementing elements that don't properly support both modes. I want documentation authors to support both of them if they're using Furo.I'll cut a release next weekend. If you want to try it out, the current http://pradyunsg.me/furo/ pages reflect the current implementation that is on the
mainbranch.pradyunsg commentedon Jul 26, 2021
Thanks to @sdabhi23 for his sample above! It definitely saved me a lot of searching-for-the-right-syntax, even though I've made a few different choices on how things should work. ^>^
pradyunsg commentedon Jul 29, 2021
This is released in beta39. Thanks @pavithraes for the filing this!