基本用法#

1
::btn{href="https://example.com" text="点我"}

渲染效果：

参数说明#

href 只接受 http(s) 与站内相对路径。像 javascript: 这类协议会被直接拒绝，不会渲染出按钮——这是为了防止在文章里埋入可执行脚本。

样式变体#

四个变体放在一起对比：

图标#

icon 支持以下取值（也支持包含这些关键字的其他写法，如 icon="fa-download" 会被识别为下载图标）：

实际效果：

其它用法#

新窗口打开

独占一行（移动端尤其有用）

指向站内文件

1
::btn{href="/downloads/demo.zip" text="下载示例包" variant="primary" icon="download"}

基本用法#

1
::video{platform="bilibili" bvid="BV1fK4y1s7Qf" title="示例视频"}

交互说明：视频默认不自动加载播放器。页面上先显示「封面 + 播放按钮」， 点一下按钮才会真正加载 B 站 / YouTube 播放器并自动开播。这样首屏更轻、 也不会出现「看不到播放按钮 / B 站登录弹窗挡住」的问题。 B 站封面会在构建时自动抓取；也可以用 poster 指定自定义封面。

参数说明#

三种来源#

① B 站 — 给 bvid 即可

1
::video{platform="bilibili" bvid="BV1fK4y1s7Qf" title="B 站视频"}

② YouTube — 给 id 即可

1
::video{platform="youtube" id="5gIf0_xpFPI" title="YouTube 视频"}

③ 第三方嵌入地址 — 直接给 src

1
::video{src="https://www.youtube.com/embed/5gIf0_xpFPI" title="直接给嵌入地址"}

本地视频文件#

把视频放进 public/videos/ 目录，用 src 指向它：

1
::video{src="/videos/demo.mp4" title="本地视频示例"}

也可以指定封面与宽高比：

1
::video{src="/videos/demo.mp4" title="4:3 视频" poster="/images/cover.avif" ratio="4/3"}

本地视频需要你自己把文件放进 public/videos/ 目录，仓库里没有预置样例视频， 所以这里只给代码示例，不做实际渲染演示。

关于宽高比#

播放器外层是一个固定宽高比的容器，宽度跟随正文栏，高度按比例自动缩放。这样在窄屏下播放器不会被压扁——这一点比直接写 width="100%" height="468" 要好得多，后者会导致手机端高度写死、宽度被压缩，画面比例直接变形。

默认是 16/9，竖屏视频可以改成 9/16：

1
::video{src="/videos/vertical.mp4" title="竖屏视频" ratio="9/16"}

用法#

1
::gallery
2
![说明文字1](images/01.avif)
3
![说明文字2](images/02.avif)
4
![说明文字3](images/03.avif)
5
::

说明#

指令必须独占一行#

::btn{...} 和 ::video{...} 都要单独占一行，前后留空行。写在句子中间会被当成普通文本。

1
正确：
2

3
::btn{href="https://example.com" text="点这里"}
4

5
错误：
6

7
请点 ::btn{href="https://example.com" text="这里"} 前往

参数值里的引号#

所有参数值都要用英文双引号包起来。值里不能再出现双引号。

属性的顺序无所谓#

::btn{text="点我" href="https://example.com"} 和 ::btn{href="https://example.com" text="点我"} 等价。