Blog: Multiple post_dirs support?

[stratself]

Hello,

I'd like to setup an MkDocs blog that gather posts from /articles and /notes and collate them into the main page /. My directory tree is as below:

.
├── docs
│   ├── articles
│   │   ├── an-article.md
│   │   └── another-article.md
│   ├── index.md
│   ├── notes
│   │   ├── a-note.md
│   │   └── another-note.md
│   └── other-docs
│       └── not-a-blogpost.md
└── mkdocs.yml

AFAIK, this is not possible because post_dir only accepts one string value. Is that true? And are there any workarounds to enable 2 post_dirs, 1 blog scenario?

My use case is that I'd like to keep /articles and /notes in separate folders on my FS for archival/backup purposes. Thanks in advance

[alexvoss]

You can create the directories within the post_dir. The directory structure inside is effectively ignored because blog posts get their URL through the date and slug (which defaults to a slugified version of the header via a slugify function).

[alexvoss]

You can also create multiple instances of the blog plugin with different settings, though I guess this would also not give you exactly what you want. Hope one or the other compromise will work for you.

[kamilkrzyskow]

Though I'd like to keep the directory structure as-is. If I specify post_dir: . however, I'd include the unwanted not-a-blogpost.md page.

The blog by default expects a blog_dir to separate it from non-blog pages, setting blog_dir: . assumes that everything will be a blog post. Now you're trying to "exclude" a page 🤔.

I understand that URLs are its own customizable thing, so I'm not touching them. However if there are multiple post dirs, each dir can benefit from having a custom "default" slug, categories, etc

The current logic is that directories inside post_dir are ignored, and they're not taken into consideration when creating slugs.
This way of separation of concerns allows to input any structure of files under post_dir and don't worry about the output URL as it will be normalized according to the other settings.

The settings set on the pages specify their URL, so a page has to define the categories, creation date etc.

Now you'd like to use different post_dir as a way to manage the URLs and separate the categories that way?
I think your approach is simply incompatible, as the url_format doesn't specify directory structure to select.

There are other blog plugins in the MkDocs ecosystem, so perhaps they would offer that functionality.
https://github.com/mkdocs/catalog

[stratself]

Hi all,

Thanks for clarifying how the URL scheme works again. Knowing this, I've tried the following:

• Moving articles/ and notes/ into a common folder posts/
• Using the meta plugin, I created .meta.yml files with categories matching the folder names

docs/posts/
├── articles
│   ├── .meta.yml <<< categories: [ articles ]
│   ├── an-article.md
│   └── another-article.md
└── notes
    ├── .meta.yml
    └── a-note.md <<< categories: [ notes ]

Then, I configured mkdocs.yml plugins as below

plugins:
  - blog:
      blog_dir: .
      post_dir: posts
      post_url_format: "{categories}/{slug}"
      categories_url_format: "{slug}"
      archive: false
  - meta

The result is that /articles and /notes are now valid paths which are actually generated category pages. They too can show up in the normal navigation with nav:

nav:
  - index.md
  - Articles: articles
  - Notes: notes

Pic of navigation

My only issue with this is that I can't get rid of the Categories section on nav (or can I?). Furthermore in posts with multiple categories, this fully depends on - meta categories being rendered before frontmatter categories, as the slugify function takes the first one. I might try again using tags or writing my own slug function.

---

This is basically just an elaborated hack, as all of you have said, it's not a perfect solution with lots of compromises, but I'm documenting here in case someone may find it useful and can extend it some way. To be honest my main motivation for multiple post_dirs is because I'm looking for some kind of multi-section feature in a blog plugin. To which I say...

There are other blog plugins in the MkDocs ecosystem, so perhaps they would offer that functionality.
https://github.com/mkdocs/catalog

Finally, thanks for this. I'll have a look at them too

[kamilkrzyskow]

My only issue with this is that I can't get rid of the Categories section on nav (or can I?)

Hmm first idea is to add a monkey patch, and overwrite the function in the plugin 🤔

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

Lines 203 to 210 in 8b94981

	# 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)

This part which adds the Section would have to be removed

[
EDIT2: You could look at the plugin I wrote for the mkdocs-nype theme, which adds a custom categorization and does a similar monkey patch:

• Ways to extend the Material theme (Nype SAP) #8223

]

---

EDIT: Also good work on the hack 👍 Such customization is expected in this case, good to see an example of meta plugin usage.
Thanks for sharing.

[stratself]

From your hints, I basically got this hooks.py to remove the Categories section. The event priority needs to be lower than that of the blog plugin's on_nav():

from mkdocs.plugins import event_priority
@event_priority(-51) # anything below -50
def on_nav(nav, *, config, files):
    # could've also been a one-liner list comprehension
    for item in nav.items:
        if item.is_section and item.title == "Categories":
            categoriesSection = item
    nav.items = nav.items.remove(categoriesSection)
    return nav

It's rudimentary, but this monkeypatch is pretty good for me now

[stratself]

I found mkdocs-blogging-plugin to work with multiple dirs, and allow putting the blog list/category-specific list in any page with the {{ blog_content <category-name> }} directive.

In that plugin, categories are defined per-directory and the frontmatter-declared categories seems to not matter. So for more organizations tags shall be used.

To demonstrate, I'll use the following tree:

docs/
├── articles
│   ├── an-article.md
│   └── another-article.md
├── foo
│   └── notes
│       └── a-note.md
├── nonblog
│   ├── not-a-blogpost.md
├── index.md <<< {{ blog_content }}
├── articles.md <<< {{ blog_content articles }}
└── notes.md <<< {{ blog_content notes }}

And the following mkdocs.yml:

plugins:
  - blogging:
      dirs:
        - foo/notes
        - articles
      categories:
        - name: notes
          dirs:
            - foo/notes
        - name: articles
          dirs:
            - articles

Now both /notes(.md) and /articles(.md) shows the category-specific posts which are also represented with a filesystem-similar URL (e.g. /foo/notes/a-note).

While I need further testing (esp. with compliance to rss) before deciding on it, I'll mark this as an answer anyhow. Anyone please feel free to suggest any other solutions :)