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

本文覆盖主题启用的全部 16 个 markdown-it 插件，每项含用途、语法、示例、实现效果，供自动化测试断言。

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

用途

在 Markdown 中直接使用 emoji 短代码。

语法

:smile: :heart: :rocket:

示例

😄 微笑｜ ❤️ 爱心｜ 🚀 火箭｜ 👍 点赞

实现效果

短代码渲染为彩色 emoji。

测试断言：页面含 emoji 渲染标记（<span class="emoji"> 或直接 emoji 字符）。

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

用途

定义缩写词，悬停显示全称。

语法

*[HTML]: Hyper Text Markup Language
HTML 是网页的标准语言。

示例

W3C 制定 Web 标准。

实现效果

缩写词带虚线下划线，悬停显示全称。

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

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

用途

文末脚注引用。

语法

这里是正文[^1]。

[^1]: 这是脚注内容。

示例

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

实现效果

正文上标数字，点击跳转文末脚注。

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

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

用途

++插入文本++ 渲染为下划线插入效果。

语法

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

示例

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

实现效果

插入文本带下划线（类似修订标记）。

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

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

用途

~下标~ 渲染为下标。

语法

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

示例

CO₂ 是二氧化碳。

实现效果

文本渲染为下标。

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

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

用途

^上标^ 渲染为上标。

语法

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

示例

2¹⁰ = 1024。

实现效果

文本渲染为上标。

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

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

用途

==高亮== 渲染为荧光笔高亮。

语法

这是 ==重点内容==。

示例

请特别注意密码安全。

实现效果

文本带高亮背景色。

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

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

用途

渲染可勾选的任务列表。

语法

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

示例

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

实现效果

复选框 + 已完成任务带删除线。

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

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

用途

增强表格语法：单元格合并、多行表头、对齐等。

语法

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

示例

功能	状态	优先级
基础	✅	高
高级	✅	中
实验	⚠️	低

实现效果

表格正确渲染，对齐生效。

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

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

用途

用 =宽x高 控制图片显示尺寸。

语法

![图片](url =300x200)

示例

实现效果

图片按指定尺寸显示。

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

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

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

用途

::: 类型 渲染自定义容器。

语法

::: warning
警示内容
:::

示例

这是 warning 容器。

这是 tip 容器。

实现效果

容器带色条和淡色背景（映射到 note 样式）。

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

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

用途

渲染定义列表（术语 + 描述）。

语法

术语
: 定义描述

示例

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

实现效果

术语加粗，描述缩进。

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

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

用途

渲染 LaTeX 数学公式（内联 + 块级）。

语法

内联：$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}

实现效果

公式渲染为 SVG 数学符号。

测试断言：页面含 math 渲染标记（SVG 或 math 容器）。

公式双引擎（mathjax / katex，2026-09-10 补）

主题 post.math.engine 支持二选一（根 _config.yml markdown 插件配套切换）：

引擎	分隔符	渲染
`mathjax`（默认）	$...$ 行内 / `$$...$$` 块级（mathjax3 5.x 硬编码，`$...$` 不支持）	Node 端 SSR 输出 MathJax SVG（`<mjx-container>`），无需前端 JS
`katex`	$...$ / `$$...$$` + `$...$` / `\[...\]`（brackets 需独立成块）	SSR 渲染 + 前端加载 KaTeX CSS（`static_prefix.katex`）

切换 katex：注释掉 markdown.plugins 里的 markdown-it-mathjax3，启用 texmath，post.math.engine: katex。脑图（markmap）内嵌公式固定走 KaTeX（.katex），与正文 MathJax 并存（双通道）。

14. 中文排版 cjk-breaks（markdown-it-cjk-breaks）

用途

中文行内换行优化（避免中英文间错误断行）。

语法

这是中文测试内容，混合English和中文。

实现效果

中英文混排行内不错误断行。

测试断言：中文文本正常渲染。

15. 任务列表/表格综合（multimd-table 增强）

用途

多行表头 + 单元格合并等高级表格。

语法

| 表头1 | 表头2 |
| ----- | ----- |
| 单元格 | 单元格 |

示例

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

实现效果

增强表格正确渲染。

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

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

示例

任务清单（task-checkbox）：

emoji 正常：✅
缩写正常：[API]: Application Programming Interface API
数学正常： $a^{2} + b^{2} = c^{2}$

定义列表（deflist）：
Markdown
: 轻量级标记语言。
: 由 John Gruber 发明。

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

实现效果

多插件组合在同一页面正常工作。

测试断言：页面含多类标记组合。

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

用途

给元素加 class / id / 自定义属性（{#id .class key=val}），用于样式定位与锚点。

语法

段落 {.text-center #intro}
[链接](url){target="_blank"}

示例

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

实现效果

元素带上指定 class / id / 属性，供 CSS / JS 选择器使用。

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

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

用途

链接自动加 target="_blank" + rel="noopener noreferrer"（新窗口打开 + 防反向链接）。

语法

[外部链接](https://hexo.io)
[站内链接](/posts/8a11fe0a/)

示例

Hexo 官网｜站内文章

实现效果

外链新窗口打开 + 防反向链接（rel noopener noreferrer）
注意：当前配置 pattern: ^https?:// 未生效（markdown-it-link-attributes 只认 matcher 函数，不认 pattern 字符串）——正文链接（含站内）统一加 target；模板生成的链接（prenext 上下篇等）不受影响

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

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

用途

!!! type 语法渲染提示块（与 §11 container 的 ::: 语法互补，python-markdown 风格）。

语法

!!! warning
    警示内容（缩进 4 空格）

示例

Warning

这是 warning admon——注意内容。

Tip

这是 tip admon——小技巧。

实现效果

带图标 + 色条的提示块（支持 note/info/tip/warning/danger/error 等类型）。

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

⚠️ 已知坑

坑 1：标题编号双重叠加

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

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

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

本文已正确设置 closeAutoTocNum: true。

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

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

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

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

附：markdown-it 插件速查表

插件	语法	渲染	测试标记
emoji	`:smile:`	emoji 字符	emoji
abbr	`*[ABBR]: 全称`	`<abbr>`	abbr
footnote	`[^1]`	脚注	footnote
ins	`++文本++`	`<ins>`	ins
sub	`~文本~`	`<sub>`	sub
sup	`^文本^`	`<sup>`	sup
mark	`==文本==`	`<mark>`	mark
task-checkbox	`- [x]`	复选框	task-list-item
multimd-table	表格	`<table>`	table
imsize	`=200x100`	尺寸图	img
container	`::: type`	note 容器	note
deflist	`术语: 定义`	`<dl>`	dl
mathjax3	$公式$	SVG	math
cjk-breaks	自动	中文优化	-
attrs	`{#id .class key=val}`	元素属性	class/id
link-attributes	外链自动	target=_blank + rel	target
admon	`!!! type`	提示块	admon