媒体嵌入（5个指令）
媒体嵌入指令（5个指令）
用于在文章中插入图片、画廊、视频和音频。
增强图片（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（必填）：图片地址，支持@img/、相对路径和外链，本地图片构建时会被优化alt：图片描述，会显示在图片下方作为 captionwidth/height：设置图片尺寸ratio：固定宽高比，如1/1、16/9download：true或自定义下载链接，显示下载按钮fancybox：false可禁用点击放大
画廊（gallery）
图片网格或瀑布流展示，适合多张图片的排版。
瀑布流：按图片原始比例错落排列。
固定比例：统一裁成正方形。
:::gallery{layout="grid"}
:::
<!-- 瀑布流 -->
:::gallery{layout="flow"}
...
:::
<!-- 统一裁成正方形 -->
:::gallery{layout="grid" ratio="square"}
...
:::layout：grid（网格，默认）或flow（瀑布流）size：xs|s|m|l|xl|mix，控制图片尺寸ratio：square|portrait|origin，固定图片比例，origin保持原始比例
摄影框（photo）
展示单张摄影作品，底部一栏显示相机品牌和拍摄参数。有两种样式：模糊背景（默认）和白边水印。
<!-- 模糊背景：照片居中，四周是它自己的模糊放大 -->
::photo{src="@img/blog/my-post/a.jpg" brand="Fujifilm" focal="23mm" aperture="f/8" shutter="1/250s" iso="ISO 160"}
<!-- 白边水印：照片下方一条白边，左边品牌型号，中间品牌 Logo，右边参数和时间 -->
::photo{src="@img/blog/my-post/b.jpg" type="watermark" brand="Sony" model="α7 IV" focal="35mm" aperture="f/2.8" shutter="1/125s" iso="ISO 400" datetime="2026.09.20"}| 属性 | 默认值 | 说明 |
|---|---|---|
src | — | 必填，图片地址，支持 @img/、相对路径和外链，本地图片构建时会被优化 |
alt | — | 图片描述 |
type | blur | 样式：blur 模糊背景，watermark 白边水印 |
brand | — | 相机品牌，如 Fujifilm、Sony、Canon。常见品牌会显示 Logo |
logo | 同 brand | 想显示的 Logo 和品牌名不一样时单独指定 |
model | — | 机型，只在 watermark 样式显示 |
focal、aperture、shutter、iso | — | 焦距、光圈、快门、感光度，原样显示，按这个顺序排成一行 |
datetime | — | 拍摄时间，原样显示，只在 watermark 样式显示 |
fancybox | 开 | 写 fancybox="false" 关闭点击放大 |
音频播放器（audio）
在文章中插入音频，支持本地音频、网易云音乐和语音消息三种模式。
00:0000:00
写法：
:::audio{src="https://example.com/music.mp3" title="歌曲名" artist="艺术家" cover="https://..."}
:::src（必填）：音频文件地址title：歌曲标题artist：艺术家cover：封面图（可选），支持@img/、相对路径和外链，本地图片构建时会被优化align：对齐方式，可选left（默认）、center、rightwidth：自定义宽度，如width="400px"
居中对齐：
00:0000:00
自定义宽度：
00:0000:00
卡片模式（带封面）：
写法：
:::audio{netease="25706282" title="晴天" artist="周杰伦"}
:::
:::audio{netease="25706282" title="晴天" artist="周杰伦" mode="card"}
:::netease（必填）：网易云音乐歌曲 ID- 从网易云音乐网页版分享链接中获取歌曲 ID
mode：mini（默认，窄条）或card（带封面的大卡片）align：对齐方式，可选left（默认）、center、rightwidth：自定义宽度，如width="400px"
15"
写法：
:::audio{voice="https://example.com/voice.mp3" duration="15"}
:::voice（必填）：语音文件地址duration：语音时长（秒），用于显示波形长度align：对齐方式，可选left（默认）、center、rightwidth：自定义宽度，如width="400px"
视频播放器（video）
在文章中插入视频，支持本地视频、Bilibili 和 YouTube 三种模式。本地视频支持画中画（PiP）浮动播放器。
本地视频（带封面）
:::video{src="https://example.com/video.mp4" poster="https://example.com/poster.jpg" ratio="16/9"}
:::src（必填）：视频文件地址poster：封面图，显示自定义播放按钮覆盖层，点击后播放。支持@img/、相对路径和外链，本地图片构建时会被优化ratio：宽高比，默认16/9，任意宽/高都行，如4/3、1/1、9/16width：最大宽度，如width="600px"align：对齐方式，可选left（默认）、center、rightautoplay：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:3 宽高比
Bilibili
:::video{bilibili="BV1GJ411x7h7"}
:::bilibili（必填）：B 站 BV 号ratio、width、align与本地视频相同- 不支持画中画（iframe 内视频无法控制）