Built-in `blog` plugin not compatible with `mkdocs-static-i18n`

[jeremy-feng]

Context

I want to write blogs in multiple languages. I found mkdocs-static-i18n is easy to use.

So I try to organize my blog contents with two languages, zh(default language) and en. That is, one is file_name.md and another one is file_name.en.md.

Bug description

mkdocs-static-i18n is a nice plugin for write contents in multiple laguages. However, when I use both blog and mkdocs-static-i18n plugins, adding a .md file in blog/posts will result in an error: AttributeError: 'NoneType' object has no attribute 'title'

Traceback (most recent call last):
  File "C:\Users\Administrator\miniconda3\lib\runpy.py", line 194, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Users\Administrator\miniconda3\lib\runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "C:\Users\Administrator\miniconda3\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "C:\Users\Administrator\miniconda3\lib\site-packages\click\core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "C:\Users\Administrator\miniconda3\lib\site-packages\click\core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "C:\Users\Administrator\miniconda3\lib\site-packages\click\core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "C:\Users\Administrator\miniconda3\lib\site-packages\click\core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "C:\Users\Administrator\miniconda3\lib\site-packages\click\core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "C:\Users\Administrator\miniconda3\lib\site-packages\mkdocs\__main__.py", line 234, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "C:\Users\Administrator\miniconda3\lib\site-packages\mkdocs\commands\serve.py", line 116, in serve
    server.serve()
  File "C:\Users\Administrator\miniconda3\lib\site-packages\mkdocs\livereload\__init__.py", line 162, in serve
    self._build_loop()
  File "C:\Users\Administrator\miniconda3\lib\site-packages\mkdocs\livereload\__init__.py", line 184, in _build_loop
    func()
  File "C:\Users\Administrator\miniconda3\lib\site-packages\mkdocs\commands\serve.py", line 76, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "C:\Users\Administrator\miniconda3\lib\site-packages\mkdocs\commands\build.py", line 311, in build
    env = config.plugins.run_event('env', env, config=config, files=files)
  File "C:\Users\Administrator\miniconda3\lib\site-packages\mkdocs\plugins.py", line 520, in run_event
    result = method(item, **kwargs)
  File "C:\Users\Administrator\miniconda3\lib\site-packages\material\plugins\blog\plugin.py", line 489, in on_env
    self._generate_excerpt(file, base, config, files)
  File "C:\Users\Administrator\miniconda3\lib\site-packages\material\plugins\blog\plugin.py", line 730, in _generate_excerpt
    excerpt = Page(page.title, temp, config)
AttributeError: 'NoneType' object has no attribute 'title'

I tested many senarios.

• Use both blog and mkdocs-static-i18n:
  • AttributeError: 'NoneType' object has no attribute 'title'
• Only use blog but not mkdocs-static-i18n:
  • Blog style works well but I can not write contents in multiple laguanges with ease.
• Only use mkdocs-static-i18n but not blog:
  • I can not write contents in multiple laguanges, but the blog features are all lost.

Related links

https://ultrabug.github.io/mkdocs-static-i18n/

Reproduction

I tried to generate a reproduction .zip file using the built-in info plugin.

When I run mkdocs build, it asks me to upgrade to the latest version. So I have to replace my current insider version to public version.

But my issue need to use blog plugin. So I cannot build it as well.

I have prepared a zip file which contains the minimal project source files. I hope you can help me solve it. Thank you!

test.zip

Steps to reproduce

1. mkdocs serve. There should be an error indicating that there is a problem (possibly related to blog title) with the .md file in /blog.
2. If you delete the i18n plugin, you will find that the blog is rendered well.

Browser

Chrome

Before submitting

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues or 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! We'll look into the issues with the info plugin shortly – thanks for trying to stick to the process! I believe that it would be great to have better interop between the blog plugin and the static-i18n plugin, so we'll see if and how we can improve it.

[squidfunk]

I've looked into this issue, and honestly, I have no idea if and how this can be fixed. The reason is that the mkdocs-static-i18n plugin seems to heavily modify the configuration, probably to make it work with the way the plugin implements its i18n support. What is weird is the following settings when running the blog plugin and i18n plugin together:

INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
              - blog/posts/2023-01-14-test/index.md
              - blog/archive/2023.md
              - blog/category/test.md
INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
              - blog/posts/2023-01-14-test/index.md
              - blog/archive/2023.md
              - blog/category/test.md

First of all, I can only guess that we see this twice because of the two languages you configured. However, the blog plugin itself temporarily adds these entries to the navigation, so the warnings should not be printed, since the blog plugin controls where links to these pages are put. Yet, they appear. I think that this could be one of the reasons why both plugins don't work together – the i18n plugin seems to apply its own logic which conflicts with the blog plugin.

When implementing plugins, we always try to do it in a way that they work together with third-party without problems. However, that's not always possible, because each plugin has its assumptions and sometimes additional effort must be put into making them work together. I believe that this problem can be solved, but given that the i18n plugin is very complex and puts several plugin "under its control" (as it says for itself in the comments), I believe that support must be implemented in the i18n plugin. Thus, I suggest to raise this issue to the maintainers of the i18n plugin, ideally when the blog plugin is released into the community edition, which should happen in 1-2 months. We're happy to collaborate on fixing this issue.

Until then, we must consider this issue as not fixable.

[squidfunk]

Other than that, you might achieve i18n with an alternative approach – by splitting your project into two separate projects, one per language, as described in this discussion. The language selector will very soon receive capabilities to stay on the same page when switching languages, same as with the version selector.

This approach does not need any third-party plugins and is likely to be more stable and future proof.

[jeremy-feng]

I've looked into this issue, and honestly, I have no idea if and how this can be fixed. The reason is that the mkdocs-static-i18n plugin seems to heavily modify the configuration, probably to make it work with the way the plugin implements its i18n support. What is weird is the following settings when running the blog plugin and i18n plugin together:

INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
              - blog/posts/2023-01-14-test/index.md
              - blog/archive/2023.md
              - blog/category/test.md
INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
              - blog/posts/2023-01-14-test/index.md
              - blog/archive/2023.md
              - blog/category/test.md

First of all, I can only guess that we see this twice because of the two languages you configured. However, the blog plugin itself temporarily adds these entries to the navigation, so the warnings should not be printed, since the blog plugin controls where links to these pages are put. Yet, they appear. I think that this could be one of the reasons why both plugins don't work together – the i18n plugin seems to apply its own logic which conflicts with the blog plugin.

When implementing plugins, we always try to do it in a way that they work together with third-party without problems. However, that's not always possible, because each plugin has its assumptions and sometimes additional effort must be put into making them work together. I believe that this problem can be solved, but given that the i18n plugin is very complex and puts several plugin "under its control" (as it says for itself in the comments), I believe that support must be implemented in the i18n plugin. Thus, I suggest to raise this issue to the maintainers of the i18n plugin, ideally when the blog plugin is released into the community edition, which should happen in 1-2 months. We're happy to collaborate on fixing this issue.

Until then, we must consider this issue as not fixable.

Thanks for your detailed explanation. The blog plugin has done a great job. Just a few lines of config code and I can get many powerful features. Thanks for your work!

[jeremy-feng]

Other than that, you might achieve i18n with an alternative approach – by splitting your project into two separate projects, one per language, as described in this discussion. The language selector will very soon receive capabilities to stay on the same page when switching languages, same as with the version selector.

This approach does not need any third-party plugins and is likely to be more stable and future proof.

This is a good approach. I will try it. Thanks!