mkdocs
Dark mode support based on OS choice
I'm not sure if it's already done, but I couldn't find anything in the docs. If not, I think this would be a cool feature. I did see nav_style in the theme support, but that seems to only allow the header to be switched at compile time, as opposed to styling the page at runtime based on user/OS choice.
Case Study: favicon
Can it be changed depending upon the browser's light or dark theme?
GitHub.com Open a browser in light theme, and the GitHub.com favicon is black on transparent. Switch to dark theme, and GitHub's favicon switches to white on transparent. It looks... good, is visible
mkdocs.org In light theme, browse to https://www.mkdocs.org/ , observe the favicon is black on transparent. Switch to dark theme, refresh, the MkDocs favicon is remains black on dark, barely discernable...
Personally, I detest dark mode for anything. But that is just my personal opinion. While I won't force that opinion on others, I have absolutely no motivation to spend time on this. If anyone wants to work on this, they are welcome to provide a PR. I would be willing to review the PR.
Any PR needs to address all of the following concerns:
- All built-in themes should be addressed in the same manner. In other words, a single PR should address both built-in themes, not just the one you care about (although... see next item).
- The
readthedocstheme is a clone of the Sphinx theme of the same name. Any dark mode in this theme much reflect the upstream theme. I haven't checked if the upstream theme even supports a dark mode, so this may be moot. I'll leave it to someone else to do the research and provide links to back it up. - The
mkdocstheme is based on bootstrap/bootswatch. There may be a simple way to switch between light/dark there. However, we provide various overrides and additional non-bootswatch CSS/images which would need to all be addressed as well. - Any switch to enable/disable dark mode should be a theme config setting. I'm assuming the setting would have 3 options (light, dark, and system). No changes should need to be made to MkDocs outside of the theme. As an aside, any third-party themes should be able to implement dark mode without any changes to MkDocs at all.
- Before accepting any PR, someone will need to promise to continue to support dark mode. In other words, they will need to remain available to address bug reports and adapt future changes to MkDocs to work with dark mode.
Material for MkDocs has implemented a configurable and user-selectable light/dark mode. From my experience I can say that it's a lot of work making everything (especially syntax highlighting) to work for both, light and dark modes, especially in terms of keeping contrast ratios for accessibility. The best approach is probably to use CSS variables as we do over at Material, but that will keep some browsers (hello IE11) out of the door. Thus, the themes should first be migrated to CSS variable definitions before addressing dark mode, or there will be a lot of duplication that might be tedious to maintain.
A toggle must ensure that there's no flash of white until switching to dark when based on local storage.
This is great @squidfunk! We are using Material for MkDocs, and I didn't realize this was a feature. I didn't even think to look there as I expected theme switching to be a core feature.
All built-in themes should be addressed in the same manner. In other words, a single PR should address both built-in themes, not just the one you care about (although... see next item).
The
readthedocstheme is a clone of the Sphinx theme of the same name. Any dark mode in this theme much reflect the upstream theme. I haven't checked if the upstream theme even supports a dark mode, so this may be moot. I'll leave it to someone else to do the research and provide links to back it up.
AFAICS there is no dark mode for readthedocs theme on their page.
A proposal would be to implement Google Material dark mode design as base for all dark modes. With Bootstrap use its primary color (on that page blue instead of violet).
Should be also useful to update HLJS v11+, IIRC they added some more dark theme alternatives to their syntax highlighting styles. (see also #3189).
- The
mkdocstheme is based on bootstrap/bootswatch. There may be a simple way to switch between light/dark there. However, we provide various overrides and additional non-bootswatch CSS/images which would need to all be addressed as well.
This might be difficult as some themes was made to be light (Lumen) or dark (Cyborg/Darkly/Slate), would be strange have a system dark mode and choose Lumen (or light with Darkly). I guess a solution might have a light and a dark version of the (s)css files for each theme and in some cases to use only one of them?
- Any switch to enable/disable dark mode should be a theme config setting. I'm assuming the setting would have 3 options (light, dark, and system). No changes should need to be made to MkDocs outside of the theme. As an aside, any third-party themes should be able to implement dark mode without any changes to MkDocs at all.
This seems obvious to me as it's a matter of styles and a bit of js for the switcher, I guess.
- Before accepting any PR, someone will need to promise to continue to support dark mode. In other words, they will need to remain available to address bug reports and adapt future changes to MkDocs to work with dark mode.
This doesn't seem very reliable, who knows what will happen next, or one day what will happen, suddenly remove dark mode support because 1 person is MIA? Instead it should be a well documented feature with a shared support from the team (at least 2 or 3 people). OTOH AFAIK Bootstrap/Bootswatch and ReadTheDocs themes haven't changed much over the years and if the implementation is generic and same for all (material.io for dark, 2 scss for each theme plus a required _variables.scss override for bootstrap) wouldn't requre much maintenance. Or, can be this a "themes plugin"?
Anyway, I started to work on this these days at least for a personal theme.
- "mkdocs" theme is kinda dead
- "readthedocs" theme will not deviate from upstream
- External "material" theme supports this
- Other themes are also totally free to support this.
So I don't think there is anything that will be done here.
Or, can be this a "themes plugin"?
Well, in technical terms it's possible, but seems super difficult to find how to augment all CSS of all versions of all possible themes.
I just noticed that Bootstrap introduced color modes (specifically dark mode) in release 5.3. Amusingly, that was released the same day that this issue was closed. In any event, updating the mkdocs theme to Bootstrap 5.3 would give the theme dark mode support for free (we are currently at 4.1.3). Although, as the documentation notes, we would need to provide our own mechanism for switching. For reference, you can see the bootswatch color scheme used by the mkdocs theme here, which includes a light/dark mode switcher in the top right corner.
Is there any interest in reopening this given this new information?
Wow, I just discovered that Bootstrap v5 dropped jQuery as a dependency. That could be a big deal if we could remove that dependency. Although, we are using jQuery in our own custom JS code (for example, for the search implementation). Of course, that change could be made later and separately. But it is nice to know the possibility is there.
Regardless, looking through the long list of changes, it looks like it could be a bit of work to fully migrate the theme to Bootstrap 5.3.
I started this summer to make my own "material like" bootstrap theme, I miss mainly the TOC on the right and the menu on the left like in B5 page and mkdocs material. Would be nice if someone else could join and make a common theme for anyone.