内容展示指令

用于在文章中插入提示信息、图片、代码和外部链接。

信息提示

提示框（callout）

最常用的信息提示块，支持多种类型和自定义标题。

演示效果示例代码

Info

这是一条信息提示，适合补充说明背景知识或额外信息。

小技巧

通过 title 属性可以自定义提示框的标题，让提示更加明确。

注意事项

这是一条警告提示，提醒读者需要小心处理的地方。

危险操作

执行此操作前请务必备份数据，该操作不可逆！

:::callout{variant="info"}
这是一条**信息提示**，适合补充说明背景知识或额外信息。
:::

:::callout{variant="tip" title="小技巧"}
通过 `title` 属性可以自定义提示框的标题，让提示更加明确。
:::

:::callout{variant="warning" title="注意事项"}
这是一条**警告提示**，提醒读者需要小心处理的地方。
:::

:::callout{variant="danger" title="危险操作"}
执行此操作前请务必备份数据，该操作不可逆！
:::

variant 可选值：info（蓝色，普通信息）、tip（绿色，提示建议）、warning（黄色，警告注意）、danger（红色，危险警示）
title 可自定义标题，不传则使用默认类型名称

高亮块（note）

带主题色的高亮区域，适合强调重要内容。

演示效果示例代码

使用博客主题色的轻量提示块。支持 color 属性自定义颜色。

关于主题

Vergil 主题基于 Astro 构建，支持多种内容指令和自定义配置。

成功提示

文章发布成功！读者现在可以在首页看到你的新文章了。

:::note
使用博客**主题色**的轻量提示块。支持 `color` 属性自定义颜色。
:::

:::note{color="blue" title="关于主题"}
Vergil 主题基于 Astro 构建，支持多种内容指令和自定义配置。
:::

:::note{color="green" title="成功提示"}
文章发布成功！读者现在可以在首页看到你的新文章了。
:::

color 可选值：blue（科技蓝）、green（自然绿）、red（警示红）、yellow（活力黄）、purple（优雅紫）或任意十六进制色值
title 可设置标题，让提示块更具辨识度

引用卡片（quot）

带图标的引用展示，适合引用名言或重要观点。

演示效果示例代码

quote

代码是写给人看的，顺便让机器执行。

lightbulb

好的设计是显而易见的，伟大的设计是透明的。

:::quot{icon="quote"}
代码是写给人看的，顺便让机器执行。
:::

:::quot{icon="lightbulb"}
好的设计是显而易见的，伟大的设计是透明的。
:::

icon 可自定义图标，不传则使用默认引号图标
支持所有 Iconify 图标名称

段落引号（blockquote）

带引号装饰的引用段落，适合长段引用。

演示效果示例代码

这是使用 blockquote 指令的引用示例。
支持多段落内容，适合引用长段文字或他人的精彩论述。顶部左右角会自动显示引号图标作为装饰。

:::blockquote
这是使用 blockquote 指令的引用示例。

支持多段落内容，适合引用长段文字或他人的精彩论述。顶部左右角会自动显示引号图标作为装饰。
:::

使用 <blockquote> 标签包裹内容
顶部左右角自动显示引号图标
支持多段落 Markdown 内容

图片媒体

增强图片（image）

带说明文字和可选下载按钮的单张图片展示。

演示效果示例代码

壮丽山景

带下载按钮的山峰

正方形裁剪

::image{src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=800&q=80" alt="壮丽山景"}

::image{src="https://images.unsplash.com/photo-1464822759023-fed622ff2c3b?w=800&q=80" alt="带下载按钮的山峰" download="true"}

::image{src="https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=800&q=80" alt="正方形裁剪" ratio="1/1" width="300px"}

src（必填）：图片地址
alt：图片描述，会显示在图片下方作为 caption
width / height：设置图片尺寸
ratio：固定宽高比，如 1/1、16/9
download：true 或自定义下载链接，显示下载按钮
fancybox：false 可禁用点击放大

画廊（gallery）

图片网格或瀑布流展示，适合多张图片的排版。

演示效果示例代码

壮丽山峰

山间湖泊

森林小径

海边日落

城市夜景

田园风光

:::gallery{layout="grid"}
![壮丽山峰](https://images.unsplash.com/photo-1464822759023-fed622ff2c3b?w=400&q=80)
![山间湖泊](https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&q=80)
![森林小径](https://images.unsplash.com/photo-1448375240586-882707db888b?w=400&q=80)
![海边日落](https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&q=80)
![城市夜景](https://images.unsplash.com/photo-1519501025264-65ba15a82390?w=400&q=80)
![田园风光](https://images.unsplash.com/photo-1500382017468-9049fed747ef?w=400&q=80)
:::

layout：grid（网格，默认）或 flow（瀑布流）
size：xs | s | m | l | xl | mix，控制图片尺寸
ratio：square | portrait | origin，固定图片比例，origin 保持原始比例

摄影框（photo）

带水印的摄影展示，适合摄影作品的专业呈现。

演示效果示例代码

::photo{src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=800&q=80" watermark="true"}

::photo{src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=800&q=80" watermark="Vergil Theme"}

src（必填）：图片地址
watermark：水印文字，true 使用默认水印，或传入自定义文字

代码技术

终端块（terminal）

终端样式的代码块，模拟命令行界面。

演示效果示例代码

安装依赖

npm installnpm run dev

npm install
npm run dev

Git 操作

git initgit add .git commit -m "init"git push origin main

git init
git add .
git commit -m "init"
git push origin main

```bash terminal title="安装依赖"
npm install
npm run dev
```

```bash terminal title="Git 操作" linenos
git init
git add .
git commit -m "init"
git push origin main
```

title：终端窗口标题
linenos：显示行号
highlight：高亮指定行号

代码面板（panel）

将多个相关代码块或文字段落放入同一个面板中并列展示。每段有独立的左侧标签和右侧说明，支持每段单独复制。

适用于多语言代码对比、前后端配对、请求与响应、多环境配置对比、文字内容分段等场景。

代码块模式文字内容模式示例代码

发送端

Objective-C

+ (void)test {
    [[NSNotificationCenter.defaultCenter
        postNotificationName:@"test" object:nil];
}

+ (void)test {
    [[NSNotificationCenter.defaultCenter
        postNotificationName:@"test" object:nil];
}

订阅端

Swift

func setup() {
    list.add(title: "test") { section in
        section.add(title: "设置 Observer") {
            NotificationCenter.default.addObserver(...)
        }
    }
}

func setup() {
    list.add(title: "test") { section in
        section.add(title: "设置 Observer") {
            NotificationCenter.default.addObserver(...)
        }
    }
}

精简版

1 分钟

创建项目只需一行命令：

bash

npx create-my-app

npx create-my-app

详细版

5 分钟

确保 Node.js ≥ 18
运行 npx create-my-app
按提示选择模板
进入目录运行 npm run dev

代码块模式：

:::panel
```objc title="发送端" right="Objective-C"
+ (void)test {
    [[NSNotificationCenter.defaultCenter
        postNotificationName:@"test" object:nil];
}
```

```swift title="订阅端" right="Swift"
func setup() {
    list.add(title: "test") { section in
        ...
    }
}
```
:::

文字内容模式：

:::panel

<!-- label: 精简版 | 1 分钟 -->
创建项目只需一行命令：

```bash
npx create-my-app
```

<!-- label: 详细版 | 5 分钟 -->
1. 确保 Node.js ≥ 18
2. 运行 `npx create-my-app`

:::

代码块模式：title → 左侧标签，right → 右侧说明；未指定 title 时使用语言名作为左侧标签
文字内容模式： 用 | 分隔左右标签；省略 | 及之后内容则只有左侧标签
两种模式可以在同一个 panel 中混合使用
鼠标悬停在段落上，右侧显示 Copy 按钮，点击可复制该段代码

私密内容（private）

将敏感内容放入加密容器，读者需要输入正确密码才能查看。支持密码提示和重新锁定。

演示效果示例代码

私密内容

此内容已加密，请输入密码查看

提示：主题名称

密码错误，请重试

:::private{password="vergil" hint="主题名称"}
这是加密的内容，只有知道密码的人才能看到。

- API 密钥：`sk-xxxxxxxxx`
- 数据库密码：`my-secret-pass`
:::

password（必填）：解密密码
hint（可选）：密码提示，帮助读者回忆密码
支持段落、列表、代码块等任意 Markdown 内容
解密后显示 重新锁定 按钮，可再次隐藏内容
采用 AES-CBC + PBKDF2 加密，密码不会存储在页面中

音频播放器（audio）

在文章中插入音频，支持本地音频、网易云音乐和语音消息三种模式。

标准播放器网易云音乐语音消息

SoundHelix Song 1

T. Schürger

00:00

写法：

:::audio{src="https://example.com/music.mp3" title="歌曲名" artist="艺术家" cover="https://..."}
:::

src（必填）：音频文件地址
title：歌曲标题
artist：艺术家
cover：封面图 URL（可选）
align：对齐方式，可选 left（默认）、center、right
width：自定义宽度，如 width="400px"

居中对齐：

SoundHelix Song 1

T. Schürger

00:00

自定义宽度：

SoundHelix Song 1

T. Schürger

00:00

写法：

:::audio{netease="25706282" title="晴天" artist="周杰伦"}
:::

netease（必填）：网易云音乐歌曲 ID
从网易云音乐网页版分享链接中获取歌曲 ID
align：对齐方式，可选 left（默认）、center、right
width：自定义宽度，如 width="400px"

15"

写法：

:::audio{voice="https://example.com/voice.mp3" duration="15"}
:::

voice（必填）：语音文件地址
duration：语音时长（秒），用于显示波形长度
align：对齐方式，可选 left（默认）、center、right
width：自定义宽度，如 width="400px"

视频播放器（video）

在文章中插入视频，支持本地视频、Bilibili 和 YouTube 三种模式。本地视频支持画中画（PiP）浮动播放器。

本地视频（带封面）

演示效果示例代码

:::video{src="https://example.com/video.mp4" poster="https://example.com/poster.jpg" ratio="16/9"}
:::

src（必填）：视频文件地址
poster：封面图，显示自定义播放按钮覆盖层，点击后播放
ratio：宽高比，默认 16/9，可选 4/3、1/1
width：最大宽度，如 width="600px"
align：对齐方式，可选 left（默认）、center、right
autoplay：true 自动播放（静音）
pip：画中画模式，可选 auto（默认，滚动离开自动触发）、manual（手动触发）、off（关闭）

本地视频（原生 controls）

不指定 poster 时，直接使用原生 <video controls> 播放器。

演示效果示例代码

:::video{src="https://example.com/video.mp4" ratio="16/9"}
:::

不指定 poster 时，使用原生浏览器播放器控件
其他参数与带封面模式相同

本地视频（画中画 auto）

视频播放中向下滚动离开视口时，自动弹出右下角浮动播放器。

演示效果示例代码

:::video{src="..." poster="..." ratio="16/9" pip="auto"}
:::

pip="auto"（默认）：播放中离开视口自动进入画中画
浮动播放器支持拖动、播放/暂停、进度跳转
点击 ↩ 回到原位并恢复播放，点击 × 直接关闭

本地视频（画中画 manual）

不自动触发，鼠标悬停视频右上角显示画中画按钮，点击后手动进入浮动播放。

演示效果示例代码

:::video{src="..." poster="..." ratio="16/9" pip="manual"}
:::

pip="manual"：鼠标悬停时右上角显示画中画按钮，点击手动触发
适合不希望自动打扰读者的场景

本地视频（居中对齐）

演示效果示例代码

:::video{src="..." poster="..." align="center" width="500px" ratio="4/3"}
:::

align="center"：视频容器居中对齐
width="500px"：限制最大宽度
ratio="4/3"：4
宽高比

Bilibili

演示效果示例代码

:::video{bilibili="BV1GJ411x7h7"}
:::

bilibili（必填）：B 站 BV 号
ratio、width、align 与本地视频相同
不支持画中画（iframe 内视频无法控制）

YouTube

演示效果示例代码

:::video{youtube="jfKfPfyJRdk"}
:::

youtube（必填）：YouTube 视频 ID
autoplay：true 自动播放（自动静音，符合 YouTube 策略）
ratio、width、align 与本地视频相同
不支持画中画

复制块（copy）

带一键复制按钮的代码块，方便读者复制命令或代码。

演示效果示例代码

安装依赖

SSH 密钥

Docker 命令

:::copy{label="安装依赖"}
pnpm add remark-directive unist-util-visit
:::

:::copy{label="SSH 密钥"}
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleKey example@example.com
:::

:::copy{label="Docker 命令"}
docker run -d -p 3000:3000 --name myapp myimage:latest
:::

label：左侧标签文字，说明代码用途
内容区域会被处理为一行纯文本，点击右侧按钮即可复制

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" 为小尺寸模式