Skip to content

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

5.2.0 · 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:

Primary color

0.2.0 · 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:

Accent color

0.2.0 · 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:

Color palette toggle

7.1.0 · Default: none

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

    The following properties must be set for each toggle:

    icon

    Default: none · 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/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

    Default: none · Required – This property is used as the toggle's title attribute and should be set to a discernable name to improve accessibility. It's rendered as a tooltip.

    System preference

    7.1.0 · Default: none

    Each color palette can be linked to the user's system preference for light and dark appearance by using a media query. Simply add a media property next to the scheme definition in mkdocs.yml:

    theme:
      palette:
    
        # 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 light mode
    

    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.

    Automatic light / dark mode

    Sponsors only · insiders-4.18.0 · Experimental

    Newer operating system allow to automatically switch between light and dark appearance during day and night times. Insiders adds support for automatic light / dark mode, delegating color palette selection to the user's operating system. Add the following lines to mkdocs.yml:

    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 # (1)!
          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
    
    1. You can also define separate settings for primary and accent per color palette, i.e. different colors for light and dark mode.

    Material for MkDocs will now change the color palette each time the operating system switches between light and dark appearance, even when the user doesn't reload the site.

    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 YouTube, and want to set the primary color to your brand's palette. Just add:

    :root {
      --md-primary-fg-color:        #EE0F0F;
      --md-primary-fg-color--light: #ECB7B7;
      --md-primary-fg-color--dark:  #90030C;
    }
    
    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:

    [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
    

    Additionally, the slate color scheme defines all of it's colors via hsla color functions and deduces its colors from the --md-hue CSS variable. You can tune the slate theme with:

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

    Last update: April 14, 2023
    Created: April 14, 2023