Mkdocs-material social plugin fails with hard to diagnose error on malformed yaml headers

[butler54]

Context

When trying to introduce tags into into a website rather than

title: my title
description: my description
tags:
  - tag 1
  - tag 2

the following header was introduced

title: my title
description: my description
title:
  - tag 1
  - tag 2

Bug description

On a site with existing use of the social plugin the title field was accidentally replaced with a list e.g.

---
title: title
description: descripton
title:
  - list
  - item

Due to the handling of yaml in python (by default) the last key entered will overwrite any previously duplicated key.

This scenario produces the traceback below when trying to run mkdocs-serve with either 9.18.1 or commit 580b0b9d0279b5eedde93636ea5e7f68ca11a117.

While there is an expected failure in this scenario the traceback makes it hard to trace the error:

1. Page which caused the error is not logged..e.g. where do I look.
2. Field which triggered the error is no visible without reading code.

in effect: the bug is a lack of logging sufficient for users to root cause the issue quickly. Only those comfortable with python can identify the issue then attempt to track down the source, if the change in a site is large.

Traceback (most recent call last):
  File "/Users/anon_user/.virtualenvs/env1/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/Users/anon_user/.virtualenvs/env1/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/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 83, in serve
    builder(config)
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 76, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/mkdocs/commands/build.py", line 332, in build
    config.plugins.run_event('post_build', config=config)
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/mkdocs/plugins.py", line 522, in run_event
    result = method(**kwargs)
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/material/plugins/social/plugin.py", line 214, in on_post_build
    promise.result()
  File "/opt/homebrew/Cellar/python@3.10/3.10.12_1/Frameworks/Python.framework/Versions/3.10/lib/python3.10/concurrent/futures/_base.py", line 451, in result
    return self.__get_result()
  File "/opt/homebrew/Cellar/python@3.10/3.10.12_1/Frameworks/Python.framework/Versions/3.10/lib/python3.10/concurrent/futures/_base.py", line 403, in __get_result
    raise self._exception
  File "/opt/homebrew/Cellar/python@3.10/3.10.12_1/Frameworks/Python.framework/Versions/3.10/lib/python3.10/concurrent/futures/thread.py", line 58, in run
    result = self.fn(*self.args, **self.kwargs)
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/material/plugins/social/plugin.py", line 221, in _cache_image
    image = render_function()
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/material/plugins/social/plugin.py", line 201, in <lambda>
    render_function = lambda: self._render_card(site_name, title, description)
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/material/plugins/social/plugin.py", line 250, in _render_card
    self._render_text((826, 328), font, title, 3, 30),
  File "/Users/anon_user/.virtualenvs/env1/lib/python3.10/site-packages/material/plugins/social/plugin.py", line 283, in _render_text
    text = re.sub(r"(<[^>]+>)", "", text)
  File "/opt/homebrew/Cellar/python@3.10/3.10.12_1/Frameworks/Python.framework/Versions/3.10/lib/python3.10/re.py", line 209, in sub
    return _compile(pattern, flags).sub(repl, string, count)
TypeError: expected string or bytes-like object
make: *** [docs-serve] Error 1

Related links

• Similar cause to this:Error reading page 'tags.md': '<' not supported between instances of 'int' and 'str' #5691
• https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/

Reproduction

Single page reproducer

testmkdocs-material-social.zip

Steps to reproduce

1. Download the reproducer
2. Run - see failure
3. alter second title object in yaml header to another key e.g. tags
4. run - should be okay.

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 suggesting. Yes, we can look into whether we can improve error reporting. However, that's gonna be a challenge to scale, because the new social plugin allows authors to freely define layouts and access properties. We'll check if we can add some kind of validation to the plugin, but validating front matter has been tricky with MkDocs in the past.

[squidfunk]

Fixed in 10b1501. The community edition of the plugin will now check that title and description, the only supported properties are supported by the plugin. For the new social plugin that is currently part of Insiders, we'll evaluate whether we can allow the author to provide validations for custom front matter properties, but that's left as an exercise for the future 😊

[squidfunk]

Released as part of 9.1.19!