New exclude_docs config: gitignore-like patterns of files to exclude

[oprypin]

These files will not be picked up into the Files collection and as such, also the final built site.

Also adds the ability to un-ignore the files that MkDocs forcibly ignores.

• Closes Hidden files/directories #2139
• Closes Is there a way that I can exclude certain folders to not render on static site #2316
• Closes Files in a directory called templates are ignored #2185
• Closes Disable navigation warning #1888
• Closes Allow readme.md and index.md files  #3110

[oprypin]

I'm wondering, maybe for the sake of plugins it would be better to keep these files in the files collection but then only exclude them from being copied to the destination.

[oprypin]

Yet another idea I just had- for the sake of writing drafts, these pages would still be shown in mkdocs serve (perhaps with a forcibly inserted message about that on the page) but then excluded from build

[pawamoy]

That would be really useful indeed. I wonder if the corresponding nav entry for a given excluded file/page should also be removed when building, because when I write something for my blog I have to comment/uncomment the post in the nav until it's ready.

[oprypin]

I have made the changes from both ideas that I described.

See docs in the diff.

If people could try out this code and see if it satisfies their wishes, that would be nice.

pip install git+https://github.com/mkdocs/mkdocs.git@refs/pull/3224/head

---

There's also the rather ugly matter of injecting raw HTML:

mkdocs/mkdocs/commands/build.py

Lines 218 to 223 in 89f15d9

	if excluded:
	page.content = (
	'<div class="mkdocs-draft-marker" title="This page will not be included into the built site.">'
	'DRAFT'
	'</div>' + (page.content or '')
	)

The good thing is that all existing themes will support this out of the box (and still will be able to customize this if desired).
The bad things are kinda clear, and also it's not even translated. But how to do that it if translations are only supported for themes?

If you have better ideas how to achieve this, do let me know.

[pawamoy]

Seems to be working fine, thanks @oprypin 🙂
I'd still love not to have to comment items in the nav while they're being worked on, though this is probably another feature and could be implemented in a plugin.

What's the reason for multiline strings instead of arrays for the config settings?

[oprypin]

What's the reason for multiline strings instead of arrays for the config settings?

• Special characters such as !\*? are involved, this way we're avoiding weird YAML behavior.
• A text block is the original way to specify a gitignore file. I might add a feature to paste an external text file into mkdocs.yml, and with this approach it will fit perfectly.

[oprypin]

I'd still love not to have to comment items in the nav while they're being worked on, though this is probably another feature and could be implemented in a plugin.

If someone adds a doc to the nav but the doc will be excluded, I suspect that more people would find behavior [1] more intuitive, not sure why you prefer [2].

1. Warn that an excluded file is being added to the nav, something should be done.
2. Silently obliterate the file also from the nav.

Imagine a situation where someone already has a wide exclude pattern but then forgets about it and really tries to add a file but nothing is happening (and they can even overlook this and push the site).

@pawamoy Could you provide arguments for your case?

[pawamoy]

Could you provide arguments for your case?

Hmmm I think my main argument would be that such a feature would allow me to exclude a file and remove the corresponding nav entry automatically, until I'm ready to publish it, and in which case I either move the file around or stop excluding it. In short: exclude it once when you start working on it, re-include it once when you're ready. Without such a feature, I constantly have to comment/uncomment the nav entry in mkdocs.yml, at least if I publish other things while working on the draft. This is annoying but not critical. It's probably possible to write a plugin that does that.

[oprypin]

Hmm but you could just not add it to the nav until it's ready?

And what about my counterargument?

[pawamoy]

Hmm but you could just not add it to the nav until it's ready?

Yeah true, I guess I'm lazy and don't want to type the URL myself instead of clicking 🤔
Your counter argument is a good one, silently doing things will be create confusion.

I remember Jekyll had some first-class support for drafts. I'll check again how it works to see if there's something we can improve in MkDocs 🙂

[oprypin]

Yeah true, I guess I'm lazy and don't want to type the URL myself instead of clicking 🤔

Hmm that gives me an idea

mkdocs/mkdocs/commands/build.py

Lines 314 to 316 in 89f15d9

	"The following pages are being built only for the preview "
	"but will be excluded from `mkdocs build` per `exclude_docs`:\n - "
	+ "\n - ".join(excluded)

what if this message would proactively print the localhost URLs of the pages 😃 rather than just the path

[pawamoy]

That would be nice yes :)