How to set dark-mode default to light?

[meysam81]

Hey guys,
It may be too much to ask, but I'm clueless as to how to set the default preference of dark-mode-enabled mkdocs to light.
There is a working example right here: kubernetes-sigs/gateway-api#2896
But it seems like it is not working as I expect it to.

Would you help with this, please?

Thanks.

[alexvoss]

It seems that the dark mode was removed from the site? Can you point me at the configuration that was used or, even better, create a minimal reproduction that we can use to suggest how to do this?

[meysam81]

this is the snippet in the config for adding dark-mode:

  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: (prefers-color-scheme)
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference
  custom_dir: site-src/overrides

Yet even having the light mode at the top, the site is still rendering the system default. The desire is to pick the light mode as the default, which is not happening.

[alexvoss]

Ok, I can reproduce the problem, which is that when the OS is set to dark mode, the color scheme used is also dark. This is reflected in the icon used and in the data stored in the browser local storage. This looks like a deliberate design decision to me, which makes sense, I think.

A user browsing sites in dark mode will not want to all of a sudden be confronted by a page that forces light mode. So, as far as I can tell, this is not a problem with your configuration, which produces a behaviour that IMHO is consistent with likely user expectations.

The easiest way to change the behaviour is to just remove the option that follows the OS. That will not work for people who have set their OS to switch automatically, though.

You could try to force light mode in the absence of a user preference by setting the appropriate values in the browser's local storage if no user preference is recorded yet. You'd need to make sure that your code runs before the JavaScript code from Material. That way, people would start with light mode but can still change it to auto or dark.

Hope this helps.

[kamilkrzyskow]

It's hard to tell if this is a bug or design choice 🤔 I believe this is a bug. I agree that the config order loaded on a page should be the same as the one set in the mkdocs.yml. However, currently it searches for the first toggle that matches the browser media settings. So as I have dark mode enabled in the system as default in this config it selects the second automatic toggle, as it's universal.

0 - (prefers-color-scheme: light)
1 - (prefers-color-scheme) <-- this is chosen
2 - (prefers-color-scheme: dark)
---
0 - (prefers-color-scheme: light)
1 - (prefers-color-scheme: dark) <-- this is chosen
---
0 - (prefers-color-scheme: dark) <-- this is chosen
1 - (prefers-color-scheme: light)

mkdocs-material/src/templates/assets/javascripts/components/palette/index.ts

Lines 88 to 95 in 2e1e109

	const current = __md_get<Palette>("__palette") || {
	index: inputs.findIndex(input => matchMedia(
	input.getAttribute("data-md-color-media")!
	).matches)
	}
	/* Emit changes in color palette */
	const index = Math.max(0, Math.min(current.index, inputs.length - 1))

---

So just like Alex said, you have to set the palette in Local Storage before bundle.js executes.
https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme

{% extends "base.html" %}

{% block scripts %}
  <!-- Add scripts that need to run before here -->
  {{ super() }}
{% endblock %}

Or create a hacky Python hook, that modifies bundle.js directly (has the risk of breaking with an update)

• Disabling media pause when switching content tabs. #6844 (reply in thread)

Or maintain your own theme fork with modified TypeScript above.