mkdocs-file-filter-plugin 0.0.1

A MkDocs plugin that lets you exclude/include docs files using globs, regexes and gitignore-style file.

File exclude/include plugin for MkDocs

---

mkdocs-file-filter is a mkdocs plugin that allows you to exclude/include files from your input using Unix-style wildcards (globs), regular expressions (regexes) or .mkdocsignore file (gitignore-style syntax).

Quick start

1. Install the plugin using pip.

pip install mkdocs-file-filter-plugin

1. In your project, add a plugin configuration to mkdocs.yml:

plugins:
  - file-filter:
      mkdocsignore: true
      mkdocsignore_file: 'custom/path/.mkdocsignore' # relative to mkdocs.yml
      exclude_glob:
        - 'exclude/this/path/*'
        - 'exclude/this/file/draft.md'
        - '*.tmp'
        - '*.gz'
      exclude_regex:
        - '.*\.(tmp|bin|tar)$'
      include_glob:
        - 'include/this/path/*'
        - 'include/this/file/Code-of-Conduct.md'
        - '*.png'
        - 'assets/**' # the material theme requires this folder
      include_regex:
        - '.*\.(js|css)$'

External config file

The plugin supports external files for the plugin configuration. If the external config file is specified, then *_glob: and *_regex: are not taken mkdocs.yml - only config from the external file applies.

plugins:
  - file-filter:
      # config: !ENV [MY_FILE_FILTER_CONFIG, 'mkdocs.file-filter.yml']
      config: mkdocs.file-filter.yml

External plugin config file example.

mkdocsignore: false
exclude_glob:
  - 'exclude/this/path/*'
  - 'exclude/this/file/draft.md'
  - '*.tmp'
  - '*.gz'
exclude_regex:
  - '.*\.(tmp|bin|tar)$'
include_glob:
  - 'include/this/path/*'
  - 'include/this/file/Code-of-Conduct.md'
  - '*.png'
  - 'assets/**' # the material theme requires this folder
include_regex:
  - '.*\.(js|css)$'

HINT

For external file config, you can use MkDocs Environment Variables to set the desired file dynamically. A useful case for serving the site with different content based on stage/environment. Works well with CI/CD automation.

.mkdocsignore

Setting mkdocsignore to true will exclude the dirs/files specified in the .mkdocsignore. Use the same syntax as you use for gitignore.

Optionally you can set mkdocsignore_file parameter with your path to .mkdocsignore file. By default, the plugin uses .mkdocsignore from the root of your MkDocs.

You can combine mkdocsignore with globs/regex as well. The patterns from both will apply.

External config for mkdocsignore.

plugins:
  - file-filter:
      mkdocsignore: true # default: false
      mkdocsignore_file: 'custom/path/.myignore' # relative to mkdocs.yml, default: .mkdocsignore

Example .mkdocsignore file.

# MkDocs
docs/test/**
docs/**/draft-*.md

Conflict behavior

It is possible to exclude and include will have conflict. For example, you could exclude drafts/* but include *.md. In that case, include has higher priority over exclude. So all *.md files from the drafts folder will be included.

Some useful stuff

If you do not provide patterns, everything will stay the same - standard MkDocs behavior.

Because of the YAML syntax specifics, patterns that start with a punctuation mark must be quoted.

The preferred way for quotes is to use single quotes ' rather than double quotes " - regex backslash escapes are preserved correctly without being doubled up.

License

mkdocs-file-filter-plugin is distributed under the terms of the MIT license.