blog plugin breaks when trying to use 2 blog instances

[zerenxyz]

Contribution guidelines

• I've read the contribution guidelines and wholeheartedly agree

I've found a bug and checked that ...

• ... the problem doesn't occur with the mkdocs or readthedocs themes
• ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
• ... the documentation does not mention anything about my problem
• ... there are no open or closed issues that are related to my problem

Description

I am trying to create 2 blog post locations, when declaring the plugin blog with their own blog_dir it breaks giving AttributeError: 'NoneType' object has no attribute 'append'

Expected behaviour

It should work with 2 blogs running independently

Actual behaviour

I get an error when running mkdocs serve of the following:

INFO     -  Building documentation...
INFO     -  Cleaning site directory
Traceback (most recent call last):
  File "/Users/zeren/Projects/Github/two-blogs/venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/mkdocs/__main__.py", line 234, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 82, in serve
    builder(config)
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 75, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/mkdocs/commands/build.py", line 297, in build
    files = config.plugins.run_event('files', files, config=config)
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/mkdocs/plugins.py", line 517, in run_event
    result = method(item, **kwargs)
  File "/Users/zeren/Projects/Github/two-blogs/venv/lib/python3.10/site-packages/material/plugins/blog/plugin.py", line 293, in on_files
    root.append({ "__posts": list(self.post_meta_map.keys()) })
AttributeError: 'NoneType' object has no attribute 'append'

Steps to reproduce

1. pip install mkdocs material
2. pip install mkdocs material insiders
3. add theme name in mkdocs.yml
4. add blog plugin with blog_dir as "blog"
5. add another blog plugin entry with blog_dir as "tutorial"
6. Create blog/posts/ and blog/index.md
7. create tutorial/posts and tutorial/index.md
8. run mkdocs serve

Package versions

• Python: 3.10.7
• MkDocs: 1.4.1
• Material: 8.5.7+insiders.4.26.1

Configuration

site_name: My Docs
theme:
  name: material

plugins:
  - blog:
      enabled: true
      blog_dir: blog
  - blog:
      enabled: true
      blog_dir: tutorial

System information

• Operating system: macOS 12.6
• Browser: Chrome/Firefox

[squidfunk]

Thanks for reporting. Did you create blog/index.md and tutorial/index.md inside docs? This is not clear from your description. Note that the blog_dir is always relative to docs_dir, which is mentioned in the documentation:

The path must be defined relative to docs_dir.

[zerenxyz]

Sorry if it wasnt cleared, yup I have docs/blog/index.md and docs/tutorial/index.md created, each folder also has a folder called /posts/

[squidfunk]

Thanks! So first of all, your configuration is missing an integral part of the blog plugin configuration, namely where in the navigation the blog plugin should be mounted. This is explained in the documentation:

nav:
  - Blog:
    - blog/index.md
  - Tutorial:
    - tutorial/index.md
plugins:
  - blog:
      blog_dir: blog
  - blog:
      blog_dir: tutorial

I've improved the error reporting, so the blog plugin will now fail with a better message when the nav entries are missing. This was done in squidfunk/mkdocs-material-insiders@502ee4ebf3cb9babc9ccead727922c05c1540d16.

There was another problem with the way the blog plugin tricks MkDocs into not reporting the blog posts before the on_nav event, which I fixed in squidfunk/mkdocs-material-insiders@964d09f751225d829bc54a1cc9f76b4d0a215d5b, but still, when you configure the plugins like this, the second instance seems to override the first instance. The first plugin instance gets the same configuration as the second one. @oprypin, could this be related to the new plugin lifecycle? It can be easily reproduced with the above configuration. I'm not sure whether this is a bug in MkDocs.

[oprypin]

I don't think MkDocs ever intended to support specifying the same plugin multiple times. The main thing for MkDocs to add in that case would be a more direct error message...

[oprypin]

I suppose I could instead choose to "properly" support multiple instances of the same plugin.

I implement it here. https://github.com/mkdocs/mkdocs/compare/inst

It works as expected then, as far as I see.
And for a setup like this

  - blog:
      blog_custom_dir: overrides
  - blog:
      blog_dir: tutorial
      blog_dzir: tutorial

The log message now looks like

Config value 'plugins': Plugin 'material/blog #2' option 'blog_dzir': Unrecognised configuration name: blog_dzir

(note the #2)

[oprypin]

Please do give feedback whether you think this should be unleashed upon the world 😅

[zerenxyz]

Would the setup require blog_custom_dir instead of blog_dir for both plugin instances? 😓

[squidfunk]

@zerenxyz please never use blog_custom_dir. It's an internal setting, as documented in the code base. @oprypin I'll check it as soon as possible and give you feedback, but from what you describe it looks exactly like what we need. Material for MkDocs provides several plugins that are related to documentation content (tags, blog, social plugin), for which users might want to provide multiple slightly different configurations.

[squidfunk]

LGTM! I installed MkDocs from the inst branch and can confirm that now two instances of the blog plugin can live alongside each other. We just need to bump our minimum version when the fix gets released as part of MkDocs.

In the meantime, you just need to install MkDocs from git:

pip install --force git+https://github.com/mkdocs/mkdocs@inst

[zerenxyz]

Awesome! Does that break anything if I have MkDocs material and insiders installed via pip?

[oprypin]

I'm basically already tracking this MkDocs feature in this issue, so I may as well put this out here:

I plan to require the plugin to set an attribute supports_multiple_instances = True (ideas for shorter names are welcome), otherwise duplicated plugin entries will cause a warning that assumes that it was a mistake.

[oprypin]

And I do plan to include this in 1.4.2 - within a week

[squidfunk]

Released as part of 8.5.8+insiders-4.26.2. MkDocs version was bumped to 1.4.2 and the tags and blog plugin now allow for multiple instances, thanks to @oprypin.