卡片与链接（6个指令）

卡片与链接指令

用于在文章中展示 GitHub 信息、网站收藏、海报墙、标签和按钮。

GitHub 卡片（ghcard）

展示 GitHub 仓库或用户信息。

演示效果示例代码

withastro/astro

octocat

For all time, always.

0 followers 0 following 0 repos

:::ghcard{type="repo" repo="withastro/astro"}
:::

:::ghcard{type="user" user="octocat" bio="For all time, always."}
:::

type：repo（仓库卡片）或 user（用户卡片）
repo：仓库全名，格式为 owner/repo（type="repo" 时必填）
user：GitHub 用户名（type="user" 时必填）
bio：自定义用户简介（可选，仅 user 类型有效）
avatar：false 可隐藏用户头像（可选，仅 user 类型有效）
数据通过 GitHub API 动态获取

标签链接（hashtag）

带样式的标签，适合文章分类或话题标记。

演示效果示例代码

自动轮询颜色：Astro 博客教程前端 CSS
自定义颜色：指定蓝色指定红色

- 自动轮询颜色：:hashtag[Astro]{href="/tags/astro"} :hashtag[博客]{href="/tags/blog"} :hashtag[教程]{href="/tags/tutorial"} :hashtag[前端]{href="/tags/frontend"} :hashtag[CSS]{href="/tags/css"}
- 自定义颜色：:hashtag[指定蓝色]{href="/tags/blue" color="blue"} :hashtag[指定红色]{href="/tags/red" color="red"}

:hashtag 默认自动轮询 7 种颜色（红、橙、黄、绿、青、蓝、紫），无需指定 color
href 为跳转链接
color 可手动自定义颜色
左侧会自动显示 # 图标

按钮（button）

带样式的链接按钮，适合引导读者操作。

演示效果示例代码

普通按钮：查看文档 GitHub
带图标的按钮：搜索
小尺寸按钮：标签
图标按钮组：文档源码示例

- 普通按钮：:button[查看文档]{href="/" color="accent"} :button[GitHub]{href="/" color="blue"}
- 带图标的按钮：:button[搜索]{href="/search" color="green" icon="lucide:search"}
- 小尺寸按钮：:button[标签]{href="/tags" color="purple" size="xs"}
- 图标按钮组：:button[文档]{href="/docs" color="cyan" icon="lucide:book-open"} :button[源码]{href="/github" color="cyan" icon="lucide:code"} :button[示例]{href="/demo" color="cyan" icon="lucide:trophy"}

href 为跳转链接
color 可自定义颜色
icon 支持 Iconify 图标名（如 lucide:search）或图片 URL
size="xs" 为小尺寸模式

数字名片（yoicard）

文章末尾的”数字名片”指令，接近实体名片的 1.75

横版比例、纸张阴影、印刷字体。所有字段都可定制，适合作者署名 / 关于我 / 文末签名等场景。

演示效果示例代码

Alex Chen

Web Developer · Blogger

折腾博客和摄影的开发者 — 记录每一次心动

深色撞色

custom

深底自动反白字 — 衬线名字 + 金色 accent

:::yoicard{name="Alex Chen" role="Web Developer · Blogger"}

折腾博客和摄影的开发者 — *记录每一次心动*

<!-- contact -->

**alex.dev**
alex@example.com
:::

:::yoicard{name="深色撞色" role="custom" bg="#1a3a2e" accent="#d4af37" icon="lucide:zap" font-name="Georgia, serif"}

深底自动反白字 — *衬线名字 + 金色 accent*

<!-- contact -->

**alex.dev**
alex@example.com
:::

属性参考

身份

name(必填)
role
/简介(单行,可选)

背景(四选一,优先级 bg-image > bg-gradient > bg-pattern > bg)

bg
,如 "#1a3a2e"
bg-image
URL/路径
bg-pattern
diagonal | dots | grid | grain
bg-gradient
渐变字符串(自动包装为 linear-gradient(...))
bg-mode:full(默认) | left | right —— 仅 bg-image 生效
bg-overlay:dark(默认) | light | none | 自定义颜色 —— 仅 bg-mode="full" 生效

装饰

logo
(默认圆形,1px 边线随明暗自适应)
logo-shape:circle(默认) | square | rounded
icon
icon,Iconify 全称如 lucide:sparkles、solar:hashtag-square-bold
qr
(任意 URL),build 时生成 SVG,扫码可读
accent
/icon 颜色,默认跟随文字色

字体

font-name
。完整 font-family 字符串。建议先在 site-config.fontsRegistry 注册,或写带 fallback 的标准栈
font-body

配色

text:auto(默认,按背景明暗反转) | light | dark | #hex
name-color
name 颜色
role-color
role 颜色

Slot 写法

容器 body 用  标记切成两段:

写法	中间 bio	底部联系
`内容...<!-- contact -->内容...`	标记前	标记后
`内容...`(无标记)	全部	空
`<!-- contact -->内容...`	空	全部
(空)	空	空

注意

bio 区会以斜体小字呈现
联系区使用等宽字体
设置 qr 时,联系区右下角自动生成二维码;移动端(<480px)下隐藏 QR 以避免拥挤
自定义字体需先在 site-config.fontsRegistry 注册,或在 font-name/font-body 中包含完整 fallback 链

网站卡片（sites）

以网格形式展示一组网站收藏，自动抓取封面截图，适合展示常用工具、设计资源、推荐阅读等。

前置配置

使用前需在 src/data/config/links.ts 中定义分组数据：

export const links = {
    design: [
        {
            title: 'Unsplash',
            url: 'https://unsplash.com',
            description: 'Photos for everyone.',
            icon: 'https://unsplash.com/favicon.ico',
            labels: [{ name: '图片', color: '#3b82f6' }]
        },
    ],
    tools: [
        {
            title: 'Figma',
            url: 'https://figma.com',
            description: 'The collaborative interface design tool.',
            icon: 'https://figma.com/favicon.ico',
            labels: [{ name: '设计', color: '#a259ff' }]
        },
    ],
};

字段	必填	说明
`title`	是	网站标题
`url`	是	网站链接
`description`	否	描述，未填时显示 URL
`icon`	否	图标 URL，未填时自动尝试获取 `/favicon.ico`
`cover`	否	封面图 URL，未填时自动使用截图服务抓取
`labels`	否	标签列表，`[{ name, color }]`

封面截图服务可在 site-config.ts 中切换：

screenshotService: 'thumio',  // 'thumio'（默认）或 'mshots'

基本用法

演示效果示例代码

Unsplash

UnsplashPhotos for everyone.

Dribbble

DribbbleDiscover the world's top designers.

Heroicons

HeroiconsFree Open Source SVG Icons.

Astro

AstroThe web framework for content-driven websites.

Tailwind CSS

Tailwind CSSRapidly build modern websites without ever leaving your HTML.

GitHub

GitHubWhere the world builds software.

:::sites{group="design"}
:::

group（必填）：对应 links.ts 中的分组名称
响应式网格布局，悬停时卡片上浮、封面放大

海报卡片（posters）

posters 与 sites 共用同一套 links 配置，但采用竖向比例，适合电影海报、专辑封面等收藏。

演示效果示例代码

星际穿越

千与千寻

盗梦空间

肖申克的救赎

肖申克的救赎

泰坦尼克号

泰坦尼克号

黑客帝国

大话西游

霸王别姬

:::posters{group="movies"}
:::

<!-- 正方形比例——专辑封面 -->
:::posters{group="albums" ratio="square"}
:::

<!-- 固定列数 -->
:::posters{group="movies" cols="4"}
:::

属性	默认值	说明
`ratio`	`portrait`	`portrait`（2 ）或 `square`（1 ）
`cols`	自动	固定列数：`2`~`8`

sites vs posters

	`sites`	`posters`
比例	横向（3 ）	竖向（2 ）或正方形
信息	封面 + 图标 + 标题 + 描述 + 标签	封面 + 悬停标题
适用	网站收藏	海报、专辑、封面

未知标题

00:00

00:00

播放列表