fix: silence mkdocs social plugin warnings in strict mode

The social plugin (`mkdocs-material`) requires cairosvg for generating
Open Graph social card images. This dependency was never included in the
docs dependency group, so the plugin emitted a warning on every page.
With strict mode enabled, these warnings aborted the build.

Changes:

- Add `mkdocs-material[imaging]` extra to the docs dependency group,
  which pulls in `cairosvg`, `cairocffi`, `cssselect2`, `defusedxml`,
  and `tinycss2`. This requires the system Cairo library (`libcairo2`),
  which is pre-installed on GitHub Actions ubuntu-latest runners.
- Gate the social plugin behind an `ENABLE_SOCIAL_CARDS` env var
  (defaults to false) so local development does not require Cairo.
- Set `ENABLE_SOCIAL_CARDS=true` in the docs publish workflow so social
  cards are generated for the published site.

Author: jonathanhefner

.github/workflows/publish-docs-manually.yml

@@ -31,3 +31,5 @@ jobs:
 
       - run: uv sync --frozen --group docs
       - run: uv run --frozen --no-sync mkdocs gh-deploy --force
+        env:
+          ENABLE_SOCIAL_CARDS: "true"

mkdocs.yml

@@ -112,7 +112,8 @@ watch:
 
 plugins:
   - search
-  - social
+  - social:
+      enabled: !ENV [ENABLE_SOCIAL_CARDS, false]
   - glightbox
   - mkdocstrings:
       handlers:

pyproject.toml

@@ -75,7 +75,7 @@ dev = [
 docs = [
     "mkdocs>=1.6.1",
     "mkdocs-glightbox>=0.4.0",
-    "mkdocs-material>=9.5.45",
+    "mkdocs-material[imaging]>=9.5.45",
     "mkdocstrings-python>=2.0.1",
 ]