MkDocs · Schema

MkDocs Configuration

Schema for the MkDocs project configuration file (mkdocs.yml). Defines all settings that control site metadata, navigation, themes, plugins, Markdown extensions, and build behavior for generating static documentation sites.

DocumentationMarkdownOpen SourcePythonStatic Site Generator

Properties

Name Type Description
site_name string The main title for the project documentation site. This required setting is passed as the site_name context variable when rendering the theme.
site_url string The full canonical URL where the documentation will be hosted. Used to add a canonical link tag to each HTML page and to configure the dev server mount path.
site_description string A description for the documentation project added to the HTML meta tags.
site_author string The name of the author added to the HTML meta tags.
repo_url string URL to the source repository (GitHub, Bitbucket, GitLab, etc.). When set, provides a link to the repository on each documentation page.
repo_name string Display name for the repository link. Defaults to 'GitHub', 'Bitbucket', or 'GitLab' when the repo_url matches those domains, otherwise uses the hostname.
edit_uri string Path from repo_url to the docs directory for direct page editing links. Automatically set for known hosts (GitHub, GitLab, Bitbucket). Set to empty string to disable.
edit_uri_template string More flexible alternative to edit_uri using Python format strings. Supports {path}, {path_noext}, and {path!q} (percent-encoded). Mutually exclusive with edit_uri.
docs_dir string The directory containing the documentation Markdown source files.
site_dir string The output directory where the generated static site files will be written.
copyright string A copyright notice to add to the footer of documentation pages.
nav object Defines the navigation structure of the documentation site as a list of title-to-path mappings or nested sections.
exclude_docs string Gitignore-style patterns of files relative to the docs directory to exclude from the site build.
draft_docs string Gitignore-style patterns of files relative to the docs directory to mark as drafts. Draft pages are excluded from production builds.
not_in_nav string Gitignore-style patterns of files relative to the docs directory that are intentionally not included in the nav (suppresses warning log messages).
theme object The MkDocs theme configuration. Can be a string theme name or an object with theme name and options.
dev_addr string The IP address and port for the local development server started by mkdocs serve.
use_directory_urls boolean When true, generates page_name/index.html style URLs. When false, generates page_name.html style files. True generates cleaner URLs.
strict boolean When true, enables strict mode which stops the build on warnings rather than continuing.
remote_branch string The remote branch to commit to when deploying with mkdocs gh-deploy.
remote_name string The remote name to push to when deploying with mkdocs gh-deploy.
extra_css array List of additional CSS files from the docs directory to include in the generated site.
extra_javascript array List of additional JavaScript files from the docs directory to include in the generated site. Items can be strings or script objects with defer/async attributes.
extra_templates array List of additional Jinja2 HTML or XML template files to build with the global context.
markdown_extensions array List of Python-Markdown extension names or extension configuration objects to enable. Built-in extensions (toc, tables, fenced_code) are always enabled.
plugins array List of MkDocs plugins to use during the build. Each item is either a plugin name string or a mapping of plugin name to its configuration options.
hooks array List of Python script filenames to import as plugin instances. Hooks allow local plugin-like customization without packaging.
watch array Additional paths to watch for changes during mkdocs serve (triggers live reload).
extra object A mapping of arbitrary data passed to the Jinja2 template context. Allows theme authors to require extra configuration data without explicit MkDocs support.
validation object Configuration for MkDocs validation warnings emitted during the build.
View JSON Schema on GitHub

JSON Schema

mkdocs-config-schema.json Raw ↑ 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://apievangelist.com/schemas/mkdocs/mkdocs-config.json",
  "title": "MkDocs Configuration",
  "description": "Schema for the MkDocs project configuration file (mkdocs.yml). Defines all settings that control site metadata, navigation, themes, plugins, Markdown extensions, and build behavior for generating static documentation sites.",
  "type": "object",
  "required": ["site_name"],
  "properties": {
    "site_name": {
      "type": "string",
      "description": "The main title for the project documentation site. This required setting is passed as the site_name context variable when rendering the theme.",
      "minLength": 1
    },
    "site_url": {
      "type": "string",
      "format": "uri",
      "description": "The full canonical URL where the documentation will be hosted. Used to add a canonical link tag to each HTML page and to configure the dev server mount path."
    },
    "site_description": {
      "type": "string",
      "description": "A description for the documentation project added to the HTML meta tags."
    },
    "site_author": {
      "type": "string",
      "description": "The name of the author added to the HTML meta tags."
    },
    "repo_url": {
      "type": "string",
      "format": "uri",
      "description": "URL to the source repository (GitHub, Bitbucket, GitLab, etc.). When set, provides a link to the repository on each documentation page."
    },
    "repo_name": {
      "type": "string",
      "description": "Display name for the repository link. Defaults to 'GitHub', 'Bitbucket', or 'GitLab' when the repo_url matches those domains, otherwise uses the hostname."
    },
    "edit_uri": {
      "type": "string",
      "description": "Path from repo_url to the docs directory for direct page editing links. Automatically set for known hosts (GitHub, GitLab, Bitbucket). Set to empty string to disable."
    },
    "edit_uri_template": {
      "type": "string",
      "description": "More flexible alternative to edit_uri using Python format strings. Supports {path}, {path_noext}, and {path!q} (percent-encoded). Mutually exclusive with edit_uri."
    },
    "docs_dir": {
      "type": "string",
      "description": "The directory containing the documentation Markdown source files.",
      "default": "docs"
    },
    "site_dir": {
      "type": "string",
      "description": "The output directory where the generated static site files will be written.",
      "default": "site"
    },
    "copyright": {
      "type": "string",
      "description": "A copyright notice to add to the footer of documentation pages."
    },
    "nav": {
      "description": "Defines the navigation structure of the documentation site as a list of title-to-path mappings or nested sections.",
      "$ref": "#/$defs/NavItem"
    },
    "exclude_docs": {
      "type": "string",
      "description": "Gitignore-style patterns of files relative to the docs directory to exclude from the site build."
    },
    "draft_docs": {
      "type": "string",
      "description": "Gitignore-style patterns of files relative to the docs directory to mark as drafts. Draft pages are excluded from production builds."
    },
    "not_in_nav": {
      "type": "string",
      "description": "Gitignore-style patterns of files relative to the docs directory that are intentionally not included in the nav (suppresses warning log messages)."
    },
    "theme": {
      "description": "The MkDocs theme configuration. Can be a string theme name or an object with theme name and options.",
      "oneOf": [
        {
          "type": "string",
          "description": "Theme name string shorthand (e.g., 'mkdocs', 'readthedocs').",
          "enum": ["mkdocs", "readthedocs"]
        },
        {
          "$ref": "#/$defs/ThemeConfig"
        }
      ],
      "default": "mkdocs"
    },
    "dev_addr": {
      "type": "string",
      "description": "The IP address and port for the local development server started by mkdocs serve.",
      "default": "127.0.0.1:8000",
      "pattern": "^.+:[0-9]+$"
    },
    "use_directory_urls": {
      "type": "boolean",
      "description": "When true, generates page_name/index.html style URLs. When false, generates page_name.html style files. True generates cleaner URLs.",
      "default": true
    },
    "strict": {
      "type": "boolean",
      "description": "When true, enables strict mode which stops the build on warnings rather than continuing.",
      "default": false
    },
    "remote_branch": {
      "type": "string",
      "description": "The remote branch to commit to when deploying with mkdocs gh-deploy.",
      "default": "gh-pages"
    },
    "remote_name": {
      "type": "string",
      "description": "The remote name to push to when deploying with mkdocs gh-deploy.",
      "default": "origin"
    },
    "extra_css": {
      "type": "array",
      "description": "List of additional CSS files from the docs directory to include in the generated site.",
      "items": {
        "type": "string",
        "description": "Path to a CSS file relative to the docs directory."
      },
      "default": []
    },
    "extra_javascript": {
      "type": "array",
      "description": "List of additional JavaScript files from the docs directory to include in the generated site. Items can be strings or script objects with defer/async attributes.",
      "items": {
        "oneOf": [
          {
            "type": "string",
            "description": "Path to a JavaScript file relative to the docs directory."
          },
          {
            "$ref": "#/$defs/ExtraScript"
          }
        ]
      },
      "default": []
    },
    "extra_templates": {
      "type": "array",
      "description": "List of additional Jinja2 HTML or XML template files to build with the global context.",
      "items": {
        "type": "string",
        "description": "Path to a template file."
      },
      "default": []
    },
    "markdown_extensions": {
      "type": "array",
      "description": "List of Python-Markdown extension names or extension configuration objects to enable. Built-in extensions (toc, tables, fenced_code) are always enabled.",
      "items": {
        "oneOf": [
          {
            "type": "string",
            "description": "Python-Markdown extension name."
          },
          {
            "type": "object",
            "description": "Extension name mapped to its configuration options.",
            "additionalProperties": {
              "type": "object"
            }
          }
        ]
      }
    },
    "plugins": {
      "type": "array",
      "description": "List of MkDocs plugins to use during the build. Each item is either a plugin name string or a mapping of plugin name to its configuration options.",
      "items": {
        "oneOf": [
          {
            "type": "string",
            "description": "Plugin name as registered via the mkdocs.plugins entry point group."
          },
          {
            "type": "object",
            "description": "Plugin name mapped to its configuration options.",
            "additionalProperties": {
              "type": "object"
            }
          }
        ]
      },
      "default": ["search"]
    },
    "hooks": {
      "type": "array",
      "description": "List of Python script filenames to import as plugin instances. Hooks allow local plugin-like customization without packaging.",
      "items": {
        "type": "string",
        "description": "Path to a Python script file to use as a hook."
      }
    },
    "watch": {
      "type": "array",
      "description": "Additional paths to watch for changes during mkdocs serve (triggers live reload).",
      "items": {
        "type": "string",
        "description": "File system path to watch."
      },
      "default": []
    },
    "extra": {
      "type": "object",
      "description": "A mapping of arbitrary data passed to the Jinja2 template context. Allows theme authors to require extra configuration data without explicit MkDocs support.",
      "additionalProperties": true
    },
    "validation": {
      "$ref": "#/$defs/ValidationConfig",
      "description": "Configuration for MkDocs validation warnings emitted during the build."
    }
  },
  "$defs": {
    "NavItem": {
      "description": "A navigation item which can be a list of title-to-path mappings or nested sections.",
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "description": "A navigation entry mapping a display title to a page path or a nested list of nav items.",
            "additionalProperties": {
              "oneOf": [
                {
                  "type": "string",
                  "description": "Path to the Markdown file relative to the docs directory."
                },
                {
                  "$ref": "#/$defs/NavItem"
                }
              ]
            }
          }
        ]
      }
    },
    "ThemeConfig": {
      "type": "object",
      "description": "Full theme configuration object specifying theme name and theme-specific options.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "The theme name. Use null to use a custom theme without a base theme.",
          "enum": ["mkdocs", "readthedocs"]
        },
        "custom_dir": {
          "type": "string",
          "description": "Path to a directory of custom theme overrides. Files here override corresponding theme files."
        },
        "static_templates": {
          "type": "array",
          "description": "List of templates to render as static pages even without a corresponding Markdown source.",
          "items": {
            "type": "string"
          }
        },
        "locale": {
          "type": "string",
          "description": "The locale (language code) for theme localization, e.g. 'en', 'fr', 'de'."
        },
        "language": {
          "type": "string",
          "description": "Alias for locale used by some themes."
        }
      },
      "additionalProperties": true
    },
    "ExtraScript": {
      "type": "object",
      "description": "A JavaScript file reference with optional loading attributes.",
      "required": ["path"],
      "properties": {
        "path": {
          "type": "string",
          "description": "Path to the JavaScript file relative to the docs directory."
        },
        "defer": {
          "type": "boolean",
          "description": "When true, adds the defer attribute to the script tag.",
          "default": false
        },
        "async": {
          "type": "boolean",
          "description": "When true, adds the async attribute to the script tag.",
          "default": false
        },
        "type": {
          "type": "string",
          "description": "The type attribute for the script tag (e.g., 'module')."
        }
      }
    },
    "ValidationConfig": {
      "type": "object",
      "description": "Controls validation behavior and warning levels during site builds.",
      "properties": {
        "nav": {
          "$ref": "#/$defs/NavValidationConfig"
        },
        "links": {
          "$ref": "#/$defs/LinksValidationConfig"
        }
      }
    },
    "NavValidationConfig": {
      "type": "object",
      "description": "Validation settings for navigation structure.",
      "properties": {
        "omitted_files": {
          "type": "string",
          "description": "Warning level when a doc file is never mentioned in the navigation.",
          "enum": ["warn", "info", "ignore"],
          "default": "info"
        },
        "not_found": {
          "type": "string",
          "description": "Warning level when navigation links to a relative path that does not exist as a page.",
          "enum": ["warn", "info", "ignore"],
          "default": "warn"
        },
        "absolute_links": {
          "type": "string",
          "description": "Warning level when navigation links to an absolute path starting with /.",
          "enum": ["warn", "info", "ignore", "relative_to_docs"],
          "default": "info"
        }
      }
    },
    "LinksValidationConfig": {
      "type": "object",
      "description": "Validation settings for in-page Markdown links.",
      "properties": {
        "not_found": {
          "type": "string",
          "description": "Warning level when a Markdown doc links to a relative path that does not exist.",
          "enum": ["warn", "info", "ignore"],
          "default": "warn"
        },
        "absolute_links": {
          "type": "string",
          "description": "Warning level when a Markdown doc links to an absolute path starting with /.",
          "enum": ["warn", "info", "ignore", "relative_to_docs"],
          "default": "info"
        },
        "unrecognized_links": {
          "type": "string",
          "description": "Warning level when a Markdown doc links to a relative path that does not look like a valid internal link (e.g., ends with /).",
          "enum": ["warn", "info", "ignore"],
          "default": "info"
        },
        "anchors": {
          "type": "string",
          "description": "Warning level when a Markdown doc links to an anchor not present on the target page.",
          "enum": ["warn", "info", "ignore"],
          "default": "info"
        }
      }
    }
  }
}