简介

hexo-renderer-markdown-it 是一款用于 Markdown 解析和渲染的插件。

  • 用于替换 Hexo 默认自带的 Markdown 渲染器。
  • 提供了更丰富的 Markdown 解析和渲染。

安装

注意：请确保你在 Hexo 主目录下进行以下操作。

  1. 卸载 Hexo 默认自带的 Markdown 渲染器
1
npm un hexo-renderer-marked --save
  1. 安装 hexo-renderer-markdown-it 插件
1
npm i hexo-renderer-markdown-it --save

配置

hexo-renderer-markdown-it 的所有配置，均在 Hexo 的主要配置文件 _config.yml 中进行配置。
配置的方式，主要分为：

  • 简单配置（支持三种配置级别）
  • 高级配置（更详细的定制：渲染器、插件、自动标题ID）

简单配置

hexo-renderer-markdown-it 提供三种简单配置方式（配置级别）zero、default、commonmark。
在 Hexo 的 _config.yml 文件中配置以下内容：

1
2
3
4
# Markdown-it config
#markdown: 'zero'
#markdown: 'default'
markdown: 'commonmark'

每种简单配置有其默认的一些设置。更多个性化配置，请参考：高级配置。

  • zero：禁用大多数解析器功能。仅支持斜体和粗体，甚至不支持所有原始Markdown功能。
  • default（GFM）：解析器的行为类似于github规范。
  • commonmark：提供比Zero预设更多的功能。 此设置将强制插件使用最新的CommonMark规范。

警告：选择任何这些预设将阻止您使用任何随附的插件。

高级配置

hexo-renderer-markdown-it 提供的高级配置，是对简单配置的详细定制。
在 Hexo 的 _config.yml 文件中配置以下内容（官方提供的完整配置，没有特殊需要不用再次修改）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Markdown-it config
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: true
    typographer: true
    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: ¶

高级配置详解

渲染器

1
2
3
4
5
6
7
8
9
# Markdown-it config
markdown:
  render:
    html: true
    xhtmlOut: false
    breaks: true
    linkify: true
    typographer: true
    quotes: '“”‘’'
  • html：定义文档中的HTML内容是否应转义或传递给最终结果。
1
2
html: true # 不转义 HTML 内容
html: false # 转义 HTML 内容，使标签作为文本输出
  • xhtmlOut：定义解析器是否将导出完全兼容XHTML的标记。
1
2
xhtmlOut: true # 必须使用完全的 XHTML 代码，换行必须为 <br/>
xhtmlOut: false # 不必必使用完全的 XHTML 代码，换行可以为 <br>
  • breaks：使源文件中的换行符被解析为
    标记。每次按Enter键都会创建换行符。
1
2
breaks: true # 每次会车换行相当于一个 <br/> 标签
breaks: false # Pa每次会车换行会被忽略
  • linkify：解析器能够将直接粘贴到文本中的链接内联。
1
2
linkify: true # 类似链接的文本，作为链接输出
linkify: false # 类似链接的文本，依然作为文本输出
  • typographer：可以替换常见的排版元素。
1
2
typographer: true # 替换常见的排版元素
typographer: false # 不替换常见的排版元素
  • quotes：单引号、双引号如何被替换
1
2
quotes: '“”‘’' # 'single'、"double" 变成 ‘single’、“double”
quotes: '«»“”' # 'single'、"double" 变成 “single”、«single»

插件

hexo-renderer-markdown-it 默认集成5个 markdown-it 插件

1
2
3
4
5
6
7
8
# Markdown-it config
markdown:
  plugins:
    - markdown-it-abbr
    - markdown-it-footnote
    - markdown-it-ins
    - markdown-it-sub
    - markdown-it-sup
  • markdown-it-abbr：缩写插件
1
2
3
4
5
*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium

The HTML specification
is maintained by the W3C.
  • markdown-it-footnote：脚注插件
1
2
3
4
5
6
7
8
9
10
basic footnote[^1]
here is an inline footnote[^2](inline footnote)
and another one[^3]
and another one[^4]

[^1]: basic footnote content
[^3]: paragraph
footnote
content
[^4]: footnote content with some [markdown](https://en.wikipedia.org/wiki/Markdown)
  • markdown-it-ins：下划线插件
1
++inserted++ => <ins>inserted</ins>
  • markdown-it-sub：下标插件
1
H~2~0 => H<sub>2</sub>O
  • markdown-it-sup：上标插件
1
29^th^ => 29<sup>th</sup>

当然也可以自行安装其他插件：

自动标题ID

使你能够自动为标题创建 ID，以便你可以链接回它们。 由于有效的html文档不能包含两个具有相同ID的元素，因此将对照已给定的其他 ID 来检查添加的每个标题 ID 。

如果title ID 已经给出，这将改变后续各个至title-v2，title-v3等…

v是可以更改的默认冲突后缀。

1
2
3
4
5
6
7
8
9
10
# Markdown-it config
markdown:
  anchors：
    level：2	＃创建 ID 的最低级别。（例如 h2 到 h6）
    collisionSuffix：'v'	＃如果 ID 重复，则后缀为给定的数字。       
    permalink：false	＃如果为 true，则创建除标题外具有永久链接的锚标记。               
    permalinkClass：header-anchor	＃用于永久链接锚标记的类。
    permalinkSymbol：¶	＃用于制作永久链接的符号
    case：0 	＃将锚转换为（1）小写；（2）大写
    separator：'-'	＃用字符替换空格

这个功能我没有使用，也就没太关注。

最后再来说一下我遇到的问题：

一开始我以为是 markdown 渲染引擎的问题，按照上面的步骤把渲染引擎改成了 hexo-renderer-markdown-it ，但是改完之后还是没有用，然后就折腾了一天，最后在 GitHub 的 Issues 上面找到（试出）了解决方法：

把 cheerio 1.0.0-rc.2 升级到 cheerio@0.22.0，果然我还是太菜了。