卡片与链接指令（6个指令）

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

GitHub 卡片（ghcard）

展示 GitHub 仓库或用户信息。

演示效果示例代码

withastro/astro

octocat

For all time, always.

0 followers 0 following 0 repos

octocat

0 followers 0 following 0 repos

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

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

:::ghcard{type="user" user="octocat" avatar="false"}
:::

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

放到右侧边栏

除了正文，你也可以通过 GhCard 组件把卡片放到页面右侧边栏。在 Astro 页面（如 src/pages/blog/[id].astro）中，向 BaseLayout 的 right-sidebar slot 传入组件即可：

Astro

---import BaseLayout from '../../layouts/BaseLayout.astro';import GhCard from '../../components/widgets/GhCard.astro';--- <BaseLayout ...>  <div slot="right-sidebar" class="p-4 pt-6">    <GhCard mode="repo" repo="withastro/astro" />    <GhCard mode="user" user="octocat" bio="For all time, always." avatar={false} />  </div>  <!-- 文章正文 --></BaseLayout>

---
import BaseLayout from '../../layouts/BaseLayout.astro';
import GhCard from '../../components/widgets/GhCard.astro';
---

<BaseLayout ...>
  <div slot="right-sidebar" class="p-4 pt-6">
    <GhCard mode="repo" repo="withastro/astro" />
    <GhCard mode="user" user="octocat" bio="For all time, always." avatar={false} />
  </div>
  <!-- 文章正文 -->
</BaseLayout>

GhCard 组件属性：

属性	类型	必填	说明
`mode`	`'repo' \| 'user'`	是	卡片类型
`repo`	`string`	mode=repo	仓库全名 `owner/repo`
`user`	`string`	mode=user	GitHub 用户名
`bio`	`string`	否	用户简介（仅 user）
`avatar`	`boolean`	否	是否显示头像，默认 `true`（仅 user）

由于数据通过客户端 JS 获取，放在边栏也会自动填充 GitHub API 数据。

标签链接（hashtag）

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

演示效果示例代码

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

示例里的 href 统一指向标签索引页，实际使用时填你自己的标签地址，比如 /tags/前端/。

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

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

按钮（button）

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

演示效果示例代码

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

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

href 为跳转链接
color 可自定义颜色
icon 支持 Iconify 图标名（如 lucide:search）或图片地址（外链、@img/、相对路径）
size="xs" 为小尺寸模式

数字名片（yoicard）

文章末尾的”数字名片”，横版比例接近实体名片（宽是高的 1.75 倍），带纸张阴影和印刷字体。适合作者署名、关于我、文末签名等场景。

演示效果示例代码

你的名字

写作者 · 摄影爱好者

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

深色撞色

custom

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

全图背景

bg-image full

背景图铺满，默认加一层暗色遮罩 — 右上角 logo，右下角二维码

半图背景

bg-mode right

图片只占右半边，文字在左边

渐变背景

bg-gradient

没有联系区的名片 — 只改名字颜色

:::yoicard{name="你的名字" role="写作者 · 摄影爱好者"}

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

<!-- 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
:::

:::yoicard{name="全图背景" role="bg-image full" bg-image="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=900&q=80" accent="#fbbf24" icon="lucide:sparkles" logo="https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=80&q=80" qr="https://example.com"}

背景图铺满，默认加一层暗色遮罩 — *右上角 logo，右下角二维码*

<!-- contact -->

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

:::yoicard{name="半图背景" role="bg-mode right" bg-image="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=900&q=80" bg-mode="right"}

图片只占右半边，文字在左边

<!-- contact -->

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

:::yoicard{name="渐变背景" role="bg-gradient" bg-gradient="135deg, #fef3c7, #fed7aa" name-color="#c0392b"}

没有联系区的名片 — *只改名字颜色*
:::

属性参考

属性	默认值	说明
`name`	—	必填，名字
`role`	—	头衔或一句话简介，单行
`bg`	—	纯色背景，如 `#1a3a2e`
`bg-image`	—	背景图，支持 `@img/`、相对路径和外链，本地图片构建时会被优化
`bg-mode`	`full`	背景图铺法：`full` 铺满、`left` 只占左半、`right` 只占右半
`bg-overlay`	`dark`	铺满时盖在图上的遮罩：`dark`、`light`、`none`，或一个颜色
`bg-pattern`	—	内置纹理：`diagonal`、`dots`、`grid`、`grain`
`bg-gradient`	—	CSS 渐变，如 `135deg, #fef3c7, #fed7aa`，会自动包上 `linear-gradient(...)`
`logo`	—	右上角的图，写法同 `bg-image`
`logo-shape`	`circle`	logo 形状：`circle`、`square`、`rounded`
`icon`	—	左上角的装饰图标，Iconify 全称，如 `lucide:sparkles`
`accent`	跟随文字色	左上角短线和图标的颜色
`qr`	—	二维码内容，一般写主页地址。构建时生成 SVG，放在联系区右下角
`font-name`	主题字体	名字的字体，完整的 `font-family` 写法
`font-body`	主题字体	其余文字的字体
`text`	`auto`	文字配色：`auto` 按背景深浅自动选、`light` 浅色字、`dark` 深色字，或 `#hex`
`name-color`	—	只改名字的颜色
`role-color`	—	只改头衔的颜色

四种背景同时写时只生效一种，优先级 bg-image > bg-gradient > bg-pattern > bg。

Slot 写法

容器 body 用  标记切成两段:

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

注意

bio 区会以斜体小字呈现
联系区使用等宽字体
设置 qr 时,联系区右下角自动生成二维码;移动端(<480px)下隐藏 QR 以避免拥挤
自定义字体需先在 site-config.fontsRegistry 注册,或在 font-name/font-body 中包含完整 fallback 链
text="auto" 对渐变背景一律用深色字。深色渐变要自己加 text="light"

网站卡片（sites）

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

前置配置

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

TypeScript

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' }]        },    ],};

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`	否	图标地址，可以写 `'@img/...'`（本地图片会被优化）或外链，未填时自动尝试获取 `/favicon.ico`
`cover`	否	封面图地址，写法同 `icon`，未填时自动配封面，见下文
`labels`	否	标签列表，`[{ name, color }]`

默认封面

没填 cover 时，封面按下面的顺序来：

站点的分享卡片图（og:image）：大多数站点都给社交分享准备了一张设计过的卡片图。构建时会读一次站点首页，取出这张图的地址直接引用，不下载、不生成文件。
网页截图：站点没有分享卡片图、构建时访问不到，或者这张图日后失效了，就换成截图服务截的首屏。

截图服务在 src/data/config/links.ts 中切换：

TypeScript

export const screenshotService = 'mshots';  // 'mshots'（默认）或 'thumio'

export const screenshotService = 'mshots';  // 'mshots'（默认）或 'thumio'

两个服务都是免费的。mshots 会等页面脚本跑完再截，靠 JavaScript 渲染的站点也能截到内容；thumio 不等，这类站点常截成空白。截图的已知限制：

少数站点会拦截截图机器人（比如 Unsplash），截出来是拒绝访问的页面。
同一个地址第一次被请求时需要几秒生成，第一位访客可能先看到一张占位图，之后才有缓存。

两种都不满意的站点，直接给它填 cover。cover 支持 '@img/...'，可以自己截一张放进 src/assets/img/，构建时会一并优化。

基本用法

演示效果示例代码

UnsplashPhotos for everyone.

图片

DribbbleDiscover the world's top designers.

设计

HeroiconsFree Open Source SVG Icons.

图标

AstroThe web framework for content-driven websites.

框架

Tailwind CSSRapidly build modern websites without ever leaving your HTML.

CSS

GitHubWhere the world builds software.

工具

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

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

海报卡片（posters）

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

正方形，适合专辑封面：

Random Access Memories

Abbey Road

1989

Dark Side of the Moon

Thriller

Nevermind

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

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

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

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

sites vs posters

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

目录

卡片与链接（6个指令）

卡片与链接指令（6个指令）

GitHub 卡片（ghcard）

放到右侧边栏

标签链接（hashtag）

按钮（button）

数字名片（yoicard）

属性参考

Slot 写法

注意

网站卡片（sites）

前置配置

默认封面

基本用法

海报卡片（posters）

sites vs posters