Hexo主题功能测试-Markdown语法篇

本文覆盖主题启用的全部 16 个 markdown-it 插件。每个插件都按同一条学习路径组织：最小示例 → 常用变体 → 全部写法 → 参数与选项 → 边界与坑。所有示例都是「效果在前、源码在后」成对出现——看到什么就能立刻知道怎么写的。

插件注册位置：根 _config.yml 的 markdown.plugins；渲染配置（breaks / linkify / typographer / html）在同文件 markdown.render。

1. emoji 表情（markdown-it-emoji）

用途：在 Markdown 正文里用短代码写 emoji，不必依赖输入法。

学习路径：最小示例 → 常用变体 → 全部写法 → 参数与选项 → 边界与坑

1.1 最小示例

效果：😄

对应源码：

:smile:

两个冒号夹住短代码名，解析后就是 emoji 字符本身。

1.2 常用变体

效果：❤️ 🚀 👍

对应源码：

:heart: :rocket: :+1:

符号类短代码同样支持，+1 / -1 这种带符号的名字也能用。

效果：✅

对应源码：

:white_check_mark:

多词短代码用下划线连接，不用连字符。

效果：中文😄中文

对应源码：

中文:smile:中文

冒号两侧无需空格，紧贴中文也能转换。

1.3 全部写法

1.4 参数与选项

插件以裸 use() 启用，无 options：整套 shortcode 表全量注册，无法按需裁剪白名单。

输出就是纯 emoji 字符（不额外包 <span>），所以样式完全由系统 emoji 字体决定。

1.5 边界与坑

1.6 小结

• 记不住短代码名就直接输入 emoji 字符，效果一样
• 多词名一律下划线：white_check_mark，不是 white-check-mark
• 想禁用某个短代码做不到——插件不支持白名单

测试断言：页面含 emoji 渲染字符（如 😄 ✅）。

2. 缩写 abbr（markdown-it-abbr）

用途：给缩写词挂全称，鼠标悬停时显示。

学习路径：最小示例 → 常用变体 → 全部写法 → 参数与选项 → 边界与坑

2.1 最小示例

效果：

W3C 制定 Web 标准。

对应源码：

*[W3C]: World Wide Web Consortium
W3C 制定 Web 标准。

定义行 *[缩写]: 全称 独占一行，紧随其后的正文里同名缩写自动带虚线。

2.2 常用变体

效果：HTML 定义结构，CSS 定义表现。

对应源码：

*[HTML]: Hyper Text Markup Language
*[CSS]: Cascading Style Sheets
HTML 定义结构，CSS 定义表现。

多行定义连续写即可，一次定义全文生效。

效果：同一缩写出现两次：HTML 与 HTML。

对应源码：

*[HTML]: Hyper Text Markup Language
同一缩写出现两次：HTML 与 HTML。

正文里每一处都会加 abbr，只需定义一次。

2.3 全部写法

2.4 参数与选项

• 定义行格式固定：*[缩写]: 全称，冒号后可带空格
• 缩写区分大小写：定义了 HTML 不会匹配小写 html
• 定义行位置不影响效果：插件在 block 解析阶段先收集全部定义，写在正文之后同样生效

2.5 边界与坑

2.6 小结

• 定义行一定单独一行，别和正文挤在一起
• 大小写敏感，HTML ≠ html
• 定义放文末也行，位置无所谓

测试断言：页面含 <abbr 标记。

3. 脚注 footnote（markdown-it-footnote）

用途：正文挂角标，注释集中排到文末。

学习路径：最小示例 → 常用变体 → 全部写法 → 参数与选项 → 边界与坑

3.1 最小示例

效果：Hexo 是一个快速静态博客框架[^hexo]。

对应源码：

Hexo 是一个快速静态博客框架[^hexo]。

[^hexo]: Hexo 官网：https://hexo.io

正文写 [^标签]，任意位置写 [^标签]: 内容，自动生成角标 + 文末脚注列表 + 回链箭头。

3.2 常用变体

效果：数字标签也行[^{1]，命名标签也行[}named]。

对应源码：

数字标签也行[^1]，命名标签也行[^named]。

[^1]: 数字标签的脚注。
[^named]: 命名标签的脚注，标签可以是任意单词。

标签只是配对用的标识，渲染出来的序号按出现顺序自动排。

效果：同一脚注引用两次：第一处[^{dup]，第二处[}dup]。

对应源码：

同一脚注引用两次：第一处[^dup]，第二处[^dup]。

[^dup]: 只有一条定义，但两个回链。

第二次起自动加后缀（[1:1]），文末脚注项会带两个 ↩ 回链。

3.3 全部写法

3.4 参数与选项

插件无 options。脚注列表自动追加到文末（<hr> + <section class="footnotes">），每条的回链箭头（↩）自动生成，无需手写。

3.5 边界与坑

3.6 小结

• 标签用有意义的名字（[^hexo]）比数字好维护
• 定义统一堆文末，别散落在正文中间
• 一稿多引没问题，回链自动生成

测试断言：页面含 footnote 相关标记（<sup 或 footnotes）。

4. 插入文本 ins（markdown-it-ins）

用途：++插入文本++ 渲染为下划线插入效果（修订标记语义）。

学习路径：最小示例 → 常用变体 → 全部写法 → 参数与选项 → 边界与坑

4.1 最小示例

效果：这是 插入的内容。

对应源码：

这是 ++插入的内容++。

4.2 常用变体

效果：本次更新 新增了暗色模式 支持。

对应源码：

本次更新 ++新增了暗色模式++ 支持。

内容是中文短语也照常工作，只要在同一行内闭合。

效果：多词 含空格

对应源码：

++多词 含空格++

和 ~ / ^ 不同，++ 允许内容含空格。

4.3 全部写法

4.4 参数与选项

插件无 options；<ins> 的样式（下划线/颜色）由主题 CSS 决定，与语法无关。

4.5 边界与坑

4.6 小结

• 唯一写法 ++…++，没有 ~~ 那种双字符变体
• 必须同一行闭合

测试断言：页面含 <ins 标记。

5. 下标 sub（markdown-it-sub）

用途：~下标~ 渲染为下标，用于化学式、变量下标。

学习路径：最小示例 → 常用变体 → 全部写法 → 参数与选项 → 边界与坑

5.1 最小示例

效果：H₂O 是水的化学式。

对应源码：

H~2~O 是水的化学式。

5.2 常用变体

效果：CO₂ 是二氧化碳。

对应源码：

CO~2~ 是二氧化碳。

效果：_word 这种单词下标也可以。

对应源码：

~word~ 这种单词下标也可以。

5.3 全部写法

5.4 参数与选项

插件无 options。注意：单个 ~ 由本插件处理，~~ 属于另一套规则（删除线）。

5.5 边界与坑

5.6 小结

• 单个 ~ 是下标，两个 ~~ 是删除线，别混
• 下标内容不能含空格

测试断言：页面含 <sub 标记。

6. 上标 sup（markdown-it-sup）

用途：^上标^ 渲染为上标，用于指数、单位。

学习路径：最小示例 → 常用变体 → 全部写法 → 参数与选项 → 边界与坑

6.1 最小示例

效果：E=mc² 是质能方程。

对应源码：

E=mc^2^ 是质能方程。

6.2 常用变体

效果：2¹⁰ = 1024。

对应源码：

2^10^ = 1024。

效果：x² + y² = z²（同一行多次使用）

对应源码：

x^2^ + y^2^ = z^2^（同一行多次使用）

6.3 全部写法

6.4 参数与选项

插件无 options；上标字号由主题 CSS（sup 样式）控制。

6.5 边界与坑

6.6 小结

• ^…^ 内容不能含空格（和 ++ 不同）
• 表格里的 ^^ 是合并语法，与上标无关

测试断言：页面含 <sup 标记。

7. 高亮 mark（markdown-it-mark）

用途：==高亮== 渲染为荧光笔高亮。

学习路径：最小示例 → 常用变体 → 全部写法 → 参数与选项 → 边界与坑

7.1 最小示例

效果：这是 重点内容。

对应源码：

这是 ==重点内容==。

7.2 常用变体

效果：请特别注意 密码安全。

对应源码：

请特别注意 ==密码安全==。

效果：多词 含空格 同样有效。

对应源码：

==多词 含空格== 同样有效。

7.3 全部写法

7.4 参数与选项

插件无 options；高亮底色由主题 CSS 决定，改色改 mark 样式而非语法。

7.5 边界与坑

7.6 小结

• ==…== 允许空格，比 ~/^ 宽松
• 必须同一行闭合，空内容不生效

测试断言：页面含 <mark 标记。

8. 任务列表 task-checkbox（markdown-it-task-checkbox）

用途：- [x] / - [ ] 渲染为只读复选框列表。

学习路径：最小示例 → 常用变体 → 全部写法 → 参数与选项 → 边界与坑

8.1 最小示例

效果：

• 已完成任务
• 未完成任务

对应源码：

- [x] 已完成任务
- [ ] 未完成任务

8.2 常用变体

效果：

• 主题测试文章创建
• 自动化测试脚本
• 视觉回归验证

对应源码：

- [x] 主题测试文章创建
- [x] 自动化测试脚本
- [ ] 视觉回归验证

效果（嵌套 + 行内语法）：

• 父级任务 加粗 🚀
  • 子任务一
  • 子任务二

对应源码：

- [ ] 父级任务 **加粗** :rocket:
  - [x] 子任务一
  - [ ] 子任务二

复选框后的内容仍走 inline 解析：粗体、emoji、行内代码都能用。

8.3 全部写法

8.4 参数与选项

插件裸启用、无 options，但它默认给 checkbox 写入 disabled：渲染为 <input type="checkbox" disabled>，并给 <li> 加 task-list-item 类、给 <ul> 加 task-list 类。

8.5 边界与坑

8.6 小结

• 只读展示，别指望读者能勾
• 想保存进度就得用真正的待办服务，静态站做不到

测试断言：页面含 task-list-item 或 checkbox 标记。

9. 表格增强 multimd-table（markdown-it-multimd-table）

用途：在标准表格语法上追加对齐、行合并、列合并、表题。

学习路径：最小示例 → 对齐 → 行合并 → 列合并 → 表题 → 全部写法 → 参数与选项 → 边界与坑

9.1 最小示例

效果：

对应源码：

| 左对齐 | 居中 | 右对齐 |
| :----- | :--: | -----: |
| a | b | c |

冒号位置决定对齐：:--- 左、:--: 中、---: 右。

9.2 常用变体

效果（行合并，^^ 表示与上一行合并）：

对应源码：

| 组 | 项 | 状态 |
| :--- | :--- | :--- |
| A | 基础 | ✅ |
| ^^ | 高级 | ✅ |
| B | 实验 | ⚠️ |

需要 rowspan: true（本项目已开启），且 ^^ 必须在有上一行的连续行里。

效果（列合并，留空单元格向右跨列）：

对应源码：

| 模块 | 说明 | 备注 |
| :--- | :--- | :--- |
| 表格 | 跨两列 ||
| 图片 | 单列 | 正常 |

效果（表题，表格下方单独一行 [标题]）：

对应源码：

| 插件 | 类型 | 状态 |
| :---- | :--- | :--- |
| emoji | 行内 | ✅ |
| footnote | 行内 | ✅ |
| mathjax3 | 块级 | ✅ |

[常用插件一览]

表题渲染为 <caption> 且靠下（caption-side: bottom），空行隔开后归属上一张表。

9.3 全部写法

9.4 参数与选项

想用单元格内多行，得在 markdown.plugins 里把该项选项改成 multiline: true 再 clean 构建。

9.5 边界与坑

9.6 小结

• 对齐靠分隔行冒号，行合并靠 ^^，列合并靠留空
• ^^ 不能隔空行，否则合并失效
• 表题写在表格下方，用 [标题]

测试断言：页面含 <table 标记。

10. 图片尺寸 imsize（markdown-it-imsize）

用途：用 =宽x高 控制图片显示尺寸，编译期写进 <img> 的 width/height。

学习路径：最小示例 → 只定宽/只定高 → 百分比 → 全部写法 → 参数与选项 → 边界与坑

10.1 最小示例

效果：

对应源码：

![封面](https://blog.17lai.site/medias_webp/cover/hexo.webp =200x100)

尺寸串挂在 URL 之后，与 URL 用空格分隔。

10.2 常用变体

效果（只定宽，高度按比例自适应）：

对应源码：

![封面-只定宽](https://blog.17lai.site/medias_webp/cover/hexo.webp =240x)

效果（只定高，宽度按比例自适应）：

对应源码：

![封面-只定高](https://blog.17lai.site/medias_webp/cover/hexo.webp =x80)

效果（百分比宽度，必须带 x）：

对应源码：

![封面-百分比](https://blog.17lai.site/medias_webp/cover/hexo.webp =30%x)

10.3 全部写法

10.4 参数与选项

• 尺寸串挂在 URL 之后，与 URL 用空格分隔：![alt](图片地址 =宽x高)
• 无插件级 options，写法即参数
• 百分比必须写成 =50%x（带 x 占位），裸 =50% 不识别

10.5 边界与坑

与 imgsize.js 的区别：markdown-it-imsize 是 Markdown 渲染插件，在编译阶段处理 =宽x高 语法并写入 <img> 标签的 width/height 属性；主题另有 scripts/events/lib/imgsize.js 脚本，在运行时为未手动指定尺寸的 <img> 注入真实宽高（本地同步读取/网络异步拉取），防 CLS。两者协作：手动指定的尺寸由 imsize 插件处理，未指定的由 imgsize.js 兜底。

10.6 小结

• 两个数字用 x 连，缺哪个就空着：=300x、=x200
• 百分比必须带 x：=50%x，裸 =50% 会整段失效
• 别在尺寸后加 title，插件不认

测试断言：页面含 img 且带尺寸属性。

11. 容器 container（markdown-it-container）

用途：::: 类型 渲染带语义色的提示容器（Markdown 层，不是 tag 插件）。

学习路径：最小示例 → 常用类型 → 全部写法 → 参数与选项 → 与 note 的区别 → 边界与坑

11.1 最小示例

效果：

对应源码：

::: warning
这是 warning 容器。
:::

开始与结束标记各占一行，容器名只能用白名单里的 7 个。

11.2 常用类型

效果：

对应源码：

::: tip
这是 tip 容器（蓝色，与 info 同义）。
:::

效果（多段内容，空行不结束容器）：

对应源码：

::: note
第一段说明。

第二段仍在同一容器内。
:::

11.3 全部写法

11.4 参数与选项

本项目注册的 7 个容器名（其余名字不识别）：

无标题参数：::: tip 容器标题 里的「容器标题」会被丢弃（实测只渲染 <div class="tip"><p>内容</p></div>），需要标题请改用 §19 admon 或 {% note %} 标签。

11.5 与 note 标签的区别

{% note primary 说明 %}
正文
{% endnote %}

11.6 边界与坑

11.7 小结

• 想无脑用就记 warning / note / info 三个
• 要标题、要图标、要折叠 → 用 {% note %}，不要在 ::: 上折腾
• 别嵌套 :::，会出错

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

12. 定义列表 deflist（markdown-it-deflist）

用途：术语 + 描述的结构化列表（<dl>/<dt>/<dd>）。

学习路径：最小示例 → 多定义 → 全部写法 → 参数与选项 → 边界与坑

12.1 最小示例

效果：

Markdown

轻量级标记语言。

由 John Gruber 于 2004 年创建。

对应源码：

Markdown
: 轻量级标记语言。

术语行与 : 定义 行之间不能有空行，冒号后要一个空格。

12.2 常用变体

效果（一个术语多条定义）：

Hexo

快速、简洁且高效的博客框架。

基于 Node.js 编写。

对应源码：

Hexo
: 快速、简洁且高效的博客框架。
: 基于 Node.js 编写。

效果（定义内可用行内语法）：

Node.js

支持 JavaScript 与 npm 生态。

对应源码：

Node.js
: 支持 **JavaScript** 与 `npm` 生态。

12.3 全部写法

12.4 参数与选项

插件无 options。要求：术语行与 : 定义 行之间不能有空行，冒号后需一个空格。

12.5 边界与坑

12.6 小结

• 术语行、: 定义 行必须紧贴，中间不能空行
• 一个术语可以挂多条定义

测试断言：页面含 <dl / <dt / <dd> 标记。

13. 数学公式 mathjax3（markdown-it-mathjax3）

用途：编译期把 LaTeX 渲染成 SVG（SSR，无前端 JS 依赖）。

学习路径：行内 → 块级 → 全部写法 → 参数与选项 → 边界与坑

13.1 行内公式

效果：质能方程 $E=m{c}^2$是最著名的物理公式之一。

对应源码：

质能方程 $E=mc^2$ 是最著名的物理公式之一。

单个 $ 包裹，与文字同排；内部不能换行。

13.2 块级公式

效果：

对应源码：

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

$$ 各占一行，内容居中独占一块。

效果（块级多行，\\ 换行 + aligned 环境）：

对应源码：

$$
\begin{aligned}
a^2 + b^2 &= c^2 \\
\int_0^1 x^2 dx &= \frac{1}{3}
\end{aligned}
$$

13.3 全部写法

13.4 参数与选项

13.5 边界与坑

在 Hexo 博客中使用 markdown-it 插件渲染 SupercalifragilisticexpialidociousEnglishWord 这类长单词时，fallback 行为取决于断行机会。

源码一个字都不用改：插件在 CJK 字符与拉丁字母/数字/西文标点之间插入零宽空格（U+200B）作为断行点。

效果（插件未覆盖的场景仍可能溢出）：中文句子里的超长 URL 仍会溢出容器，因为零宽空格不插入 URL 内部。

对应源码：

中文句子里的超长 URL 仍会溢出容器：https://example.com/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

14.2 全部写法

无语法：插件自动生效，源码一个字都不用改。它在 CJK 字符与拉丁字母/数字/西文标点之间插入断行机会（零宽空格），让浏览器在中英文交界处正常折行，而不是把整串英文挤到下一行或撑破容器。

14.3 参数与选项

无 options、无开关，全站所有正文生效。不作用于代码块/行内代码内容。

14.4 边界与坑

14.5 小结

• 零配置、纯收益，没有需要学的东西
• 唯一要注意的是超长 URL 仍会溢出，必要时手动断行

测试断言：中文文本正常渲染（无异常断字）。

15. 表格进阶实战（multimd-table 组合用法）

用途：把对齐、行合并、列合并、表题组合到一张真实表格里。

学习路径：组合示例 → 启用项 → multiline 说明 → 边界与坑

15.1 组合示例

效果：

对应源码：

| 分类 | 插件 | 状态 |
| :--- | :--- | :--: |
| 行内 | emoji | ✅ |
| ^^ | footnote | ✅ |
| ^^ | mark | ✅ |
| 块级 | mathjax3 | ✅ |
| ^^ | container | ✅ |

[按渲染阶段分类]

连续 ^^ 会逐行向上合并（rowspan 累加），分类列只写一次。

15.2 常用变体

效果（列合并 + 右对齐数值）：

对应源码：

| 项目 | 说明 | 数值 |
| :--- | :--- | ---: |
| 表格扩展 | 跨两列 ||
| 行合并 | `^^` | 2 |
| 表题 | `[标题]` | 1 |

15.3 启用项

multiline 未启用时的现象：单元格里换行会被拆成新的一行，而不是同一单元格内的多行内容。真需要多行单元格只能改配置 + clean 构建，或用 HTML 表格。

15.4 边界与坑

15.5 小结

• 行合并写 ^^，列合并留空，表题写 [标题]
• 组合使用时最容易踩的坑是「行间空行」——合并立刻失效

测试断言：页面含 <table 标记（≥2 个表格）。

16. 综合测试（多插件组合）

用途：验证多个插件在同一段内容里互不干扰。

学习路径：组合示例 → 逐项拆解 → 边界与坑

16.1 组合示例

效果：

任务清单（task-checkbox + emoji）：

• emoji 正常：✅
• 插入正常：新增内容
• 数学正常： $a^2+b^2=c^2$

定义列表（deflist）：

Markdown

轻量级标记语言。

由 John Gruber 发明。

脚注（footnote）：主题测试文章共 4 篇^[1]。

对应源码：

**任务清单**（task-checkbox + emoji）：

- [x] emoji 正常：:white_check_mark:
- [x] 插入正常：++新增内容++
- [x] 数学正常：$a^2 + b^2 = c^2$

**定义列表**（deflist）：

Markdown
: 轻量级标记语言。
: 由 John Gruber 发明。

**脚注**（footnote）：主题测试文章共 4 篇[^total]。

[^total]: 内容tag篇、交互视觉篇、布局页面篇、Markdown语法篇。

16.2 逐项拆解

16.3 边界与坑

16.4 小结

• 插件之间基本互不冲突，冲突集中在符号重叠：~/^ 与数学、== 与 attrs
• 混排时优先用代码块包住原始语法示例

测试断言：页面含多类标记组合（checkbox + dl + footnote + ins）。

17. 行内属性 attrs（markdown-it-attrs）

用途：给块级/行内元素加 id / class / 自定义属性，用于样式定位、锚点、target。

学习路径：最小示例 → 行内元素 → 链接 → 全部写法 → 参数与选项 → 边界与坑

17.1 最小示例

效果：

这是居中段落（class 定位）。

对应源码：

这是居中段落（class 定位）。
{.text-center}

属性块独占下一行，作用于上一个块级元素。

17.2 常用变体

效果（行内元素后紧贴，同一行）：这是红色粗体的示例。

对应源码：

这是**红色粗体**{.red}的示例。

行内元素必须与属性块同一行，否则属性落到段落上。

效果（链接加属性）：带 target 的链接

对应源码：

[带 target 的链接](https://hexo.io){target="_blank"}

效果（多个 class 连写）：这里的文字同时带两个 class。

对应源码：

这里的文字同时带两个 class。
{.my-class .another-class}

多个 class 用空格分隔连写；#id、key=value 可以混在同一个花括号里。属性块必须紧贴上一块，中间隔空行会变成空段落 <p class="…"></p>。

17.3 全部写法

17.4 参数与选项

17.5 边界与坑

17.6 小结

• 三种位置：块后独占一行、行内元素后紧贴、链接后紧贴
• 关键在「同一行」——跨行就换作用对象
• 纯文本不能直接挂属性，先包成行内元素

测试断言：页面含带 text-center class 的元素。

18. 外链属性 link-attributes（markdown-it-link-attributes）

用途：给 Markdown 链接自动加 target="_blank" + rel="noopener noreferrer"。

学习路径：最小示例 → 站内链接 → 锚点/裸 URL → 全部写法 → 参数与选项 → 边界与坑

18.1 最小示例

效果：Hexo 官网

对应源码：

[Hexo 官网](https://hexo.io)

新窗口打开 + 防反向链接，源码里什么都不用写。

18.2 常用变体

效果（站内链接同样被加 target）：站内文章

对应源码：

[站内文章](/posts/8a11fe0a/)

效果（锚点链接也被命中）：回到顶部

对应源码：

[回到顶部](#)

效果（linkify 自动识别的裸 URL）：https://hexo.io

对应源码：

https://hexo.io

裸 URL 由 linkify: true 转成链接，再被本插件加上属性。

18.3 全部写法

18.4 参数与选项

18.5 边界与坑

18.6 小结

• 「只对外链生效」这条当前不成立——pattern 是无效配置
• 结果：正文里所有链接都新窗口打开，站内跳转也开新标签
• 想修就得改 matcher 函数，改配置后 clean 构建

测试断言：外链 <a> 含 target="_blank" + rel="noopener noreferrer"。

19. admon 提示块（markdown-it-admon）

用途：!!! type 语法渲染提示块（python-markdown 风格，与 §11 的 ::: 并存）。

学习路径：最小示例 → 自定义标题 → 不同类型 → 全部写法 → 参数与选项 → 边界与坑

19.1 最小示例

效果：

对应源码：

!!! note
    这是 note admon——最基础的提示块。

正文必须缩进 4 空格，否则落在块外。

19.2 常用变体

效果（自定义标题，类型后直接写文字）：

对应源码：

!!! warning 部署前请先备份
    改动 `_config.yml` 后记得 clean 构建。

效果（不写标题时用类型名，首字母大写）：

对应源码：

!!! tip
    这是 tip admon——小技巧。

效果（多段内容 + 列表）：

对应源码：

!!! danger
    危险操作示例：

    - 删除 `public/`
    - 覆盖 `_config.yml`

空行后继续缩进 4 空格，仍属于同一块。

19.3 全部写法

19.4 参数与选项

19.5 边界与坑

19.6 小结

• 三要素：!!! 类型、缩进 4 空格、可选标题（不加引号）
• 想折叠 → 用 {% note %}，admon 的 ??? 在这个版本不存在
• 类型不校验，拼错不报错但没样式

测试断言：页面含 admon 渲染标记。

⚠️ 已知坑

坑 1：标题编号双重叠加

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

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

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

本文已正确设置 closeAutoTocNum: true。

坑 2：{% raw %}` 忘了包 **现象**：示例源码里的 `{% note %}`、`{{ }}` 被真实执行或报模板错误。 **正确做法**：所有含 `{% %}` / `{{ }}` 的示例代码块都用 `{% raw %}` … `{% endraw %} 包住。

坑 3：配置项写了不生效

现象：link-attributes 的 pattern: ^https?://、mathjax3 的 inlineMath 都写了，但行为没变。

原因：两处都是插件不认这个键（一个只认 matcher 函数，一个是源码硬编码 $/$$），配置静默失效。

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

现象：修改根 _config.yml 的 markdown.plugins（如切换 mathjax/katex 引擎、开 multiline）后页面不变。

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

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

附：markdown-it 插件速查表

参考&致谢

系列教程

全部文章RSS订阅

Hexo 主题功能测试系列

• Hexo主题功能测试-布局与页面篇 —— 页面布局、导航、侧边栏、卡片等结构功能
• Hexo主题功能测试-交互视觉篇 —— 代码高亮、图片灯箱、动画、明暗切换等交互
• Hexo主题功能测试-内容tag篇 —— note / tabs / timeline / label / button 等 tag 插件
• Hexo主题功能测试-Markdown语法篇 —— Markdown 渲染与扩展语法
• Hexo主题功能测试-自动化测试篇 —— 主题功能的自动化测试方案