写主题时有个很现实的问题:提示块、选项卡、时间轴这些「好看的排版」,官方 Markdown 都不支持。常见做法是装一堆 hexo-tag-* 插件,但那违背了「零第三方依赖」的初衷——而且每装一个,就多一份「升级后不兼容」的风险。
于是我把它们全写进了主题的 scripts/tags/index.js,一共 14 个标签。这一篇讲实现思路和几个必须知道的坑。
一、标签清单与注册方式
1 | const register = (name, fn, options) => |
| 标签 | 别名 | 用途 |
|---|---|---|
note |
info / success / warning / danger / tip / quote | 提示块 |
fold |
collapse |
折叠面板 |
tabs / tab |
— | 选项卡 |
timeline / event |
— | 时间轴 |
row / col |
— | 栅格 |
button |
btn |
按钮 |
label |
badge |
徽标 |
icon |
fa |
SVG 图标(自带雪碧图) |
mermaid |
— | 流程图 |
linkcard |
— | 链接卡片 |
参数解析统一走一个函数,同时支持逗号和空格分隔:
1 | function toList(args) { |
二、跨标签收集:父子标签怎么协同
tabs / tab 这类父子标签有个麻烦:Hexo 是先解析子标签再解析父标签的,子标签执行时拿不到父标签的上下文。
解法是在模块作用域放一个数组收集子项,父标签渲染时一次性取走:
1 | const tabStore = []; |
splice(0, len) 会同时清空数组。如果只读取不清空,下一篇文档的 tab 会串到这一篇里——这是多页面渲染时最容易出现的脏状态 bug。凡是跨标签共享的数组,取用时必须清空。
三、内容渲染的降级链
标签内容可能是 Markdown,也可能是现成 HTML。判断逻辑:
1 | function md(content) { |
三档降级保证了:即使站点没装 hexo-renderer-marked,标签也不会炸,最坏情况只是换行退化成 <br>。
四、内容过滤器:没有 cheerio 怎么改 HTML
scripts/filters/content.js 在 after_post_render 阶段统一增强正文:代码块工具条、标题锚点、表格滚动容器、图片懒加载、外链新窗口、任务列表。
核心手法在第二篇提过——占位保护 + 正则。完整流程是:
1 | hexo.extend.filter.register('after_post_render', function (data) { |
\u0000 是正文里几乎不可能出现的字符,避免与用户内容冲突。选占位符的第一原则是「不可能自然出现在输入里」,其次才是可读性。
五、三个必踩的坑
坑 1:未知标签会让整个构建失败
很多主题有 tabs_end 这个标签,本主题没有。照着旧习惯写上去,构建直接抛:
1 | Nunjucks Error: unknown block tag: tabs_end |
想在文章里展示标签语法本身(比如写主题文档),必须用 raw 标签包住,否则引擎会把它当真标签执行掉:
1 | {% tabs %} |
上面这段示例之所以能原样显示,是因为它在源码里被 raw 标签包住了——raw 开闭标签之间的内容不做任何解析,原样输出。写教程类文章时这是刚需。
本主题的 tabs 就是上面这种成对写法,没有 tabs_end。
坑 2:EJS 注释里不能写 EJS 标签
1 | <!-- ❌ 这样写会导致编译失败 --> |
注释里的 <% %> 照样会被解析器识别,然后报 Could not find matching close tag。
坑 3:编译失败时退出码仍然是 0
这是最要命的一条:EJS 编译失败时 hexo generate 的退出码是 0,只是写出了 0 字节的 HTML。
所以 CI 或测试脚本里绝对不能只看退出码:
1 | # ❌ 会漏过所有编译失败 |
我一度以为某个广告位没渲染是逻辑问题,实际上是模板编译失败输出了空文件,而脚本看退出码 0 就放行了。凡是「看起来构建成功但内容不对」,先查产物字节数。
六、为什么坚持自己做而不是装插件
算一笔账:14 个标签 + 1 个过滤器,约 400 行 JS,换来:
- 零依赖(不占
node_modules,不受插件停更影响); - 样式完全可控(不用去覆盖插件自带的 CSS);
- 与主题令牌体系天然一致(插件不知道你的
--c-primary-bg)。
代价是维护责任转移到自己身上。对长期维护的主题来说这笔账划算;对一次性站点,装插件更快。选择依据是维护周期,不是代码量。
系列导航
系列总入口 · 上一篇:从响应式到自适应式响应 · 下一篇:运行期多语言切换与 AdSense
评论