mkdocs-file-filter-plugin
Advanced tools
A MkDocs plugin that lets you exclude/include docs files using globs, regexes, gitignore-style file and Markdown/Frontmatter tags metadata.
❗ This plugin is under early Alpha stage. Significant changes may occur. It may not yet be fully compatible with other MkDocs configurations and thus may break with some advanced configs. Once these have been resolved and all bugs have been ironed out, it will be moved to an upper stage.
mkdocs-file-filter-plugin is a mkdocs plugin that allows you to exclude/include files using Unix-style wildcards (globs), regular expressions (regexes), .mkdocsignore (gitignore-style file) or Markdown/FrontMatter tags metadata.
This package requires Python >=3.8 and MkDocs version 1.4.0 or higher.
Install the plugin using pip:
pip install mkdocs-file-filter-plugin
Or include it in a requirements.txt file in your project:
mkdocs==1.4.*
mkdocs-file-filter-plugin
and run
pip install -r requirements.txt
Install the plugin using Poetry:
poetry add mkdocs-file-filter-plugin
Add a plugin configuration to mkdocs.yml - below example contains only example, to adjust config for your needs read Usage section:
# mkdocs.yml
plugins:
- search # if you include another plugin, and want search you have to add it again
- file-filter:
filter_nav: true # default value
exclude_glob:
- 'exclude/this/path/**'
- 'exclude/this/file/draft.md'
- '*.tmp'
exclude_regex:
- '.*\.(tmp|bin|tar)$'
exclude_tag:
- draft
- preview
include_glob:
- 'include/this/path/**'
- 'include/this/file/Code-of-Conduct.md'
- '*.png'
- 'assets/**' # the material theme requires this folder
include_regex:
- '.*\.(js|css)$'
include_tag:
- released
⚠️ NOTE
If you have no
pluginsentry in your config file yet, you'll likely also want to add thesearchplugin. MkDocs enables it by default if there is nopluginsentry set, but now you have to enable it explicitly.More information about plugins in the MkDocs documentation.
The plugin supports external files for the plugin configuration. If the external config file is specified, then plugin's config properties from mkdocs.yml are overwritten.
# mkdocs.yml
plugins:
- search # if you include another plugin, and want search you have to add it again
- file-filter:
config: !ENV [MY_FILE_FILTER_CONFIG, '.file-filter.yml']
# config: path/to/config/file/.file-filter.yml
💡 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/etc. Works well with CI/CD automation.
External plugin config file example:
# .file-filter.yml
enabled: !ENV [CI, true]
enabled_on_serve: true
filter_nav: true
mkdocsignore: false
exclude_glob:
- 'exclude/this/path/*'
- 'exclude/this/file/draft.md'
- '*.tmp'
exclude_regex:
- '.*\.(tmp|bin|tar)$'
exclude_tag:
- draft
include_glob:
- 'include/this/path/*'
- 'include/this/file/Code-of-Conduct.md'
- '*.png'
- 'assets/**' # the material theme requires this folder
include_regex:
- '.*\.(js|css)$'
include_tag:
- prod
⚠️ NOTE
External config uses exactly the same properties as plugin's config in the
mkdocs.ymlexceptconfigproperty.External config support MkDocs Environment Variables as well.
The below table shows all supported options by the plugin.
| Option | Type | Default | Description |
|---|---|---|---|
config | string | none | Path to external plugin's configuration file |
enabled | bool | true | Turn on/off plugin without removing/adding plugin's config from mkdocs.yml |
enabled_on_serve | bool | true | Turn on/off plugin on serve command |
only_doc_pages | bool | false | Filtering limited only to the documentation pages (markdown files), the rest included by default. |
filter_nav | bool | true | Remove nav items pointed to excluded files |
mkdocsignore | bool | false | Use gitignore-style file for patterns |
mkdocsignore_file | string | .mkdocsignore | Path to gitignore-style file with patterns |
metadata_property | string | tags | What Markdown/FrontMatter metadata property list will be used for checking keywords |
exclude_tag | [string] | none | List of excluded tags |
include_tag | [string] | none | List of included tags |
exclude_glob | [string] | none | Exclude glob patterns |
include_glob | [string] | none | Include glob patterns |
exclude_regex | [string] | none | Exclude regex patterns |
include_regex | [string] | none | Include regex patterns |
⚠️ NOTE
If you do not provide patterns, everything will stay the same - standard MkDocs behavior - include all.
Because of the YAML syntax specifics, glob/regex 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.You can combine all patterns - globs/regexes with tags, and mkdocsignore.
# mkdocs.yml
plugins:
- file-filter:
filter_nav: true # default value
exclude_glob:
- 'drafts/**'
include_glob:
- 'drafts/**/preview-*.md'
RESULT: exclude all content from drafts and related subdirectories, but include all markdown files with prefix starting preview from drafts and related subdirectories.
⚠️ NOTE
Glob patterns relative to your docs_dir setting from
mkdocs.yml
# mkdocs.yml
plugins:
- file-filter:
filter_nav: true # default value
exclude_regex:
- '.*\.(tmp|bin|tar)$'
include_regex:
- '.*\.(js|css)$'
RESULT: exclude all files with tmp, bin or tar extension and include all files with js, or css extension.
⚠️ NOTE
Regex patterns relative to your docs_dir setting from
mkdocs.yml
You can filter your content based on the Markdown metadata (often called front-matter) keywords.
By default plugin filter files using tags property of your Markdown metadata.
# mkdocs.yml
plugins:
- file-filter:
filter_nav: true # default value
exclude_tag:
- abc
- draft
- alpha
include_tag:
- foo
- release
- beta
fileA.md metadata example:
<!-- fileA.md -->
---
tags:
- foo
- bar
---
# Markdown with tags metadata
Lorem ipsum dolor sit amet...
fileB.md metadata example:
<!-- fileB.md -->
---
tags:
- abc
- xyz
---
# Markdown with tags metadata
Lorem ipsum dolor sit amet...
RESULT: only fileA.md will be included.
Because the tags property is very often used to render tags on the site, in some scenarios, you'd like to filter files using specific tag keywords and avoid rendering them. In that case, you can create a custom metadata list and use it for filtering without affecting tags' used for rendering.
Set metadata_property with your custom list property, e.g., labels for this example.
# mkdocs.yml
plugins:
- file-filter:
filter_nav: true # default value
metadata_property: labels
exclude_tag:
- foo
- draft
- alpha
include_tag:
- xyz
- release
- beta
fileA.md metadata example:
<!-- fileA.md -->
---
tags:
- foo
- bar
labels:
- draft
- internal
---
# Markdown with metadata - tags and custom list
Lorem ipsum dolor sit amet...
fileB.md metadata example:
<!-- fileB.md -->
---
tags:
- foo
- bar
labels:
- release
- v1
---
# Markdown with metadata - tags and custom list
Lorem ipsum dolor sit amet...
RESULT: only fileB.md will be included.
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.
Example config for mkdocsignore.
# mkdocs.yml
plugins:
- file-filter:
filter_nav: true # default value
mkdocsignore: true # default: false
mkdocsignore_file: 'custom/path/.mkdocsignore' # optional, relative to mkdocs.yml, default: .mkdocsignore
Example .mkdocsignore file.
# MkDocs
docs/test/**
docs/**/draft-*.md
RESULT: exclude all content from docs/test and related subdirectories and all markdown files with prefix starting draft from docs and related subdirectories.
⚠️ NOTE
.mkdocsignore patterns relative to your root.
Suppose you customized MkDocs navigation configuration, and your nav contains elements defined in exclude patterns. In that case, the default MkDocs behavior is to render navigation to a non-existing file, and generated site gives 404.
By default, the plugin filters those cases and removes not working navigation items.
You can control the plugin's behavior to explicitly disable that option by setting filter_nav: false.
Example mkdocs.yml config.
# mkdocs.yml
nav:
- Foo: exclude/this/path
- Bar: exclude/this/file/draft.md
- Abc:
- About: exclude/this/path/about.md
- Contact: include/this/file/contact.md
- Xyz: path/xyz.md
plugins:
- file-filter:
filter_nav: true # default value
exclude_glob:
- 'exclude/this/path/**'
- 'exclude/this/file/draft.md'
Nav results with filter_nav: false:
- Foo: exclude/this/path # -> 404
- Bar: exclude/this/file/draft.md # -> 404
- Abc:
- About: exclude/this/path/about.md # -> 404
- Contact: include/this/file/contact.md
- Xyz: path/xyz.md
Nav results with filter_nav: true:
- Abc:
- Contact: include/this/file/contact.md
- Xyz: path/xyz.md
⚠️ NOTE
If you use any other 3rd-party plugins that modify navigation (e.g., mkdocs-awesome-pages-plugin) - first, test and evaluate expected behavior. Plugin configuration order may impact results.
In most cases is recommended to transform navigation first and next filter with the file-filter plugin.
By default, the plugin analyzes all files required to build a site. It includes the theme and all files inside docs like jpg, png, etc. By setting the only_doc_pages option to true, the plugin will only analyze and applies rules to documentation pages (markdown files). All rules that apply to non-documentation pages, such as regexes or globs with patterns related to jpg, png, tmp, css, etc, will be omitted.
Example mkdocs.yml config.
# mkdocs.yml
plugins:
- file-filter:
only_doc_pages: true # default value is false
exclude_regex:
- '.*\.md$'
include_tag:
- released
RESULT: Include only markdown files with the meta-data tag released and all theme and other files under the docs folder like images, etc.
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.
This plugin has been tested with Material for MkDocs theme, and two 3rd party plugins that nicely complement each other.
mkdocs.ymlExample mkdocs.yml config with the proper order of plugins.
# mkdocs.yml
plugins:
- search
- awesome-pages #before file-filter
# awesome-pages config
- file-filter:
only_doc_pages: true
mkdocsignore: true
exclude_glob:
- "**/draft-*.md"
- "**/preview-*.md"
include_regex:
- "tags.md"
include_tag:
- released
- public preview
exclude_tag:
- draft
- mkdocs_exclude_unused_files #after file-filter
# exclude-unused-files config
mkdocs-file-filter-plugin is distributed under the terms of the MIT license.
FAQs
A MkDocs plugin that lets you exclude/include docs files using globs, regexes, gitignore-style file and Markdown/Frontmatter tags metadata.
We found that mkdocs-file-filter-plugin demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.