Add social plugin for per-page social cards with auto-generated preview images

Author: williambdean

.github/workflows/ci.yml

@@ -18,6 +18,7 @@ jobs:
       - uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
+      - run: sudo apt-get install -y libcairo2
       - run: uv run mkdocs build
       - uses: peaceiris/actions-gh-pages@v4
         with:

.gitignore

@@ -3,3 +3,4 @@ docs/blog/posts/drafts/*
 .python-version
 __pycache__/
 .agents/
+.cache/

Makefile

@@ -1,2 +1,4 @@
+CAIRO_LIB := $(shell pkg-config --variable=libdir cairo)
+
 html: 
-	uv run mkdocs serve
+	DYLD_FALLBACK_LIBRARY_PATH=$(CAIRO_LIB) uv run mkdocs serve

docs/overrides/main.html

@@ -2,9 +2,6 @@
 
 {% block extrahead %}
   <meta name="google-site-verification" content="8viHBc_t5bEEtPJfuu29pd_den6Xa6tD4G9ZdCLOwl4">
-  <meta property="og:image" content="{{ config.site_url }}images/social-banner.png">
-  <meta property="og:image:width" content="1200">
-  <meta property="og:image:height" content="630">
   {% if "blog/posts/" in page.url %}
     {% set description = page.meta.description | default(config.site_description) %}
     <script type="application/ld+json">

mkdocs.yml

@@ -34,6 +34,7 @@ plugins:
   - search
   - mkdocs-video
   - tags
+  - social
   - markdownextradata
   - git-revision-date-localized:
       enable_creation_date: true
@@ -42,6 +43,7 @@ plugins:
       categories:
         - tags
       comments_path: "#__comments"
+      image: images/social-banner.png
   # - mkdocs-jupyter
 
 markdown_extensions:

pyproject.toml

@@ -21,6 +21,8 @@ docs = [
     "mkdocs-git-revision-date-localized-plugin>=1.1.0,<2",
     "mkdocs-video>=1.5.0",
     "mkdocs-rss-plugin>=1.19.0",
+    "cairosvg>=2.9.0",
+    "cairocffi>=1.7.1",
 ]
 misc = [
     "pandas>=2.0.3,<3",