mkdocs-exclude

mkdocs-exclude is a small plugin for MkDocs, the Python-based static site generator, that lets you keep specific files or directories out of your generated documentation site. Rather than moving unwanted files out of your docs source tree, you configure a list of Unix-style glob patterns or regular expressions in mkdocs.yml, and the plugin filters matching paths from the build’s file list before MkDocs renders them.

It exists to close a gap MkDocs itself doesn’t fill directly — several long-standing MkDocs issues asked for exactly this exclusion capability, and mkdocs-exclude was built to answer them. Configuration takes just a few lines: a glob list, a regex list, or both, applied against every file’s path as MkDocs assembles the site tree.

What You Get

• Glob-based exclusion — filter files with familiar Unix-style wildcards like *.tmp or exclude/this/path/*.
• Regex-based exclusion — match file paths with full regular expressions for more precise control.
• Zero-config default — with no patterns configured, the plugin does nothing, so it’s safe to add speculatively.
• Cross-platform path matching — normalizes Windows-style backslash paths so the same glob/regex config works identically on Windows and Unix.

Common Use Cases

• Keeping draft or work-in-progress markdown files in the docs folder without publishing them.
• Excluding large binary assets (PDFs, archives, temp files) that live alongside docs but shouldn’t ship in the built site.
• Filtering out platform- or environment-specific files during CI builds using regex patterns.
• Trimming a shared docs directory down to just the subset relevant to a given MkDocs site.

Under The Hood

Architecture The entire plugin is a single class, Exclude, defined in mkdocs_exclude/plugin.py and re-exported through mkdocs_exclude/__init__.py. It subclasses mkdocs.plugins.BasePlugin, declares a config_scheme of two optional options (glob, regex), and implements exactly one lifecycle hook, on_files, which MkDocs calls with the full list of discovered File objects. The hook builds an include(name) closure that checks a candidate path against every glob and regex, then re-runs that same check against a /-normalized copy of the path to handle Windows separators, and returns a new mkdocs.structure.files.Files collection containing only the files that passed. There is no other layering — no separate modules for parsing, validation, or output — which is appropriate given the plugin does exactly one job.

Tech Stack The project is plain Python with a single runtime dependency, mkdocs itself, declared in setup.py’s install_requires. Packaging uses classic setuptools.setup() rather than a modern pyproject.toml/hatch/poetry setup, and the plugin registers itself with MkDocs through the standard mkdocs.plugins entry-point group (exclude = mkdocs_exclude:Exclude), which is how MkDocs discovers and loads third-party plugins by name from mkdocs.yml. There is no bundler, no compiled assets, and no separate deployment target — it ships as a plain PyPI sdist/wheel.

Code Quality No test files or test directory exist anywhere in the repository, and there is no CI configuration (no .github/workflows, no tox.ini). Error handling is minimal — the module trusts its inputs rather than validating glob/regex syntax explicitly, and a malformed regex would surface as a raw Python exception. Naming is short and direct (include, globs, regexes) and comments are used sparingly but effectively to explain the Windows path-separator edge case, which is the one genuinely subtle piece of logic in the file.

What Makes It Unique The plugin’s contribution is narrow but concrete: MkDocs itself has no built-in way to exclude files from a build by pattern, and mkdocs-exclude was written specifically in response to user requests filed against MkDocs’ own issue tracker asking for this. Its approach — matching both the original and separator-normalized path against every pattern — is a small, deliberate correctness fix rather than a novel technique, and the implementation otherwise relies entirely on Python’s standard fnmatch and re modules rather than any custom matching engine.