Social plugin makes Mkdocs build crashing when system dependencies are not met

[Guts]

Context

Our Mkdocs website is collaborative and many of writers are using Windows without any ability to install the CairoSVG dependencies at system level (https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#cairo-graphics).

Bug description

Expected behavior: try/except the exception raised by cairosvg and display a error, warning or even info message to inform that social cards have been disabled, but let the build going on.

Related links

• https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/
• https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/#cairo-graphics

Reproduction

Sorry I cant' generate a minimal reproduction since the build is failing. Still, here comes a manual zip: material-social-card-build-crash.zip

Steps to reproduce

Install:

pip install --upgrade --force-reinstall mkdocs-material[imaging]

Given this mkdocs.yml:

site_name: My Docs
site_url: https://example.com

theme:
  name: material

plugins:
  - info
  - social:
      enabled: true
      cards: true

Running build:

(.venv) PS C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash> mkdocs build
Traceback (most recent call last):
  File "C:\Users\username\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Users\username\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\click\core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\click\core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\click\core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\click\core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\click\core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\mkdocs\__main__.py", line 283, in build_command
    cfg = config.load_config(**kwargs)
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\mkdocs\config\base.py", line 378, in load_config
    errors, warnings = cfg.validate()
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\mkdocs\config\base.py", line 230, in validate
    run_failed, run_warnings = self._validate()
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\mkdocs\config\base.py", line 188, in _validate
    self[key] = config_option.validate(value)
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\mkdocs\config\config_options.py", line 182, in validate    
    return self.run_validation(value)
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\mkdocs\config\config_options.py", line 1064, in run_validation
    self.load_plugin_with_namespace(name, cfg)
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\mkdocs\config\config_options.py", line 1102, in load_plugin_with_namespace
    return (name, self.load_plugin(name, config))
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\mkdocs\config\config_options.py", line 1120, in load_plugin    plugin_cls = self.installed_plugins[name].load()
  File "C:\Users\username\AppData\Local\Programs\Python\Python310\lib\importlib\metadata\__init__.py", line 171, in load
    module = import_module(match.group('module'))
  File "C:\Users\username\AppData\Local\Programs\Python\Python310\lib\importlib\__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
    from cairosvg import svg2png
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\cairosvg\__init__.py", line 26, in <module>
    from . import surface  # noqa isort:skip
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\cairosvg\surface.py", line 9, in <module>
    import cairocffi as cairo
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\cairocffi\__init__.py", line 47, in <module>
    cairo = dlopen(
  File "C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash\.venv\lib\site-packages\cairocffi\__init__.py", line 44, in dlopen
    raise OSError(error_message)  # pragma: no cover
OSError: no library called "cairo-2" was found
no library called "cairo" was found
no library called "libcairo-2" was found
cannot load library 'libcairo.so.2': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.so.2'
cannot load library 'libcairo.2.dylib': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo.2.dylib'        
cannot load library 'libcairo-2.dll': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'libcairo-2.dll'
(.venv) PS C:\Users\username\Documents\GitHub\Perso\material-social-card-build-crash>

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. Please see #6818 (comment) why we're not considering this.

[kamilkrzyskow]

I agree that OSError shouldn't just out right crash during config load and I have written a comment in the PR.

Here I would like to question:

using Windows without any ability to install the CairoSVG dependencies at system level

I used the social plugin on Windows with success, installed with the recommended compiled MINGW version from the docs.
Perhaps I had to add the installation path to the Environmental PATH manually myself, but I'm not sure anymore.

What I mean to say is that if the writers were able to install Python and know how to run the mkdocs build command then I assume they should be able to follow the CairoSVG installation process.

Assuming the OSError gets fixed one could also add more validation in a hook that would detect any particular issue with CairoSVG installation and provide more explanation what to do. Perhaps this should also be handled in the plugin 🤔