From 1fc25a89ccbeb202f52136d5a92c502010baba05 Mon Sep 17 00:00:00 2001
From: Xianpeng Shen <xianpeng.shen@gmail.com>
Date: Sat, 25 Jul 2026 15:32:51 +0300
Subject: [PATCH] feat(social): generate Open Graph / social card images
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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
---
 .github/workflows/deploy.yml | 11 +++++++++++
 docs/requirements.txt        |  2 +-
 mkdocs.yml                   |  2 ++
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 0d9092c..c252524 100644
--- a/.github/workflows/deploy.yml
+++ b/.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:
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 894d190..00d8272 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,4 +1,4 @@
 markdown-gfm-admonition
 mkdocs
 mkdocs-include-markdown-plugin
-mkdocs-material
+mkdocs-material[imaging]
diff --git a/mkdocs.yml b/mkdocs.yml
index 8d96a63..429449e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -84,6 +84,8 @@ markdown_extensions:
 
 plugins:
   - search
+  - social:
+      cards: !ENV [CARDS, false]
   - blog
 
 extra_css: