Catch 22? social plugin is not installed

[PEZ]

I'm trying to set up social cards, disabling them for local builds usingan environment variable that is only:

plugins:
  - social:
      cards: !ENV [MKDOCS_SOCIAL_CARDS, false]

This is set to true in CI, and things seems to work. However, building this locally I get this:

INFO     -  Building documentation...
ERROR    -  Config value: 'plugins'. Error: The "social" plugin is not installed
Aborted with 1 Configuration Errors!

Locally I don't have insiders, since it's an open source project and any contributor should be able to build docs. I don't need social cards then either.

What am I not getting here?

[PEZ]

Maybe I shouldn't say that things are working on CI. It doesn't crash, but I also see no social card meta data in the generated pages.

Here's the site built: https://calva.io

[PEZ]

I take that last thing back. I had configured the wrong environment variable. 🤦

Now PIL is croaking on some image having too many pixels. I'll fix that. It really is the local build case that I don't know how to fix.

[squidfunk]

How did you install Insiders? Did you clone it via git or did you install via pip? It sounds like you cloned from git, and are missing:

pip install -e mkdocs-material

[PEZ]

The PIL error was actually about the site logo, which was a too big SVG. Maybe the social cards docs should have something about this. Normally it doesn't matter, so there might be more people using ”big” SVG images.

[squidfunk]

The PIL error was actually about the site logo, which was a too big SVG. Maybe the social cards docs should have something about this. Normally it doesn't matter, so there might be more people using ”big” SVG images.

Would it be possible that you share the logo? That would make debugging easier. You can also send it to [email protected], if you don't want to post it publicly.

[PEZ]

How did you install Insiders? Did you clone it via git or did you install via pip? It sounds like you cloned from git

I only install insiders in CI. Since my team mates and contributors can't instal insiders, I don't want to do that either locally, so that it works same for me as for them.

[PEZ]

Thanks for Materials for MkDocs! It has served Calva so well, since I switched to it. I haven't sponsored before because I feel I contribute to open source with my time, but now I really wanted those nice social cards.

[squidfunk]

Thanks for sponsoring! There are still some rough edges on the new plugins here and there, but we're gravitating towards stability with every release. The workaround shouldn't be necessary when I added the empty hull plugins.

[PEZ]

Here's another rough edge for the social card plugin. 😄

https://developers.facebook.com/tools/debug/?q=https%3A%2F%2Fcalva.io%2Fbabashka

[squidfunk]

Oh yeah, well, emojis are not supported. We can only set one font, i.e., the one that you configure via mkdocs.yml 😐 But we could filter those out – I think this would be the best approach.

[PEZ]

Configuring to use Inter crashes the build... Anyway, I'll skip emojis for now. 😀

[DragonflyRobotics]

I had the same issue and the problem is with the versioning. I was using a older version of MKDocs Material (8.3.x) which doesn't have builtin support for socials. I had to run the following:

pip install mkdocs-material mkdocs-material-extensions --upgrade
pip install pillow cairosvg --upgrade

This updated all the dependencies and allowed it to use the plugin.

You have to also have the latest version of Pillow since otherwise, you will get this error:

AttributeError: 'ImageDraw' object has no attribute 'textbbox'

I hope this helps. Let me know if you have any other issues.

[ssbarnea]

@DragonflyRobotics I can say that even after installing these I get this error.

IMHO, this error message is a bug by itself because it is incomplete and confusing as it does not tell the user what he needs to do to fix it. Clearly "social" plugin is expected to exist and is missing but we need an actionable error instead, not an "opaque" message like this.

@squidfunk What do you think about this? Any chance we could get an explicit error instead? I do have some projects where social works and some where it does not, but no idea why. I would even find a full trace exception more useful than this error.

[ssbarnea]

More details on my error. I created a theme that is based on material at https://github.com/ansible/mkdocs-ansible and published it, basically it only adds some default settings and includes a full list of plugins that we want to use in our projects, but no other customizations.

Still, the moment I switch from "theme: material" to "theme: ansible", mkdocs build starts to complain about Config value 'plugins': The "social" plugin is not installed, which I find very weird as nothing else is changed, the installed python dependencies are the same.

I am starting to believe that there is somewhere a check for theme name that breaks the social plugin on purpose.

[squidfunk]

When you build a theme that extends from Material for MkDocs, you can't use the shortcut social plugin name, because your theme is not material anymore – it's a different theme. You must reference plugins with the material/ prefix, specifically:

plugins:
  - material/social

This is not a limitation of Material for MkDocs, but is behavior that was introduced in MkDocs 1.4.0 to allow themes to provide built-in plugins while minimizing name collisions with third-party plugins. I searched their docs, but it doesn't seem to be documented. It might be a good idea to take this upstream, since this impacts all themes that provide built-in plugins, if extended. Alternatively, you might be able to just subclass all plugins and ship them as if they were bundled with your theme.

[squidfunk]

All plugins are registered in pyproject.toml:

mkdocs-material/pyproject.toml

Lines 59 to 64 in cd73ef1

	[project.entry-points."mkdocs.plugins"]
	"material/info" = "material.plugins.info.plugin:InfoPlugin"
	"material/offline" = "material.plugins.offline.plugin:OfflinePlugin"
	"material/search" = "material.plugins.search.plugin:SearchPlugin"
	"material/social" = "material.plugins.social.plugin:SocialPlugin"
	"material/tags" = "material.plugins.tags.plugin:TagsPlugin"

[squidfunk]

Oh, and I believe there's absolutely nothing we can do to improve error reporting – you're extending and MkDocs can't find the built-in plugin. The error is happening outside the scope of Material for MkDocs, since the plugins are not resolved at all.

[weitzman]

FYI, I got an error like this and had to install the pip package mentioned at https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#dependencies