Possible regression in Blog functionality

[mikegrima]

Context

Hello:

I was utilizing the blog feature with the beta release 9.2.0b2. Dependabot has made updates to the latest version of mkdocs-material, and in the latest release there appears to be a regression.

Bug description

When running mkdocs build or mkdocs serve on the latest versions of mkdocs-material (9.2.8), I encounter the following stack trace:

mkdocs: commands[0]> mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/runner/work/starfleet/starfleet/site
Traceback (most recent call last):
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/click/core.py", line [143](https://github.com/gemini-oss/starfleet/pull/91/checks#step:5:144)4, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/mkdocs/__main__.py", line 286, in build_command
    build.build(cfg, dirty=not clean)
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/mkdocs/commands/build.py", line 311, in build
    nav = config.plugins.on_nav(nav, config=config, files=files)
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/mkdocs/plugins.py", line 536, in on_nav
    return self.run_event('nav', nav, config=config, files=files)
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/mkdocs/plugins.py", line 507, in run_event
    result = method(item, **kwargs)
  File "/home/runner/work/starfleet/starfleet/.tox/mkdocs/lib/python3.10/site-packages/material/plugins/blog/plugin.py", line 180, in on_nav
    items[items.index(page)] = self.blog
ValueError: SectionPage(title='Blog', url='/starfleet/blog/') is not in list
mkdocs: exit 1 (0.84 seconds) /home/runner/work/starfleet/starfleet> mkdocs build pid=2686```

Here is a link to the GH action where this is happening: https://github.com/gemini-oss/starfleet/pull/91/checks

When going from the beta release of 9.2.0b2 to 9.2.8, I had to make a change to the .authors.yml file, which I did accordingly: https://github.com/gemini-oss/starfleet/pull/91/files#diff-587acea3a21bb5b4b2aee25b9d125cbbb7611164d7e41b31bf1c91ffa15676f7.

However, for some reason, all real versions after the beta releases cause an issue. I haven't had time to pop a debugger in, but just wanted to get this documented in case anyone else saw this.

I see the error above regardless if I have the link to the blog in mkdocs.yml. That file is here: https://github.com/gemini-oss/starfleet/blob/main/mkdocs.yml. I also made no changes to this file; only change made was to the authors file since the initial error message informed me of the schema change.

Also while going through the bug reporting page, I followed the instructions to disable the extra css as well as the gen_files plugin and it had no impact.

Related links

• Reporting a bug
• Source Repo
• Draft PR to update version
• Blog instructions that I followed
• GH Actions output showing errors

Reproduction

9.2.8-blog-regression.zip

Steps to reproduce

1. Update to the latest mkdocs and mkdocs material versions on PyPI
2. Run mkdocs serve or mkdocs build

Browser

No response

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• I have attached a .zip file with a minimal reproduction.

[squidfunk]

Thanks for reporting. This is a duplicate of #5971 – it's related to the section index plugin, where SectionPage is coming from (see stack trace). I think it was already reported upstream, but you should check back with the maintainer.

• regression: Enabling the plug-in messes up items as written in SUMMARY.md from mkdocs-literate-nav oprypin/mkdocs-section-index#18

[squidfunk]

Possible workaround: remove section-index and use Material for MkDocs navigation.indexes feature. If that doesn't work, please provide a minimal reproduction without the use of external plugins and we're happy to investigate.

[oprypin]

It is not a duplicate of #5971

[squidfunk]

@oprypin thanks for investigating! Checking again, it looks related to the fact that the section index plugin replaces the page in the navigation, so the page that was priorly assigned to the blog does not exist in the navigation anymore. Note that we currently have a hack in place to mount the blog at the correct location in the navigation:

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

Lines 170 to 192 in 6ffc9f4

	# Hack: since MkDocs will always create a page for the entrypoint even
	# though we already created it in `on_files`, we must replace the page
	# that MkDocs created with the entrypoint we already have on our hands.
	# Hopefully, this hack can be removed soon - see https://t.ly/9nehI
	page = self.blog.file.page
	self._attach_at(page.parent, page, self.blog)
	# Hack: update page instances in navigation - this can also be removed
	# once an already open pull request is merged - see https://t.ly/9C_Kz
	for page in [self.blog, *self.blog.posts, *self.blog.views]:
	assert isinstance(page, Page)
	# Check if the page that we generated is identical to the page that
	# is associated with the file - if it is, we're good
	temp = page.file.page
	if not temp or temp == page:
	continue
	# If not, MkDocs overwrote our page with a new instance, which we
	# need to replace with the one we generated
	page.file.page = page
	for items in [self._resolve_siblings(page, nav), nav.pages]:
	items[items.index(temp)] = page

This hack assumes that the page that MkDocs created in _data_to_navigation is still part of the navigation, which conflicts with the behavior of the section index plugin that replaces it, as it runs before the blog plugin due to the defined event priorities that we use in the blog plugin:

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

Lines 161 to 166 in 6ffc9f4

	# Attach posts and views to navigation (run later) - again, we allow other
	# plugins to alter the navigation before we start to attach posts and views
	# generated by this plugin at the correct locations in the navigation. Also,
	# we make sure to correct links to the parent and siblings of each page.
	@event_priority(-50)
	def on_nav(self, nav, *, config, files):

We already raised an issue upstream saying that MkDocs should probably allow plugins to create their own page objects to implement custom behaviors, which is necessary for blog posts, as all metadata must be available to generate archive and category files/pages, as well as for those pages, which we generate in on_files and define here. We also proposed a PR to implement this proposal:

• Allow plugins to provide their own Page mkdocs/mkdocs#3367
• Allow plugins to override Page when populating navigation mkdocs/mkdocs#3366

In general, it looks like it's a good time to rethink navigation population and page construction in MkDocs to allow for more sophisticated plugins like the blog plugin. The section index plugin also uses a (rather unorthodox? not sure) approach to circumvent the behavior that is fixed by the aforementioned PR here.

Happy for any feedback and to gravitate towards a solution that makes the plugin ecosystem work together in a better and more empowering way ☺️ Until then, we must consider the section index plugin being incompatible with the blog plugin. As mentioned before, the navigation.indexes feature might be a good replacement, albeit there are currently still some minor issues that we need to work out:

• Navigation indexes are not rendered correctly on the Blog index from the second page onwards #5972

[mikegrima]

Happy to report that using navigation.indexes works. I don't notice any differences between that and the prior plugin so I'm going to stick with navigation.indexes.

Thank you all!

[squidfunk]

Thanks for checking back!