Mkdocs: Add configuration option to ignore files/paths

[pixelbrackets]

»mkdocs« converts all Markdown files to HTML and then copies all other files, except dot files and directories, into the build directory (according to my own tests and https://github.com/mkdocs/mkdocs/issues/1488#issuecomment-389519974).

Is it possible to customize or append something to the ignore pattern?

Use case:

• Project X has docs in the root directory (readme, changelog, contribution guide, etc.) - mkdocs then copies all source files into the build folder as well. Would be better to be able to ignore a src and test folder etc.

• Project Y has to build two versions of the same documentation - one complete (eg. extended support), one with some files missing (eg. communuty edition).

Of course it is possible in both cases to remove the desired files after mkdocs completes the conversion. Depending on the size of the repository this may waste resources, which may be saved when then files are not precessed in the first place due to a »ignore« option.

[waylan]

I'm closing this as a duplicate of #1152. While different reasons and arguments are cited, the request is essentially the same: provide a way to "exclude" files in the docs_dir. As stated in #1152:

There is no "exclude" of any kind. It was never anticipated that non-documentation would be in the docs_dir...

Of course, this request is not asking for non-documentation files to be excluded, but for documentation files to be excluded. To that I would say: then don't include them in the docs_dir. However, the use case in the instant request seems to stem from a desire to reuse the same base set of files to build multiple different sites with a different subset of files in each site. In theory, that should already be possible with symbolic links today (perhaps excluding Windows users). The idea is that you could create your master documents in one directory, and then in various other directories create subsets of links to the documents in the master, so that each docs_dir only contains the files relevant for that specific "site."

As an aside, I am currently working on the pages refactor which completely reworks the way documents are discovered and represented internally. I expect that when that is done (next release), it will be easy for a third party plugin to add an exclude option. It should also be be easier for a plugin to "include" files which are not actually in the docs_dir. Therefore, there should be multiple different ways to address these sorts of use cases, all of which are likely to be more flexible than any feature we could add directly to MkDocs.

[pixelbrackets]

Sidenote: The mentioned refactoring is complete.

A plugin would have to listen to the »on_files« event:

on_files
The files event is called after the files collection is populated from the docs_dir. Use this event to add, remove, or alter files in the collection. Note that Page objects have not yet been associated with the file objects in the collection. Use Page Events to manipulate page specific data.
https://www.mkdocs.org/user-guide/plugins/#on_files

[apenwarr]

I created a mkdocs-exclude plugin that uses the new plugin API to do what's requested in this bug:
https://github.com/apenwarr/mkdocs-exclude

Hope this helps!

[nigelwelham]

Hi - is there any way to filter out the mkdocs build warning of included files that are not explicitly defined in the yaml nav: section. It seems a little unintuitive - or have I missed something?

[waylan]

@nigelwelham, those are not warnings, but "info" messages (a warning would cause --strict mode to fail). As such, filtering them out would also filter out all other "info" level messages, which would effectively be "quit" mode. We do not currently have a "quiet" mode, but any discussion about that should be a separate issue.