故事的开始

脚注和参考文献对于Hexo博客大概是一个过于“Heavy”的功能,但是我的确需要它。之前我一直采取自己手写html标签的方法来添加脚注和参考文献(方法好像来自stackoverflow):

1
2
<a href="#bib1" id="bib1ref"><sup>[1]</sup></a>
<a id="bib1" href="#bib1ref"><sup>[1]</sup></a>

得到的效果大概是这样的(链接点击后可以互相跳转):

这是一句需要参考文献的话。[1]

[1] 参考文献的具体内容。

这样写了五十几篇文章(之前英诗的脚注和参考文献都是这么解决的)之后,我终于厌倦满天飞的html标签和需要自己手动维护的编号了。

hexo-renderer-markdown-it插件

于是我找到了这个插件:hexo-renderer-markdown-it,其中包含了脚注功能。下面讲一下我的安装和配置过程吧。

Disclaimer:我只能保证以下内容在今天(2018.8.12)和当前插件的版本(3.4.1)是适用的。(虽然作者已经三年没有更新了,以至于有人fork了一个功能更强大的hexo-renderer-markdown-it-plus出来……虽然这个插件也有段时间没更新了)

首先卸载原来的markdown渲染插件(我这里原来是marked,这是Hexo提供的默认渲染插件),然后把hexo-renderer-markdown-it装上:

1
2
npm un hexo-renderer-marked --save
npm i hexo-renderer-markdown-it --save

然后在根目录下的_config.yml中进行相应的配置。简单的配置方法只包括设置markdown格式,这里就不详述了。高级的配置方法中包含很多可选项:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# Markdown-it config
## Docs: https://github.com/celsomiranda/hexo-renderer-markdown-it/wiki
markdown:
# 渲染设置
render:
# 置为true时,html内容保持不变;置为false时,html内容将被转义成普通字符串
html: true
# 是否生成与XHTML完全兼容的标签(虽然我不懂是什么意思)
xhtmlOut: false
# 置为true时,每个换行符都被渲染成一个<br>(即Hexo的默认表现);置为false时,只有空行才会被渲染为<br>(GFM的默认表现)
breaks: true
# 是否自动识别链接并把它渲染成链接
linkify: true
# 是否自动识别印刷格式(意思是把(c)渲染为©这样的)
typographer: true
# 如果typographer被设置为true,则该选项用于设置将dumb quotes("")自动替换为smart quotes
quotes: '“”‘’'
# 设置所需插件
plugins:
- markdown-it-abbr
- markdown-it-footnote
- markdown-it-ins
- markdown-it-sub
- markdown-it-sup
# 锚点设置(因为我没有尝试相关内容,所以就不翻译相关说明了)
anchors:
level: 2
collisionSuffix: 'v'
permalink: true
permalinkClass: header-anchor
permalinkSymbol:

插件的效果

这里的示例参考了markdown-it-footnote(也就是markdown-it自己用于实现脚注功能的插件):

1
2
3
4
5
6
7
8
9
10
11
12
Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

Subsequent paragraphs are indented to show that they belong to the previous footnote.

This paragraph won’t be part of the note, because it isn’t indented.

Here is an inline note.^[Inlines notes are easier to write.
Since you don't have to pick an identifier and move down to type the note.]

Here is a footnote reference,[1] and another.[2]

This paragraph won’t be part of the note, because it isn’t indented.

Here is an inline note.[3]

这个插件似乎参考了Pandoc的规范:

  • 脚注标识符中不能包含空格、tab或换行符,且标识符不会出现在最终的渲染结果中
  • 每条脚注的前后都应该有空行
  • 如果需要在脚注中分段,可以将后面的段缩进来表示它们属于同一段脚注
  • 脚注不一定必须位于文档的最后部分,除了块元素内部,它们可以出现在其他任何位置(虽然在这个插件中并未实现)
  • 行内脚注不能分段

(值得注意的是,[^1]:中的冒号是语法重要的一部分。)

在文章最下面应该能看到分割线和脚注的内容。说实话,我对这个插件的效果并不完全满意,因为我无法区分脚注和参考文献,也无法自定义脚注的显示位置。如果希望采用现有工具实现上述需求的话,可能改用个人维基效果会比较好,但那样又实在太“Heavy”了,我已经尝试过并放弃这种做法了。所以,如果以后有时间,我也尝试去开发一个markdown-it-footnote-plus一类的东西好了。


  1. Here is the footnote.

  2. Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they belong to the previous footnote.

  3. Inlines notes are easier to write.
    Since you don't have to pick an identifier and move down to type the note.