Mkdocs-material: Dark mode CSS file

[henrywhitaker3]

Description

I made a dark mode CSS file for this, repo here. There is a live demo here, which just uses your site as an example (mainly because it had examples of all the different things you can use). I know, from looking at closed issues about a dark mode, that you wanted to implement one but didn't have the time, so feel free to use this however you want.

Screenshots / Mockups

[squidfunk]

Thanks for providing your template. It surely is a great starting point for providing a dark mode. I will integrate this into the current iteration (Material v5) which I'm currently working on.

[cryocaustik]

@squidfunk another option to consider if you're thinking of building in a dark theme
https://github.com/fmaida/mkdocs-material-dark-theme

[markusressel]

This is awesome, thx for integrating a dark theme into upstream! :nerd_face:
If you need more inspiration, here is my take from some time ago (which I still use today):
https://github.com/markusressel/MkDocs-Material-Dark-Theme

I had a look at the source of MkDocs-Material, but I don't have the skills to figure out how a dark mode would be integrated, so I can't really help with that.

[Stanzilla]

You guys can use this PR as a base https://github.com/squidfunk/mkdocs-material/pull/1409

[rjduran]

Is this the correct place to submit a request for making light/dark modes a toggle? That way a user to the site has the option to switch as needed.

[squidfunk]

We’ll probably add a toggle in 5.1 or 5.2 that defaults to prefers-color-scheme.

[ofek]

Dark mode will be in 5.2?

[squidfunk]

Probably, because it's likely the next thing I'll be working on, but can't put an estimate on it. Note that there are already some v5 compatible dark modes out there.

[squidfunk]

1639 contains the dark mode implementation, which is still a WIP.

[w4nderlust]

If it is of any help, also I implemented a, admittedly hacky, dark mode theme for my project https://uber.github.io/ludwig/user_guide/ . The source code (which is basically a css on top of the regular one, is here: https://github.com/uber/ludwig/blob/master/mkdocs/docs/stylesheets/extra.css
Would love to see a dark theme one could just turn on in the configuration, will make my like much easier :)

[squidfunk]

@w4nderlust really like the Uber Ludwig docs – saw them when it came out, as I've noticed some spike in my visitor graph 😉 The native dark mode will probably be a little different, but I might borrow some stuff for inspiration.

[squidfunk]

Took some time and finished dark mode. #1639 should be ready to go.

It's likely that we discover some edge cases that don't work yet, but for now it should be fine. Currently, only author-defined and set from mkdocs.yml, but adding a toggle is easy, as can be seen in the docs.

As described in #1639, the implementation allows for further color schemes besides a dark mode, so we could add a high-contrast mode for visually impaired people. Therefore, color schemes are not a binary/boolean thing, but another dimension among primary and accent colors. If somebody comes up with a good idea of how we could integrate a toggle to switch between those modes, or how to configure which modes the user should be allowed to choose, we can integrate it into master.

What's even better: the new implementation allows for the addition of third-party color schemes via extra CSS, which could then be used from mkdocs.yml. Take the new slate color scheme for example:

https://github.com/squidfunk/mkdocs-material/blob/a1e25a219a000e9d027224c0b6612e48e358e7af/src/assets/stylesheets/palette/_scheme.scss#L27-L55

The color scheme is then used as:

https://github.com/squidfunk/mkdocs-material/blob/a1e25a219a000e9d027224c0b6612e48e358e7af/mkdocs.yml#L56-L57

Now, if somebody wants to build a color scheme called blueberry, just create a new CSS file and override all variables (or those that are different from the default scheme) with:

/* extra.css */
[data-md-color-scheme="blueberry"] {
  /* ... all overrides ... */
}

The CSS can be added via extra_css and can then be used with:

extra_css:
  - docs/extra.css
theme:
  palette:
    scheme: blueberry

[Stanzilla]

that's super cool!

[facelessuser]

Nice work!

[ofek]

Absolutely amazing! Ship it 🚀

[w4nderlust]

That's amazing, simplifies adding themes a lot! Can wait to see it in the release

[squidfunk]

Released as part of 5.2.0!