Skip to content

Configuration Reference

Learn how to configure MkDocs Material to create the perfect documentation site for your needs.

Configuration File

All configuration is done in mkdocs.yml at the root of your project. This file uses YAML format and controls every aspect of your site.

Essential Metadata

Site Information

mkdocs.yml
# Basic site information
site_name: My Documentation          # Required: Your site title
site_url: https://example.com        # Required: Full URL (needed for features)
site_author: Your Name               # Optional: Author name
site_description: >                  # Optional: Site description for SEO
  A comprehensive guide to using
  our amazing product with examples
  and best practices.

# Repository information
repo_url: https://github.com/username/repo     # Optional: Repository URL
repo_name: username/repo                       # Optional: Repository name
edit_uri: edit/main/docs/                      # Optional: Edit link path

# Copyright
copyright: Copyright © 2024 Your Name     # Optional: Footer copyright

site_url is Required

Many features like social cards and sitemaps require site_url to be set correctly.

Theme Configuration

Basic Theme Setup

mkdocs.yml
theme:
  name: material                    # Use Material theme
  custom_dir: overrides            # Optional: Custom theme overrides
  language: en                     # Optional: Site language

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

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

  # Font configuration
  font:
    text: Roboto                   # Body text font
    code: Roboto Mono              # Code font

  # Logo and icons
  logo: assets/logo.svg            # Site logo
  favicon: assets/favicon.png      # Browser favicon

  # Repository icon
  icon:
    repo: fontawesome/brands/github

Theme Features

Enable powerful features by adding them to the features list:

mkdocs.yml
theme:
  features:
    # Navigation features
    - navigation.instant          # Single-page application behavior
    - navigation.tracking         # Anchor tracking
    - navigation.tabs             # Tab navigation
    - navigation.tabs.sticky      # Sticky navigation tabs
    - navigation.sections         # Collapsible sections
    - navigation.expand           # Auto-expand sections
    - navigation.path             # Breadcrumbs
    - navigation.prune            # Prune large sections
    - navigation.indexes          # Section index pages
    - navigation.top              # Back to top button
    - navigation.footer           # Previous/next links

    # Table of contents
    - toc.follow                  # Follow scroll
    - toc.integrate               # Integrate with navigation

    # Search features
    - search.suggest              # Search suggestions
    - search.highlight            # Highlight search terms
    - search.share                # Share search URL

    # Content features
    - content.code.annotate       # Code annotations
    - content.code.copy           # Copy button on code blocks
    - content.code.select         # Line selection
    - content.tabs.link           # Link content tabs
    - content.tooltips            # Tooltips
    - content.action.edit         # Edit page action
    - content.action.view         # View source action

    # Header features
    - header.autohide             # Auto-hide header
    - announce.dismiss            # Dismissible announcements

Plugins Configuration

Essential Plugins

mkdocs.yml
plugins:
  # Built-in search (enabled by default)
  - search:
      lang: en
      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])'
      pipeline:
        - stemmer
        - stopWordFilter

  # Git revision date
  - git-revision-date-localized:
      type: iso_datetime
      enable_creation_date: true

  # Minification
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true

  # Redirects
  - redirects:
      redirect_maps:
        'old-page.md': 'new-page.md'
        'legacy/': 'current/'

  # Social cards
  - social:
      cards: true
      cards_layout_options:
        background_color: "#1e1e1e"
        color: "#ffffff"

Markdown Extensions

Python Markdown Extensions

mkdocs.yml
markdown_extensions:
  # Python Markdown
  - abbr                          # Abbreviations
  - admonition                    # Admonition blocks
  - attr_list                     # Attribute lists
  - def_list                      # Definition lists
  - footnotes                     # Footnotes
  - md_in_html                    # Markdown in HTML
  - toc:                          # Table of contents
      permalink: true             # Permalink symbols
      permalink_title: Link to this section
      toc_depth: 4                # TOC depth
  - tables                        # Tables
  - meta                          # Metadata

PyMdown Extensions

mkdocs.yml
markdown_extensions:
  # PyMdown Extensions
  - pymdownx.arithmatex:          # Math support
      generic: true
  - pymdownx.betterem:            # Better emphasis
      smart_enable: all
  - pymdownx.caret               # Caret (insertions)
  - pymdownx.critic              # Critic markup
  - pymdownx.details             # Collapsible blocks
  - pymdownx.emoji:              # Emoji support
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:          # Code highlighting
      anchor_linenums: true      # Anchor line numbers
      line_spans: __span         # Line spans
      pygments_lang_class: true  # Pygments CSS classes
  - pymdownx.inlinehilite        # Inline code highlighting
  - pymdownx.keys                # Keyboard keys
  - pymdownx.mark                # Mark text
  - pymdownx.smartsymbols        # Smart symbols
  - pymdownx.superfences:        # Nested code blocks
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:             # Content tabs
      alternate_style: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.tasklist:           # Task lists
      custom_checkbox: true
  - pymdownx.tilde               # Tilde (deletions)
  - pymdownx.snippets:           # Include snippets
      base_path: docs

Simple Navigation

mkdocs.yml
nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
    - Configuration: getting-started/configuration.md
  - User Guide:
    - Overview: guide/overview.md
    - Basic Usage: guide/basic.md
    - Advanced: guide/advanced.md
  - API Reference: api/
  - About:
    - License: about/license.md
    - Contributing: about/contributing.md
mkdocs.yml
nav:
  - Home: index.md
  - Getting Started:
    - getting-started/index.md      # Section index
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
  - Features:
    - features/index.md             # Section index
    - Navigation: features/navigation.md
    - Search: features/search.md
    - Themes: features/themes.md

Extra Configuration

Additional Settings

mkdocs.yml
# Extra configuration
extra:
  # Social links
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/username
      name: GitHub
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/username
      name: Twitter
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/username
      name: LinkedIn


  # Version selection
  version:
    provider: mike
    default: stable

# Extra CSS and JavaScript
extra_css:
  - stylesheets/extra.css
  - stylesheets/custom.css

extra_javascript:
  - javascripts/extra.js
  - javascripts/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

Configuration Best Practices

1. Use Environment Variables

For sensitive data, use environment variables:

mkdocs.yml
extra:
  custom_setting: !ENV CUSTOM_API_KEY

2. Organize Large Configurations

Split large configurations into sections with comments:

mkdocs.yml
# ============================================
# SITE INFORMATION
# ============================================
site_name: My Documentation
site_url: https://example.com

# ============================================
# THEME CONFIGURATION
# ============================================
theme:
  name: material
  # ... more theme config

# ============================================
# PLUGINS
# ============================================
plugins:
  - search
  # ... more plugins

3. Use YAML Anchors

Reduce repetition with YAML anchors:

mkdocs.yml
# Define anchor
_shared: &shared
  icon: material/link
  name: External link

# Use anchor
extra:
  social:
    - <<: *shared
      link: https://github.com/username
    - <<: *shared
      link: https://twitter.com/username

4. Validate Your Configuration

Always validate your configuration:

# Check syntax
mkdocs build --strict

# Test locally
mkdocs serve --strict

Complete Example

Here's a complete mkdocs.yml example with all common options:

Complete mkdocs.yml

```yaml # Site information site_name: Ultimate MkDocs Material Guide site_url: https://mkdocs-ultimate.example.com site_author: Documentation Team site_description: The definitive guide to MkDocs Material

# Repository
repo_url: https://github.com/org/mkdocs-ultimate
repo_name: org/mkdocs-ultimate
edit_uri: edit/main/docs/

# Copyright
copyright: Copyright &copy; 2024 Documentation Team

# Theme configuration
theme:
  name: material
  custom_dir: overrides
  language: en

  # Features
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.path
    - navigation.top
    - search.suggest
    - search.highlight
    - search.share
    - content.code.annotate
    - content.code.copy
    - content.tabs.link

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

  # Fonts
  font:
    text: Roboto
    code: Roboto Mono

  # Logo and icons
  logo: assets/logo.svg
  favicon: assets/favicon.png
  icon:
    repo: fontawesome/brands/github

# Plugins
plugins:
  - search
  - minify:
      minify_html: true
  - git-revision-date-localized:
      type: iso_datetime

# Markdown extensions
markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

# Navigation
nav:
  - Home: index.md
  - Getting Started:
    - getting-started/index.md
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
    - Configuration: getting-started/configuration.md

# Extra configuration
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/org/mkdocs-ultimate
      name: GitHub

# Extensions
extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js
```

Next Steps

Now that you understand configuration, explore: