Registry / web-framework / mkdocs-exclude

mkdocs-exclude

JSON →
library1.0.2pypypiunverified

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.

web-framework
pip install mkdocs-exclude
github ↗package ↗
INSTALL
IMPORT
SIG · MKDOCS-EXCLUDE
M
mkdocs-exclude
web-frameworkpythonv1.0.2
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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)$'
Debug
Known issues
breakingMkDocs 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.
affects: MkDocs 2.0+
gotchaYAML 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.
affects: All versions
gotchaMkDocs 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.
affects: MkDocs 1.5+
Errors
Common errors & fixes
While parsing a block mapping, did not find expected key. (marked with "---" as the next element)
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
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.
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.
Upgrade
Version history
1.0.2latest on PyPI · released Feb 20, 2019
Audit
Dependencies
mkdocsrequiredThis is an MkDocs plugin and requires MkDocs to function.
Agent activity
6 hits · last 30 days
node
6
Resources
githubhttps://github.com/apenwarr/mkdocs-exclude ↗
packagehttps://pypi.org/project/mkdocs-exclude/ ↗
mkdocs-exclude — pip install mkdocs-exclude · libregistry