写博客文章时，经常需要在正文里贴一段链接，比如某篇参考资料、某个开源项目、或者本站的另一篇文章。直接贴一个 URL 显得生硬，放一张截图又无法更新。于是本站新增了「链接卡片」：在文章里写一行指令，构建时会自动抓取对方页面的标题和描述，渲染成一张可点击的卡片。
下面用几个例子演示它的用法，也是这篇文章本身的真实渲染效果。
语法
链接卡片由 ::link-card 指令构成，必须独立成段书写：
::link-card[URL]
::link-card[URL 说明文字]
::link-card[URL] title="覆盖标题" description="覆盖描述"- URL 支持第三方外链（http/https）和本站链接（
/开头或本站域名）。 - 卡片信息优先使用手动覆盖的
title/description，其次是抓取或本地解析到的标题与描述。 - 不加任何参数时，外链会在构建时自动抓取 TDK，站内链接则直接从本地内容解析，不发出任何网络请求。
外链卡片
先看一个最简单的写法，只给一个 GitHub 仓库地址：
构建时插件会请求该页面，从 og:title / og:description（或 <title> 与 meta description）中提取标题和描述，卡片默认在新标签页打开。同一次构建里重复的链接只会抓取一次。
带说明文字的卡片
方括号里 URL 之后的文字会作为「说明文字」，在抓取结果缺失时充当兜底标题。比如：
如果对方页面能正常抓到标题，说明文字就不会显示。
站内文章卡片
引用本站其他文章时，链接会自动识别为站内链接，从文章 frontmatter 直接读取标题与描述，不联网、不耗时：
画廊也是一样的用法：
自定义标题与描述
需要完全掌控卡片文案时，可以手动覆盖标题和描述（优先级最高）：
失败降级
如果外链抓取失败（对方站点拒绝访问、页面超时、或者干脆是个不存在的域名），卡片不会报错，而是降级为「域名 + URL」的可点击卡片，构建始终能正常完成。例如下面这个链接必然会抓取失败：
实现与限制
- 抓取发生在构建期（Node 环境），不会给浏览器增加任何运行时请求；关键词（keywords）会抓取但暂不展示。
- 每次抓取带浏览器 UA、5 秒超时，同一链接去重缓存；站点无响应时按降级卡片兜底。
- 指令段要求整段纯文本，说明文字里不要混入加粗、行内代码等 Markdown 标记。
- 卡片样式跟随主题的 Light / Dark 两态，也尊重系统的「减少动态效果」偏好。
如果你在文章里看到任何一张卡片显示异常，多半是对方页面没有可用的元信息，给它补一个 title 或 description 即可。
评论