Skip to content

Configuration

Learn how to configure your MkDocs project and customize the Material theme.

MkDocs Configuration

The main configuration file is mkdocs.yml in the root of your project.

Basic Settings

site_name: Your Project Name
site_description: A brief description of your project
site_author: Your Name
site_url: https://example.com

Theme Configuration

Configure the Material theme:

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

Color Schemes

Available primary colors:

  • red, pink, purple, deep purple
  • indigo, blue, light blue, cyan
  • teal, green, light green, lime
  • yellow, amber, orange, deep orange

Features

Enable Material theme features:

theme:
  features:
    - navigation.instant      # Instant loading
    - navigation.tracking     # Anchor tracking
    - navigation.tabs         # Top-level tabs
    - navigation.sections     # Section index pages
    - navigation.expand       # Expand navigation
    - navigation.top          # Back to top button
    - search.suggest          # Search suggestions
    - search.highlight        # Highlight search terms
    - content.code.copy       # Copy code button

Markdown Extensions

Enable powerful Markdown features:

markdown_extensions:
  - pymdownx.highlight:       # Code highlighting
      anchor_linenums: true
  - pymdownx.inlinehilite     # Inline code highlighting
  - pymdownx.snippets         # Include snippets
  - pymdownx.superfences      # Nested code blocks
  - pymdownx.tabbed:          # Tabbed content
      alternate_style: true
  - admonition                # Admonition blocks
  - pymdownx.details          # Collapsible admonitions
  - pymdownx.emoji:           # Emoji support
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - attr_list                 # Add attributes to elements
  - md_in_html                # Markdown in HTML

Define your site's navigation structure:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - User Guide:
      - Installation: guide/installation.md
      - Configuration: guide/configuration.md
  - API Reference:
      - Overview: api/overview.md
      - Functions: api/functions.md
  - About: about.md

Advanced Configuration

Add social media links to your header:

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

Analytics

Add Google Analytics:

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

Set copyright information:

copyright: Copyright © 2024 Your Organization

Repository Information

Link to your repository:

repo_name: username/repo
repo_url: https://github.com/username/repo
edit_uri: edit/main/docs/

Custom CSS and JavaScript

Add custom styling or scripts:

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js

Create the files:

docs/
  stylesheets/
    extra.css
  javascripts/
    extra.js

Plugins

Extend MkDocs functionality with plugins:

plugins:
  - search:
      lang: en
  - tags
  - git-revision-date-localized:
      enable_creation_date: true

Install plugin dependencies:

pip install mkdocs-git-revision-date-localized-plugin

Environment-Specific Configuration

You can use different configurations for different environments:

Development

Create mkdocs.dev.yml:

INHERIT: mkdocs.yml
site_url: http://localhost:8000

Use it:

mkdocs serve -f mkdocs.dev.yml

Production

Your main mkdocs.yml serves as the production configuration.

Configuration Examples

Minimal Configuration

site_name: My Docs
theme:
  name: material

site_name: Comprehensive Documentation
site_description: Full-featured docs with all Material theme features
site_url: https://docs.example.com

theme:
  name: material
  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
  font:
    text: Roboto
    code: Roboto Mono
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.tabs.link

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - attr_list
  - md_in_html
  - tables
  - footnotes

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/your-org
  analytics:
    provider: google
    property: G-XXXXXXXXXX

copyright: Copyright © 2024 Your Organization

plugins:
  - search
  - tags

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Deployment:
      - Cloudflare Pages: deployment/cloudflare-pages.md
      - Configuration: deployment/configuration.md
  - About: about.md

Validation

Validate your configuration:

mkdocs build --strict

This will fail if there are any warnings or errors.

Resources