本文既是 matery 主题内容 tag 插件的完整使用教程，也是 自动化测试靶场。主题原生注册的 tag 见
themes/matery/scripts/tags/（index.js 统一注册）。自动化测试会断言下方标注的渲染标记。
1. 便签 note
用途
文章内的彩色提示块，用于警示/成功/信息/危险等强调内容。
语法
{% note 颜色 %}内容{% endnote %}- 颜色（可选，默认 default）：
default/primary/success/info/warning/danger - 别名：
{% subnote %}（次级便签）
全部颜色示例
default 默认便签——普通提示
primary 主要便签——重点强调
success 成功便签——操作完成提示
info 信息便签——补充说明
warning 警告便签——注意事项
danger 危险便签——严重警告
实现效果
彩色圆角卡片，左侧色条 + 图标（成功 ✓ / 警告 ⚠ / 危险 ✕）。
测试断言：页面含
class="note标记（6 种颜色各 1 处）。
2. 时间线 timeline
用途
按时间顺序展示事件/版本记录/成长历程。
语法
{% timeline 标题,颜色 %}
<!-- timeline 时间节点 -->
- 事件内容（支持 Markdown）
<!-- endtimeline -->
{% endtimeline %}- 标题：时间线整体标题
- 颜色（可选）：
green/blue/red/orange等 - 时间节点：
<!-- timeline 日期 -->分隔每个事件
示例
主题功能演进记录
2026-08
- 新增内容 tag 测试页（note/timeline/tabs/label 等完整教程）
- 相册数据重构（galleries.yml 三种形式）
- 统一 lightGallery 图像查看库
2026-07
- 评论区架构优化（comment: waline）
- 修复 href=/ MIME 样式错误
实现效果
垂直时间线 + 圆点标记，支持颜色主题，标题用 Markdown 渲染。
测试断言：页面含
timeline标记 + 3 个时间节点。
3. 标签页 tabs
用途
多标签内容切换，适合分类展示/步骤说明/对比内容。
语法
{% tabs 唯一名称,激活序号 %}
<!-- tab 标签标题 -->
内容（支持 Markdown 和内联 tag）
<!-- endtab -->
{% endtabs %}- 唯一名称：必填，用于生成 id（空格转
-） - 激活序号：可选，默认 1（第一个标签激活）
- 标签标题：
<!-- tab 标题 -->定义每个标签
示例（默认激活第一个）
- 功能全面：内容 tag 覆盖 10+ 插件
- 配置灵活：每个功能可独立开关
- 性能优化：懒加载 + 占位防 CLS
- 配置项多，上手有学习成本
- 部分功能依赖外部 CDN
- 技术博客：代码/教程/对比
- 个人博客：相册/项目/历程
实现效果
Materialize tabs 风格，点击切换，激活标签高亮。
测试断言：页面含
nav-tabs标记 + 3 个标签。
4. 行内标签 label
用途
行内彩色小标签，用于关键词/状态/分类标注。
语法
{% label 颜色@文字 %}- 颜色（可选，默认 default）：
default/primary/success/info/warning/danger - ★ 注意参数顺序：颜色在
@前，文字在@后（源码split('@')，classes=args[0]、text=args[1]）
全部颜色示例
默认 主要 成功 信息 警告 危险实现效果
行内圆角彩色标签，文字白底或彩色背景。
测试断言：页面含
class="label标记（6 种颜色）。
5. 按钮 button
用途
文章内 CTA 按钮，用于跳转/下载/操作入口。
语法
{% button 链接,文字,图标,title %}- ★ 链接在第一个参数（源码
url=args[0]、text=args[1]），文字第二 - 链接：必填，跳转 URL（可相对路径
/） - 文字：按钮显示文字
- 图标（可选）：Font Awesome 图标名（如
home、github，自动补fa fa-前缀） - title（可选）：hover 提示文字（非颜色！）
- 别名：
{% btn %}
示例
返回首页 访问GitHub 关于我 纯文字按钮实现效果
Materialize 风格按钮，带图标 + 波浪点击效果。
测试断言：页面含
btn标记（≥4 个按钮）。
6. GitHub 卡片 githubCard
用途
展示 GitHub 仓库信息卡片（星标/分支/简介）。
语法
{% githubCard user:用户名 repo:仓库名 %}- user：必填，GitHub 用户名
- repo：必填，仓库名
- 可选参数（高级）：
width/height/theme/align
示例
实现效果
仓库卡片：仓库名 + 简介 + 星标/分支数，点击跳转仓库。依赖 GitHub API（失败时降级为链接）。
测试断言：页面含
github-card或仓库名链接标记。
7. Mermaid 流程图
用途
渲染 Mermaid 图表（流程图/时序图/类图等）。
Front-matter 配置（重要）
mermaid: true # 在文章 front-matter 中开启（否则 Mermaid 不渲染）同时需在主题 _config.yml 启用：
post:
mermaid:
enable: true语法
{% mermaid %}
graph TD
A --> B
{% endmermaid %}示例 1：流程图（graph）
graph TD
A[构建] --> B{测试}
B -->|通过| C[部署]
B -->|失败| D[修复]
D --> B
C --> E[监控]
示例 2：时序图（sequenceDiagram）
sequenceDiagram
participant U as 用户
participant S as 服务器
participant D as 数据库
U->>S: 发起请求
S->>D: 查询数据
D-->>S: 返回结果
S-->>U: 响应页面
示例 3：类图（classDiagram）
classDiagram
class 用户 {
+String 姓名
+登录()
}
class 博客 {
+String 标题
+发布()
}
用户 --> 博客
实现效果
Mermaid 渲染为 SVG 图表，暗色模式自适应（主题已适配）。
测试断言：页面含
class="mermaid"标记（≥3 个图表）。
8. PDF 嵌入 pdf
用途
文章内嵌 PDF 文件查看器。
语法
{% pdf 文件URL %}- 文件URL：PDF 文件地址（本地或远程）
示例
{% pdf /medias_webp/docs/sample.pdf %}实现效果
PDF.js 查看器（翻页/缩放/下载）。
测试断言：页面含 pdf 相关容器标记。
9. 插入片段 insertmd
用途
插入 source/_template/ 下的 Markdown 模板片段，实现内容复用。
语法
{% insertmd '文件名.md' %}- 文件名：
source/_template/下的文件名（含 .md）
示例
{% insertmd 'disclaimer.md' %}实现效果
渲染模板片段内容到当前位置（异步加载，支持嵌套）。
测试断言：渲染后含模板片段内容。
10. 微信对话卡片 wechat_dialog
用途
渲染微信聊天界面卡片，用于对话示例/客服场景。
语法
{% wechat_dialog %}
User: 用户说的话
Assistant: AI/客服的回复
{% endwechat_dialog %}- 行格式：
User:开头 = 右侧用户气泡；Assistant:开头 = 左侧助手气泡 - 支持：多行内容、Markdown 渲染（加粗/列表等）
- 别名：
{% wd %}等价于{% wechat_dialog %}
示例
你好，我想了解 matery 主题
好的，有什么可以帮您？
主题支持哪些功能？
内容 tag、相册、搜索、评论等 20+ 功能
实现效果
微信风格气泡对话，左右分列，头像+气泡。
测试断言：页面含微信对话容器标记（
.chat-container）。
11. 分组图片 groupimage
用途
将多张图片按行列网格布局展示（自动分列布局）。
语法
{% groupimage 数量 布局 %}
{% endgroupimage %}- 第一参数：图片数量（2-10）
- 第二参数（可选）：布局（如
2-1表示第一行 2 张、第二行 1 张） - 图片：用标准 Markdown 图片语法写在标签体内
- 别名：
{% gi %}等价于{% groupimage %}
示例（3 张图，2+1 布局）
实现效果
图片网格布局（2+1 分列），hover 放大。
测试断言：页面含
group-image容器标记。
12. URL 卡片 valkyrurl
用途
展示链接的摘要卡片（标题、描述、图标），用于推荐链接/引用资源。
语法
{% valkyrurl [url=https://example.com] [title=标题] [desc=描述] [avatar=图标URL] %}- 参数：方括号
[key=value]格式url必填，目标链接title可选，卡片标题（缺省用 url）desc可选，描述文字avatar可选，图标图片 URL
示例
实现效果
链接卡片：站点图标 + 标题 + 描述，点击跳转。
测试断言：页面含 URL 卡片容器标记（
.vkr-url-wrapper）。
13. 容器 admonition（markdown-it-container）
用途
通过 markdown-it-container 插件，用 ::: 语法渲染提示容器（warning/note/info 等）。
语法
::: warning
*这里放警示内容*
:::- 类型：
warning/note/info/attention/error等
示例
::: warning
这是一个 warning 容器——需要注意的内容！
:::
::: note
这是一个 note 容器——补充说明。
:::
::: info
这是一个 info 容器——信息提示。
:::
实现效果
带左侧色条 + 图标 + 淡色背景的提示容器。
测试断言：页面含
admonition容器标记。
附：tag 插件速查表
| 插件 | 语法 | 关键参数 | 是否需要 frontmatter |
|---|---|---|---|
| note | {% note 颜色 %}内容{% endnote %} | 6 色 | 否 |
| timeline | {% timeline 标题,颜色 %}...{% endtimeline %} | 标题/颜色 | 否 |
| tabs | {% tabs 名称,序号 %}...{% endtabs %} | 名称/序号 | 否 |
| label | {% label 颜色@文字 %} | 颜色在前文字在后 | 否 |
| button | {% button 链接,文字,图标,title %} | 链接第一/文字第二 | 否 |
| githubCard | {% githubCard user:xx repo:yy %} | user/repo | 否 |
| mermaid | {% mermaid %}...{% endmermaid %} | 图表类型 | 是（mermaid: true） |
{% pdf URL %} | URL | 否 | |
| insertmd | {% insertmd 'file.md' %} | 文件名 | 否 |
| wechat_dialog | {% wechat_dialog %}User:/Assistant: 行{% endwechat_dialog %} | User/Assistant 行 | 否 |
| groupimage | {% groupimage 数量 布局 %}{% endgroupimage %} | 数量/布局 | 否 |
| valkyrurl | {% valkyrurl [url=xxx] %} | url/title/desc | 否 |
| admonition | ::: warning 内容 ::: | warning/note/info | 否 |
