編輯式 OG 卡片

每篇文章一個統一的連結預覽圖片。每張卡片包含：

頂部有一條分隔線，包含一個提示標籤（系列或章節）、主題和一行元資訊（閱讀時間或日期），
一個大型襯線字體的標題，設定為真實文字，因此拼寫永遠正確，只縮小到需要的大小，其中一兩個單詞使用強調色，
作者行，包含姓名縮寫或照片，以及文章的 URL，
右側的藝術元素：四種區塊構圖之一，從文章的 slug 選擇（這樣文章能保持自己的卡片）、您選擇的圖片，或無，同時標題會延伸得更寬。

一個腳本將您的文章讀入 cards.json，您進行審查，另一個腳本使用機器上已有的 Chrome 渲染每張卡片。無需安裝任何東西。

你需要什麼

Node.js 18 或更新版本。
Chrome、Chromium 或 Edge。腳本會在常見位置找到它；如果找不到，請設定 CHROME_PATH。
渲染時需要網路連線，以載入 Google Fonts 樣式表（Instrument Serif, Inter, IBM Plex Mono）。若要離線渲染，請參閱「疑難排解」。

此技能的資料夾是下面的 <skill>：也就是此 SKILL.md 所在的資料夾。

步驟

1. 建立 `cards.json`

從 Markdown 文章（Astro、Hugo、Jekyll、Eleventy、Next.js MDX 或任何有前置元數據的）：

node <skill>/scripts/from-posts.mjs content/blog --site=yourblog.example --path=/blog/ --out-dir=public/og

它會讀取該資料夾下的所有 .md、.mdx 和 .markdown 檔案，並為每篇文章建立一張卡片，最新的文章排在最前面。draft: true 的文章會被跳過。從前置元數據中提取的欄位如下：

卡片欄位	來源
`slug`	`slug`，否則為 `permalink`，否則為檔案名稱（如果是 `index.md` 則是資料夾名稱），不包含開頭的日期
`title`	`og_title`，否則為 `title`
`kicker`	`kicker`，否則為 `series`，否則為 `--kicker=...`，否則為 "Article"
`topic`	`topic`，否則為第一個 `category`，否則為第一個標籤
`meta`	`reading_time`，否則以每分鐘 230 個單詞計算："8 min read"
`author`	`author`（文字，或其中的 `name`），否則為 `--author=...`
`url`	`--site` + `--path` + slug，顯示在作者下方
`out`	`<out-dir>/<slug>.png`；如果沒有 `--out-dir`，則放在文章旁，檔案名稱為 `<name>.og.png`（如果是 `index.md` 則是 `og.png`）

每當新增文章時重新執行：cards.json 中已有的卡片會保留您的編輯，新文章會被加入，已刪除的文章會被移除。

手動建立，適用於非 Markdown 的頁面（電子報、著陸頁、文件章節），請自行撰寫相同格式的 JSON：

{
  "theme": { "paper": "#131313", "ink": "#f2ede4", "accent": "#ff7a45" },
  "defaults": { "kicker": "Night Desk", "author": "Ines Varga" },
  "cards": [
    {
      "slug": "issue-41",
      "title": "Why every newsroom is quietly *rebuilding its CMS*",
      "topic": "Issue 41",
      "meta": "Oct 2026",
      "url": "nightdesk.example/41",
      "tags": ["#media", "№ 41"]
    }
  ]
}

defaults 會填補卡片中遺漏的任何欄位。

2. 編輯卡片

打開 cards.json 並檢查標題：

將承載重點的一兩個單詞用 *星號* 包圍起來；它們會以強調色的斜體顯示。例如："Shipping a design system *in a week*"。
標題在 70 個字元以內閱讀效果最佳；上限為 110 個字元。超過約 80 個字元字型會變小。可以使用文章前置元數據中的 og_title 或在 cards.json 中直接縮短。

一張卡片可以包含的所有欄位：

欄位	用途	限制
`title`	標題（必填）	110
`slug`	定義檔案名稱並選擇版面配置（除非設定了 `out`，否則必填）	–
`out`	PNG 的輸出位置，相對於 `cards.json`（預設為 `og/<slug>.png`）	–
`kicker`	左上角的標籤，使用強調色	24
`topic`	緊接在提示標籤之後；同時也是藝術元素上的預設主題標籤	28
`meta`	右上角：閱讀時間、日期、期數	20
`author`	作者行名稱；縮寫會顯示在圓圈中	32
`avatar`	圓圈中使用的照片，取代縮寫（路徑或 URL）	–
`url`	顯示在名稱下方	48
`art`	`blocks`（預設）、`image` 或 `none`	–
`image`	用於 `"art": "image"` 的圖片（路徑或 URL）；會被裁切成 390×430	–
`layout`	1 到 4，自行選擇區塊構圖	–
`tags`	藝術元素上最多兩個小標籤，例如 `["#css", "Part 2"]`	16 each

主題設定每張卡片的外觀：paper（背景）、ink（文字）和 accent（強調色），以十六進位表示，再加上 serif、sans 和 mono 用於其他 Google Fonts 字體系列。強調色會直接用於區塊；對於文字，卡片會將其變暗或變亮，直到可讀為止。兩個可作為起點的主題：預設的墨水藍色（#fafaf7, #17181c, #2433e8）和夜間模式（#131313, #f2ede4, #ff7a45）。

3. 渲染

node <skill>/scripts/render.mjs cards.json

它會先檢查每張卡片，並一次列出所有問題，然後以每次四張卡片的速度渲染（每張約一秒），並檢查每個 PNG 是否為 1200×630。加上 --scale=2 可產生 2400×1260 的圖片（在高密度螢幕上更清晰，檔案大小約為兩倍），或使用 --only=slug,slug 重新渲染特定卡片。

4. 檢視

打開 og-preview.html（與 cards.json 放在一起）：所有卡片並排顯示。檢查那些縮小很多的標題（將其縮短）、強調單詞是否落在錯誤的短語上，以及相鄰卡片是否看起來有足夠的差異。變更卡片的 layout 以選擇另一種構圖。

5. 嵌入到網站中

卡片只有在每個頁面使用絕對 URL 指向其圖片時，才會在預覽中顯示。在頁面的 <head> 中加入：

<meta
  property="og:image"
  content="https://yourblog.example/og/design-system-in-a-week.png"
/>
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="og:image:alt" content="Shipping a design system in a week" />
<meta name="twitter:card" content="summary_large_image" />

在文章版面配置或模板中一次完成，根據 slug 動態生成，而不是每篇文章手動添加：

Next.js (App Router)：在文章路由的 generateMetadata 中，回傳 openGraph: { images: [{ url: /og/${slug}.png, width: 1200, height: 630 }] } 和 twitter: { card: 'summary_large_image' }，並在根佈局中設定 metadataBase，使 URL 變為絕對路徑。
Astro, Eleventy, Jekyll, Hugo：將這些標籤新增到基礎版面配置的 head 中，使用網站 URL 加上 /og/ 再加上頁面的 slug。
圖片與文章放在一起（沒有 --out-dir）：使用您的框架提供同位置檔案的路徑。

部署後，將文章 URL 貼到連結預覽檢查工具，或貼到 X、LinkedIn 或 Slack 的草稿中，以查看卡片。平台會快取預覽；更改圖片後可能需要一段時間才會顯示新圖片。

6. 保持自動化（可選）

為了在每次建置時為新文章生成卡片，請將此技能的 scripts/ 和 template/ 資料夾複製到您的儲存庫中（例如 tools/og/），並在建置之前執行兩個腳本，例如在 package.json 中作為 prebuild 腳本：

"prebuild": "node tools/og/scripts/from-posts.mjs content/blog --site=yourblog.example --path=/blog/ --out-dir=public/og && node tools/og/scripts/render.mjs cards.json"

建置機器需要安裝 Chrome；大多數 CI 映像檔都有，或者設定 CHROME_PATH。

疑難排解

render: fix cards.json first：每行會指出卡片、欄位和限制。
找不到 Chrome：安裝 Chrome 或 Chromium，或設定 CHROME_PATH 指向可執行檔。
標題顯示為普通襯線字體或標籤顯示為系統字型：Google Fonts 樣式表未載入。若要離線渲染，請安裝 Instrument Serif、Inter 和 IBM Plex Mono（全部可從 Google Fonts 免費取得），並在主題中設定 "fonts": ""。"fonts" 也可以是您自己的樣式表 URL，用於其他字體系列。
平台上的預覽顯示舊圖片或沒有圖片：檢查 og:image URL 是否可以在瀏覽器中打開，並且是絕對路徑（包含 https:// 和您的網域），然後要求平台重新抓取頁面，或等待其快取過期。

檔案

scripts/from-posts.mjs：將前置元數據轉換為 cards.json，並在後續執行中保留您的編輯。無依賴項。
scripts/render.mjs：檢查 cards.json，渲染 PNG 並寫入 og-preview.html。無依賴項。
scripts/chrome.mjs：尋找 Chrome 並進行螢幕截圖。
template/：卡片本身。card.html 和 card.css 是佈局，card.js 填入文字、選擇可讀顏色、繪製藝術元素並調整標題大小。
examples/field-notes/：一個小部落格（posts/）和透過 from-posts.mjs 從中生成的 cards.json，並已加入強調單詞。examples/night-desk/：一個手寫的 cards.json，適用於深色主題的電子報。Lookbk 上的預覽圖就是從這些範例渲染的。
NOTICE.md：此技能使用的字型和軟體。

編輯風連結預覽卡