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

Enable Material's social plugin so every page gets an auto-generated
Open Graph / Twitter card image — links shared to GitHub/Slack/X now
render a rich preview instead of a bare URL.

Card generation needs native imaging libs (Cairo etc.), which aren't
available in every build environment (e.g. Netlify PR previews). To keep
those builds working, the plugin is gated behind a CARDS env var that
defaults to false; only the GitHub Pages deploy — where the libs are
installed — sets CARDS=true and actually renders the cards.

- mkdocs.yml: add `social` plugin with `cards: !ENV [CARDS, false]`
- docs/requirements.txt: mkdocs-material -> mkdocs-material[imaging]
- deploy.yml: install imaging system deps and set CARDS=true for the build

Author: shenxianpeng

.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

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