mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-13 18:40:54 +01:00

2022-01-16 19:45:40 +01:00

12 KiB

Raw Blame History

template
overrides/main.html

Changing the colors

As any proper Material Design implementation, Material for MkDocs supports Google's original color palette, which can be easily configured through mkdocs.yml. Furthermore, colors can be customized with a few lines of CSS to fit your brand's identity by using CSS variables.

Configuration

Color palette

Color scheme

:octicons-tag-24: 5.2.0 · :octicons-milestone-24: Default: default

Material for MkDocs supports two color schemes: a light mode, which is just called default, and a dark mode, which is called slate. The color scheme can be set via mkdocs.yml:

theme:
  palette:
    scheme: default

Click on a tile to change the color scheme:

default slate

Primary color

:octicons-tag-24: 0.2.0 · :octicons-milestone-24: Default: indigo

The primary color is used for the header, the sidebar, text links and several other components. In order to change the primary color, set the following value in mkdocs.yml to a valid color name:

theme:
  palette:
    primary: indigo

Click on a tile to change the primary color:

red pink purple deep purple indigo blue light blue cyan teal green light green lime yellow amber orange deep orange brown grey blue grey black white

Accent color

:octicons-tag-24: 0.2.0 · :octicons-milestone-24: Default: indigo

The accent color is used to denote elements that can be interacted with, e.g. hovered links, buttons and scrollbars. It can be changed in mkdocs.yml by choosing a valid color name:

theme:
  palette:
    accent: indigo

Click on a tile to change the accent color:

red pink purple deep purple indigo blue light blue cyan teal green light green lime yellow amber orange deep orange

Color palette toggle

:octicons-tag-24: 7.1.0 · :octicons-milestone-24: Default: none

It's also possible to offer a list of color palettes to the user, each of which can include a scheme, primary and accent color each. The user can toggle between those color palettes:

theme:
  palette: # (1)!
    - scheme: default
      toggle:
        icon: material/toggle-switch-off-outline # (2)!
        name: Switch to dark mode
    - scheme: slate # (3)!
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode

Note that the theme.palette setting is now defined as a list.
Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard:
With 2 (color schemes) x 21 (primary colors) x 17 (accent color) = 714 combinations, it's impossible to ensure that all configurations provide a good user experience (e.g. yellow on light background). Make sure that the color combination of your choosing provides enough contrast and tweak CSS variables where necessary.

The following properties must be set for each toggle:

icon{ #toggle-icon }

:octicons-milestone-24: Default: none · :octicons-alert-24: Required – This property must point to a valid icon path referencing any icon bundled with the theme, or the build will not succeed. Some popular combinations:

:material-toggle-switch-off-outline: + :material-toggle-switch: – material/toggle-switch-off-outline + material/toggle-switch
:material-weather-sunny: + :material-weather-night: – material/weather-sunny + material/weather-night
:material-eye-outline: + :material-eye: – material/eye-outline + material/eye
:material-lightbulb-outline: + :material-lightbulb: – material/lightbulb-outline + material/lightbulb
:material-brightness-4: + :material-brightness-7: – material/brightness-4 + material/brightness-7

name{ #toggle-name }

:octicons-milestone-24: Default: none · :octicons-alert-24: Required – This property is used as the toggle's title attribute and should be set to a discernable name to improve accessibility. It will appear on mouse hover.

System preference

:octicons-tag-24: 7.1.0 · :octicons-milestone-24: Default: none

In order to automatically set the color palette to the user's system preference, a media query can be set as part of the media property next to the toggle definition in mkdocs.yml:

theme:
  palette:
    - media: "(prefers-color-scheme: light)" # (1)!
      scheme: default
      toggle:
        icon: material/toggle-switch-off-outline
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)" # (2)!
      scheme: slate
      toggle:
        icon: material/toggle-switch
        name: Switch to light mode

This media query is checked first. It's also the fallback when no media query matches.
This media query is checked second. If it doesn't match, the first one is automatically used.

When the user first visits your site, the media queries are evaluated in the order of their definition. The first media query that matches selects the default color palette.

Customization

Custom colors

Material for MkDocs implements colors using CSS variables (custom properties). If you want to customize the colors beyond the palette (e.g. to use your brand-specific colors), you can add an additional style sheet and tweak the values of the CSS variables.

Let's say you're :fontawesome-brands-youtube:{ style="color: #EE0F0F" } YouTube, and want to set the primary color to your brand's palette. Just add:

=== ":octicons-file-code-16: docs/stylesheets/extra.css"

``` css
:root {
  --md-primary-fg-color:        #EE0F0F;
  --md-primary-fg-color--light: #ECB7B7;
  --md-primary-fg-color--dark:  #90030C;
}
```

=== ":octicons-file-code-16: mkdocs.yml"

``` yaml
extra_css:
  - stylesheets/extra.css
```

See the file containing the color definitions for a list of all CSS variables.

Custom color schemes

Besides overriding specific colors, you can create your own, named color scheme by wrapping the definitions in a [data-md-color-scheme="..."] attribute selector, which you can then set via mkdocs.yml as described in the color schemes section: