Community图像github.com

分享卡片

从一个 HTML 模板为网站的每个页面生成 1200x630 的 Open Graph 预览图,并在构建时将每个页面的标题、描述、规范地址和图片标签写入其 HTML 中,确保在聊天应用和社交网站上分享的链接能显示正确的预览,即使是单页应用也不例外。

分享卡片 是什么?

`share-cards` 是一个 AI 代理技能,旨在解决单页应用(SPA)在社交分享时链接预览不准确或无预览的常见问题。其核心原理是:预览爬虫(如聊天应用、社交网站)不会执行 JavaScript,因此 SPA 返回的相同 HTML 会导致所有链接显示相同预览。该技能通过两个主要步骤解决此问题:首先,使用一个 HTML 模板和页面列表,在无头浏览器中为每个页面渲染出 1200x630 大小的 JPEG 图像;其次,在构建时,将原始 `index.html` 根据配置生成多个 HTML 文件,每个文件都包含独有的 `<title>`、描述、规范 URL 以及 `og:*` 和 `twitter:*` 元标签。该技能支持 Vite 插件集成或作为构建后命令运行,并提供了多种预设模板(如 editorial、minimal、technical)和主题自定义选项,确保卡片风格与项目一致。在部署前,还能通过预览和验证命令确保卡片输出质量。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VinVirtual/share-cards/tree/HEAD

Installed? Explore more 图像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

分享卡片 是做什么的?

预览爬虫(聊天应用、社交网站、搜索引擎)会读取服务器发送的 HTML,但不会执行 JavaScript。单页应用会为每个地址返回相同的 HTML,因此所有链接都显示相同的预览。share-cards 解决了这两个问题:

  1. 渲染:一个 HTML 模板 + 页面列表 → 在无头浏览器中为每个页面绘制一张 1200x630 JPEG 图片。
  2. 注入:构建后的 index.html → 为每个页面生成独立的 HTML 文件,各自包含独有的 <title>、描述、规范 URL、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` 后自动运行注入
$S/references/templates.md  插槽、变量以及如何编写自定义模板
$S/examples/site/           一个包含 4 个页面的示例,并附有生成的卡片和注入后的页面
$S/README.md                配置参考、框架注意事项、限制说明

工作流程

  1. 检查机器环境:运行 $S/cards check。只有 render 和 preview 命令才需要浏览器。
  2. 查找页面:读取项目的路由或内容文件夹,列出所有公开地址。找到静态文件服务的目录(public/、static/)以及构建输出目录(dist/、build/、out/)。
  3. 脚手架初始化:运行 $S/cards init <project>(当页面列表应根据项目自身的路由或内容数据动态构建时,添加 --mjs 选项,以确保列表不会因手动更新而与实际内容脱节)。设置 siteUrl(真实的 https:// 域名)、siteName、imageDir(静态文件夹内的路径,例如 public/og)、imageUrlPath(该文件夹对应的访问路径,例如 /og)以及 dist。
  4. 编写每个页面的条目:
    • title:页面完整标题,将显示在预览中。
    • description:一句话描述,不超过 160 个字符。
    • cardTitle:卡片上绘制的文字。保持简短(大约 2 到 6 个单词)。用 *星号* 标记需要以强调色绘制的单词。
    • cardDescription(可选,卡片上更短的一行文字)、kicker(小标签)、art(项目中的图片文件)、template(按页面指定模板)。
    • 切勿为这些字段编造事实、数字或引文。所有内容必须取自页面本身。
  5. 选择模板和主题:editorial(纸质风格,粗衬线)、minimal(白色,简洁)、technical(深色,等宽字体)。将 theme 设置为项目自身的颜色。如需其他模板,运行 $S/cards eject <name> card.html,编辑该文件,然后设置 "template": "./card.html"。详情请参阅 references/templates.md。
  6. 渲染:运行 $S/cards render <project>。仔细阅读所有警告:如果标题或描述被截断,说明文字需要缩短。
  7. 查看结果:运行 $S/cards preview <project> 会生成 cards-preview/contact-sheet.png 和 chat-preview.png。务必检查这两张 PNG 图片。检查每张卡片是否有文字截断、拥挤、对比度不足以及图片遮挡文字等问题。修改后重新渲染。在亲自查看之前,不要告诉用户卡片看起来没问题。
  8. 准备页面框架:inject 命令会填充已有的标签,如果缺少所需标签则会报错。运行 $S/cards tags <project>,将生成的标签块粘贴到源文件 index.html 的 <head> 中,替换掉旧的分享标签(或者使用 --add-missing 选项自动添加缺失的标签)。
  9. 集成到构建流程:
    • Vite:将 $S/vite-plugin.mjs 中的 shareCards() 添加到 plugins 数组中(详情见 README)。
    • 其他框架:在构建命令之后运行 $S/cards inject <project>。
  10. 托管平台路由规则:如果托管平台有将所有请求重写为 /index.html 的兜底规则,请使用 $S/cards rewrites vercel|netlify|netlify-toml <project> 打印页面级的路由规则,并将它们放置在兜底规则之前。将规则展示给用户,未经告知不要直接修改托管平台配置。
  11. 验证:构建网站后,运行 $S/cards verify <project>。它必须以 All good. 结尾。
  12. 告知用户剩余步骤:部署网站,然后将一个真实链接粘贴到聊天应用中。预览会被各个应用缓存,有时会持续数天;设置 "versionImages": true 可以在卡片内容变化时更改图片地址。

规则

  • siteUrl 必须是生产环境的域名。预览图片需要绝对 https:// 地址。
  • 在构建之前渲染卡片,以便构建过程会将它们复制到输出目录。同时,将卡片文件和 cards.lock.json 提交到版本控制。这样,CI 环境就不需要浏览器了。
  • 渲染过程中不会从网络获取任何内容,除非配置中设置了 "allowNetwork": true。Web 字体必须是列在 fonts 下的本地文件。
  • 字体默认使用系统字体栈,因此在不同的机器上绘制的卡片可能会有所不同。为了在所有环境中获得一致的输出,请将字体文件添加到项目中(检查其许可证),并在 fonts 下列出它们。
  • 明确说明未检查的内容:各应用实际爬虫的行为,以及部署后托管平台的路由效果。

相关技能