Hexo主题功能测试-内容tag篇

本文既是 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 等
时间节点： 分隔每个事件

示例

主题功能演进记录

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（第一个标签激活）
标签标题： 定义每个标签

示例（默认激活第一个）

功能全面：内容 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 数量 布局 %}
![图片说明1](图片URL1)
![图片说明2](图片URL2)
{% endgroupimage %}

第一参数：图片数量（2-10）
第二参数（可选）：布局（如 2-1 表示第一行 2 张、第二行 1 张）
图片：用标准 Markdown 图片语法写在标签体内
别名：{% gi %} 等价于 {% groupimage %}

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

实现效果

图片网格布局（2+1 分列），hover 放大。

测试断言：页面含 group-image 容器标记。

12. URL 卡片 cardurl

用途

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

语法

{% cardurl [url=https://example.com] [title=标题] [desc=描述] [avatar=图标URL] %}

参数：方括号 [key=value] 格式
- url 必填，目标链接
- title 可选，卡片标题（缺省用 url）
- desc 可选，描述文字
- avatar 可选，图标图片 URL

示例

夜法之书-hexo仓库

个人独立blog源码，基于hexo搭建

实现效果

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

测试断言：页面含 URL 卡片容器标记（.card-url-wrapper）。

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

用途

通过 markdown-it-container 插件，用 ::: 语法渲染提示容器（warning/note/info 等）。

语法

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

类型：warning/note/info/attention/error 等

已废弃：原 {% admonition %} tag 形式已移除（tag 插件不存在）；提示块现由 markdown-it-container（:::）与 markdown-it-admon（!!!，见 Markdown 语法篇）提供。

示例

这是一个 warning 容器——需要注意的内容！

这是一个 note 容器——补充说明。

这是一个 info 容器——信息提示。

这是一个 attention 容器——注意警示。

这是一个 error 容器——严重错误。

实现效果

带左侧色条 + 图标 + 淡色背景的提示容器。

测试断言：页面含 admonition 容器标记。

14. 加密片段 tag（`{% encrypt %}`）

用途

文章内某段 markdown 内容加密，输入密码解密展开显示。每个片段独立密码，互不影响。

语法

{% encrypt 密码 "提示标题" "内容简介" %}
被加密的 markdown（可含内部 tag，如 note/timeline 等）
{% endencrypt %}

参数	必填	作用
密码	✅	解密密码（Hexo 自动去引号）
标题（第二个引号参数）	❌	加密块提示语（显示在密码框上方）
简介（第三个引号参数）	❌	密码输入框占位（显示在输入框）

示例（本测试片段）

私有内容

实现效果

渲染后该片段变为加密容器（密码框），输入 test-secret 解密展开
内部 tag 支持：片段内可嵌套 {% note %} 等 tag（方案 Y：after_post_render 二次渲染，实测通过）
无明文泄漏：渲染后的 HTML 不含片段明文（加密发生在最终 HTML）
免重输：解密后 1 天内刷新免密（存派生 dk 非密码，TTL 机制）

自动化测试

集成测试 tools/tests/encrypt-integration.test.js（L2n）覆盖：S1 无明文泄漏 / I1 片段解密 / I1b 内部 note 渲染 / I1c markdown 粗体 / S2 dk 存储无密码。

Wiki 文档页（layout/wiki.ejs）支持整页加密：侧栏数据源（source/_data/docs-sidebar.yml）配置 encrypt_password 后，该 wiki 全部页面加密，输入密码解密渲染。

# source/_data/docs-sidebar.yml
encrypt_password: "你的密码"    # 必填，整站 wiki 加密
encrypt_message: 本文已加密      # 可选，提示语
encrypt_placeholder: 请输入密码   # 可选，输入框占位

跨页共享：解密后派生密钥（dk）存 localStorage，同 wiki 其他页面自动解密，无需重复输入。

测试断言：L2y（wiki 加密页解密）+ L8 8c（加密 wiki 可访问）。

解密后统一刷新

加密内容解密后，正文组件需重新初始化（解密前是密文，DOM 无这些元素）。统一触发点：hbe-bundle onSuccess 回调（文章/相册/wiki/片段共用），各监听器只保留特有处理；encrypt_ 前缀配置键在侧栏渲染时跳过（不显示为目录项）。

组件	解密后动作
代码块	`codeWidget()` 扫描新 pre 生成 toolbar
图片灯箱	`articleInit()` 包装 img → lightGallery
Mermaid	`events.refresh()` 重渲染（幂等）
布局	`refreshLayout()` 重排

详细表格见布局篇 §11「解密后统一刷新」。测试断言：L2y（解密后组件初始化）。

15. 数学公式（MathJax / KaTeX 双通道）

用途

正文 LaTeX 公式渲染 + 脑图内嵌公式，MathJax 与 KaTeX 双通道并存。

配置（根 `_config.yml` + 主题 `_config.yml`）

# 根 _config.yml：markdown-it-mathjax3（Node 端 SSR 输出 MathJax SVG）
markdown:
  plugins:
    - name: markdown-it-mathjax3
      options:
        tex:
          inlineMath: [['$', '$']]
          displayMath: [['$$', '$$']]
          processEscapes: true

# 主题 _config.yml：post.math 引擎（Fluid 风格，二选一）
post:
  math:
    enable: false          # 开启后文章默认可用
    specific: true         # true 时需 front-matter `math: true` 才启动
    engine: mathjax        # Options: mathjax | katex

engine: mathjax（默认）： $...$ 行内 / $$...$$ 块级（mathjax3 5.x 硬编码 $/$$，$...$ 不支持）
engine: katex：切换时注释掉 markdown-it-mathjax3、启用 texmath——支持 $...$ /$$...$$ + $...$/\[...\]（brackets 需独立成块），前端加载 KaTeX CSS（SSR 已渲染无需 JS）
markmap 脑图内嵌公式：hexo_markmap.features 含 math → 脑图内公式走 KaTeX 渲染（.katex）

语法

内联公式：$E=mc^2$
块级公式：
$$
\int_0^1 x^2 dx = \frac{1}{3}
$$

示例

内联公式： $E = m c^{2}$ ；块级公式：

\int_{0}^{\infty} e^{- x^{2}} d x = \frac{\sqrt{π}}{2}

实现效果

正文公式渲染为 MathJax SVG（<mjx-container>），无需前端 JS（SSR 输出）
脑图内嵌公式渲染为 KaTeX（.katex）
明暗主题自适应

测试断言：tools/tests/rich-content-integration.test.js（L2o）：公式页 mjx-container ≥ 10 + katex ≥ 1（双通道）。

16. 脑图 markmap

用途

将 Markdown 列表渲染为可交互的思维导图（缩放/折叠/链接）。

配置（根 `_config.yml` 的 `hexo_markmap`）

hexo_markmap:
  CDN: 'jsdelivr'   # 2026-08-24: fastly.jsdelivr.net 不可达，换 cdn.jsdelivr.net
  features:
    - math          # 脑图内公式（KaTeX）
    - prism         # 代码高亮
    - zoom          # 缩放
  theme: auto

语法

{% markmap 350px %}
- 节点 1
  - 子节点 1.1
  - 子节点 1.2
- 节点 2
{% endmarkmap %}

高度参数：{% markmap 350px %}（可选，默认高度）
内容：标准 Markdown 无序列表（支持链接 / inline code / 加粗 / KaTeX 公式）

示例

实现效果

Markdown 列表渲染为可交互脑图（.markmap-container svg），支持缩放/折叠/链接跳转，暗色自适应。

测试断言：tools/tests/rich-content-integration.test.js（L2o）：.markmap svg 渲染。

附：非 tag 主题功能

以下三项不属于「文章内嵌 tag 插件」范畴（§1–§16），而是主题级独立功能。分组于此以区分 tag 与非 tag 功能边界。

17. 打字机 typing（fun_features）

用途

首页 Banner 副标题逐字打字动画（与交互视觉篇 §3 的 subtitle.typed 同源，配置聚合在 fun_features.typing）。

配置（主题 `_config.yml` 的 `fun_features`）

fun_features:
  typing:
    enable: true      # 打字机开关
    typeSpeed: 70     # 打印速度，数字越大越慢
    cursorChar: "_"   # 光标字符
    loop: false       # 是否循环播放

实现效果

首页 Banner 副标题逐字打出 + 光标闪烁（.typed-cursor）
支持 index.slogan.api 接口取副标题（请求失败回落 text 字段）
page.subtitle: false 可关闭单页打字机

测试断言：tools/tests/rich-content-integration.test.js（L2o）：首页 .typed-cursor 存在。

18. 社交分享 sharejs

用途

文章底部社交分享按钮（微博/微信/QQ/豆瓣等），一键分享当前文章。

配置（主题 `_config.yml`）

sharejs:
  enable: true
  # 支持顺序：twitter, facebook, google, qq, qzone, wechat, weibo, douban, linkedin
  sites: twitter,facebook,qq,qzone,wechat,weibo,douban

# addthis 备选（与 sharejs 二选一）
addthis:
  enable: false
  pubid: 613a04428f842fe1

实现效果

文章底部 .social-share 分享条（data-sites 属性控制显示哪些平台）
微信分享生成二维码（data-wechat-qrcode-helper 提示文案）
仅 post 页渲染（page.layout == 'post'）

测试断言：tools/tests/rich-content-integration.test.js（L2o）：.social-share 组件存在。

19. Live2D 看板娘

用途

页面右下角 Live2D 看板娘（纯静态模型，无 PHP 后端），可交互对话/切换模型。

配置（主题 `_config.yml`）

live2dWidget:
  enable: true

实现效果

看板娘容器（#live2dcanvas / #waifu）右下角常驻
回访用户守卫：localStorage.viewCount > 1 才加载（首访不加载，性能保护）
模型静态化在 source/live2d/（Cubism2/Cubism5 双运行时），明暗自适应

测试断言：tools/tests/rich-content-integration.test.js（L2o）：设置 viewCount=3 后看板娘容器存在。

⚠️ 已知坑

坑 1：标题编号双重叠加

现象：标题渲染为「1. 1. 概述」（两个编号）。

原因：主题 CSS 自动给 h2–h6 加编号（默认开启），手写编号（如 ## 1. 概述）会叠加。

正确做法：手写编号的页面在 front-matter 加 closeAutoTocNum: true；不手写编号的页面不要加该字段。

本文已正确设置 closeAutoTocNum: true。

坑 5：改配置后必须 clean 构建

现象：修改 tag 插件相关配置（如 post.mermaid.enable、live2dWidget.enable、sharejs.enable 等）后页面不变。

原因：Hexo 缓存机制不会自动检测配置变更。

正确做法：改配置后必须 npm run clean && npm run build。

附：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	`{% pdf URL %}`	URL	否
insertmd	`{% insertmd 'file.md' %}`	文件名	否
wechat_dialog	`{% wechat_dialog %}User:/Assistant: 行{% endwechat_dialog %}`	User/Assistant 行	否
groupimage	`{% groupimage 数量布局 %}![图](url){% endgroupimage %}`	数量/布局	否
cardurl	`{% cardurl [url=xxx] %}`	url/title/desc	否
admonition	`::: warning 内容 :::`	container `:::`；原 `{% admonition %}` tag 已废弃	否
encrypt	`{% encrypt 密码 "标题" "简介" %}...{% endencrypt %}`	密码/标题/简介	否
公式	$...$ / `$$...$$`	mathjax3（SSR SVG）/ katex 引擎	是（mathjax: true）
markmap	`{% markmap 350px %}列表{% endmarkmap %}`	高度/features(math/prism/zoom)	否
打字机	`fun_features.typing`	typeSpeed/cursorChar/loop	否
分享	`sharejs.sites`	twitter/wechat/weibo 等	否（仅 post 页）
Live2D	`live2dWidget.enable`	回访用户守卫 viewCount>1	否

Hexo主题功能测试-内容tag篇

https://blog.17lai.site/posts/8a11fe0a/

作者

夜法之书

发布于

2026年8月7日

许可协议。转载请注明来源

CC BY-NC-SA 4.0

教程功能测试 tag

赏

Hexo主题功能测试-内容tag篇

1. 便签 note

用途

语法

全部颜色示例

实现效果

2. 时间线 timeline

用途

语法

示例

实现效果

3. 标签页 tabs

用途

语法

示例（默认激活第一个）

实现效果

4. 行内标签 label

用途

语法

全部颜色示例

实现效果

5. 按钮 button

用途

语法

示例

实现效果

6. GitHub 卡片 githubCard

用途

语法

示例

实现效果

7. Mermaid 流程图

用途

Front-matter 配置（重要）

语法

示例 1：流程图（graph）

示例 2：时序图（sequenceDiagram）

示例 3：类图（classDiagram）

实现效果

8. PDF 嵌入 pdf

用途

语法

示例

实现效果

9. 插入片段 insertmd

用途

语法

示例

实现效果

10. 微信对话卡片 wechat_dialog

用途

语法

示例

实现效果

11. 分组图片 groupimage

用途

语法

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

实现效果

12. URL 卡片 cardurl

用途

语法

示例

实现效果

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

用途

语法

示例

实现效果

14. 加密片段 tag（{% encrypt %}）

用途

语法

示例（本测试片段）

实现效果

自动化测试

Wiki 整体加密（docs-sidebar）

解密后统一刷新

15. 数学公式（MathJax / KaTeX 双通道）

用途

配置（根 _config.yml + 主题 _config.yml）

14. 加密片段 tag（`{% encrypt %}`）

配置（根 `_config.yml` + 主题 `_config.yml`）

配置（根 `_config.yml` 的 `hexo_markmap`）

配置（主题 `_config.yml` 的 `fun_features`）

配置（主题 `_config.yml`）

配置（主题 `_config.yml`）