MkDocs Configuration Reference

MkDocs Configuration Reference

Complete mkdocs.yml configuration settings documentation.

Official Documentation: https://www.mkdocs.org/user-guide/configuration/

Configuration File

MkDocs uses a YAML configuration file named mkdocs.yml (or mkdocs.yaml) in the project root.

Project Information Settings

site_name

• Type: string
• Required: Yes
• Description: The name of your documentation site
• Example:

  site_name: My Documentation
  

site_url

• Type: string (URL)
• Default: null
• Description: The canonical URL of the site. Adds canonical link and helps with sitemap generation
• Example:

  site_url: https://example.com/docs/
  

site_description

• Type: string
• Default: null
• Description: A description of the documentation site (added as meta tag)
• Example:

  site_description: Comprehensive API documentation for our project
  

site_author

• Type: string
• Default: null
• Description: The author of the documentation (added as meta tag)
• Example:

  site_author: John Doe
  

repo_url

• Type: string (URL)
• Default: null
• Description: Repository URL. Adds a link to your repository (GitHub, GitLab, Bitbucket, etc.)
• Example:

  repo_url: https://github.com/username/repository
  

repo_name

• Type: string
• Default: Automatically detected from repo_url
• Description: Repository link text
• Example:

  repo_name: username/repository
  

edit_uri

• Type: string

• Default: Automatically computed from repo_url

• Description: Path from repo_url to the docs directory for edit links

• Examples:

  # For GitHub (default)
  edit_uri: edit/main/docs/
  
  # For Bitbucket
  edit_uri: src/default/docs/
  
  # For GitLab
  edit_uri: -/edit/main/docs/
  
  # Disable edit links
  edit_uri: ""
  

edit_uri_template

• Type: string
• Default: null
• Description: Template for edit links using Python string formatting
• Example:

  edit_uri_template: "https://github.com/org/repo/edit/main/docs/{path}"
  

copyright

• Type: string
• Default: null
• Description: Copyright notice to display in the footer
• Example:

  copyright: Copyright © 2024 My Company
  

Repository Settings

remote_branch

• Type: string
• Default: gh-pages
• Description: The remote branch to commit to for mkdocs gh-deploy
• Example:

  remote_branch: gh-pages
  

remote_name

• Type: string
• Default: origin
• Description: The remote name to push to for mkdocs gh-deploy
• Example:

  remote_name: origin
  

Documentation Layout

nav

• Type: list
• Default: Automatically generated from file structure
• Description: Defines the navigation structure
• Example:

  nav:
    - Home: index.md
    - User Guide:
        - Installation: user-guide/installation.md
        - Configuration: user-guide/configuration.md
        - Advanced:
            - Plugins: user-guide/advanced/plugins.md
            - Themes: user-guide/advanced/themes.md
    - API Reference: api/
    - About:
        - License: about/license.md
        - Release Notes: about/changelog.md
  

exclude_docs

• Type: string or list of strings (glob patterns)
• Default: See below
• Description: Patterns for files to exclude from the built site
• Default patterns:
  • Any file named __pycache__
  • Any file with .pyc extension
  • Hidden files (starting with .)
• Example:

  exclude_docs: |
    *.py
    /drafts/**
    api-draft.md
  

draft_docs

• Type: string or list of strings (glob patterns)
• Default: null
• Description: Files to treat as drafts (shown in serve, excluded from build)
• Example:

  draft_docs: |
    drafts/**
    *.draft.md
  

not_in_nav

• Type: string or list of strings (glob patterns)
• Default: null
• Description: Pages to include in build but not warn about if missing from nav
• Example:

  not_in_nav: |
    api/**
    /tags.md
  

Build Directories

docs_dir

• Type: string (path)
• Default: docs
• Description: Directory containing documentation source files
• Example:

  docs_dir: documentation
  

site_dir

• Type: string (path)
• Default: site
• Description: Directory where the output HTML is built
• Example:

  site_dir: public
  

Theme Configuration

theme

• Type: string or mapping
• Default: mkdocs
• Description: The theme to use for the documentation
• Simple Example:

  theme: readthedocs
  

• Advanced Example:

  theme:
    name: material
    palette:
      - scheme: default
        toggle:
          icon: material/brightness-7
          name: Switch to dark mode
      - scheme: slate
        toggle:
          icon: material/brightness-4
          name: Switch to light mode
    features:
      - navigation.tabs
      - navigation.sections
      - toc.integrate
      - search.suggest
      - search.highlight
    language: en
    font:
      text: Roboto
      code: Roboto Mono
  

Theme Sub-settings

theme.name

• Type: string
• Required: When using mapping format
• Description: Name of installed theme
• Built-in themes: mkdocs, readthedocs

theme.custom_dir

• Type: string (path)
• Default: null
• Description: Directory with custom theme overrides
• Example:

  theme:
    name: material
    custom_dir: overrides
  

theme.static_templates

• Type: list
• Default: []
• Description: Static template pages to render
• Example:

  theme:
    name: mkdocs
    static_templates:
      - sitemap.xml
      - 404.html
  

theme.locale

• Type: string (ISO 639-1 language code)
• Default: en
• Description: Language locale for the theme
• Example:

  theme:
    name: material
    locale: es
  

CSS and JavaScript

extra_css

• Type: list
• Default: []
• Description: Additional CSS files to include
• Example:

  extra_css:
    - css/custom.css
    - css/print.css
    - https://cdn.example.com/styles.css
  

extra_javascript

• Type: list or list of mappings
• Default: []
• Description: Additional JavaScript files to include
• Simple Example:

  extra_javascript:
    - js/custom.js
    - https://cdn.example.com/script.js
  

• Advanced Example with attributes:

  extra_javascript:
    - path: js/custom.js
      async: true
    - path: js/analytics.js
      defer: true
    - path: js/module.js
      type: module
  

extra_templates

• Type: list
• Default: []
• Description: Additional template files to render
• Example:

  extra_templates:
    - custom.html
    - robots.txt
  

extra

• Type: mapping
• Default: {}
• Description: Extra context variables for templates
• Example:

  extra:
    version:
      provider: mike
      default: stable
    social:
      - icon: fontawesome/brands/github
        link: https://github.com/username
      - icon: fontawesome/brands/twitter
        link: https://twitter.com/username
    analytics:
      provider: google
      property: G-XXXXXXXXXX
  

Preview Server

use_directory_urls

• Type: boolean
• Default: true
• Description: Use directory URLs (page/ vs page.html)
• Example:

  use_directory_urls: true  # Results in /page/
  use_directory_urls: false # Results in /page.html
  

strict

• Type: boolean
• Default: false
• Description: Enable strict mode (halt on warnings)
• Example:

  strict: true
  

dev_addr

• Type: string
• Default: 127.0.0.1:8000
• Description: Address to use for mkdocs serve
• Example:

  dev_addr: 0.0.0.0:8080
  

watch

• Type: list
• Default: []
• Description: Additional directories to watch for changes
• Example:

  watch:
    - ../my_module
    - ../tests
  

Validation Settings

validation

• Type: mapping
• Description: Controls for build warnings and validation
• Full Example:

  validation:
    nav:
      omitted_files: warn # warn | info | ignore
      not_found: warn # warn | info | ignore
      absolute_links: warn # warn | info | ignore
    links:
      not_found: warn # warn | info | ignore
      anchors: warn # warn | info | ignore
      absolute_links: warn # warn | info | ignore | relative_to_docs
      unrecognized_links: warn # warn | info | ignore
  

validation.nav.omitted_files

• Values: warn, info, ignore
• Default: info
• Description: Files in docs_dir not included in nav

validation.nav.not_found

• Values: warn, info, ignore
• Default: warn
• Description: Files in nav that don't exist

validation.nav.absolute_links

• Values: warn, info, ignore
• Default: info
• Description: Absolute paths in nav configuration

validation.links.not_found

• Values: warn, info, ignore
• Default: warn
• Description: Links to missing pages

validation.links.anchors

• Values: warn, info, ignore
• Default: info
• Description: Links to missing anchors

validation.links.absolute_links

• Values: warn, info, ignore, relative_to_docs
• Default: info
• Description: Absolute links starting with /
• Special value: relative_to_docs - Treat /path as relative to docs_dir

validation.links.unrecognized_links

• Values: warn, info, ignore
• Default: info
• Description: Unrecognized link formats

Markdown Extensions

markdown_extensions

• Type: list or mapping

• Default: []

• Description: Python Markdown extensions to enable

• Example:

  markdown_extensions:
    # Simple extensions
    - toc
    - tables
    - footnotes
  
    # Extensions with configuration
    - toc:
        permalink: true
        slugify: !!python/object/apply:pymdownx.slugs.slugify
          kwds:
            case: lower
    - pymdownx.highlight:
        anchor_linenums: true
        line_spans: __span
        pygments_lang_class: true
    - pymdownx.superfences:
        custom_fences:
          - name: mermaid
            class: mermaid
            format: !!python/name:pymdownx.superfences.fence_code_format
    - admonition
    - pymdownx.details
    - pymdownx.tabbed:
        alternate_style: true
    - attr_list
    - md_in_html
  

Plugins

plugins

• Type: list or mapping
• Default: ['search'] if not specified
• Description: Plugins to enable
• Example:

  plugins:
    - search:
        separator: '[\s\-\.]+'
        min_search_length: 3
        lang:
          - en
          - es
        prebuild_index: false
        indexing: full
    - tags:
        tags_file: tags.md
    - social:
        cards: true
        cards_dir: assets/images/social
    - minify:
        minify_html: true
        minify_js: true
        minify_css: true
    - git-revision-date-localized:
        enable_creation_date: true
        type: timeago
  

Search Plugin Configuration

The built-in search plugin accepts these options:

plugins.search.separator

• Type: string (regex)
• Default: r'[\s\-]+'
• Description: Word separator pattern

plugins.search.min_search_length

• Type: integer
• Default: 3
• Description: Minimum search query length

plugins.search.lang

• Type: string or list
• Default: Theme locale or ['en']
• Description: Language(s) for search stemming

plugins.search.prebuild_index

• Type: boolean or string
• Default: false
• Description: Pre-build search index (requires Node.js)

plugins.search.indexing

• Type: string
• Default: full
• Values: full, sections, titles
• Description: What to include in search index

Hooks

hooks

• Type: list
• Default: []
• Description: Python scripts with event hooks
• Example:

  hooks:
    - scripts/hooks.py
  

Hook Script Example:

# scripts/hooks.py
import logging

def on_pre_build(config):
    """Called before the build process starts."""
    logging.info("Starting documentation build...")

def on_page_markdown(markdown, page, config, files):
    """Called when markdown is loaded, before conversion to HTML."""
    return markdown.replace('{{VERSION}}', config['extra']['version'])

def on_page_content(html, page, config, files):
    """Called after markdown is converted to HTML."""
    return html

Environment Variables

Using !ENV tag

• Description: Reference environment variables in configuration

• Syntax: !ENV [VAR_NAME, 'default_value'] or !ENV VAR_NAME

• Example:

  site_name: !ENV [SITE_NAME, "My Documentation"]
  site_url: !ENV SITE_URL
  
  theme:
    name: !ENV [THEME_NAME, "material"]
  
  extra:
    analytics:
      property: !ENV GOOGLE_ANALYTICS_KEY
    version: !ENV [VERSION, "dev"]
  

Path References

Using !relative tag

• Description: Specify paths relative to config file or docs directory

• Syntax: !relative $config_dir/path or !relative $docs_dir/path

• Example:

  theme:
    custom_dir: !relative $config_dir/custom_theme
  
  extra_css:
    - !relative $docs_dir/stylesheets/extra.css
  
  plugins:
    - macros:
        include_dir: !relative $config_dir/includes
  

Configuration Inheritance

INHERIT

• Type: string (path)
• Description: Inherit configuration from a parent file
• Example:

base.yml:

site_name: My Documentation
theme:
  name: material
  palette:
    primary: indigo
plugins:
  search: {}
  tags: {}

mkdocs.yml:

INHERIT: base.yml

site_name: My Documentation - Development
theme:
  palette:
    primary: green

# Plugins are merged, not replaced
plugins:
  minify: {}

Complete Configuration Example

# Project information
site_name: My Project Documentation
site_url: https://example.com/
site_description: Comprehensive documentation for My Project
site_author: Development Team

# Repository
repo_url: https://github.com/myorg/myproject
repo_name: myorg/myproject
edit_uri: edit/main/docs/

# Copyright
copyright: Copyright © 2024 My Organization

# Configuration
theme:
  name: material
  custom_dir: overrides

  # Theme configuration
  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

  features:
    - announce.dismiss
    - content.action.edit
    - content.action.view
    - content.code.annotate
    - content.code.copy
    - content.tabs.link
    - content.tooltips
    - header.autohide
    - navigation.expand
    - navigation.footer
    - navigation.indexes
    - navigation.instant
    - navigation.sections
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
    - toc.follow
    - toc.integrate

  font:
    text: Roboto
    code: Roboto Mono

  language: en

  icon:
    logo: material/library
    repo: fontawesome/brands/github

# Extensions
markdown_extensions:
  # Python Markdown
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
      toc_depth: 3
  - tables

  # Python Markdown Extensions
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.betterem
  - 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
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

# Plugins
plugins:
  - search:
      separator: '[\s\-\.]+'
      lang:
        - en
  - tags:
      tags_file: tags.md
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true

# Customization
extra:
  version:
    provider: mike
    default: latest

  social:
    - icon: fontawesome/brands/github
      link: https://github.com/myorg
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/myorg
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/company/myorg

  analytics:
    provider: google
    property: !ENV GOOGLE_ANALYTICS_KEY
    feedback:
      title: Was this page helpful?
      ratings:
        - icon: material/emoticon-happy-outline
          name: This page was helpful
          data: 1
          note: Thanks for your feedback!
        - icon: material/emoticon-sad-outline
          name: This page could be improved
          data: 0
          note: Thanks for your feedback!

  consent:
    title: Cookie consent
    description: >-
      We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.


# Additional CSS
extra_css:
  - stylesheets/extra.css

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

# Navigation
nav:
  - Home: index.md
  - Getting Started:
      - Installation: getting-started/installation.md
      - Quick Start: getting-started/quickstart.md
      - Configuration: getting-started/configuration.md
  - User Guide:
      - user-guide/index.md
      - Basics: user-guide/basics.md
      - Advanced: user-guide/advanced.md
      - Best Practices: user-guide/best-practices.md
  - API Reference:
      - api/index.md
      - Core API: api/core.md
      - Extensions: api/extensions.md
  - Contributing:
      - contributing/index.md
      - Development Setup: contributing/setup.md
      - Guidelines: contributing/guidelines.md
  - About:
      - Release Notes: about/changelog.md
      - License: about/license.md

# Page tree
exclude_docs: |
  *.py
  /templates/

not_in_nav: |
  /tags.md

# Strict mode
strict: !ENV [STRICT, false]

# Development server
dev_addr: 127.0.0.1:8000

# Build directories
docs_dir: docs
site_dir: site

# Validation
validation:
  nav:
    omitted_files: warn
    not_found: warn
  links:
    not_found: warn
    anchors: info
    absolute_links: relative_to_docs

Official Resources

• Configuration Guide: https://www.mkdocs.org/user-guide/configuration/
• YAML Syntax: https://yaml.org/
• Environment Variables: https://www.mkdocs.org/user-guide/configuration/#environment-variables
• Plugin Catalog: https://github.com/mkdocs/catalog