Themes

Material for MkDocs provides extensive theming capabilities, including color schemes, fonts, icons, and complete customization options to match your brand identity.

Overview

Theme features include:

• Color schemes - Light and dark modes
• Color palettes - Primary and accent colors
• Typography - Custom fonts and sizes
• Icons - Material, FontAwesome, and custom icons
• Logo & Favicon - Brand identity
• Custom CSS - Complete styling control

Color Schemes

Light and Dark Modes

Configure color schemes in mkdocs.yml:

theme:
  palette:
    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Available Schemes

Scheme	Description	Use Case
default	Light background	Standard documentation
slate	Dark background	Dark mode
Custom	Your own scheme	Brand consistency

Color Palettes

Primary Colors

Available primary colors:

• red - Attention, warnings
• pink - Playful, creative
• purple - Premium, creative
• deep-purple - Rich, luxurious
• indigo - Professional, trustworthy
• blue - Corporate, reliable
• light-blue - Fresh, modern
• cyan - Tech, innovation
• teal - Balanced, growth
• green - Success, nature
• light-green - Fresh, eco-friendly
• lime - Energetic, vibrant
• yellow - Optimistic, friendly
• amber - Warm, inviting
• orange - Energetic, bold
• deep-orange - Passionate, strong
• brown - Earthy, stable
• grey - Neutral, professional
• blue-grey - Modern, sophisticated
• black - Elegant, powerful
• white - Clean, minimal

Accent Colors

Accent colors for interactive elements:

theme:
  palette:
    primary: indigo
    accent: amber  # Links, buttons, selections

Custom Colors

Define custom color schemes:

/* docs/assets/stylesheets/custom-theme.css */
[data-md-color-scheme="custom"] {
  --md-primary-fg-color: #1976d2;
  --md-primary-fg-color--light: #42a5f5;
  --md-primary-fg-color--dark: #0d47a1;
  --md-primary-bg-color: #fff;
  --md-primary-bg-color--light: #ffffffb3;

  --md-accent-fg-color: #ff9800;
  --md-accent-fg-color--transparent: #ff980020;
  --md-accent-bg-color: #fff;
  --md-accent-bg-color--light: #ffffffb3;
}

Typography

Font Configuration

theme:
  font:
    text: Roboto        # Body text
    code: Roboto Mono   # Code blocks

Available Fonts

Popular font combinations:

Text Font	Code Font	Style
Roboto	Roboto Mono	Material Design
Inter	JetBrains Mono	Modern
Open Sans	Source Code Pro	Classic
Lato	Fira Code	Clean
Poppins	Cascadia Code	Friendly
IBM Plex Sans	IBM Plex Mono	Professional

Custom Fonts

Load custom fonts:

extra_css:
  - assets/stylesheets/custom-fonts.css

/* custom-fonts.css */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;700&display=swap');

:root {
  --md-text-font: "Inter";
}

Font Sizes

Adjust typography scale:

/* Increase base font size */
:root {
  --md-typeset-font-size: 1.1rem;
  --md-code-font-size: 0.95em;
}

/* Responsive font sizes */
@media screen and (min-width: 1220px) {
  :root {
    --md-typeset-font-size: 1.125rem;
  }
}

Icons and Logo

Logo Configuration

theme:
  logo: assets/logo.svg
  favicon: assets/favicon.png
  icon:
    logo: material/library

Icon Sets

Available icon libraries:

• Material Design Icons - 7000+ icons
• FontAwesome - 2000+ icons
• Octicons - GitHub's icon set
• Simple Icons - Brand icons

Custom Icons

Add custom icon sets:

theme:
  icon:
    repo: fontawesome/brands/github
    edit: material/pencil
    view: material/eye

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

Theme Customization

Override Files

Directory structure for customizations:

docs/
├── overrides/
│   ├── .icons/           # Custom icons
│   ├── assets/
│   │   ├── images/      # Theme images
│   │   ├── javascripts/ # Custom JS
│   │   └── stylesheets/ # Custom CSS
│   ├── partials/        # Template overrides
│   │   ├── footer.html
│   │   ├── header.html
│   │   └── nav.html
│   └── main.html        # Main template

Custom CSS Variables

/* Complete theme customization */
:root {
  /* Primary color shades */
  --md-primary-fg-color: #1976d2;
  --md-primary-fg-color--light: #42a5f5;
  --md-primary-fg-color--dark: #0d47a1;

  /* Text colors */
  --md-default-fg-color: #212121;
  --md-default-fg-color--light: #757575;
  --md-default-fg-color--lighter: #9e9e9e;
  --md-default-fg-color--lightest: #bdbdbd;

  /* Background colors */
  --md-default-bg-color: #ffffff;
  --md-default-bg-color--light: #fafafa;
  --md-default-bg-color--lighter: #f5f5f5;
  --md-default-bg-color--lightest: #eeeeee;

  /* Code block colors */
  --md-code-bg-color: #f5f5f5;
  --md-code-fg-color: #c7254e;

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

  /* Footer colors */
  --md-footer-bg-color: #424242;
  --md-footer-bg-color--dark: #212121;
  --md-footer-fg-color: #ffffff;
  --md-footer-fg-color--light: #bdbdbd;
  --md-footer-fg-color--lighter: #757575;
}

Advanced Theming

Component Styling

Style specific components:

/* Navigation */
.md-nav__title {
  font-weight: 700;
  text-transform: uppercase;
  font-size: 0.7rem;
}

/* Search */
.md-search__input {
  border-radius: 24px;
  background-color: var(--md-default-bg-color--lighter);
}

/* Tables */
.md-typeset table:not([class]) {
  border-radius: 8px;
  overflow: hidden;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

/* Code blocks */
.md-typeset pre {
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}

/* Tabs */
.md-typeset .tabbed-labels {
  border-bottom: 2px solid var(--md-primary-fg-color);
}

Animations

Add smooth transitions:

/* Page transitions */
.md-content__inner {
  animation: fadeIn 0.3s ease-in-out;
}

@keyframes fadeIn {
  from { opacity: 0; transform: translateY(10px); }
  to { opacity: 1; transform: translateY(0); }
}

/* Hover effects */
.md-nav__link {
  transition: color 0.2s, background-color 0.2s;
}

.md-nav__link:hover {
  background-color: var(--md-primary-fg-color--transparent);
}

/* Smooth scrolling */
html {
  scroll-behavior: smooth;
}

Theme Toggle

Custom theme switcher:

// docs/assets/javascripts/theme-toggle.js
const toggleTheme = () => {
  const body = document.body;
  const currentTheme = body.getAttribute('data-md-color-scheme');
  const newTheme = currentTheme === 'default' ? 'slate' : 'default';

  body.setAttribute('data-md-color-scheme', newTheme);
  localStorage.setItem('theme', newTheme);

  // Update toggle button
  const toggle = document.querySelector('.theme-toggle');
  toggle.innerHTML = newTheme === 'default' ? '🌙' : '☀️';
};

// Load saved theme
document.addEventListener('DOMContentLoaded', () => {
  const savedTheme = localStorage.getItem('theme') || 'default';
  document.body.setAttribute('data-md-color-scheme', savedTheme);
});

Brand Themes

Corporate Theme

/* Professional corporate theme */
:root {
  --md-primary-fg-color: #003366;
  --md-primary-fg-color--light: #004080;
  --md-primary-fg-color--dark: #002244;
  --md-accent-fg-color: #0066cc;

  /* Typography */
  --md-text-font: "IBM Plex Sans";
  --md-code-font: "IBM Plex Mono";
}

/* Remove rounded corners for corporate look */
.md-typeset pre,
.md-typeset table:not([class]),
.admonition {
  border-radius: 0;
}

Startup Theme

/* Modern startup theme */
:root {
  --md-primary-fg-color: #6c5ce7;
  --md-primary-fg-color--light: #a29bfe;
  --md-primary-fg-color--dark: #5f3dc4;
  --md-accent-fg-color: #00cec9;

  /* Gradients */
  --gradient-primary: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

/* Gradient header */
.md-header {
  background: var(--gradient-primary);
}

Minimal Theme

/* Clean minimal theme */
:root {
  --md-primary-fg-color: #000000;
  --md-accent-fg-color: #000000;
  --md-default-bg-color: #ffffff;
  --md-code-bg-color: #f8f8f8;
}

/* Remove shadows and borders */
* {
  box-shadow: none !important;
}

.md-header {
  border-bottom: 1px solid #e0e0e0;
}

Responsive Theming

Mobile Adjustments

/* Mobile-specific theme adjustments */
@media screen and (max-width: 768px) {
  :root {
    --md-typeset-font-size: 0.9rem;
  }

  .md-nav__title {
    font-size: 1.2rem;
  }

  /* Larger touch targets */
  .md-nav__link {
    padding: 0.8rem 1rem;
  }
}

Dark Mode Optimizations

/* Dark mode specific adjustments */
[data-md-color-scheme="slate"] {
  /* Softer contrast */
  --md-default-bg-color: #1e1e1e;
  --md-default-bg-color--light: #2d2d2d;
  --md-code-bg-color: #2d2d2d;

  /* Better readability */
  --md-typeset-color: #e0e0e0;

  /* Syntax highlighting for dark mode */
  --md-code-hl-number-color: #b5cea8;
  --md-code-hl-string-color: #ce9178;
  --md-code-hl-keyword-color: #569cd6;
}

Performance

Optimize Fonts

theme:
  font: false  # Disable Google Fonts

/* Self-host fonts */
@font-face {
  font-family: 'CustomFont';
  src: url('../fonts/custom-font.woff2') format('woff2');
  font-display: swap;
}

Reduce CSS

/* Remove unused features */
.md-search__scrollwrap,
.md-sidebar__scrollwrap {
  scrollbar-width: thin;
}

/* Simplify animations */
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Best Practices

1. Consistency: Maintain consistent color usage
2. Accessibility: Ensure sufficient contrast ratios
3. Performance: Optimize assets and fonts
4. Responsiveness: Test on various devices
5. Branding: Align with brand guidelines

Examples

Complete Theme Configuration

# mkdocs.yml
theme:
  name: material
  custom_dir: overrides

  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-4
        name: Switch to auto

  font:
    text: Inter
    code: Fira Code

  logo: assets/logo.svg
  favicon: assets/favicon.png

  icon:
    repo: fontawesome/brands/github
    edit: material/pencil
    view: material/eye

extra_css:
  - assets/stylesheets/theme.css
  - assets/stylesheets/custom.css

See Also

• Material for MkDocs - Changing Colors
• Material for MkDocs - Changing Fonts
• Material Design Color System
• Custom Theme Development