Using mkdocs-awesome-pages-plugin with material-mkdocs (insiders) blog plugin

[boozedog]

Hey there, I was hoping to use awesome-pages but I have the blog feature of material-mkdocs (insiders) enabled. Sadly there is a conflict which leads to the error:

ERROR    -  Blog root 'blog/index.md' not in navigation.

On the other repo, a user has shared some modified awesome-pages code to resolve this, but it doesn't look like he submitted a PR for it ... would you consider using his code as basis for a fix so we can use the blog feature with mkdocs-awesome-pages-plugin?

His code can be found in the discussion here: https://github.com/squidfunk/mkdocs-material/discussions/5132#discussioncomment-5339477

[polymorcodeus]

I've added my commits to a branch here: https://github.com/polymorcodeus/mkdocs-awesome-pages-plugin/tree/adding-support-for-material-blog

However all? of the pytests fail with a variation of ImportError: cannot import name 'MkDocsConfig' from 'mkdocs.config.defaults' And unfortunately - we are now outside the realm of my python knowledge.

[lukasgeiter]

As long as the blog feature isn't publicly available, I can't reproduce the issue. Of course I would consider a PR.

@polymorcodeus MkDocsConfig was probably added after version 1.2.3 (which is currently pinned in this repo)

[kamilkrzyskow]

@polymorcodeus In Python there are type hints, unlike TypeScript they're not mandatory and they're not used everywhere in this code base. If you're still keen on using it then you should be able to use base.Config as MkDocsConfig inherits from it. I think it will be the same with MkDocsNavigation and Navigation

I also don't have access to Insiders, so it's hard to tell if this is the proper way of doing it, as in using modified internals of MkDocs to make this plugin work with Material's built-in blog plugin.

Before my PR to fix the social plugin got accepted I just monkey patched it with a hook. I've read the discussion linked above and I see that Material's author is reluctant to make changes to his plugin until a wider public can use it. However, I myself would try to first fix the issue there, before changing this plugin.

[polymorcodeus]

No dramas on my end - I had made a private fork of this to be able to go live with the Blog plug-in and still be able to use the features that I wanted here. I'll leave it to others to decide which direction to go. :)

Just figured I'd try and help out if anyone else needed the "quick fix."

[boozedog]

No dramas on my end - I had made a private fork of this to be able to go live with the Blog plug-in and still be able to use the features that I wanted here. I'll leave it to others to decide which direction to go. :)

Just figured I'd try and help out if anyone else needed the "quick fix."

@polymorcodeus any chance you'd be willing to make your fork public :smile:

[polymorcodeus]

Should be public: https://github.com/polymorcodeus/mkdocs-awesome-pages-plugin/tree/adding-support-for-material-blog

[GJCav]

As long as the blog feature isn't publicly available, I can't reproduce the issue. Of course I would consider a PR.

@polymorcodeus MkDocsConfig was probably added after version 1.2.3 (which is currently pinned in this repo)

Now blog plugin is public in material-mkdocs 9.2.0b0. So, it is appreciated if awesome-pages-plugin solves the conflict.

[lukasgeiter]

Thanks, I'm able to reproduce the issue. There seems to be a PR on the insiders repo: https://github.com/squidfunk/mkdocs-material-insiders/pull/64. Can someone with access tell me if that resolves the issue?

[squidfunk]

Jup, the linked PR solves the issue, but it's currently no mergeable as it needs some cleanup before.

I'm currently quite busy with refactoring everything that's going into 9.2.0, and rework our plugin documentation. I also expect that we hit a few bumps after 9.2.0 is out since a much broader audience will start using the plugin, as it is a pretty big and fundamental change that we ship (thanks to our amazing sponsors). I'll revisit the PR as soon as the dust settles, and I guarantee that this functionality will be added, so it'll work with this plugin as well.

Please give us some more time. In case you need it now, a similar fix was already published by the awesome @polymorcodeus in https://github.com/squidfunk/mkdocs-material/discussions/5132#discussioncomment-5339477.

I've read the discussion linked above and I see that Material's author is reluctant to make changes to his plugin until a wider public can use it.

@kamilkrzyskow Could you please tell me where you felt I was "reluctant"? I try to chose my words wisely and nicely, but I might have been in a hurry and haven't made my decision clear enough. To clarify again: I didn't say no, it's just a matter of priorities. You know, Material for MkDocs is a project used by thousands of companies and users. In fact, an expected number of 15m unique users look at websites built with Material for MkDocs every month. I'm trying to make it better everyday, and I understand that from a user perspective, the problem you are currently experiencing for you is the most important, but unfortunately, we have to prioritize. Thank you very much for your understanding and help.

[kamilkrzyskow]

@squidfunk I'm not sure where I felt you were reluctant, it's been 2 months since that time, could be also just my imagination. I've read over it again, and found this https://github.com/squidfunk/mkdocs-material/discussions/5132#discussioncomment-5196669

I'm not sure if this is of benefit to many users, so I think our time is better invested in other features [...] I believe that this plugin should solve the issue at hand.

"this plugin", as I understand it, referred to awesome-pages.

I guess, I simply used the word "reluctant" to describe you prioritizing other things and postponing working on this feature, and also not being sure if it's the responsibility of the Blog plugin or the awesome-pages plugin to handle this error 😅 I surely didn't use the word to imply that you don't want to deal with this issue at all. However, after checking the dictionary, I see that "hesitant" could have been a better word to choose at that time or maybe the sentence should be written in a completely different tone 🤔.

Sorry for any confusion I caused ✌️

[squidfunk]

As an update: we're close to finishing a ground-up rewrite of the blog plugin, which removes all of the current limitations and improves interop with third party plugins like awesome pages and friends. I'm sorry this took some time and made so many people upset, but I think the result is a very mature implementation which allows us to take blogging to the next level.

For updates, please follow https://github.com/squidfunk/mkdocs-material/issues/5686

[squidfunk]

Material for MkDocs 9.2.0 was just released! It should now work with awesome pages and other plugins that allow for dynamic management of navigation. If you encounter errors, please create an bug report in our repository with a minimal reproduction and we're more than happy to fix it. I think this issue can be considered resolved.