mkdocs-material/docs/guides/changing-colors.md

template
overrides/main.html

Changing colors

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

Configuration

Color scheme

:octicons-file-code-24: Source · :octicons-tools-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 from mkdocs.yml:

theme:
  palette:
    scheme: default

:material-cursor-default-click-outline: click on a tile to change the color scheme:

default slate

The color scheme can also be set based on user preference, which makes use of the prefers-color-scheme media query. This can be done by adding the following to mkdocs.yml:

theme:
  palette:
    scheme: preference

Primary color

:octicons-file-code-24: Source · :octicons-tools-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

:material-cursor-default-click-outline: 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-file-code-24: Source · :octicons-tools-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 chosing a valid color name:

theme:
  palette:
    accent: indigo

:material-cursor-default-click-outline: 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

Customization

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 stylesheet and tweak the following CSS variables:

:root {

  /* Default color shades */
  --md-default-fg-color:               hsla(0, 0%, 0%, 0.87);
  --md-default-fg-color--light:        hsla(0, 0%, 0%, 0.54);
  --md-default-fg-color--lighter:      hsla(0, 0%, 0%, 0.32);
  --md-default-fg-color--lightest:     hsla(0, 0%, 0%, 0.07);
  --md-default-bg-color:               hsla(0, 0%, 100%, 1);
  --md-default-bg-color--light:        hsla(0, 0%, 100%, 0.7);
  --md-default-bg-color--lighter:      hsla(0, 0%, 100%, 0.3);
  --md-default-bg-color--lightest:     hsla(0, 0%, 100%, 0.12);

  /* Primary color shades */
  --md-primary-fg-color:               hsla(231, 48%, 48%, 1);
  --md-primary-fg-color--light:        hsla(231, 44%, 56%, 1);
  --md-primary-fg-color--dark:         hsla(232, 54%, 41%, 1);
  --md-primary-bg-color:               hsla(0, 0%, 100%, 1);
  --md-primary-bg-color--light:        hsla(0, 0%, 100%, 0.7);

  /* Accent color shades */
  --md-accent-fg-color:                hsla(231, 99%, 66%, 1);
  --md-accent-fg-color--transparent:   hsla(231, 99%, 66%, 0.1);
  --md-accent-bg-color:                hsla(0, 0%, 100%, 1);
  --md-accent-bg-color--light:         hsla(0, 0%, 100%, 0.7);
}

The colors of code blocks, admonitions, text links and the footer can be adjusted through dedicated CSS variables, which partly default to the base colors or neutral colors:

:root > * {

  /* Code color shades */
  --md-code-bg-color:                  hsla(0, 0%, 96%, 1);
  --md-code-fg-color:                  hsla(200, 18%, 26%, 1);

  /* Text color shades */
  --md-text-color:                     var(--md-default-fg-color);
  --md-text-link-color:                var(--md-primary-fg-color);

  /* Admonition color shades */
  --md-admonition-bg-color:            var(--md-default-bg-color);
  --md-admonition-fg-color:            var(--md-default-fg-color);

  /* Footer color shades */
  --md-footer-bg-color:                hsla(0, 0%, 0%, 0.87);
  --md-footer-bg-color--dark:          hsla(0, 0%, 0%, 0.32);
  --md-footer-fg-color:                hsla(0, 0%, 100%, 1);
  --md-footer-fg-color--light:         hsla(0, 0%, 100%, 0.7);
  --md-footer-fg-color--lighter:       hsla(0, 0%, 100%, 0.3);
}

Caveats

!!! warning "Accessibility – not all color combinations work well"

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_), so make
sure that the color combination of your choosing provides enough contrast
and tweak CSS variables where necessary.