MkDocs Exclude Plugin

1.0.2 · active · verified Thu Apr 16

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.

Common errors

```
While parsing a block mapping, did not find expected key. (marked with "---" as the next element)
```
cause Incorrect YAML indentation for the `glob` or `regex` lists under the `exclude` plugin configuration.

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`).
```
expected a single document but found a multi-document source
```
cause A pattern starting with a punctuation mark (e.g., `*`, `!`) was not quoted in the `mkdocs.yml` file, leading to YAML parsing issues.

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.
```
Files are not being excluded from the build, even with patterns configured.
```
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.

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.

Warnings

breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install mkdocs-exclude Install mkdocs-exclude

Quickstart

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.

plugins:
  - exclude:
      glob:
        - 'exclude/this/path/*'
        - "*.tmp"
        - "*.pdf"
        - "*.gz"
      regex:
        - '.*\.(tmp|bin|tar)$'

view raw JSON →