输入关键词,开始搜索

↑↓ 选择↵ 打开esc 关闭
沉浸

内容指令

内容指令

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

什么是指令

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

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

语法规则

  • 行内指令::指令名[内容]{属性}
  • 块级指令:以 ::: 开头和结尾,中间是内容
  • 容器指令:外层冒号数量 必须严格大于 内层。例如 :::: 包 :::,::::: 包 ::::
  • 属性 {...} 写在开头那一行,属性再多也不能换行,换行会让整个指令失效、原样显示成文字

块级指令示例

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

效果:

Tip

这是一个提示框,用来强调重要信息。

嵌套容器指令

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

两层嵌套(:::: 包 :::)—— 最常用的形式,如标签页里放提示框:

::::tabs
tab: 选项一

:::callout{type="tip"}
选项一里的提示框
:::

tab: 选项二

选项二的内容
::::

三层嵌套(::::: 包 :::: 包 :::)—— 例如网格内放标签页,格子之间用 --- 分隔:

:::::grid{cols="2"}
::::tabs
tab: 安装

:::callout{type="tip"}
推荐用 pnpm
:::

tab: 运行

在项目目录执行 `pnpm dev`
::::

---

:::callout{type="info"}
另一个格子
:::
:::::
Tip

记不住冒号数量?一个口诀:容器永远比内容多一个冒号。要包 ::: 就用 ::::,要包 :::: 就用 :::::。

行内指令示例

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

效果:

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

指令分类

Vergil 提供 51 个指令,按用途分为八类:

结构排版(9个指令)

用于组织文章版面:

内容展示(8个指令)

用于插入提示信息、代码和私密内容:

媒体嵌入(5个指令)

用于插入图片、画廊、视频和音频:

卡片与链接(6个指令)

用于展示外部信息和交互链接:

文字与交互

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

图表可视化(2个指令)

用于插入流程图和数据可视化图表:

时间规划(4个指令)

用于时间管理、任务规划和目标跟踪:

可视化叙事(2个指令)

用于故事叙述和思维整理:

数学公式

LaTeX 数学公式渲染,通过 frontmatter 选择引擎:

使用建议

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