内容指令

内容指令是 Vergil 在 Markdown 基础上扩展的一组语法，用于在文章中插入更丰富的元素，比如提示框、图片画廊、标签页等。

什么是指令

指令是包裹在特殊标记中的内容块。Vergil 基于 remark-directive 规范实现，支持三种形式：

形式	标记	用途
行内指令	:	嵌入段落中的文字装饰，如 :mark[高亮]
块级指令	:::	独占一行的内容块，如提示框、折叠面板
容器指令	:::: 或更多	包含其他指令的容器，如标签页、网格

语法规则

• 行内指令：:指令名[内容]{属性}
• 块级指令：以 ::: 开头和结尾，中间是内容
• 容器指令：外层冒号数量 必须严格大于 内层。例如 :::: 包 :::，::::: 包 ::::

块级指令示例

:::callout{variant="tip"}
这是一个提示框，用来强调重要信息。
:::

效果：

嵌套容器指令

当指令内部需要包含其他指令时，外层使用更多冒号。规则很简单：外层冒号 > 内层冒号。

两层嵌套（:::: 包 :::）—— 最常用的形式，如标签页：

::::tabs
:::tab{label="选项一"}
选项一的内容
:::
:::tab{label="选项二"}
选项二的内容
:::
::::

三层嵌套（::::: 包 :::: 包 :::）—— 例如网格内放标签页：

:::::grid{cols=2}
::::grid-cell
:::callout{variant="tip"}
单元格内的提示框
:::
::::
::::grid-cell
:::callout{variant="note"}
另一个单元格
:::
::::
:::::

行内指令示例

这是一段文字，其中 :mark[关键内容] 被高亮显示。

效果：

这是一段文字，其中 关键内容 被高亮显示。

指令分类

Vergil 提供 30+ 个指令，按用途分为三类：

结构排版

用于组织文章版面：

• 网格（grid） — 多列布局
• 标签页（tabs） — 切换面板
• 折叠面板（folding） — 可展开收起的内容
• 时间线（timeline） — 时间顺序列表
• 横幅（banner） — 顶部大图
• 标题装饰（title） — 美化标题
• 诗词排版（poetry） — 传统诗词格式
• 信纸（paper） — 信纸样式
• 卷轴（reel） — 垂直滚动文字

内容展示

用于插入提示信息、图片、代码和链接：

• 提示框（callout） — 信息/警告/提示
• 高亮块（note） — 主题色高亮
• 引用卡片（quot） — 引用展示
• 段落引号（blockquote） — 带引号的段落
• 增强图片（image） — 带说明和下载的图片
• 画廊（gallery） — 图片网格或瀑布流
• 摄影框（photo） — 带水印的摄影展示
• 终端块（terminal） — 终端样式代码块
• 复制块（copy） — 一键复制代码
• GitHub 卡片（ghcard） — 展示 GitHub 仓库或用户
• 海报墙（posters） — 友情链接展示
• 标签链接（hashtag） — 带样式的标签
• 按钮（button） — 链接按钮

文字与交互

用于美化文字和增加互动性：

• 高亮（mark） — 文字高亮
• 下划线（u） — 下划线
• 着重号（emp） — 着重号
• 波浪线（wavy） — 波浪下划线
• 删除线（del） — 删除线
• 上标（sup）/ 下标（sub） — 上下标
• 键盘按键（kbd） — 键盘按键样式
• 模糊显示（blur） — 点击显示隐藏内容
• 密码遮罩（psw） — 点击显示密码
• 复选框（checkbox） — 可勾选列表
• 单选框（radio） — 单选列表
• 步骤标记（step-brackets） — 步骤编号

使用建议

• 不要在一篇文章中使用过多指令，保持简洁
• 提示框（callout）适合强调关键信息，但每篇文章不超过 3 个
• 图片画廊（gallery）适合展示多张照片，单张图片直接用 Markdown 语法即可
• 折叠面板（folding）适合隐藏长代码或补充说明