Skip to content

Built-in CSS variables

Material for MkDocs utilizes built-in CSS variables prefixed with --md- to allow deep theme customization without recompiling the underlying source code. These properties are mapped to the global :root scope or tied directly to light (default) and dark (slate) color palettes.

Color Palette Variables

These variables control the core branding of your documentation site. To override them, set your palette colors to custom in mkdocs.yml and declare the new values in an extra_css file.

  • –md-primary-fg-color: Header, sidebar, and primary component background.
  • –md-primary-fg-color–light: Lighter shade for subtle borders or active states.
  • –md-primary-fg-color–dark: Darker shade for contrast adjustments.
  • –md-primary-bg-color: Foreground text or icons positioned against the primary color.
  • –md-accent-fg-color: Interactive elements like buttons, scrollbars, and hovered links.
  • –md-accent-bg-color: Text color used explicitly on top of accent elements.

Text & Interface Contrast Colors

Material for MkDocs uses specific foreground (-fg-) and background (-bg-) variables to maintain crisp, readable contrast levels across default and dark modes.

  • –md-default-fg-color: Standard body text color.
  • –md-default-fg-color–light: Secondary text (e.g., meta details, timestamps).
  • –md-default-fg-color–lighter: Muted text (e.g., structural placeholders).
  • –md-default-bg-color: Overall page background color.
  • –md-default-bg-color–light: Lighter container backgrounds (e.g., code blocks, tables).–md-default-bg-color
  • –lighter: Lightest shading variant (e.g., keyboard shortcuts tags).

Typography Variables

Fonts, weights, and rendering options are governed by these structural typography settings:

  • –md-text-font: Main body text font family stack.
  • –md-code-font: Monospace font family stack for code blocks and inline formatting.
  • –md-typeset-font-size: Global body text font size.
  • –md-typeset-line-height: Line height baseline for optimized layout reading rhythm.

Layout Dimensions & Responsiveness

These variables dictate the maximum grid widths and flexible column breakpoints for sidebars and text containers.

  • –md-page-main-width: Constrained maximum layout width for content and sidebars combined (typically 61rem).
  • –md-sidebar-width: Fixed widths allocated explicitly to the left and right navigation layouts (typically 12.1rem).

Global Changes to Built-in Styles

Declare overrides in docs/stylesheets/extra.css.

Example:
:root {
  /* Change primary color to a custom brick red */
  --md-primary-fg-color:        #b30000;
  --md-primary-fg-color--light: #ff4d4d;
  --md-primary-fg-color--dark:  #800000;

  /* Make content layouts wider */
  --md-page-main-width:         75rem;
}
In HTML, :root represents the <html> element and is identical to the selector html, except that its specificity is higher than html’s. See :root CSS pseudo-class

Core Color CSS Variables

CSS Variable Description
–md-primary-fg-color Main primary color (header, sidebar, active tabs)
–md-primary-fg-color–light Lighter shade of the primary color
–md-primary-fg-color–dark Darker shade of the primary color
–md-primary-bg-color Background color used with primary elements
–md-primary-bg-color–light Light variant of primary background
–md-accent-fg-color Accent color (hover states, focused buttons, active links)
–md-default-fg-color Default text and foreground elements
–md-default-fg-color–light Secondary or muted text color
–md-default-fg-color–lighter Disabled or faintest text color
–md-default-fg-color–lightest Subtler borders or dividers
–md-default-bg-color Base background color for pages
–md-default-bg-color–light Alternative light background sections
–md-default-bg-color–lighter Container or card backgrounds
–md-default-bg-color–lightest Deepest background contrast layer
–md-code-bg-color Background color for code blocks
–md-code-fg-color Text color inside code blocks

Core CSS Variable Categories

Material for MkDocs organizes its theme configuration around primary, accent, and default surface color tokens:

  • Default (–md-default-*): Controls main text foreground and surface background colors. Inverted automatically when switching between light and dark schemes.
  • Primary (–md-primary-*): Applied to prominent layout blocks like the header, sidebar navigation highlights, and active tabs
  • Accent (–md-accent-*): Used for interactive highlights, active links, progress indicators, and button hover states.Code &
  • Typeset (–md-code-*): Defines styling for inline code blocks and syntax-highlighted containers.

Inspect Source SCSS

View the official mappings and default fallback tokens directly inside the theme’s _colors.scss repository file: squidfunk / mkdocs-material , here: > src > templates > assets > stylesheets > main : _config.scss