Markdown 语法扩展

本页汇总主题通过 hexo-renderer-markdown-it 启用的 17 个 markdown-it 插件（emoji / attrs / link-attributes / abbr / footnote / ins / sub / sup / mark / task-checkbox / multimd-table / imsize / container / admon / deflist / mathjax3 / cjk-breaks，配置见根 _config.yml），外加综合示例与速查表。每个插件给出用途、语法、示例、效果，示例可直接复制到文章测试。

怎么读这页：每个语法都按「效果 → 对应源码」成对展示——先看页面真实渲染，再抄下面的 Markdown 源码。参数表与「边界与坑」全部取自 _config.yml 的插件配置和 node_modules 里插件的实际源码，不是猜的。

与「布局与页面」的行内加粗标签风格不同，本页因需容纳代码块与真实渲染示例，采用三级子标题（最小示例/常用变体/全部写法/参数与选项/边界与坑/小结）分隔。
注意：展示语法的代码块一律用 raw 标签包裹（raw 与 endraw 成对），防止 nunjucks 预渲染时误处理或吞掉后续内容。
注意：本文含真实数学公式示例（第 16 项），因此 front-matter 已声明 mathjax: true——文章正文出现 $...$ / $$...$$ 公式时都必须声明它，否则公式原样显示。

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

用途：在 Markdown 中直接使用 emoji 短代码，无需复制 Unicode 字符。

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

1.1 最小示例

效果：

😄

对应源码：

:smile:

冒号包住英文短代码即可，无需任何配置。

1.2 常用变体

效果：

😄 微笑 ｜ ❤️ 爱心 ｜ 🚀 火箭 ｜ 👍 点赞 ｜ 🎉 庆祝 ｜ ⚠️ 警告

对应源码：

:smile: 微笑 ｜ :heart: 爱心 ｜ :rocket: 火箭 ｜ :+1: 点赞 ｜ :tada: 庆祝 ｜ :warning: 警告

短代码可以连续写多个，也可以夹在句子中间。

效果：

提交前记得 ✅ 跑测试，别 🙈 直接推。

对应源码：

提交前记得 :white_check_mark: 跑测试，别 :see_no_evil: 直接推。

1.3 全部写法

1.4 参数与选项

_config.yml 里是裸加载（- markdown-it-emoji，没有 options），因此使用插件默认值：

需要精简/自定义时，在 _config.yml 里改成对象形式：

- name: markdown-it-emoji
  options:
    enabled: [smile, heart]

1.5 边界与坑

1.6 小结

• 冒号包短代码，名字查 emoji cheat sheet
• 不启用 ASCII 表情，:) 不是 emoji
• 想缩小可用范围就传 options.enabled

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

用途：在元素后追加 {#id .class key=val} 给元素加 id / class / 自定义属性，用于微调样式或锚点定位。

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

2.1 最小示例

给段落加内联样式——最直观能看到 attrs 在起作用：

效果：

这段文字的颜色由 {style=...} 控制，不是主题默认色。

对应源码：

这段文字的颜色由 `{style=...}` 控制，不是主题默认色。{style="color:#c2185b"}

2.2 常用变体

给图片设宽高（不用 imsize 插件也能改尺寸）：

效果：

对应源码：

![封面](https://blog.17lai.site/medias_webp/cover/hexo.webp){width=120}

给链接加 id / class / 自定义属性：

效果：

链接

对应源码：

[链接](https://example.com){.external #link1 data-x="1"}

给围栏代码块加属性（属性写在 info 串末尾）：

效果：

{.demo-block}
console.log('这一块的 pre 元素带 class="demo-block"');

对应源码：

```js {.demo-block}
console.log('这一块的 pre 元素带 class="demo-block"');
```

2.3 全部写法

2.4 参数与选项

插件版本 4.5.0，_config.yml 裸加载 → 全部默认值：

安全提示：allowedAttributes: [] 意味着正文可以写 onclick=、style= 等任意属性。多作者站点建议收紧为 [id, class, /^data-/]。

2.5 边界与坑

2.6 小结

• {...} 必须贴在元素行尾（表格是例外：下方空两行）
• #id / .class / key=val，值含空格加双引号
• 默认放行所有属性，多作者站点要收紧白名单

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

用途：给页面里的链接统一加 target="_blank" + rel="noopener noreferrer"，新窗口打开且防反向 tabnabbing。

学习路径：最小示例 → 站内链接的真实行为 → 全部写法 → 参数与选项 → 边界与坑 → 小结

3.1 最小示例

效果：

外部链接——点击会在新标签页打开。

对应源码：

[外部链接](https://example.com)

3.2 站内链接也会新窗口（真实行为）

_config.yml 里写了 pattern: ^https?://，但 当前插件版本（4.0.1）根本不读取 pattern——源码里只认 matcher 函数和 attrs。配置无法用 YAML 表达函数，于是第一个配置项无条件命中所有 <a>：

效果：

站内链接 /about/ 和 锚点链接 同样会被加上 target="_blank"（右键「检查」可验证）。

对应源码：

[站内链接 /about/](/about/) 和 [锚点链接](<#1-emoji-表情（markdown-it-emoji）>)

3.3 全部写法

3.4 参数与选项

想真正只处理外链，只能换成能在 _config.yml 里表达的形式（当前不支持），或在主题层用前端脚本/渲染后处理挑出 http(s) 链接——YAML 里改 pattern 不会有任何效果。

3.5 边界与坑

3.6 小结

• 效果是「全站所有 <a> 都新窗口」，不是「只外链」
• pattern 是装饰性配置，改它没用（4.0.1 无此分支）
• 单链接想改回本窗口，靠配置做不到

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

用途：定义缩写词，悬停时显示全称（生成 <abbr> 标签）。

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

4.1 最小示例

定义行 *[缩写]: 全称 独占一行，正文里出现该词即自动包 <abbr>：

效果：

W3C 制定 Web 标准。

对应源码：

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

4.2 常用变体

多个缩写（一行一个定义）：

效果：

HTML 负责结构，CSS 负责样式。

对应源码：

*[HTML]: Hyper Text Markup Language
*[CSS]: Cascading Style Sheets
HTML 负责结构，CSS 负责样式。

定义写在文末也生效（实测：插件在整篇 block 解析完、inline 解析后才做替换，与使用位置无关）：

效果：

先出现 API 这个词，定义在下面。

对应源码：

先出现 API 这个词，定义在下面。

*[API]: Application Programming Interface

4.3 全部写法

4.4 参数与选项

裸加载，无可配选项。定义区由插件在 state.env.abbreviations 里维护，正文替换是整篇统一做的。

4.5 边界与坑

4.6 小结

• 定义行 *[缩写]: 全称 独占一行
• 位置任意，全篇生效
• 大小写敏感，代码内不替换

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

用途：在文末集中展示注释/出处，正文以上标数字引用。

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

5.1 最小示例

效果：

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

对应源码：

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

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

5.2 常用变体

命名 id（比数字更好维护，不会因为增删顺序错位）：

效果：

主题用 matery^[2]，评论用 Waline^[3]。

对应源码：

主题用 matery[^matery]，评论用 Waline[^waline]。

[^matery]: 基于 blinkfox/hexo-theme-matery 深度魔改。
[^waline]: 部署在 waline.17lai.site。

多行脚注（续行缩进 4 个空格）：

效果：

多行脚注可以写两段内容^[4]。

对应源码：

多行脚注可以写两段内容[^multi]。

[^multi]: 第一行。
    第二行，缩进 4 空格仍属于同一条脚注。

5.3 全部写法

5.4 参数与选项

裸加载，无可配选项。渲染结构固定：sup.footnote-ref + hr.footnotes-sep + section.footnotes + 有序列表，回跳链接带 ↩︎。

5.5 边界与坑

5.6 小结

• 引用 [^id]、定义 [^id]: 内容，位置随意
• 编号自动，命名 id 更好维护
• 未引用的定义不显示

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

用途：++文本++ 渲染为带下划线的插入文本（类似修订标记）。

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

6.1 最小示例

效果：

这是 插入的内容。

对应源码：

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

6.2 常用变体

修订场景（配合删除线表达「删了什么、加了什么」）：

效果：

旧方案 轮询 WebSocket 推送。

对应源码：

旧方案 ~~轮询~~ ++WebSocket 推送++。

与高亮并用：

效果：

新增暗色模式支持。

对应源码：

++新增==暗色模式==支持++。

6.3 全部写法

6.4 参数与选项

裸加载，无可配选项。

6.5 边界与坑

6.6 小结

• ++ 是「加」，~~ 是「删」
• 里面别放复杂嵌套

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

用途：~文本~ 渲染为下标。

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

7.1 最小示例

效果：

H₂O 是水的化学式。

对应源码：

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

7.2 常用变体

化学式 / 变量下标：

效果：

CO₂ 是二氧化碳；数组元素记作 a_i。

对应源码：

CO~2~ 是二氧化碳；数组元素记作 a~i~。

与删除线区分（最容易混的地方）：

效果：

H₂O 是下标，H2O 是删除线。

对应源码：

H~2~O 是下标，~~H2O~~ 是删除线。

7.3 全部写法

7.4 参数与选项

裸加载，无可配选项。

7.5 边界与坑

7.6 小结

• 下标用单 ~，删除线用双 ~~
• 不支持嵌套

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

用途：^文本^ 渲染为上标。

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

8.1 最小示例

效果：

2¹⁰ = 1024。

对应源码：

2^10^ = 1024。

8.2 常用变体

英文序数：

效果：

29^th 、 1^st 、 2^nd 。

对应源码：

29^th^ 、 1^st^ 、 2^nd^ 。

与数学公式区分：

效果：

行内上标 2¹⁰ 用插件；真正的公式 $2^{10}$走 mathjax（第 16 节）。

对应源码：

行内上标 2^10^ 用插件；真正的公式 $2^{10}$ 走 mathjax（第 16 节）。

8.3 全部写法

8.4 参数与选项

裸加载，无可配选项。

8.5 边界与坑

8.6 小结

• ^ 是上标，~ 是下标
• 复杂公式交给 mathjax

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

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

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

9.1 最小示例

效果：

请特别注意 密码安全。

对应源码：

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

9.2 常用变体

多处高亮：

效果：

备份 → 验证 → 再删原文件，顺序不能反。

对应源码：

==备份== → ==验证== → ==再删原文件==，顺序不能反。

9.3 全部写法

9.4 参数与选项

裸加载，无可配选项；高亮色由主题 CSS 的 mark 规则决定。

9.5 边界与坑

9.6 小结

• == 双等号高亮
• 少量使用，别整段涂

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

用途：渲染带复选框的任务清单。

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

10.1 最小示例

效果：

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

对应源码：

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

方括号内为 x 表示已完成，为空格表示未完成。

10.2 常用变体

真实清单：

效果：

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

对应源码：

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

大写 X 与有序列表：

效果：

1. 大写 X 同样算完成
2. 有序列表也能用

对应源码：

1. [X] 大写 X 同样算完成
2. [ ] 有序列表也能用

10.3 全部写法

10.4 参数与选项

插件裸加载 → 默认参数：

10.5 边界与坑

10.6 小结

• - [x] / - [ ]，方括号后必须有空格
• 大写 X 也可以
• 复选框是禁用的展示态，不能点

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

用途：标准 GFM 表格 + 对齐控制 + 单元格合并（_config.yml 已开 rowspan: true）。

学习路径：最小示例 → 常用变体（对齐 / 合并） → 全部写法 → 参数与选项 → 边界与坑 → 小结

11.1 最小示例

效果：

对应源码：

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

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

11.2 常用变体

合并单元格（|| 横向合并、^^ 纵向合并）：

效果：

对应源码：

| 组 | 项目 | 说明 |
| :-- | :--: | :-- |
| A | foo || 
| ^^ | bar | 第二行 |
| B | baz | 单独一行 |

横合并：某行少写一个单元格、用 || 收尾，左侧单元格 colspan 增加。纵合并：写 ^^ 表示「与上一行同列合并」。

11.3 全部写法

11.4 参数与选项

_config.yml 当前只开了一个选项：

11.5 边界与坑

11.6 小结

• 对齐看分隔行冒号
• 跨列 ||、跨行 ^^（rowspan 已开）
• 表格前留空行，单元格竖线要转义

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

用途：在图片地址后追加 =宽x高 控制显示尺寸，无需 CSS。

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

12.1 最小示例

效果：

对应源码：

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

12.2 常用变体

只定宽（高度按原图比例自动）：

效果：

对应源码：

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

只定高：

效果：

对应源码：

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

12.3 全部写法

12.4 参数与选项

裸加载，无可配选项。输出的是 HTML width / height 属性：只约束显示尺寸，不会裁剪原图。

12.5 边界与坑

12.6 小结

• 语法是 url =宽x高，= 前有空格
• 300x / x200 表示只定一边
• 只改显示尺寸，不改图片本身

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

用途：::: 类型 渲染带色条 + 淡色背景的提示容器。主题已注册 7 种类型：warning / note / info / attention / error / tip / hint。

学习路径：最小示例 → 七种类型 → 全部写法 → 参数与选项 → 边界与坑 → 小结

13.1 最小示例

效果：

对应源码：

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

13.2 七种类型

效果：

对应源码：

::: note
note —— 补充说明。
:::

::: info
info —— 信息提示。
:::

::: attention
attention —— 注意警示。
:::

::: error
error —— 严重错误。
:::

::: tip
tip —— 小技巧。
:::

::: hint
hint —— 隐含提示。
:::

13.3 全部写法

13.4 参数与选项

_config.yml 里用 7 个对象形式分别注册（裸 use 不注册任何容器）：

- name: markdown-it-container
  options: warning
- name: markdown-it-container
  options: note
# … info / attention / error / tip / hint 同理

13.5 边界与坑

13.6 小结

• 三行结构：::: 类型 + 内容 + :::
• 类型必须小写且已注册（7 种）
• 没有标题/折叠能力——需要时用 admon 或 note

14. 提示容器 admon（markdown-it-admon）

用途：!!! 类型 渲染带色条 + 淡色背景的提示容器，渲染为 .admonition 结构。与第 13 节 container 是两个独立插件：标记不同（!!! vs :::）、渲染不同（<div class="admonition tip"> vs <div class="tip">）。

学习路径：最小示例 → 标题与无标题 → 任意类型 → 全部写法 → 参数与选项 → 边界与坑 → 小结

14.1 最小示例

内容缩进 4 空格，块由两个连续空行闭合：

效果：

对应源码：

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

14.2 自定义标题与无标题

标题写在类型后（空格分隔），默认标题是类型名首字母大写；写 "" 表示不要标题：

效果：

对应源码：

!!! note 自定义标题：部署前检查
    标题可以自己写。

""
这一块没有标题，只有正文。

14.3 任意类型

类型不限制（validate 只检查 tag 非空），写成什么就是什么 class，样式由主题 CSS 决定：

效果：

对应源码：

!!! info
    信息块。

!!! example 示例
    类型名可以随便写，没有对应 CSS 时退化为基础样式。

14.4 全部写法

14.5 参数与选项

14.6 边界与坑

14.7 小结

• !!! + 缩进内容 + 两个空行闭合
• 标题默认是类型名，"" 可去掉
• 类型不校验，但没有 CSS 的类型只剩基础样式

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

用途：渲染定义列表（术语 + 多条描述）。

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

15.1 最小示例

术语一行，描述以 :（冒号 + 空格）开头：

效果：

Hexo

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

对应源码：

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

15.2 多条定义

同一个术语可以挂多条描述：

效果：

Hexo

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

基于 Node.js 编写。

对应源码：

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

15.3 全部写法

15.4 参数与选项

裸加载，无可配选项。输出 <dl> / <dt> / <dd>，主题给术语加粗、描述缩进。

15.5 边界与坑

15.6 小结

• 术语独占一行，描述以 : 开头（冒号后必须有空格）
• 空行不影响识别，但缩进决定是否并入同一条描述
• 一个术语可挂多条描述，也可写多段描述

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

用途：渲染 LaTeX 数学公式：$...$ 内联公式，$$...$$ 块级公式（需 front-matter 声明 mathjax: true）。

学习路径：最小示例 → 块级公式 → 全部写法 → 参数与选项 → 边界与坑 → 小结

16.1 最小示例

效果：

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

对应源码：

内联公式：$E=mc^2$

16.2 块级公式

块级公式上下各留一个空行，避免被当段落粘连：

效果：

对应源码：

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

16.3 全部写法

16.4 参数与选项

16.5 边界与坑

16.6 小结

• $...$ 行内、$$...$$ 块级，必须 mathjax: true
• 字面 $ 用 \$ 转义
• 分隔符写死在插件里，配置改不动

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

用途：优化中文排版：避免中英文混排时在错误位置断行。

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

17.1 最小示例

效果：

这是中文测试内容，混合 English 和 2026 年的数字，断行位置更符合中文阅读习惯。

对应源码：

这是中文测试内容，混合 English 和 2026 年的数字，断行位置更符合中文阅读习惯。

插件在中文与拉丁字符/数字边界插入零宽断行机会（<wbr> / word-break 相关处理），正文不需要写任何标记。

17.2 全部写法

17.3 参数与选项

裸加载，无可配选项——_config.yml 里只有一行 - markdown-it-cjk-breaks # 中文排版优化。

17.4 边界与坑

17.5 小结

• 零语法、零配置，写了中文就自动受益
• 只管断行，不加空格

18. 综合示例（多插件组合）

用途：验证多个插件在同一页共存不打架。

学习路径：组合效果 → 对应源码

18.1 组合效果

效果：

任务清单（task-checkbox）：

• emoji 正常：✅
• 缩写正常：API
• 数学正常： $a^2+b^2=c^2$

定义列表（deflist）：

Markdown

轻量级标记语言。

由 John Gruber 发明。

脚注（footnote）：教程 wiki 共 4 篇^[5]。

多个插件组合在同一页面正常工作，互不干扰。

18.2 对应源码

对应源码：

*[API]: Application Programming Interface

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

- [x] emoji 正常：:white_check_mark:
- [x] 缩写正常：API
- [x] 数学正常：$a^2 + b^2 = c^2$

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

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

**脚注**（footnote）：教程 wiki 共 4 篇[^total]。

[^total]: 布局、Tag 插件、交互、Markdown 语法。

附：markdown-it 插件速查表

常见坑：

• 展示语法的代码块必须用 raw 标签（raw/endraw 成对）包裹，防止 nunjucks 预渲染报错或吞掉后续内容
• 文章正文含 $...$ / $$...$$ 公式时，front-matter 必须声明 mathjax: true，否则公式不渲染
• 块级公式 $$...$$ 建议上下各留空行；需显示字面 $ 用 \$ 转义
• link-attributes 的 pattern 在 4.0.1 里不生效——所有正文链接（含站内与锚点）都会被加 target="_blank"，改配置无法只作用于外链
• 任务列表 - [x] 方括号后必须有空格；- [x]xxx 不会渲染为任务；复选框是 disabled 的展示态
• abbr 定义行 *[缩写]: 全称 位置任意（整篇 block 解析后才做替换），但必须独占一行
• container 注册 warning/note/info/attention/error/tip/hint 7 种；::: tip/::: hint 渲染为 info 蓝色提示容器
• admon 用 !!! 开头、内容缩进、两个连续空行闭合，只空一行不会结束
• multimd-table 的 ^^ 是跨行合并，不是上标；|| 是跨列
• 表格与 attrs 组合时，属性块要写在表格下方空两行处