Package: mkdocs-file-filter-plugin
MkDocs File Filter Plugin❗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-pluginis amkdocs pluginthat allows you to exclude/include files using Unix-style wildcards (globs), regular expressions (regexes),.mkdocsignore(gitignore-stylefile) or Markdown/FrontMattertagsmetadata.InstallationpipPoetryConfigurationBasicExternal configOptionsUsageGlobsRegexesTagsTags metadata propertyCustom metadata list.mkdocsignoreNavigation filteringFilter only documentation pagesConflict behavior3rd party plugins compatibilityLicenseInstallationThis package requires Python >=3.8 and MkDocs version 1.4.0 or higher.pipInstall the plugin usingpip:pip install mkdocs-file-filter-pluginOr include it in arequirements.txtfile in your project:mkdocs==1.4.*mkdocs-file-filter-pluginand runpip install -r requirements.txtPoetryInstall the plugin usingPoetry:poetry add mkdocs-file-filter-pluginConfigurationBasicAdd a plugin configuration tomkdocs.yml- below example contains only example, to adjust config for your needs readUsagesection:# mkdocs.ymlplugins:-search# if you include another plugin, and want search you have to add it again-file-filter:filter_nav:true# default valueexclude_glob:-'exclude/this/path/**'-'exclude/this/file/draft.md'-'*.tmp'exclude_regex:-'.*\.(tmp|bin|tar)$'exclude_tag:-draft-previewinclude_glob:-'include/this/path/**'-'include/this/file/Code-of-Conduct.md'-'*.png'-'assets/**'# the material theme requires this folderinclude_regex:-'.*\.(js|css)$'include_tag:-released⚠️NOTEIf you have nopluginsentry 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 theMkDocs documentation.External configThe plugin supports external files for the plugin configuration. If the external config file is specified, then plugin's config properties frommkdocs.ymlare overwritten.# mkdocs.ymlplugins:-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💡HINTFor external file config, you can useMkDocs Environment Variablesto 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.ymlenabled:!ENV[CI,true]enabled_on_serve:truefilter_nav:truemkdocsignore:falseexclude_glob:-'exclude/this/path/*'-'exclude/this/file/draft.md'-'*.tmp'exclude_regex:-'.*\.(tmp|bin|tar)$'exclude_tag:-draftinclude_glob:-'include/this/path/*'-'include/this/file/Code-of-Conduct.md'-'*.png'-'assets/**'# the material theme requires this folderinclude_regex:-'.*\.(js|css)$'include_tag:-prod⚠️NOTEExternal config uses exactly the same properties as plugin's config in themkdocs.ymlexceptconfigproperty.External config supportMkDocs Environment Variablesas well.OptionsThe below table shows all supported options by the plugin.OptionTypeDefaultDescriptionconfigstringnonePath to external plugin's configuration fileenabledbooltrueTurn on/off plugin without removing/adding plugin's config frommkdocs.ymlenabled_on_servebooltrueTurn on/off plugin onservecommandonly_doc_pagesboolfalseFiltering limited only to the documentation pages (markdown files), the rest included by default.filter_navbooltrueRemovenavitems pointed to excluded filesmkdocsignoreboolfalseUse gitignore-style file for patternsmkdocsignore_filestring.mkdocsignorePath to gitignore-style file with patternsmetadata_propertystringtagsWhat Markdown/FrontMatter metadata property list will be used for checking keywordsexclude_tag[string]noneList of excluded tagsinclude_tag[string]noneList of included tagsexclude_glob[string]noneExclude glob patternsinclude_glob[string]noneInclude glob patternsexclude_regex[string]noneExclude regex patternsinclude_regex[string]noneInclude regex patternsUsage⚠️NOTEIf 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.Globs# mkdocs.ymlplugins:-file-filter:filter_nav:true# default valueexclude_glob:-'drafts/**'include_glob:-'drafts/**/preview-*.md'RESULT:exclude all content fromdraftsand related subdirectories, but include all markdown files with prefix startingpreviewfromdraftsand related subdirectories.⚠️NOTEGlobpatterns relative to yourdocs_dirsetting frommkdocs.ymlRegexes# mkdocs.ymlplugins:-file-filter:filter_nav:true# default valueexclude_regex:-'.*\.(tmp|bin|tar)$'include_regex:-'.*\.(js|css)$'RESULT:exclude all files withtmp,binortarextension and include all files withjs, orcssextension.⚠️NOTERegexpatterns relative to yourdocs_dirsetting frommkdocs.ymlTagsYou can filter your content based on theMarkdown metadata(often called front-matter) keywords.Tags metadata propertyBy default plugin filter files usingtagsproperty of your Markdown metadata.# mkdocs.ymlplugins:-file-filter:filter_nav:true# default valueexclude_tag:-abc-draft-alphainclude_tag:-foo-release-betafileA.mdmetadata example:<!-- fileA.md -->---tags:-foo- bar---# Markdown with tags metadataLorem ipsum dolor sit amet...fileB.mdmetadata example:<!-- fileB.md -->---tags:-abc- xyz---# Markdown with tags metadataLorem ipsum dolor sit amet...RESULT:onlyfileA.mdwill be included.Custom metadata listBecause thetagsproperty 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.Setmetadata_propertywith your custom list property, e.g.,labelsfor this example.# mkdocs.ymlplugins:-file-filter:filter_nav:true# default valuemetadata_property:labelsexclude_tag:-foo-draft-alphainclude_tag:-xyz-release-betafileA.mdmetadata example:<!-- fileA.md -->---tags:-foo-bar
labels:-draft- internal---# Markdown with metadata - tags and custom listLorem ipsum dolor sit amet...fileB.mdmetadata example:<!-- fileB.md -->---tags:-foo-bar
labels:-release- v1---# Markdown with metadata - tags and custom listLorem ipsum dolor sit amet...RESULT:onlyfileB.mdwill be included..mkdocsignoreSettingmkdocsignoretotruewill exclude the dirs/files specified in the.mkdocsignore. Use the same syntax as you use forgitignore.Optionally you can setmkdocsignore_fileparameter with your path to.mkdocsignorefile. By default, the plugin uses.mkdocsignorefrom the root of your MkDocs.Example config for mkdocsignore.# mkdocs.ymlplugins:-file-filter:filter_nav:true# default valuemkdocsignore:true# default: falsemkdocsignore_file:'custom/path/.mkdocsignore'# optional, relative to mkdocs.yml, default: .mkdocsignoreExample.mkdocsignorefile.# MkDocsdocs/test/**
docs/**/draft-*.mdRESULT:exclude all content fromdocs/testand related subdirectories and all markdown files with prefix startingdraftfromdocsand related subdirectories.⚠️NOTE.mkdocsignorepatterns relative to your root.Navigation filteringSuppose you customizedMkDocs navigation configuration, and yournavcontains 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 settingfilter_nav: false.Examplemkdocs.ymlconfig.# mkdocs.ymlnav:-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.mdplugins:-file-filter:filter_nav:true# default valueexclude_glob:-'exclude/this/path/**'-'exclude/this/file/draft.md'Navresultswithfilter_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.mdNavresultswithfilter_nav: true:-Abc:-Contact:include/this/file/contact.md-Xyz:path/xyz.md⚠️NOTEIf 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.Filter only documentation pagesBy 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 theonly_doc_pagesoption totrue, 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.Examplemkdocs.ymlconfig.# mkdocs.ymlplugins:-file-filter:only_doc_pages:true# default value is falseexclude_regex:-'.*\.md$'include_tag:-releasedRESULT:Include only markdown files with the meta-data tagreleasedand all theme and other files under the docs folder like images, etc.Conflict behaviorIt is possible to exclude and include will have conflict. For example, you could excludedrafts/**but include*.md. In that case,includehas higher priority over exclude. So all*.mdfiles from the drafts folder will beincluded.3rd party plugins compatibilityThis plugin has been tested withMaterial for MkDocstheme, and two 3rd party plugins that nicely complement each other.mkdocs-awesome-pages-pluginplugin allows you to customize how your pages show up in the navigation of your MkDocs without having to configure the entire structure in yourmkdocs.ymlmkdocs-exclude-unused-filescleans up mkdocs output from files that are not referenced in pages (useful to have the smaller artifact and not exposing not attached files after filtration with the file-filter).Examplemkdocs.ymlconfig with the proper order of plugins.# mkdocs.ymlplugins:-search-awesome-pages#before file-filter# awesome-pages config-file-filter:only_doc_pages:truemkdocsignore:trueexclude_glob:-"**/draft-*.md"-"**/preview-*.md"include_regex:-"tags.md"include_tag:-released-public previewexclude_tag:-draft-mkdocs_exclude_unused_files#after file-filter# exclude-unused-files configLicensemkdocs-file-filter-pluginis distributed under the terms of theMITlicense.