Introduce CSS variables to make color customization more flexible

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

See further discussion below.

Description

This issue should track the progress and ideas of #1293.

Motivation

It is currently possible to change the primary and accent color by using a color palette with predefined names. Behind those names are several color values provided that allow for over 300 color compositions.

However, if you require a specific (i.e. custom) color, there are two options available, both of which have their downsides and require to fork this repository to do the adjustments.

1. Overwrite the generated color CSS by providing a specialized palette with your custom color assets/stylesheets/application-palette.3e3d1dff.css which is error prone.
2. Integrate the complete theme and change the values within _config.scss which in term provides a more complete and failsafe environment, but requires to build the project.

Both solutions require to take the current version of mkdocs-material and incorporate a snapshot of its files within your own documentation. This then receives only manual update by the maintainer of these documentations.

Idea

TL;DR
Use CSS variables to change the colors dynamically, creating a theme which only requires to change the variable definitions, statically or at runtime.

The color palette allows for generation of a stylesheet, as the colors are described staticly. However, CSS now allows for defining variables that are evaluated at runtime and thus different from Sass variables, which are evaluated at compile time.

The basic idea is to use those variables and have only one definition of the stylesheet which then dynamically adjusts to the variables. This simplifies the code and requires for the above color palettes to only change the variable definitions. Secondly, this allows for integrating a theme as described #1266.

As the defined colors in the palette are written to the HTML body, the next step would be to change read the HTML attributes data-md-color-primary and data-md-color-accent and update the CSS variables.

Problem

Like I described above, having static color values allows for defining the stylesheet at compile time of mkdocs-material. Using custom values requires to do this dynamically. Using JavaScript, as the current solution suggests, seems agreeably the wrong approach.

Solution

@squidfunk suggested a solution which uses a similar system on how the values of the mkdocs.yml are injected into the HTML files.

• The template would use an inline style to firstly lookup the value in the provided color palette or—if not found—inline the value as literal.

• This might be possible with fallback values where --md-color-${palette-name} would have been injected from the generated color palette similar to $clr-red-400.

  [data-md-color-primary] {
      --primary-color: var(--md-color-{{ primary }}, {{ primary }})
  }
  

Further discussion

The provided mockup and the solution discussed above will require some more thought:

1. How to provide the color palette, as this is done via CSS.
2. Provide a fallback for browsers that do not currently support variables.

Screenshots / Mockups

A working draft of the idea is described in PR #1293 which essentially allows for providing HEX colors instead of names:

theme:
  palette:
    primary: '#42f5ec'
    accent: '#f8ff29'

[squidfunk]

Implemented in 309c2b7c with the help of @Stanzilla 🐲 Will be part of the next beta (or maybe even RC)

[diba1013]

Thanks, I will look into it.