{"id":7412,"library":"mkdocs-exclude","title":"MkDocs Exclude Plugin","description":"mkdocs-exclude is a plugin for MkDocs that enables users to exclude files or entire directory trees from their documentation builds. It supports exclusion rules based on Unix-style wildcards (globs) or regular expressions (regexes). The current version is 1.0.2, and it is actively maintained as a solution for selective file exclusion in MkDocs projects.","status":"active","version":"1.0.2","language":"en","source_language":"en","source_url":"https://github.com/apenwarr/mkdocs-exclude","tags":["mkdocs","plugin","exclude","glob","regex","documentation"],"install":[{"cmd":"pip install mkdocs-exclude","lang":"bash","label":"Install mkdocs-exclude"}],"dependencies":[{"reason":"This is an MkDocs plugin and requires MkDocs to function.","package":"mkdocs","optional":false}],"imports":[],"quickstart":{"code":"plugins:\n  - exclude:\n      glob:\n        - 'exclude/this/path/*'\n        - \"*.tmp\"\n        - \"*.pdf\"\n        - \"*.gz\"\n      regex:\n        - '.*\\.(tmp|bin|tar)$'\n","lang":"yaml","description":"Add the 'exclude' plugin to your mkdocs.yml file, specifying 'glob' or 'regex' patterns for files/directories to be excluded. Remember that 'glob:' and 'regex:' lines must not start with a dash, but the patterns under them must start with a dash. Quote patterns that begin with punctuation marks."},"warnings":[{"fix":"Monitor the MkDocs 2.0 development and its plugin API for potential future migration strategies. Consider 'ProperDocs' as a drop-in replacement for MkDocs 1.x to avoid immediate breaking changes if you need to stay on MkDocs 1.x features.","message":"MkDocs 2.0, currently under development, is a complete rewrite and will introduce backward-incompatible changes. This means all existing plugins, including `mkdocs-exclude`, will cease to function, and no direct upgrade path will be available. Users should be aware of this future incompatibility.","severity":"breaking","affected_versions":"MkDocs 2.0+"},{"fix":"Ensure that `glob:` and `regex:` are directly under `exclude:`, and each pattern beneath them starts with a hyphen (`-`) followed by a space. Quote any pattern starting with a punctuation mark (e.g., `\"*.tmp\"`). For regex, use single quotes (`'`) to avoid issues with backslash escapes.","message":"YAML syntax for defining exclusion patterns requires careful attention to indentation and quoting. Incorrect indentation for `glob` or `regex` lists, or not quoting patterns that start with punctuation marks (e.g., `*.tmp`), will lead to parsing errors or patterns not being applied correctly.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the MkDocs documentation for `exclude_docs` to compare its capabilities with `mkdocs-exclude`. If `exclude_docs` suffices, you may not need this plugin. `mkdocs-exclude` offers more explicit glob/regex control which might be preferred in some cases.","message":"MkDocs versions 1.5 and later include a built-in `exclude_docs` configuration option. This provides similar file exclusion functionality using `.gitignore` pattern format directly within `mkdocs.yml`. Users should understand the differences and consider if the built-in option meets their needs before opting for the `mkdocs-exclude` plugin.","severity":"gotcha","affected_versions":"MkDocs 1.5+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure that the `glob:` and `regex:` keys are indented correctly under `exclude:`, and that each pattern within those lists starts with a hyphen and a space (`- pattern`).","cause":"Incorrect YAML indentation for the `glob` or `regex` lists under the `exclude` plugin configuration.","error":"While parsing a block mapping, did not find expected key. (marked with \"---\" as the next element)"},{"fix":"Enclose any patterns that begin with punctuation marks in quotes. For example, change `*.tmp` to `\"*.tmp\"` in glob patterns, or `'^.*\\.bak$'` for regex patterns to preserve backslashes.","cause":"A pattern starting with a punctuation mark (e.g., `*`, `!`) was not quoted in the `mkdocs.yml` file, leading to YAML parsing issues.","error":"expected a single document but found a multi-document source"},{"fix":"Verify that `exclude:` is listed directly under the `plugins:` section in your `mkdocs.yml`. Double-check your `glob` and `regex` patterns against your file structure and test them to ensure they accurately target the files you intend to exclude. Remember glob is Unix-style, and regex is Python's regex flavor.","cause":"The `mkdocs-exclude` plugin might not be correctly enabled in `mkdocs.yml`, or the exclusion patterns themselves are incorrect/not matching the target files.","error":"Files are not being excluded from the build, even with patterns configured."}]}