分享卡片 是做什么的?
预览爬虫(聊天应用、社交网站、搜索引擎)会读取服务器发送的 HTML,但不会执行 JavaScript。单页应用会为每个地址返回相同的 HTML,因此所有链接都显示相同的预览。share-cards 解决了这两个问题:
- 渲染:一个 HTML 模板 + 页面列表 → 在无头浏览器中为每个页面绘制一张 1200x630 JPEG 图片。
- 注入:构建后的
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 配置参考、框架注意事项、限制说明
工作流程
- 检查机器环境:运行
$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的兜底规则,请使用$S/cards rewrites vercel|netlify|netlify-toml <project>打印页面级的路由规则,并将它们放置在兜底规则之前。将规则展示给用户,未经告知不要直接修改托管平台配置。 - 验证:构建网站后,运行
$S/cards verify <project>。它必须以All good.结尾。 - 告知用户剩余步骤:部署网站,然后将一个真实链接粘贴到聊天应用中。预览会被各个应用缓存,有时会持续数天;设置
"versionImages": true可以在卡片内容变化时更改图片地址。
规则
siteUrl必须是生产环境的域名。预览图片需要绝对https://地址。- 在构建之前渲染卡片,以便构建过程会将它们复制到输出目录。同时,将卡片文件和
cards.lock.json提交到版本控制。这样,CI 环境就不需要浏览器了。 - 渲染过程中不会从网络获取任何内容,除非配置中设置了
"allowNetwork": true。Web 字体必须是列在fonts下的本地文件。 - 字体默认使用系统字体栈,因此在不同的机器上绘制的卡片可能会有所不同。为了在所有环境中获得一致的输出,请将字体文件添加到项目中(检查其许可证),并在
fonts下列出它们。 - 明确说明未检查的内容:各应用实际爬虫的行为,以及部署后托管平台的路由效果。