WIP – Dark mode

[squidfunk]

[netlify]

Deploy preview for mkdocs-material-preview ready!

Built with commit d114778

https://deploy-preview-1639--mkdocs-material-preview.netlify.app

[ofek]

Bottom is light btw

[facelessuser]

Yeah, I don't think he's gone through and adjusted all the colors yet. I imagine he'll update the syntax highlighter, footers, and other things. I think this is just the start.

[squidfunk]

Still WIP. Don’t worry, footer will be dark as well.

[bilal-fazlani]

Will the dark mode have to be configured in config file or users will be able to switch it on and off according to their comfort?

[squidfunk]

You can set it via mkdocs.yml, it will probably be under theme. Adding a user toggle is super easy (as can be seen in the deploy preview), so I’ll wait until a good approach for adding a general toggle has been found.

[ofek]

So it'll be released with a toggle right?

[facelessuser]

I think what he was saying is that the act of toggling is easy, but it will not have a toggle until a good toggle (where we put it) can be worked out.

[squidfunk]

Exactly. Sorry if that was not clear enough. A toggle implementation will have to change a single attribute on an element, so it’ll be like 2-3 lines of JS. I’m unsure where to put the toggle, that’s my main concern.

[ofek]

Can we bind it to a shortcut key too? 😄 In that case we could use it right away as well until toggle

[hSaria]

Another option would be to respect the OS-wide color scheme using prefers-color-scheme, so it'll automatically load the dark theme if the client has dark mode on.

[squidfunk]

There won't be a toggle at first. The reason for this is that I'm abstracting dark mode into something more generic called color schemes. This will be another option of the palette attribute in mkdocs.yml and will allow for the addition of further schemes besides a dark theme like a high contrast theme for people with impaired vision.

Thus, it's not a binary/boolean option, which makes a toggle impractical. However, later, when some people implemented good toggle solutions, which allow for flexible configuration and switching of schemes, I'm happy to integrate it.

This also means no shortcut key. However, the reactive architecture allows for easy extension, so adding it yourself is super simple.

Regarding prefers-color-scheme, there's already an open issue tracking it.

[squidfunk]

I think we have a good candidate, which should be quite ready for release now. The dark mode color scheme is called slate. Light mode is just the default scheme but will be called light for convenience. Some more variables were added:

mkdocs-material/src/assets/stylesheets/base/_colors.scss

Lines 64 to 73 in 7a12b5e

	// Admonition color shades
	--md-admonition-bg-color: var(--md-default-bg-color);
	--md-admonition-fg-color: var(--md-default-fg-color);
	// Footer color shades
	--md-footer-bg-color: hsla(0, 0%, 0%, 0.87);
	--md-footer-bg-color--dark: hsla(0, 0%, 0%, 0.32);
	--md-footer-fg-color: hsla(0, 0%, 100%, 1);
	--md-footer-fg-color--light: hsla(0, 0%, 100%, 0.7);
	--md-footer-fg-color--lighter: hsla(0, 0%, 100%, 0.3);

Thus, admonitions now have a slightly lighter background color for the slate theme, as the shadow itself doesn't give enough contrast. Universally increasing the shadow doesn't look good for the light color scheme. The footer now has distinct variables for styling.

Note, that there will always be color combinations that' don't work right out of the box, like for example the light scheme with yellow as a primary color. However, it works very well in dark mode, which is why we're going to leave it as-is. With the 21 primary colors, 16 accent colors, and the new slate color scheme, there're now 21 ⨉ 16 ⨉ 2 = 672 combinations which can be achieved without any custom CSS. With custom CSS, possibilities are obviously endless. We might add some more variables for distinct styling if we run into customization problems, but for now, it should be enough.

[facelessuser]

So does the toggle example you have only work (persistently) because you have instant enabled?

[squidfunk]

No, it’s not related to instant loading at all, so no need to enable it.

[facelessuser]

So if you switch to a different page with no instant, it'll remember whether you've toggled between light or dark? Forgive my ignorance.

[squidfunk]

No, that's up to the author to implement. I may have not read "persistently" in your comment, it can currently only be set from mkdocs.yml. The toggles are only to show how they look. It's not an official implementation, yet, so no user-land switching without some JavaScript and localstorage 😀

I thought you meant whether the example as such works only with instant loading, and that's not the case. However, with instant loading, it will be persistent until the next full reload.

[facelessuser]

Cool, I don't need switching, but I was curious. Thanks!

[Mario-Hofstaetter]

@squidfunk I wanted to try the new dark mode since I was awaiting it for weeks, but I can't get it to show.

mkdocs.yml:

site_name: My Docs
theme:
  name: 'material'
  palette:
    scheme: slate

Starting in a VM with:
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:5.2.0

I tried clearing browser cache and a different browser, Windows System Theme is dark.

What did I do wrong?

[hSaria]

I've had the same issue; specifying the primary and/or the accent color fixed it.

theme:
  name: material
  palette:
    scheme: slate
    primary: indigo

Indigo is the default

[squidfunk]

You may create an issue for that, that’s not intended.

[Mario-Hofstaetter]

Thank you @hSaria that fixed it. Are you going to create the issue?

[hSaria]

Sure, I'll create one

[auula]

I've had the same issue; specifying the primary and/or the accent color fixed it.

theme:
  name: material
  palette:
    scheme: slate
    primary: indigo

Indigo is the default

thank ❤️