Skip to content

Customization Guide

This guide shows you how to customize your Material for MkDocs site.

Theme Customization

Colors

Change the primary and accent colors in mkdocs.yml:

theme:
  name: material
  palette:
    - scheme: default
      primary: deep purple  # Change this
      accent: amber         # And this

Available colors: 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

Fonts

Customize fonts in mkdocs.yml:

theme:
  font:
    text: Roboto
    code: Roboto Mono

Popular options: Roboto, Open Sans, Lato, Montserrat, Ubuntu, Source Code Pro (for code)

Logo and Favicon

Add your own logo and favicon:

theme:
  logo: assets/logo.png
  favicon: assets/favicon.png

Place images in docs/assets/ directory.

Enable Tabs

Add tabs to the top navigation:

theme:
  features:
    - navigation.tabs
    - navigation.tabs.sticky  # Tabs stay visible when scrolling

Table of Contents

Position the table of contents:

theme:
  features:
    - toc.integrate  # Integrate TOC into navigation

Instant Loading

Enable instant page loading (SPA-like):

theme:
  features:
    - navigation.instant
    - navigation.instant.progress  # Show loading progress

Back to Top Button

theme:
  features:
    - navigation.top  # "Back to top" button

Content Features

Code Copy Button

Already enabled in this site:

theme:
  features:
    - content.code.copy

Code Annotations

Enable code annotations:

theme:
  features:
    - content.code.annotate

Then use in code blocks:

print("Hello")  # (1)!
  1. This is an annotation!

Tabs

Create tabbed content:

=== "Tab 1"
    Content for tab 1

=== "Tab 2"
    Content for tab 2

Admonitions

Create styled callouts:

!!! note "Custom Title"
    This is a note

!!! warning
    This is a warning

!!! tip
    This is a tip

Types: note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote

Add social media icons to the footer:

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/yourusername
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/yourusername
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/yourusername

Custom CSS

Add custom styles:

  1. Create docs/stylesheets/extra.css:
:root {
  --md-primary-fg-color: #ff1744;
}
  1. Reference in mkdocs.yml:
extra_css:
  - stylesheets/extra.css

Analytics

Add Google Analytics:

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

Customize the footer:

extra:
  generator: false  # Remove "Made with Material for MkDocs"

copyright: Copyright © 2024 Your Name

Plugins

Blog Plugin

Install and add a blog to your site:

uv add mkdocs-material[blog]

plugins:
  - blog

Tags Plugin

Add tags to pages:

plugins:
  - tags

Git Revision Date

Show last updated date:

uv add mkdocs-git-revision-date-localized-plugin

plugins:
  - git-revision-date-localized:
      enable_creation_date: true

Advanced Customization

Custom Templates

Override Material templates by creating files in overrides/:

  1. Set custom directory:
theme:
  custom_dir: overrides
  1. Create template overrides in overrides/ matching Material's structure

JavaScript

Add custom JavaScript:

  1. Create docs/javascripts/extra.js
  2. Reference in mkdocs.yml:
extra_javascript:
  - javascripts/extra.js

Examples

GitHub Dark: 

theme:
  palette:
    - scheme: slate
      primary: black
      accent: blue

Dracula: 

theme:
  palette:
    - scheme: slate
      primary: deep purple
      accent: pink

Nord: 

theme:
  palette:
    - scheme: slate
      primary: blue grey
      accent: light blue

Resources

Testing Changes

After making changes:

# Preview locally
uv run mkdocs serve

# Build to verify
uv run mkdocs build

Visit http://127.0.0.1:8000 to see your changes live!