Blog plugin fails with StopIteration when no nav entry is present

[paulmelis]

Context

As requested in #6039 here's a reproduction of the issue described there.

Bug description

I'm using the blog plugin to provide a "News" section on an mkdocs-material site. This includes a name different than "blog" for the blog_dir setting. When there is no entry for the news/index.md file the serving/building of the site fails with a StopIteration in the blog plugin:

  File "/home/melis/courses/blender-course/env/lib/python3.11/site-packages/material/plugins/blog/plugin.py", line 690, in _attach_to
    tail = next(item for item in reversed(items) if isinstance(item, Page))
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
StopIteration

Related links

• https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/

Reproduction

9.3.2-blog-build-fails.zip

Steps to reproduce

1. Unzip reproduction and set up virtualenv with given requirements.lock.txt
2. mkdocs serve
3. Exception trace:

(env) melis@juggle 10:10:/tmp/doh21/9.3.2-blog-build-fails$ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
WARNING -  A relative path to 'index.md' is included in the 'nav' configuration, which is not found in the documentation files.
Traceback (most recent call last):
  File "/tmp/doh21/9.3.2-blog-build-fails/env/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/mkdocs/__main__.py", line 270, in serve_command
    serve.serve(**kwargs)
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 86, in serve
    builder(config)
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 67, in builder
    build(config, live_server=None if is_clean else server, dirty=is_dirty)
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/mkdocs/commands/build.py", line 311, in build
    nav = config.plugins.on_nav(nav, config=config, files=files)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/mkdocs/plugins.py", line 536, in on_nav
    return self.run_event('nav', nav, config=config, files=files)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/mkdocs/plugins.py", line 507, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/material/plugins/blog/plugin.py", line 207, in on_nav
    self._attach_to(self.blog, Section(title, views), nav)
  File "/tmp/doh21/9.3.2-blog-build-fails/env/lib/python3.11/site-packages/material/plugins/blog/plugin.py", line 688, in _attach_to
    tail = next(item for item in reversed(items) if isinstance(item, Page))
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
StopIteration

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.

[alexvoss]

Hi, thanks for the reproduction. I will try to look at this but am traveling across timezones today, so not sure exactly how much time I will have before Monday. Since the blog plugin is one of the newer ones, I am keen to gain an understanding of how it works and this seems like a good test case. Please bear with me, I am new to trying to fix things in mkdocs-material.

[squidfunk]

@alexvoss thanks for offering to take this on. I found some time to tackle this and I'm going to look into this right now. I'm happy to give you an introduction on the blog plugin later, as there are still some edge cases to fix ☺️

[squidfunk]

Fixed in 50c273c.

In the minimal reproduction, the blog was explicitly not linked in the navigation, and thus, has no parent section assigned, which we need for correctly resolving the location at which we attach the archive and category views. We now check if the blog was explicitly not linked, and in this case, still generate all views, but do not try to link them in the navigation. All generated pages will not have previous and next pages assigned to them, which is now correct, since it's unclear what the previous and next page is without the blog being part of the navigation.

Note that when building a standalone blog, the entrypoint has no parent page as well (it's at the top-level), so we use the top-level of the navigation to resolve its siblings and append it to the end. Thus, we must check if we're building a standalone (i.e., top-level) blog or not, and branch accordingly.

[squidfunk]

Released as part of 9.4.2.