【Hexo】使用hexo-markdown-it实现渲染markdown脚注能力

慕雪的小助手正在绞尽脑汁···

慕雪小助手的总结

DeepSeek & LongCat

本文介绍了如何配置hexo-markdown-it，让hexo站点支持脚注。

1. 说明

如果你看过本文先前更新的一系列SLAM相关博客，就会发现，在【SLAM】使用evo工具来绘制ORB_SLAM2轨迹图，评估ATE\RPE指标一文中，出现了脚注的能力。

hexo在默认情况下是不支持渲染markdown脚注的，而慕雪编写博客使用的obsidian原生支持脚注。所以，我们只需要修改hexo的配置，让它也能渲染出脚注的样式，就ok了。

脚注的markdown格式如下，脚注实际内容的可以随意放置，markdown渲染器会在渲染的时候将其自动移动到文末显示。我们可以把脚注的内容直接写在脚注附近，后续编辑的时候就不需要跳到文末去看内容了，很方便。

1
2
3

这是一个脚注[^1]

[^1]: 脚注内容

比如：示例脚注文字^[1]

2. 配置

参考：https://gz-metal-cell.github.io/posts/Hexo-markdown-it/

要想实现脚注能力，需要使用github.com/hexojs/hexo-renderer-markdown-it插件，替换掉hexo原生的md渲染器。

1 2	npm uninstall hexo-renderer-marked --save # 卸载原有渲染器 npm install hexo-renderer-markdown-it --save # 更换新的

更换了渲染器之后，把下面这一段放到hexo配置文件_config.yml的最后就可以了。

# https://github.com/hexojs/hexo-renderer-markdown-it
# markdown增强插件，需要先卸载原始markdown渲染器才能安装，安装它是为了尝试脚注功能
# npm un hexo-renderer-marked --save && npm i hexo-renderer-markdown-it --save
markdown:
  preset: 'default'
  render:
    html: true
    xhtmlOut: false
    langPrefix: 'language-'
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'
  enable_rules:
  disable_rules:
  plugins:
    - markdown-it-footnote # 脚注
    - markdown-it-sub   # ~下标~
    - markdown-it-sup   # ^上标^
    - markdown-it-mark  # ==高亮==
    - markdown-it-emoji # 可以渲染:cat:这种emoji
    - markdown-it-task-lists # 任务列表 checkbox
  anchors:
    level: 2
    collisionSuffix: ''
    permalink: false
    permalinkClass: 'header-anchor'
    permalinkSide: 'left'
    permalinkSymbol: '¶'
    case: 0
    separator: '-'
  images:
    lazyload: false
    prepend_root: false
    post_asset: false
  inline: false  # https://markdown-it.github.io/markdown-it/#MarkdownIt.renderInline

其中脚注功能是插件能力的的一部分，需要添加plugins markdown-it-footnote来启用。更多插件的作用可以查看上面贴出来的博客，这里就不多记录了。目测其他的插件用不上，可以在mdit-plugins.github.io/zh/里面找其他插件。

需要注意的是，markdown-it-task-lists需要额外安装插件，否则hexo g的时候会报错

1	npm install markdown-it-task-lists

如上配置之后，可以在本地hexo s测试一下，慕雪实测和butterfly主题完全兼容，不需要修改其他任何配置。

3. 额外添加脚注提示文字

默认情况下，hexo-renderer-markdown-it提供的脚注，是没有任何提示文字，直接显示在文末的（会和正文有一条分割线）。这对不太了解脚注的读者来说可能会产生误导。

所以，我让ai编写了一个js脚本，可以在脚注之前注入一个“脚注：”提示文字，这样就能让脚注明显和其他内容区分开来了。你可以把这个js放到butterfly主题的footter或者header配置里面，就会生效。其他主题使用的方式类似，只要能给主题注入这个js即可。

注意js脚本里面会先判断路径中带有/posts，也就是本站的文章页面才会启动，否则不会生效。

1
2

# 脚注检测并显示一个加粗文字
- <script>document.addEventListener('DOMContentLoaded',()=>{if(window.location.pathname.includes('/posts')){const e=document.querySelector('.footnotes');e&&e.insertBefore(document.createElement('strong').appendChild(document.createTextNode('脚注：')).parentNode,e.firstChild);}});</script>

最终效果如图所示，红框圈出来的部分就是新增的“脚注：”提示文字。