Exclude selected markdown files from blog

[drdv]

Is it possible for used-defined markdown files that are in blog/posts to not be parsed for inclusion in the blog? For example, I could have blog/posts/some-post/README.md that is meant only for internal documentation purposes.

[squidfunk]

It's currently not supported, and I don't think it's easy to pull off with the hacks in the blog plugin that we need to do to make it work with MkDocs. Note that we're working in the background into making all of this much, much simpler, including filtering Markdown files in blog posts, so it will be possible in the future. With the current architecture, it might be achievable by writing a custom hook that removes the file from the Files collection in on_files, but that is only a guess, so some prototyping is necessary.

I'm short on time right now, but maybe you can share your solution if you find one.

[drdv]

My current solution is to use the following tree:

[.../blog]>tree
.
├── post1-artifacts-generation-dir
├── post2-artifacts-generation-dir
└── posts
    ├── post1.md
    └── post2.md

i.e., simply move the post*-artifacts-generation-dir directories out of blog/posts. Thinking a bit about all this, probably excluding individual .md files is an overkill in my case (and it is actually inconvenient). All that's needed is to have the possibility to somehow signal to mkdocs that a given directory (and it content) is not to be processed. One approach that comes to mind is to have a "special file", e.g., .mkdocsignore which if present in a directory it is left alone. Frankly, I don't mind putting the artifact-generation dirs one level up (as long as they are in the blog) and letting the posts keep only interface .md files.

Thanks

[kamilkrzyskow]

All that's needed is to have the possibility to somehow signal to mkdocs that a given directory (and it content) is not to be processed

I'm assuming you're looking for the draft_docs setting or exclude_docs, which take a .gitignore like format to target excluded paths.

Or perhaps you want a the pages to be available remotely in the built site, but "hidden". Then there is not_in_nav + a custom hook, which would adjust the data to remove the pages from the sitemap.xml and create a robots.txt to exclude the sites from crawlers.

Something like that was implemented in the mkdocs-nype theme as part of the nype_tweaks plugin, you can extract the logic into a hook.

[squidfunk]

@kamilkrzyskow the big problem is that the blog plugin must jump through some hoops to steal the posts from MkDocs, so they are not rendered in the navigation, since blog posts should only be linked from the blog index or archive and category pages. I haven't checked whether this got any easier with MkDocs 1.6.0, since it seems to be easier to at least generate files, but I doubt it. We're working on making this much easier, but with MkDocs current architecture, there's no easy, nor canonical way to do it.

mkdocs-material/src/plugins/blog/plugin.py

Lines 171 to 208 in b368cee

	# If we're not building a standalone blog, the entrypoint will always
	# have a parent when it is included in the navigation. The parent is
	# essential to correctly resolve the location where the archive and
	# category views are attached. If the entrypoint doesn't have a parent,
	# we know that the author did not include it in the navigation, so we
	# explicitly mark it as not included.
	if not self.blog.parent and self.config.blog_dir != ".":
	self.blog.file.inclusion = InclusionLevel.NOT_IN_NAV
	# Attach posts to entrypoint without adding them to the navigation, so
	# that the entrypoint is considered to be the active page for each post
	self._attach(self.blog, [None, *reversed(self.blog.posts), None])
	for post in self.blog.posts:
	post.file.inclusion = InclusionLevel.NOT_IN_NAV
	# Revert temporary exclusion of views from navigation
	for view in self._resolve_views(self.blog):
	view.file.inclusion = self.blog.file.inclusion
	for page in view.pages:
	page.file.inclusion = self.blog.file.inclusion
	# Attach views for archive
	if self.config.archive:
	title = self._translate(self.config.archive_name, config)
	views = [_ for _ in self.blog.views if isinstance(_, Archive)]
	# Attach and link views for archive
	if self.blog.file.inclusion.is_in_nav():
	self._attach_to(self.blog, Section(title, views), nav)
	# Attach views for categories
	if self.config.categories:
	title = self._translate(self.config.categories_name, config)
	views = [_ for _ in self.blog.views if isinstance(_, Category)]
	# Attach and link views for categories, if any
	if self.blog.file.inclusion.is_in_nav() and views:
	self._attach_to(self.blog, Section(title, views), nav)

[kamilkrzyskow]

Yeah, I didn't really look into the OP issue myself, as MkDocs expects the navigation to be connected to the filesystem, so there are issues all around because of it. I mostly responded to the comment with the different approach, which puts the non-blog posts in a different directory, so they're not handled the by plugin at all. Everything that's left to do to hide them from the build is to use the draft_docs.