前言

hexo-renderer-markdown-it 是一个基于 markdown-it 的 Hexo 渲染器, 比起默认的渲染插件 hexo-renderer-marked 来说能够提供更多的插件来支持更多的语法, 比如上标 / 下标 / 注脚 / Emoji Sheet 等等. 根据文档说法, 它比默认的渲染器更快, 所以在对大量的文章渲染的时候应该会有优势.

由于前几天在更新默认的渲染器后尝试 hexo-renderer-marked 的 4.1 版本发现 Hexo 的标签插件语法却被它自己的新功能 DOMPurify 毙掉了:

hexo-renderer-marked 中的新功能 DOMPurify 与部分标签外挂语法发生冲突 · Issue #205 · hexojs/hexo-renderer-marked: https://github.com/hexojs/hexo-renderer-marked/issues/205

用我蹩脚的英语水平和外国人交流实在是困难, 只好用简单的中文表述让经过翻译后也能清晰流畅.

在这个 issue 里面提到建议更换 hexo-renderer-markdown-it, 所以我就开始尝试迁移, 毕竟相对 GFM 的格式之外还有很多值得尝试的扩展语法~ 还能装插件.

以上问题已在 9 月 24 日的 Hexo 合并请求中被修复:

feat: load hexo plugin in the theme's package.json by stevenjoezhang · Pull Request #4771 · hexojs/hexo: https://github.com/hexojs/hexo/pull/4771

以下是对 hexo-renderer-markdown-it 使用的一个简单解析.

安装

要为 Hexo 安装并使用 hexo-renderer-markdown-it 需要把默认的渲染器移除之后才能安装 hexo-renderer-markdown-it 使用:

确保位于 Hexo 根目录执行以下命令.

  1. 输入以下命令移除 hexo-renderer-marked:

    1
    npm un hexo-renderer-marked --save

  2. 输入以下命令安装 hexo-renderer-markdown-it:

    1
    npm i hexo-renderer-markdown-it --save

Getting Started · hexojs/hexo-renderer-markdown-it Wiki: https://github.com/hexojs/hexo-renderer-markdown-it/wiki/Getting-Started

配置

以下内容均据项目 Wiki 编写:

Home · hexojs/hexo-renderer-markdown-it Wiki: https://github.com/hexojs/hexo-renderer-markdown-it/wiki

推荐预设

在 Hexo 配置文件 _config.yml 中插入以下内容:

_config.yml
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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
markdown:
  preset: "default" # 渲染器默认预设 # "commonmark": 使用严格 CommandMark 规定. # "default": 默认配置, 类似于 GFM # "zero": 禁用所有预设.
# 以下为 render 选项
  render:
    html: true # 是否解析 HTML 内容, 如果为 true 则表示解析, false 表示将 HTML 转意为文本.
    xhtmlOut: false # 将 HTML 内容渲染为 XHTML 的形式 (XHTML 语法非常严格, 比如原 HTML 中的 <br> 标签必须要使用 <br/> 这样的形式进行 "自闭和") 可能会出现兼容性问题.
    langPrefix: 'language-' # 只适用 Hexo 默认的两个高亮插件禁用时 # 为围栏代码块中语法定义选项渲染后自动添加 class 名前缀, 如 ---html 渲染为 <class="language-html">
    breaks: false # true 则将所有换行渲染为 <br> 标签 # 这种行为不属于 CommandMark 和 GFM.
    linkify: false # true 则自动解析链接并添加为 <a> 标签, false 则将链接渲染为文本.
    typographer: true # 默认 true # 自动转义各种排版用字符, 如 ©
    quotes: '“”‘’' # 当 typographer 定义为 true 时的自动转换引号的行为, quotes: '“”‘’' 则表示将 "123" '123'转换为 “123” ‘123’
# render 选项到此结束
  enable_rules:
  disable_rules:
# 当 preset 定义时的渲染规则 # "zero" 表示禁用所有规则而能单独启用规则 # "default" 表示启用所有规则, 所以只能禁用特定规则. # "commandmark" 将严格遵循 CommandMark 因此不能额外定义规则的启闭.
# 使用单条规则
# disable_rules: 'link'
# 使用多条规则
# disable_rules:
#    - 'link'
#    - 'image'
  plugins: # 插件选项
    - markdown-it-abbr # https://github.com/markdown-it/markdown-it-abbr
    - markdown-it-cjk-breaks # https://github.com/markdown-it/markdown-it-cjk-breaks
    - markdown-it-container # https://github.com/markdown-it/markdown-it-container
#    - markdown-it-deflist # https://github.com/markdown-it/markdown-it-deflist
    - markdown-it-emoji # https://github.com/markdown-it/markdown-it-emoji
    - markdown-it-footnote # https://github.com/markdown-it/markdown-it-footnote
    - markdown-it-ins # https://github.com/markdown-it/markdown-it-ins
    - markdown-it-mark # https://github.com/markdown-it/markdown-it-mark
    - markdown-it-sub # https://github.com/markdown-it/markdown-it-sub
    - markdown-it-sup # https://github.com/markdown-it/markdown-it-sup
#以下为额外安装插件
#    - markdown-it-task-lists # https://github.com/revin/markdown-it-task-lists
  anchors: # 锚点的配置
    level: 1 # 开始创建锚点的等级 # 如 "2" 则表示从 H2 开始创建一直到 H6(最后).
    collisionSuffix: '' # 如果遇到重复的锚点 ID 为其添加数字编号时在这个数字前添加的前缀.
    # 以下为标题锚点配置
    permalink: true # false # 如果为 true 则创建一个除标题外带有固定地址的的锚点标签.
    permalinkClass: 'anchor' # 定义固定锚点的 class 名.
    permalinkSide: 'right' # 设定为 right 则会在标题后添加固定链接.
    permalinkSymbol: '·' # 定义固定链接使用的符号
    # 标题固定锚点到此结束
    case: 0 # 转换锚点 ID 中的字母为大写或小写 # "0" 不转换, "1" 为小写, "2" 为大写.
    separator: '-' # 用于替换空格的符号. # 默认为 "-"

以上配置为目前博主的配置和自己写的注释, 一般情况下注释就能解释所有选项, 但是如果还是有看不懂的可以继续往下一节找对应选项查看更详细的解析.

选项解析

present

preset: 预设, 默认值为 "default", 可选值 "commonmark" / "default" / "zero".

  • "commonmark": 使用严格 CommonMark 模式 (只使用其标准概括的 Markdown 语法).
    查看 CommonMark 具体支持的语法:

    Markdown Reference: https://commonmark.org/help/

  • "default": 启用默认预设(使用所有内置规则, 类似于 GFM 的 Markdown 格式语法).
    若是启用则还需要单独配置下文中的 render 配置选项 html / linkify 和 typographer, 内置的规则中不包含以上三项配置.

  • "zero": 禁用所有内置规则.
    可单独在下文中的 enable_rules 选项配置要例外启用的内置规则.

下文中的 render 选项和 anchors 选项会覆盖对应的内置规则, 如果你想要启用 default 预设的时候只使用内置规则可以将这两个选项留空:

1
2
3
4
markdown:
  preset: "default"
  render:
  anchors:

render

render: 渲染选项, 默认值为:

1
2
3
4
5
6
7
8
render:
  html: true
  xhtmlOut: false
  langPrefix: 'language-'
  breaks: true
  linkify: true
  typographer: true
  quotes: '“”‘’'

  • html: 可选值为 true / false.

    控制 Markdown 文档中的 HTML 内容是否直接渲染, 如果为 true 则表示直接使用 HTML 输出, 如果为 false 则表示对 HTML 内容转意为纯文本.

  • xhtmlOut: 可选值为 true / false.

    HTML 输出时将其兼容为 XHTML.
    如果上文中的 "预设" 使用了 "commonmark" 则会自动开启.

    XHTML 对其语法要求十分严格, 典型特征是所有标签必须闭合, 比如在 HTML 中的换行标签 <br> 也必须要写为 <br /> 形式的 "自闭和标签", 所以如果在 Markdown 中写入了 <br> 标签开启这个选项后将会被转换成 <br />.

  • langPrefix: 值为字串符.

    在 Markdown 中书写代码块如果指定了语言则为输出的对应 HTML 标签 <code> 中自动添加类名前缀, 如默认值则会为<code class=" language-css">代码内容</code>.

    这个选项只有当 Hexo 内置的代码高亮插件都关闭时(使用渲染器处理代码块)才有效.

  • breaks: 可选值为 true / false.

    将 Markdown 文档中所有的换行解析为 HTML 标签 <br>. 比如你使用的是 UNIX 换行符, 会对存在的 "硬换行" 也转换为 <br> 标签.

    这不属于 CommonMark / GFM 甚至 Markdown 规范, 但是如果你喜欢使用一个换行符实现换行而不想在上一行末尾添加 Markdown 和 CommonMark 中规定的两个空格那么可以开启这个选项.

  • linkify: 可选值为 true / false.

    对正文中的链接文本自动转为超链接, 如你在 Markdown 中写了一段 https://www.baidu.com/ 没有使用链接语法或自动链接语法, 那么在渲染时也会自动渲染为 <a href="https://www.baidu.com/">https://www.baidu.com/</a> .

    个人建议: 如果要将链接显示为超链接, 建议对链接写为超链接或者自动链接, 而不是使用此自动转换. 开启这个选项只是为了防止失误忘记超链接或者自动链接而对读者造成不便.不要养成坏习惯.

  • typographer: 可选值为 true / false.

    对正文中的排版符号自动替换.

    典型的是错误的引号使用造成的 "哑引号", 即引号没有正确闭合, 如使用了两个前引号或两个后引号包裹文字, 这样的引用等于没有引用到实际的内容, 被称为 "哑引号".

    不要使用哑的引号（dumb quotes）: https://book.51cto.com/art/201012/240047.htm

  • quotes: 值为字串符.

    引号转换, 如果上一个选项 typographer 开启则此项才有效. 用于转换 "哑引号" 的成对引号或符号.
    如配置为 '“”‘’' 则表示对类似 "123" 和 '123' 的将会被转换为 “123” 和 ‘123’. 也可配置为其他成对的符号用于渲染后校对提醒.

rules

开启与禁用

rules: 规则配置, 默认配置为:

1
2
enable_rules:
disable_rules:

  1. 启用规则

    当上文小节 #present 中配置为 zero 时才能单独对规则进行启用.

    对于单个规则可配置为:

    1
    enable_rules: 'link'

    对于多个规则可配置为:

    1
    2
    3
    enable_rules:
      - 'link'
      - 'image'

  2. 禁用规则

    当上文小节 #present 中配置为 default 时才能单独对规则进行禁用.

    对于单个规则可配置为:

    1
    disable_rules: 'link'

    对于多个规则可配置为:

    1
    2
    3
    disable_rules:
      - 'link'
      - 'image'
查找规则

对于可用渲染规则可查看 Github 源文件:

以 parser_block.js 举例, 打开 Github 查看源文件代码, 开头一串字段:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var _rules = [
  // First 2 params - rule name & source. Secondary array - list of rules,
  // which can be terminated by this one.
  [ 'table',      require('./rules_block/table'),      [ 'paragraph', 'reference' ] ],
  [ 'code',       require('./rules_block/code') ],
  [ 'fence',      require('./rules_block/fence'),      [ 'paragraph', 'reference', 'blockquote', 'list' ] ],
  [ 'blockquote', require('./rules_block/blockquote'), [ 'paragraph', 'reference', 'blockquote', 'list' ] ],
  [ 'hr',         require('./rules_block/hr'),         [ 'paragraph', 'reference', 'blockquote', 'list' ] ],
  [ 'list',       require('./rules_block/list'),       [ 'paragraph', 'reference', 'blockquote' ] ],
  [ 'reference',  require('./rules_block/reference') ],
  [ 'html_block', require('./rules_block/html_block'), [ 'paragraph', 'reference', 'blockquote' ] ],
  [ 'heading',    require('./rules_block/heading'),    [ 'paragraph', 'reference', 'blockquote' ] ],
  [ 'lheading',   require('./rules_block/lheading') ],
  [ 'paragraph',  require('./rules_block/paragraph') ]
];

其中 'table' / 'code' / 'fence' / 'blockquote' / 'hr' ...... 一直到 'paragraph' 是规则名.

Advanced Configuration · hexojs/hexo-renderer-markdown-it Wiki:
https://github.com/hexojs/hexo-renderer-markdown-it/wiki/Advanced-Configuration

plugins

plugins: 插件, 默认值为空, 用于配置 markdown-it 插件的启用以及针对插件自身的配置.

查看本文章节 #插件 查看具体配置方法.

anchors

对于 Markdown 锚点的应用原理和 HTML 的关系可以查看博主写的这篇文章:

深究 Markdown 的锚点与使用方法: /works/markdown_anchor.html

可对下面的配置选项中的选项有更好的理解.

anchors: 锚点配置选项, 默认值为:

1
2
3
4
5
6
7
8
9
anchors:
  level: 2
  collisionSuffix: ''
  permalink: false
  permalinkClass: 'header-anchor'
  permalinkSide: 'left'
  permalinkSymbol: '¶'
  case: 0
  separator: '-'

  • level: 值为数字, 默认为 2.

    定义从哪一级标题开始启用附加锚点 ID, 如配置为 2 这表示从 H2 开始附加 ID 一直到 H6, 如果为 1 则表示从 H1 一直附加到 H6.

  • collisionSuffix: 值为字串符, 默认为空.

    如果锚点 ID 重复而进行附加数字编号时, 对数字后添加固定的后缀的内容, 如有一个重复 ID 的锚点为 <h2 id="锚点-1">锚点</h2> , 如果配置为 's' 则会变为 <h2 id="锚点-1s">锚点</h2>.

以下为单独的标题锚点的设置项, 本该重新归为一类, 但是项目中并没有为这里单独列出, 所以用分割线分隔用于区分.

  • permalink: 可选值为 true / false, 默认为 false.

    为每一级的标题左或者右(可配置)生成一个指向此标题的永久链接锚点, 当点击这个超链接可从指定的标题开始阅读, 或者可以复制这个永久链接成为指向这个文章章节的链接.

    如本文章的章节标题后的那个点一样的效果:

  • permalinkClass: 值为字串符, 默认为 'header-anchor'.

    定义这个标题后锚点的类名, 如配置为 'header-anchor' 则会有这样的标题后锚点HTML 语句: <a class="anchor" href="#锚点">¶</a>.

  • permalinkSide: 可选值为 left / right.

    决定这个标题锚点的位置, left 为左, right 即为右.

    本博客配置为 right 可查看标题显示效果.

  • permalinkSymbol: 值为字串符, 默认为 '¶'.

    为标题锚点指定一个显示的符号, 可以设置为 Emoji / 标点符号 / 特殊符号等等, 本博客设置为 ·.

  • case: 可选值为 0 / 1 / 2 .

    将锚点 ID 中的字母转换为大写或小写, 0 为不转换, 1 为转换为小写, 2 为转换大写.

  • separator: 值为字串符, 默认为 '-'.

    指定用于替换锚点 ID 中空格的符号.

插件

配置插件

markdown-it 最大的特点就是能够安装插件, 基于此的 hexo-renderer-markdown-it 也不列外, hexo-renderer-markdown-it 内置了部分 markdown-it 插件, 可以直接配置启用(否则默认不会启用).

在配置中找到 plugins 选项, 在此之下可配置插件的开启, 如下:

1
2
3
4
markdown:
  plugins:
    - markdown-it-abbr # 第一个插件
    - markdown-it-table-of-contents #第二个插件

可以对指定的的插件设置独有的配置项, 如下

1
2
3
4
5
6
7
8
markdown:
  plugins:
    - name: 'markdown-it-emoji' #插件名
      options: #插件选项
        shortcuts:
          laughing: ':D'
    - name: 'other-plugin' #插件名
      options: #插件选项

安装插件

内置插件

hexo-renderer-markdown-it 内置了以下插件, 可以直接写入插件名开启:

外部插件

所有的 markdown-it 插件名一般都以其 "markdown-it" 开头, 通过包安装到目录或者全局后, 直接在配置中写入插件名即可启用.

由于 hexo-renderer-markdown-it 不支持 GFM 独有的的 Todo list, 所以建议安装以下这个插件用于补足 GFM, 也方便使用:

其他

从 hexo-renderer-marked 迁移

本来不存在 "迁移" 一说, 但是要注意 hexo-renderer-markdown-it 并没有原先 Hexo 默认渲染器的部分功能, 比如:

  • lazyload

    图像延迟加载

  • mangle

    邮箱地址混淆

  • disableNunjucks

    Nunjucks 插件禁用

  • prependRoot

    图像链接根目录替换

  • external_link

    链接新标签页打开以及 nofollow 属性自动追加

    ......

这些功能都会不存在, 如果要使用最好提前安装插件替补或使用主题功能替补.

  1. 我是注释 ↩︎