share-cards 是做什麼的?
爬蟲預覽器(聊天應用程式、社交網站、搜尋引擎)讀取伺服器傳送的 HTML,不會執行 JavaScript。單頁應用程式對每個網址都傳送相同的 HTML,因此每個連結都顯示相同的預覽畫面。share-cards 同時修復這兩個問題:
- render:一個 HTML 模板 + 頁面清單 → 每個頁面一張 1200x630 JPEG,在無頭瀏覽器中繪製。
- inject:建置後的
index.html→ 每個頁面一個 HTML 檔案,各自帶有專屬的<title>、description、canonical、og:*與twitter:*標籤。
技能資料夾:~/.claude/skills/share-cards/(下文簡寫為 $S)。所有指令格式為 $S/cards <command> [dir],其中 [dir] 內含 cards.config.json。指令 $S/cards help 可列出所有指令。
$S/cards 指令列工具
$S/lib/ 設定、標籤注入、渲染、驗證、預覽、改寫規則
$S/templates/ editorial.html, minimal.html, technical.html, runtime.js
$S/vite-plugin.mjs 在 `vite build` 後執行 inject
$S/references/templates.md 插槽、變數與自訂模板的方法
$S/examples/site/ 一個含 4 個頁面的範例,附有卡片和注入後的頁面
$S/README.md 設定參考、框架注意事項、限制
工作流程
- 檢查機器:
$S/cards check。只有render和preview需要瀏覽器。 - 找出頁面:閱讀專案的路由器或內容資料夾,列出所有公開網址。找出靜態檔案的提供位置(
public/、static/)以及建置輸出位置(dist/、build/、out/)。 - 初始化:
$S/cards init <project>(當頁面清單應從專案自身的路由或內容資料建構時,加上--mjs選項,這樣清單就不會偏離)。設定siteUrl(真正的https://網域)、siteName、imageDir(位於靜態資料夾內,例如public/og)、imageUrlPath(該資料夾的對應網址路徑,例如/og)以及dist。 - 為每個頁面撰寫條目:
title:頁面完整標題,應與預覽中顯示的一致。description:一個句子,最多 160 個字元。cardTitle:繪製在卡片上的文字。保持簡短(約 2 至 6 個單詞)。以*星星*標記的文字會以強調色繪製。cardDescription(選用,卡片上較短的一行文字)、kicker(小標籤)、art(專案中的圖片檔案)、template(個別頁面覆寫用)。- 切勿為這些項目憑空捏造事實、數字或引述。所有文字應直接取自頁面本身。
- 挑選模板與主題:
editorial(紙張感、粗襯線字體)、minimal(白色、簡潔)、technical(深色、等寬字體)。將theme設定為專案本身的色彩。如需其他模板,請執行$S/cards eject <name> card.html進行編輯,然後設定"template": "./card.html"。詳見references/templates.md。 - 渲染:
$S/cards render <project>。仔細閱讀每個警告:標題或描述被截斷表示文字必須縮短。 - 檢視結果:
$S/cards preview <project>會產生cards-preview/contact-sheet.png和chat-preview.png。務必檢視這兩個 PNG 檔案。檢查每張卡片是否有文字被截斷、過於擁擠、對比度不足,以及圖片遮蓋文字等問題。修正後重新渲染。除非你已親自看過,否則不要告訴使用者卡片看起來沒問題。 - 準備頁面外殼:
inject會填入已存在的標籤,若缺少標籤則會失敗。執行$S/cards tags <project>並將輸出的區塊貼入原始index.html的<head>中,取代任何舊的分享標籤(或加上--add-missing選項)。 - 整合至建置流程:
- Vite:將
$S/vite-plugin.mjs中的shareCards()加入plugins陣列(詳見 README)。 - 其他工具:在建置指令後執行
$S/cards inject <project>。
- Vite:將
- 主機規則:若主機有全部轉發至
/index.html的 catch-all rewrite 規則,請使用$S/cards rewrites vercel|netlify|netlify-toml <project>產生頁面規則,並將這些規則放在 catch-all 規則之前。向使用者顯示這些規則;未經告知不得編輯主機設定。 - 驗證:建置網站,然後執行
$S/cards verify <project>。必須以All good.結尾。 - 告知使用者剩餘事項:部署後,將一個真實連結貼到聊天應用程式中。預覽畫面會被各應用程式快取,有時長達數天;設定
"versionImages": true可在每當卡片變更時改變圖片網址。
規則
siteUrl必須是正式環境的網域。預覽圖片需要絕對路徑的https://網址。- 在建置前先渲染卡片,這樣建置時才會複製它們,並將卡片和
cards.lock.json提交至版本控制。之後 CI 流程便無需瀏覽器。 - 除非設定檔中設定
"allowNetwork": true,否則渲染時不會從網路取得任何資源。網頁字型必須是列在fonts下的本地檔案。 - 字型預設使用系統字型堆疊,因此在不同機器上繪製的卡片可能不同。若要在所有環境獲得完全一致的輸出,請將字型檔案加入專案(檢查其授權條款)並列在
fonts下。 - 坦誠說明未檢查的項目:各應用程式的實際爬蟲行為,以及部署後主機的路由規則。