Skip to content
Return to: MkDocs-MaterialX Start Page

Changing the Colours

Back to: #Advanced-Configuration

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⚓︎

Colour Palette⚓︎

Color Scheme⚓︎

Material for MkDocs supports two color schemes: a light mode, which is called default, and a dark mode, which is called slate.

Configuration & Preview

Click on a tile to switch between light and dark mode:




Set the default color scheme by updating your mkdocs.yml:

theme:
  palette:
    scheme: default # (1)!

1. Set to slate to make dark mode the default for your users.

Primary Colour⚓︎

The primary color is used for the header, the sidebar, text links and several other components.

Configuration & Preview

Click on a tile to change the primary color of this page:























Set the primary color by updating your mkdocs.yml:

theme:
  palette:
    primary: indigo

See our guide below to learn how to set custom colors.

Accent Colour⚓︎

The accent color is used for interactive elements like hovered links, buttons, and scrollbars.

Configuration & Preview

Click on a tile to change the accent color of this page:


















Set the accent color by updating your mkdocs.yml:

theme:
  palette:
    accent: indigo

See our guide below to learn how to set custom colors.

Colour Palette Toggle⚓︎

Offering a light and dark color palette makes your documentation pleasant to read at different times of the day, so the user can choose accordingly.

Configuration

Add the following lines to mkdocs.yml:

theme:
  palette: # (1)!

    # Palette toggle for light mode
    - scheme: default
      toggle:
        icon: material/brightness-7 # (2)!
        name: Switch to dark mode

    # Palette toggle for dark mode
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  1. Note that the theme.palette setting is now defined as a list.
  2. Enter a few keywords to find the perfect icon using our icon search and click on the shortcode to copy it to your clipboard.

This configuration will render a color palette toggle next to the search bar. Note that you can also define separate settings for primary and accent per color palette.

Toggle Properties⚓︎

Required Properties

Each palette toggle in your mkdocs.yml requires these specific properties:

icon

This must point to a valid icon path. Popular pairings include:

  • + – material/brightness-7 + material/brightness-4
  • + – material/toggle-switch + material/toggle-switch-off-outline
  • + – material/weather-night + material/weather-sunny
  • + – material/eye + material/eye-outline
  • + – material/lightbulb + material/lightbulb-outline
name
This acts as the toggle's title attribute. It is rendered as a tooltip and is essential for screen readers and accessibility.

System Preference⚓︎

Automatic Light/Dark Mode

Each color palette can be linked to the user's system preference (Light or Dark mode) using a media query.

Add the media property to your mkdocs.yml like this:

theme:
  palette:

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)" # (1)!
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  1. The media queries are evaluated in the order they are defined. The first one that matches becomes the default for a first-time visitor.

Automatic Light / Dark Mode⚓︎

OS-Level Automation

Newer operating systems can automatically switch between light and dark appearance based on the time of day. Material for MkDocs can follow this lead, delegating the palette selection to the OS.

Add these lines to enable seamless switching without a page reload:

theme:
  palette:

    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

You can define separate settings for primary and accent per color palette. This allows you to have, for example, a "Deep Orange" accent in light mode but a "Cyan" accent in dark mode.

Material for MkDocs will now monitor the operating system's state and switch themes instantly, even if the user stays on the same page during the transition.

Customization⚓︎

Custom Colours⚓︎

Material for MkDocs uses CSS variables to handle its entire colour system. If you need to use brand-specific colours that aren't in the standard palette, you can override these variables using an additional style sheet.

First, set your palette to custom in mkdocs.yml:

theme:
  palette:
    primary: custom

Example: Branding your site like YouTube

To implement a specific brand palette, define the primary color and its light/dark variations in your CSS, then link that file in your configuration.

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

extra_css:
  - stylesheets/extra.css

Full Variable List

Check the official color definitions file for a comprehensive list of every CSS variable you can tweak.

Custom Colour Schemes⚓︎

Besides overriding specific colors, you can create your own named color scheme by wrapping definitions in a [data-md-color-scheme="..."] attribute selector. This allows you to select your custom theme via mkdocs.yml.

Defining a Custom Scheme

[data-md-color-scheme="youtube"] {
  --md-primary-fg-color:        #EE0F0F;
  --md-primary-fg-color--light: #ECB7B7;
  --md-primary-fg-color--dark:  #90030C;
}

theme:
  palette:
    scheme: youtube
extra_css:
  - stylesheets/extra.css

Slate Theme Tuning⚓︎

The slate color scheme defines its colors via hsla functions and deduces its shades from the --md-hue CSS variable.

Customizing the Slate Hue

You can tune the overall "tint" of the dark theme by overriding the hue value in your style sheet:

[data-md-color-scheme="slate"] {
  --md-hue: 210; /* (1)! */
}
  1. The hue value must be in the range of [0, 360].

Back to: #Advanced-Configuration