内容 Tag 插件

本页汇总 matery 主题的 13 个内容 tag 插件：note 便签、timeline 时间线、tabs 标签页、label 行内标签、button 按钮、githubCard GitHub 卡片、mermaid 图表、pdf 嵌入、insertmd 片段插入、wechat_dialog 微信对话、groupimage 分组图片、cardurl URL 卡片、admonition 容器。每个插件给出用途、语法、示例、效果，示例可直接复制到文章测试。

与「布局与页面」的行内加粗标签风格不同，本页因需容纳代码块与真实渲染示例，采用三级子标题（用途/语法/示例/效果）分隔。前 12 个为主题原生注册的 tag（themes/matery/scripts/tags/index.js 统一注册），admonition 由 markdown-it-container 插件提供（根 _config.yml 注册 7 种容器：warning/note/info/attention/error/tip/hint）。
注意：在 Markdown 代码块中展示 {% xxx %} 这类 tag 语法时，必须用 raw 标签包裹（raw 与 endraw 成对），否则 nunjucks 会预渲染导致构建报 unknown block tag。

1. 便签 note

用途

文章内的彩色提示块，用于警示 / 成功 / 信息 / 危险等强调内容。

语法

{% note 颜色 %}内容{% endnote %}

• 颜色（可选，默认 default）：default / primary / success / info / warning / danger 共 6 色
• 别名：{% subnote %}
• 进阶：颜色后可加 no-icon 隐藏左侧图标；再加 @摘要标题 生成可折叠块

示例

可折叠版本：

效果

彩色圆角卡片，左侧色条 + 图标（成功 ✓ / 警告 ⚠ / 危险 ✕），明暗模式自适应。

2. 时间线 timeline

用途

按时间顺序展示事件 / 版本记录 / 成长历程。

语法

{% timeline 标题,颜色 %}
<!-- timeline 时间节点 -->
- 事件内容（支持 Markdown）
<!-- endtimeline -->
{% endtimeline %}

• 标题：时间线整体标题（支持 Markdown）
• 颜色（可选）：green / blue / red / orange 等，作为类名追加到 .timeline
• 时间节点：<!-- timeline 日期 --> 分隔每个事件，节点标题同样支持 Markdown

示例

效果

垂直时间线 + 圆点标记，支持颜色主题，标题用 Markdown 渲染。

3. 标签页 tabs

用途

多标签内容切换，适合分类展示 / 步骤说明 / 对比内容。

语法

{% tabs 唯一名称,激活序号 %}
<!-- tab 标签标题 -->
内容（支持 Markdown 和内联 tag）
<!-- endtab -->
{% endtabs %}

• 唯一名称：必填，用于生成 id（空格转 -）
• 激活序号：可选，省略或 0 激活第一个；N 激活第 N 个
• 标签标题：<!-- tab 标题 --> 定义每个标签；标题可用 @图标 追加 Font Awesome 图标（如 @fas:home，prefix 支持 fas/far/fal/fad/fab）

示例

效果

Materialize tabs 风格，点击切换，激活标签高亮，内容区独立渲染 Markdown。

4. 行内标签 label

用途

行内彩色小标签，用于关键词 / 状态 / 分类标注。

语法

{% label 颜色@文字 %}

• 颜色（可选，默认 default）：default / primary / success / info / warning / danger
• ★ 注意参数顺序：颜色在 @ 前，文字在 @ 后（源码按 split('@') 解析，与直觉相反）

示例

效果

行内圆角彩色标签，文字白底或彩色背景。

5. 按钮 button

用途

文章内 CTA 按钮，用于跳转 / 下载 / 操作入口。

语法

{% button 链接,文字,图标,title %}

• ★ 链接在第一个参数（源码 url=args[0]、text=args[1]）
• 链接：必填，跳转 URL（可相对路径 /）
• 文字：按钮显示文字
• 图标（可选）：Font Awesome 图标名（如 home、github，自动补 fa fa- 前缀；也可直接写 fa fa-home）
• title（可选）：hover 提示文字（非颜色！）
• 别名：{% btn %}

示例

效果

Materialize 风格按钮，带图标 + 波浪点击效果。

6. GitHub 卡片 githubCard

用途

展示 GitHub 仓库信息卡片（仓库名 / 简介 / 星标 / 分支数）。

语法

{% githubCard user:用户名 repo:仓库名 %}

• user：必填，GitHub 用户名（缺省输出错误提示）
• repo：仓库名
• 可选参数：width / height（尺寸，自动去 px 后缀）、theme（非 default 才生效）、target（非 blank 才生效）、client_id（GitHub OAuth client_id；出于安全不支持 client_secret）

示例

效果

仓库卡片：仓库名 + 简介 + 星标 / 分支数，点击跳转仓库。依赖 GitHub API 懒加载（无 JS 时显示 noscript 提示，失败降级为链接）。

7. Mermaid 图表 mermaid

用途

渲染 Mermaid 图表（流程图 / 时序图 / 类图等）。

Front-matter 配置（重要）

使用前必须在文章 front-matter 声明，否则 Mermaid JS 不加载、图表不渲染：

mermaid: true

（主题 post.mermaid.enable: true 已默认开启；specific: true 模式下仅声明了 mermaid: true 的文章才加载 Mermaid JS。暗色模式自动适配。）

语法

{% mermaid %}
graph TD
    A --> B
{% endmermaid %}

示例：流程图（graph）

graph TD
    A[构建] --> B{测试}
    B -->|通过| C[部署]
    B -->|失败| D[修复]
    D --> B
    C --> E[监控]

示例：时序图（sequenceDiagram）

sequenceDiagram
    participant U as 用户
    participant S as 服务器
    participant D as 数据库
    U->>S: 发起请求
    S->>D: 查询数据
    D-->>S: 返回结果
    S-->>U: 响应页面

示例：类图（classDiagram）

classDiagram
    class 用户 {
        +String 姓名
        +登录()
    }
    class 博客 {
        +String 标题
        +发布()
    }
    用户 --> 博客

效果

Mermaid 渲染为 SVG 图表，暗色模式自适应（主题已适配）。

8. PDF 嵌入 pdf

用途

文章内嵌 PDF 文件查看器。

语法

{% pdf 文件URL %}

• 文件URL：PDF 文件地址（本地或远程）
• 自动类型检测：docs.google.com → Google Docs 预览；slideshare.net → Slideshare 嵌入；其他 → <embed> PDF 查看器

示例

{% pdf /doc/Linux学习笔记.pdf %}

示例使用站点已有的真实 PDF（/doc/Linux学习笔记.pdf），你也可以替换为任意本地或远程 PDF 地址。

效果

PDF.js 查看器（翻页 / 缩放 / 下载），默认高度 600px，响应式适配。

9. 插入片段 insertmd

用途

插入 source/ 下的 Markdown 模板片段，实现内容复用（异步渲染，支持子目录递归）。

语法

{% insertmd '路径/文件名.md' %}

• 路径：相对 source/ 目录（如 _template/disclaimer.md）
• 目录：传目录则递归收集所有 .md 文件（字母排序）合并渲染
• 分隔符：第二参数可选，渲染为 Markdown 分隔内容
• 路径不存在 → 构建日志报 error 并输出空串

示例

{% insertmd '_template/disclaimer.md' %}

效果

将模板片段内容渲染到当前位置（内容可嵌套其他 tag 插件）。

10. 微信对话卡片 wechat_dialog

用途

渲染微信聊天界面卡片，用于对话示例 / 客服场景。

语法（★ 必须是 User: / Assistant: 行格式）

{% wechat_dialog %}
User: 用户说的话
Assistant: AI/客服的回复
{% endwechat_dialog %}

• 行格式：User: 开头 = 右侧用户气泡（绿色）；Assistant: 开头 = 左侧助手气泡（灰色）
• 支持：多行内容、Markdown 渲染（加粗 / 列表等）
• 别名：{% wd %} 等价于 {% wechat_dialog %}

示例

你好，我想了解 matery 主题

好的，有什么可以帮您？

主题支持哪些功能？

内容 tag、相册、搜索、评论等 20+ 功能

效果

微信风格气泡对话，左右分列，头像 + 气泡（头像路径硬编码于主题）。

11. 分组图片 groupimage

用途

将多张图片按行列网格布局展示（自动分列布局）。

语法

{% groupimage 数量 布局 %}
![图片说明1](图片URL1)
![图片说明2](图片URL2)
{% endgroupimage %}

• 数量：图片张数（2–10，超过 10 回退每行 3 张）
• 布局（可选）：每行张数，- 分隔（如 2-1 表示第一行 2 张、第二行 1 张；各数之和必须等于数量，否则回退默认布局）
• 图片：用标准 Markdown 图片语法写在标签体内
• 别名：{% gi %} 等价于 {% groupimage %}

默认布局：2→1,1 3→2,1 4→2,2 5→3,2 6→3,3 7→3,2,2 8→3,2,3 9→3,3,3 10→3,2,2,3

示例（3 张图，2+1 布局）

效果

图片网格布局（按布局分列），hover 放大。

12. URL 卡片 cardurl

用途

展示链接的摘要卡片（标题、描述、图标），用于推荐链接 / 引用资源。

语法

{% cardurl [url=目标链接] [title=标题] [desc=描述] [avatar=图标URL] %}

• 参数：方括号 [key=value] 格式
  • url 必填，目标链接（缺省时 title 回退为 url）
  • title 可选，卡片标题
  • desc 可选，描述文字
  • avatar 可选，图标图片 URL（有则显示左侧图标）

示例

效果

链接卡片：站点图标 + 标题 + 描述，点击跳转。

13. 容器 admonition（markdown-it-container）

用途

用 ::: 类型 语法渲染提示容器（warning / note / info / attention / error / tip / hint），区别于 note tag——由 markdown-it-container 插件实现（根 _config.yml 注册，无需 front-matter）。

语法

::: warning
*这里放警示内容*
:::

• 类型：warning / note / info / attention / error 共 5 种，对应语义色（warning=橙色 / note=绿色 / info=蓝色 / attention=橙色 / error=红色）

示例

效果

带左侧色条 + 淡色背景的提示容器（div.warning 等类），明暗模式自适应。

附：tag 插件速查表

常见坑：

• 代码块内展示 {% xxx %} 语法必须用 raw 标签包裹，否则构建报 unknown block tag
• label 颜色在 @ 前、文字在 @ 后；button 链接在第一个参数
• mermaid 忘记 front-matter mermaid: true 时图表不渲染（specific 模式）
• wechat_dialog 只认 User: / Assistant: 行格式，不是行内参数
• 构建失败时先看构建日志有无 Nunjucks Error，再检查对应 tag 语法