Color schemes: allow user to choose/toggle schemes

[bnigh]

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

[bnigh]

A potential solution would be to add an optional configurable menu dropdown, where users could select the preferred palette / scheme (similar to angular material ui)

The available palette options could be controlled by config options with sensible defaults... maybe something like:

theme:
  palette:
    toggle:
      - light
      - slate

Default behavior could be to add no toggle.
If enabled, default toggle values could be the available default schemes.

This could also be used to support different primary and accent colors as well:

theme:
  palette:
    toggle:
      - scheme: light
        primary: indigo
        accent: indigo
      - scheme: slate
        primary: blue

where default primary and accent values could be inherited from the theme.palette.primary & theme.palette.accent values

The user selected value could be stored and retrieved from local storage.

This would allow for a menu toggle that would generalize to future schemes, while also supporting a dark mode toggle (albeit with an extra click)

[squidfunk]

Thanks for writing this up! That looks like a good proposal for a little iteration. Some questions:

• In the Angular example, there're titles/names for the respective schemes. How could we model those and/or should we?
• Where should we put the toggle? This is in fact a problem for which I couldn't come up with a good solution. The header bar is practically exhausted. We cannot put it between source and search bar, as the search would not be aligned anymore with the content. Also, there're some thinkable combinations: no search but repository, search but no repository, and both visible. We might also consider putting it in the footer or somewhere else, but header would be ideal, obviously. Also, there must be a solution for the mobile view, as the search bar will collapse into the icon and the repository information is hidden in the drawer.

One downside is that this will make configuration very flexible, but also very complicated, but I guess that's necessary in order to guarantee flexibility.

[bnigh]

In the Angular example, there're titles/names for the respective schemes. How could we model those and/or should we?

perhaps there could be a name attribute associated with each option:

theme:
  palette:
    toggle:
      - name: Light
        scheme: light
      - name: Dark
        scheme: slate

which could default to the scheme name?

One downside is that this will make configuration very flexible, but also very complicated, but I guess that's necessary in order to guarantee flexibility.

Yeah, definitely open to further discussion to come up with a good design.

In my opinion, I'm guessing most would use something like this to allow users to change schemes (light, dark, ... or others like high-contrast in the future) rather than change primary or accent, but perhaps those are useful if some of the selected palette colors only work well in a single scheme (ie: yellow).

---

Where should we put the toggle? This is in fact a problem for which I couldn't come up with a good solution. The header bar is practically exhausted. We cannot put it between source and search bar, as the search would not be aligned anymore with the content. Also, there're some thinkable combinations: no search but repository, search but no repository, and both visible. We might also consider putting it in the footer or somewhere else, but header would be ideal, obviously. Also, there must be a solution for the mobile view, as the search bar will collapse into the icon and the repository information is hidden in the drawer.

This is probably the biggest question... I haven't really found any great solution that I'm completely sold on yet either.

Just brainstorming though, some possibilities might be:

• for mobile:
  • I think hiding in drawer similar to repository information might make the most sense
• for desktop some possibilities:
  • (1) could have it to the left of the repository icon, but to the right of the search bar in the menu & above the content
    • this would change alignment, so this icon is aligned with content instead of search
  • (2) could have it to the left or right of the repository icon, but have both of those icons above the toc
    • this likely wouldn't leave room to display stars, forks, & the repo name for the repository info... so it could only display the icon
  • (3) could have it at the top of the toc, similar to how docker-compose has their toggle
    • this approach would have to be modified to support a drop down or somehow support more than 2 options

Hopefully the above are clear...

Looking at the README's Users section, it looks like some have added custom icons in the header:

• AWS
• BFE
• ZeroNet

not sure if it influences decision, but they all seemed to have gone with implementations similar to option (1) above.

Overall, I think the various combinations of repository info, search, & toggle would be easier to identify once a layout is decided for all 3. And yeah, almost all other implementations I have seen have had a toggle sticky near the top right of the page (for desktop), so am thinking most users would expect / want something similar.

[squidfunk]

I like that the toggle approach you propose is pretty much generalized to the whole palette, especially as some primary/accent colors work better/worse than others with the themes. It also integrates perfectly with custom, author-provided themes. However, the problem with positioning...

My main concerns:

1. The opened search bar is not aligned with the content area. That looks really odd. In the past, there was a bug where the search was a little off on the tablet breakpoint that tripped people up. Alignment should stay the same.

2. I don't have a good idea of how to integrate it into the drawer on mobile. Above the repository info? Below? It'll decrease the visible area for navigational content.

The only thing that I tried that kind of worked was putting a vertical dot menu right to the search bar, but that means we would have to hide all options behind a dropdown. It also looks odd without the repository information, as the search bar is then located above the tablet of contents. It would have the nice properties of being generalizable, but will only work for the vertical dots, as they are very narrow. We cannot support other icons, as they would be too wide. Also, color schemes are only one thing. We also should think about making room for more options like version and language selectors, etc, which were requested in the past and for which no good solution exists.

Essentially, we need to provide a user preference menu or site-wide context menu in general.

[squidfunk]

BTW, if you feel like prototyping something, we can discuss concrete implementations over in one (or multiple) PRs!

[bnigh]

Also, color schemes are only one thing. We also should think about making room for more options like version and language selectors, etc, which were requested in the past and for which no good solution exists.

Essentially, we need to provide a user preference menu or site-wide context menu in general.

Agreed.

The only thing that I tried that kind of worked was putting a vertical dot menu right to the search bar, but that means we would have to hide all options behind a dropdown

Agreed.
Considering site-wide preference menu, some sort of expandable/collapsable menu (in whatever form that takes) would seem to be the only feasible solution given the available real estate.

---

BTW, if you feel like prototyping something, we can discuss concrete implementations over in one (or multiple) PRs!

If I find some time and come up with any prototypes worth sharing, definitely will do!

[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.

[crazy-max]

@squidfunk That looks awesome thanks!

[facelessuser]

So, because I'm impatient, I put together an implementation of dark/light toggle. I'm not sure what Material's final implementation will look like, but I landed on something like this.

When the "Table of Contents" is still visible, we leave the toggle in the header to the right:

When that collapses you can access it in the hamburger menu

I guess I could always move it to the hamburger menu as soon as it is visible, but right now I just move it when the source repo stuff goes away.

I think it turned out pretty good. It's quickly accessible in mobile, and out of the way. And on the desktop, I think it's not too bad. Interested to see what the ultimate solution is for Material.

My experiment is live at: https://facelessuser.github.io/pymdown-extensions/. It should persist as I'm using localstorage.

[crazy-max]

@facelessuser I really like the toggle position!

[facelessuser]

I do let it eat into the max width of the repository info. This isn't a problem for me as I never really use anything longer than the default name of providers (github etc.). I'm sure padding and margins etc. could be massaged if a little more room was desired.

I'm not saying what I'm doing should or shouldn't be considered for the final solution, only that I think this works pretty well for my purposes, and I thought I'd share in case maybe it helped spark some ideas in moving towards a final solution.

[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.

[facelessuser]

Interested to see how that translates for easy access on mobile too. Either way, I'm very interested to see how it turns out 🙂.

[squidfunk]

Aaaand we have a toggle:

Desktop

Mobile

Demo: https://squidfunk.github.io/mkdocs-material-insiders/getting-started/

So, in the end, I decided to move it into the header, just like in your implementation. The problem with putting it in the table of contents is that it is not always rendered and may also be disabled. For this reason, it was important to detach it from the table of contents. Furthermore, there would have been problems with instant loading. It's now positioned left to the search bar and disappears when search is focused. The cool thing is that it's also part of the header on mobile, so the positioning is consistent.

Icons and titles can be freely changed. More than two color schemes can be defined, it will then cycle through them. The new config format stayed as described before:

theme:
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode
    - scheme: slate
      primary: blue
      accent: blue
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode

There's still some polishing that needs to be done, which I'll probably finish this week. It was quite hard to come up with a design and mechanism that is completely configurable and work with an arbitrary number of schemes, but I think this is a good candidate.

[crazy-max]

@squidfunk WDYT of this kind of toggle:

[squidfunk]

@crazy-max ive seen such implementations, yes. The idea behind the theme Switcher is that you can’t only toggle between 2, but multiple themes, to also provide a high contrast theme of desired. That’s not possible with the design you posted. Furthermore I wanted to keep icons configurable, so users can choose labels and icons freely, besides the actual colors.

[facelessuser]

I'm kind of glad you went for the header. So, I'm curious how this will work. If you have more than 2 themes, will it create another icon? Or does it use a generic icon with a menu?

[squidfunk]

Nope, it will just cycle through the schemes. If scheme 1 is active, it will show the icon of scheme 2. When the last scheme is active, it just wraps around to 1. So for two schemes it‘s identical to a toggle.

[squidfunk]

You can try the master of insiders if you like. Feedback appreciated!

[facelessuser]

Cool in that case, if you have more than one, you can use an icon to indicate what is currently selected, or just use something generic and have it the same for all.

That keeps it simple. I may still customize mine to move the icon to the mobile menu to maximize title space... But maybe not, I'll have to think about it, but generally I like this direction. I'll give the insiders a try.

[squidfunk]

I still want to tweak the spacing on mobile a little, so there’s some more space. In general, I want to get this out asap and then we can iterate and improve it 😊

[facelessuser]

No, this is a great start! Fine tuning can happen down the line.

[facelessuser]

Looking at this. I think when in mobile view, the padding is a bit much. It works fine in a non-mobile profile, but IMHO, I think mobile should strip the padding of the title, and reduce the padding between the buttons. Here I simply remove the padding around the title (as the buttons already provide padding, and then remove the padding between buttons.

Before:

After:

EDIT: there still is some margin between the buttons, so I think it still keeps the spacing reasonable.

[facelessuser]

I'll probably at least play around with the idea on some of my sites. For now, I'll stick with just reducing the space between buttons for now.

[facelessuser]

I like how easy the multiple schemes are to set up. Great work there.

[squidfunk]

Finally released as part of Material for MkDocs Insiders 5.5.9+insiders-1.3.0! I updated the documentation here:
https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette-toggle

Check out the official Insiders docs to see it in action:
https://squidfunk.github.io/mkdocs-material-insiders/getting-started/

[stevevanhooser]

This toggle feature is not marked as "insiders" in the documentation: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/

[squidfunk]

The color palette toggle was released in the community edition because the funding goal was hit. Therefore, it's not exclusive to Insiders anymore! Thus, the documentation is correct.

[stevevanhooser]

Oh, I just had to update to the latest. (forgot --upgrade) Thanks! Great feature!