社群分享卡片（Social Cards）

Zensical 0.0.67 開始內建原生的 social 外掛，可以替每個頁面自動產生分享圖（social card），並補上對應的 Open Graph／Twitter Card 中繼標籤。連結被分享到 Slack、X（Twitter）、Facebook、LINE 等平台時，就會顯示漂亮的預覽圖，而不是空白或預設縮圖。

最大的差異：不需要安裝 Cairo / Pillow

Material for MkDocs 的 social 外掛要產生卡片圖片，需要額外安裝 mkdocs-material[imaging]（Pillow、CairoSVG），還要在系統上裝好 Cairo Graphics 函式庫，常常是新手卡關的地方。

Zensical 的 social 外掛是原生實作（Rust），產生圖片不需要任何額外的 Python 套件或系統函式庫，pip install zensical 或 uv add zensical 裝好就能直接用。本教學在完全沒裝 Pillow、CairoSVG 或 Cairo 函式庫的環境下，實際建置過啟用 social 的專案，卡片正常產生。

啟用

[project.plugins.social]

（在 mkdocs.yml 則是 plugins: 底下加上 - social。）

WARNING -  The 'site_url' option is not set. Social cards are generated but not linked.

啟用後，zensical build 會替每一頁產生一張 1200 × 630 的 PNG，存放在 assets/images/social/<頁面路徑>.png（首頁是 index.png），並在該頁的 <head> 自動加入：

<meta property="og:type" content="website" />
<meta property="og:title" content="頁面標題 - 網站名稱" />
<meta property="og:image" content="https://your-site/assets/images/social/頁面路徑.png" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:url" content="https://your-site/頁面路徑/" />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:title" content="頁面標題 - 網站名稱" />
<meta property="twitter:image" content="https://your-site/assets/images/social/頁面路徑.png" />

og:title 與 twitter:title 的格式固定是「頁面標題 - 網站名稱」（首頁除外，首頁只用網站名稱），無法另外設定分隔字樣。

常用設定

[project.plugins.social]
enabled = true                  # 整個外掛的開關
cards = true                    # 是否產生卡片圖片
cards_dir = "assets/images/social"   # 卡片存放路徑（相對於 site_dir）
cards_layout = "default"        # 卡片版型
cards_layout_options = {}       # 版型參數，見下方
cards_include = []              # 只替符合的頁面產生卡片（留空＝全部）
cards_exclude = []               # 排除符合的頁面
cache = true                    # 在多次建置之間快取卡片
cache_dir = ".cache/plugin/social"

自訂卡片外觀

cards_layout_options 可以調整內建版型的顏色、字型、Logo、標題與說明文字，不需要自己刻版型。本教學網站實際使用的設定：

[project.plugins.social]
cards = true
cards_layout_options = { background_color = "#2b3d63", color = "#ffffff", font_family = "Noto Sans TC" }

在單一頁面覆寫

用 front matter 的 social 屬性，可以針對單一頁面覆寫卡片設定：

---
social:
  cards: false              # 這一頁不產生卡片，也不會輸出 og:image
---

---
social:
  cards_layout_options:
    background_color: "#ff1493"
    title: 自訂這張卡片上顯示的標題
---

把某個選項設成 null，可以重設回外掛的預設值。

自訂版型

想要完全自訂版型（例如加入特定的裝飾元素），可以在專案根目錄的 layouts/ 資料夾放版型檔案，再用 cards_layout 指定：

[project.plugins.social]
cards_layout = "my-custom-layout"
cards_layout_dir = "layouts"   # 預設就是 "layouts"，可省略

建議把 layouts/ 放在 docs_dir 之外，這樣自訂版型不會被複製進最後產生的網站。版型檔案的撰寫方式請參考 Material for MkDocs 的版型文件。

常見狀況

和自訂的 <head> 覆寫衝突

如果你的專案已經有自己的 overrides/main.html 或 overrides/partials/seo.html 之類的覆寫，手動輸出了 og:title、og:type、og:url、og:image、twitter:* 等標籤，啟用 social 外掛之後，這些標籤會變成兩份，因為外掛會自動插入自己的一份，不會檢查頁面裡有沒有重複。

重複的 meta 標籤不是合法的 HTML，不同社群平台的爬蟲取第一個或最後一個標籤的行為也不一致，可能導致分享預覽時而正常、時而顯示錯的標題或沒有圖片。本教學網站就踩過這個坑：先前的 overrides/partials/seo.html 自己輸出一套 og:title／og:type／og:url，啟用 social 外掛後造成重複，已經把這幾個重複的標籤從自訂覆寫移除，只保留 social 外掛沒有處理的欄位（og:site_name、og:description、og:locale、twitter:description、JSON-LD 結構化資料）。

啟用 social 外掛前，請先檢查自己的覆寫檔案有沒有手動輸出下列標籤，有的話就移除，交給外掛處理：

• og:type
• og:title
• og:url
• og:image、og:image:type、og:image:width、og:image:height
• twitter:card、twitter:title、twitter:image

卡片網址要在設定 site_url 之後才正確

卡片圖片本身一定會產生（不受 site_url 影響），但 og:image 這類需要完整網址的標籤，要有 site_url 才會輸出。本機預覽（zensical serve）如果沒設定 site_url，建置記錄裡會看到前面提到的警告，這是正常現象，不影響本機預覽，只要正式建置前確認 site_url 是正確的正式網址即可。

離線建置請關閉

和留言系統、程式庫連結一樣，social 外掛需要可對外的網址才有意義，離線使用（打包成下載檔案）時建議關閉。

實測驗證

本頁內容是在 Zensical 0.0.67、完全沒有安裝 Pillow／CairoSVG／Cairo 函式庫的環境下實際建置驗證：

• 每頁都會產生對應的 1200 × 630 PNG，檔名與頁面路徑一致（首頁是 index.png）。
• 沒有設定 site_url 時會印出警告，且頁面不含 og:image／twitter:image，但建置仍會成功、卡片仍會產生。
• front matter 的 social.cards: false 可以讓單一頁面不產生卡片、不輸出對應 meta 標籤。
• 自訂覆寫如果也輸出 og:title／og:type／og:url，會和外掛自動輸出的標籤重複（本教學網站的實際案例）。

總結

參考資料

• MkDocs plugins - social
• Built-in social plugin - Material for MkDocs
• Zensical 0.0.67 release notes