内容指令
内容指令
内容指令是 Vergil 在 Markdown 基础上扩展的一组语法，用于在文章中插入更丰富的元素，比如提示框、图片画廊、标签页等。
什么是指令
指令是包裹在特殊标记中的内容块。Vergil 基于 remark-directive 规范实现，支持三种形式：
| 形式 | 标记 | 用途 |
|---|---|---|
| 行内指令 | : | 嵌入段落中的文字装饰，如 :mark[高亮] |
| 块级指令 | ::: | 独占一行的内容块，如提示框、折叠面板 |
| 容器指令 | :::: 或更多 | 包含其他指令的容器，如标签页、网格 |
语法规则
- 行内指令：
:指令名[内容]{属性} - 块级指令：以
:::开头和结尾，中间是内容 - 容器指令：外层冒号数量 必须严格大于 内层。例如
::::包:::，:::::包::::
块级指令示例
:::callout{type="tip"}
这是一个提示框，用来强调重要信息。
:::效果：
Tip
这是一个提示框，用来强调重要信息。
嵌套容器指令
当指令内部需要包含其他指令时，外层使用更多冒号。规则很简单：外层冒号 > 内层冒号。
两层嵌套（:::: 包 :::）—— 最常用的形式，如标签页：
::::tabs
:::tab{label="选项一"}
选项一的内容
:::
:::tab{label="选项二"}
选项二的内容
:::
::::三层嵌套（::::: 包 :::: 包 :::）—— 例如网格内放标签页：
:::::grid{cols=2}
::::grid-cell
:::callout{type="tip"}
单元格内的提示框
:::
::::
::::grid-cell
:::callout{type="info"}
另一个单元格
:::
::::
:::::Tip
记不住冒号数量？一个口诀：容器永远比内容多一个冒号。要包 ::: 就用 ::::，要包 :::: 就用 ::::: 。
行内指令示例
这是一段文字，其中 :mark[关键内容] 被高亮显示。效果：
这是一段文字，其中 关键内容 被高亮显示。
指令分类
Vergil 提供 30+ 个指令，按用途分为六类：
结构排版（9个指令）
用于组织文章版面：
- 网格（grid） — 多列布局
- 标签页（tabs） — 切换面板
- 折叠面板（folding） — 可展开收起的内容
- 多级折叠（folders） — 多个可折叠的文件夹式分组
- 时间线（timeline） — 时间顺序列表
- 横幅（banner） — 顶部大图
- 诗词排版（poetry） — 传统诗词格式
- 信纸（paper） — 信纸样式
- 卷轴（reel） — 垂直滚动文字
内容展示（9个指令）
用于插入提示信息、代码和私密内容：
- 提示框（callout） — 信息/警告/提示
- 高亮块（note） — 主题色高亮
- 引用卡片（quot） — 引用展示
- 标题装饰 / 强调引用（title） — 引号或徽章样式的装饰标题
- 段落引号（blockquote） — 带引号的段落
- 终端块（terminal） — 终端样式代码块
- 代码面板（panel） — 多段并列展示
- 复制块（copy） — 一键复制代码
- 私密内容（private） — 加密容器
媒体嵌入（5个指令）
用于插入图片、画廊、视频和音频：
- 增强图片（image） — 带说明和下载的图片
- 画廊（gallery） — 图片网格或瀑布流
- 摄影框（photo） — 带水印的摄影展示
- 视频播放器（video） — 本地/Bilibili/YouTube
- 音频播放器（audio） — 本地/网易云/语音
卡片与链接（6个指令）
用于展示外部信息和交互链接：
- GitHub 卡片（ghcard） — 展示 GitHub 仓库或用户
- 数字名片（yoicard） — 作者署名/关于我
- 网站卡片（sites） — 网站收藏网格展示
- 海报墙（posters） — 竖向海报/封面网格
- 标签链接（hashtag） — 带样式的标签
- 按钮（button） — 链接按钮
文字与交互（14个指令）
用于美化文字和增加互动性：
- 高亮（mark） — 文字高亮
- 下划线（u） — 下划线
- 着重号（emp） — 着重号
- 波浪线（wavy） — 波浪下划线
- 删除线（del） — 删除线
- 上标 / 下标（sup/sub） — 上下标
- 键盘按键（kbd） — 键盘按键样式
- 模糊显示（blur） — 点击显示隐藏内容
- 密码遮罩（psw） — 点击显示密码
- 复选框（checkbox） — 可勾选列表
- 单选框（radio） — 单选列表
- 步骤标记（step-brackets） — 步骤编号
- 表情包（emoji） — 插入各种表情包
图表可视化（2个指令）
用于插入流程图和数据可视化图表：
- Mermaid 图表（mermaid） — 流程图、时序图等
- ECharts 图表（echart） — 数据可视化图表
数学公式
LaTeX 数学公式渲染，通过 frontmatter 选择引擎：
- 引擎选择 — KaTeX 与 MathJax 的对比与选择
使用建议
- 不要在一篇文章中使用过多指令，保持简洁
- 提示框（callout）适合强调关键信息，但每篇文章不超过 3 个
- 图片画廊（gallery）适合展示多张照片，单张图片直接用 Markdown 语法即可
- 折叠面板（folding）适合隐藏长代码或补充说明