Color schemes: allow user to choose/toggle schemes

I checked that…

• … the documentation does not mention anything about my idea
• … to my best knowledge, my idea wouldn’t break something for other users
• … there are no open or closed issues that are related to my idea

Description

As of #1639 a dark palette scheme (slate) was added. Discussions regarding adding a toggle for this have been discussed #1639 comments, #1716 comments, and #1266. This issue can capture these discussions. To keep this generalized, I will give my thoughts for potential solution in a comment.

Use Cases

While supporting different themes / schemes and defaulting based upon prefers-color-scheme are phenomenal, adding a toggle would directly allow each user to manually set the theme according to their preferences.

Screenshots / Mockups

n/a

[squidfunk]

Thanks for sharing your implementation! I’m planning to put it in the table of contents, as I’m thinking about moving some more stuff there like “Edit this page” and maybe a Print button, so like a context menu, which is why we need more space than just the icon. Also, maybe later, a language switch could land there. Let’s see how that works out.

[squidfunk]

I’ve started working on the theme toggle. As proposed in this issue, it’s possible to provide 2 or more alternate themes from which the user can choose. The chosen theme is persisted across requests and does not induce flickering upon page load. The author can specify an icon and a label for the theme:

theme:
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        name: Switch to light mode
        icon: material/weather-sunny
    - scheme: slate
      primary: pink
      accent: pink
      toggle:
        name: Switch to dark mode
        icon: material/weather-night

This is the current concept – it always sticks to the lower right corner:

Positioning might change, as I’m still experimenting. This is how it looks in action (click on the image, if it doesn’t auto-play):

This feature will be released in Material for MkDocs Insiders as part of the Black Pearl Funding goal. It will first be exclusively available to sponsors.