feat(social): generate Open Graph / social card images

.github/workflows/deploy.yml

@@ -8,12 +8,23 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      # Enable Material's social card generation for the deployed site.
+      # Environments without the native imaging libs (e.g. Netlify previews)
+      # leave this unset, so card generation is skipped there.
+      CARDS: 'true'
     steps:
       - name: Checkout Repository
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
 
+      - name: Install imaging system dependencies (for social cards)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
+
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:

docs/requirements.txt

@@ -1,4 +1,4 @@
 markdown-gfm-admonition
 mkdocs
 mkdocs-include-markdown-plugin
-mkdocs-material
+mkdocs-material[imaging]

mkdocs.yml

@@ -84,6 +84,8 @@ markdown_extensions:
 
 plugins:
   - search
+  - social:
+      cards: !ENV [CARDS, false]
   - blog
 
 extra_css: