给 hexo 添加数学公式渲染

1 Hexo 数学渲染器插件

1.1 hexo-renderer-marked

hexo-renderer-marked 是 Hexo 默认的渲染器，不支持复杂的数学公式，正是我需要换掉的。

1.2 hexo-renderer-kramed

hexo-renderer-kramed 在默认渲染器的基础上添加了 MathJax 的支持，支持更多的数学公式，与原渲染器有冲突，需要先卸载默认的渲染器再使用它。

1
2
npm uninstall hexo-renderer-marked --save # 先卸载原渲染器
npm install hexo-renderer-kramed --save   # 安装 hexo-renderer-kramed

配置 Hexo 根目录的配置文件 _config.yml：

1
2
3
4
5
6
7
8
kramed:
  gfm: true
  pedantic: false
  sanitize: false
  tables: true
  breaks: true
  smartLists: true
  smartypants: true

采用这种渲染器对于大多数公式都没有问题，但是复杂的公式，比如矩阵、特殊符号等仍然显示不全，无法满足我的需求。

1.3 hexo-renderer-markdown-it

hexo-renderer-markdown-it 增加了对 CommonMark 的支持，渲染速度更快，并且支持一些脚注。不过默认不支持数学公式，需要额外安装 KaTeX 插件，总之我尝试了之后，不能解决我的问题。

1.4 hexo-renderer-markdown-it-katex

hexo-renderer-markdown-it-katex 默认支持 KaTeX 插件，但是 KaTeX 插件本身对公式支持得不完善，所以仍不能满足我的需求。

1.5 hexo-renderer-markdown-it-plus

hexo-renderer-markdown-it-plus 能渲染的内容更多、支持的功能也更多，对于普通用户来说已经足够了，但是公式渲染还是不够好。

2 数学显示插件

前面介绍的都是 Hexo 的渲染器，它们本身并不具备渲染数学公式的能力（或只有简单的公式可以渲染）。真正让数学公式可以显示的是两大插件，分别是 MathJax 和 KaTeX，Hexo 的渲染器基本上是通过它们之一来获得对数学公式的支持。

相比于 MathJax 来说，KaTeX 速度更快、更轻量，但没有前者的功能多。如果你的需求仅仅是简单公式的话，KaTeX 就足够了。由于我需要编写更复杂的公式，因此我选择使用功能更多的 MathJax。具体选择什么还是取决于使用需求。

3 使用 Pandoc 获得更好的 MathJax 支持

Pandoc 是一个强大的渲染工具，它支持从多种标记格式转换为另一种标记格式，这里就包括 Markdown 和 MathJax 格式，以及其它许许多多的格式。就像瑞士军刀一样，它可以完美处理 Markdown 文档中的数学公式。可以查看 Pandoc 官网 了解更多支持的格式。插件 hexo-renderer-pandoc 可以使用 Pandoc 作为 Hexo 的渲染器。

下面介绍如何使用 Pandoc 和 MathJax 作为我的博客渲染器。

3.1 安装 Pandoc 和 hexo-renderer-pandoc 插件

首先，卸载默认的 Hexo 渲染器，安装 hexo-renderer-pandoc 插件：

1
2
npm uninstall hexo-renderer-marked --save # 先卸载原渲染器
npm install hexo-renderer-pandoc --save   # 安装 hexo-renderer-pandoc

然后，为你的电脑安装 2.0 版本以上的 Pandoc。进入 Pandoc 下载页面，点击“Download the latest installer”，然后下载安装即可（Pandoc 支持 Windows、macOS、Linux 系统）。对于 Windows 系统，可能需要重启一次电脑使配置生效。 配置 Hexo 根目录的配置文件 _config.yml：

1
2
3
4
5
6
7
8
9
pandoc:
  args:
    - '-f'
    - 'commonmark_x'
    - '-t'
    - 'html'
    - '--mathjax'
  extensions:
    - '-implicit_figures'

说明：-f 表示输入格式，-t 表示输出格式，这里的 commonmark_x 是带有扩展的 CommonMark 风格。也可以替换为以下 Markdown 变体：

  • commonmark（CommonMark Markdown 风格）
  • gfm（GitHub 风格的 Markdown）
  • markdown（Pandoc 的 Markdown 风格）
  • markdown_mmd（MultiMarkdown 风格）
  • markdown_phpextra（PHP Markdown Extra 风格）
  • markdown_strict（原始未扩展的 Markdown 风格）

--mathjax 用于添加 MathJax 数学公式的支持。

对于更多插件的配置，具体参考Pandoc User’s Guide和hexo-renderer-pandoc。

3.2 安装 hexo-filter-mathjax 插件

然后安装 hexo-filter-mathjax 插件，该插件用于后端渲染 MathJax：

1
npm install hexo-filter-mathjax

配置 Hexo 根目录的配置文件 _config.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
mathjax:
  tags: none # or 'ams' or 'all'
  single_dollars: true # enable single dollar signs as in-line math delimiters
  cjk_width: 0.9 # relative CJK char width
  normal_width: 0.6 # relative normal (monospace) width
  append_css: true # add CSS to pages rendered by MathJax
  every_page: true # if true, every page will be rendered by MathJax regardless the `mathjax` setting in Front-matter
  packages:
    - physics
    - mathtools
    - color
    - noerrors
    - amsmath
  extension_options: {}
    # you can put your extension options here
    # see http://docs.mathjax.org/en/latest/options/input/tex.html#tex-extension-options for more detail

这里主要关注以下 MathJax 的扩展包配置，也就是 packages。可以查看 The TeX/LaTeX Extension List，里面包含了目前支持的所有扩展包。我这里添加了一些需要用到的包。注意，扩展包并不是越多越好，满足够用原则即可，否则可能会拖慢渲染速度。

将 every_page 设置为 true，每个页面都会由 MathJax 呈现。如果你只需要某些页面使用 MathJax，则需要这里设置为 false，并在某篇特定的文章中，添加：

1
2
3
4
5
6
---
title: xxxx
categories: xxx
date: xxxx-xx-xx xx:xx:xx
mathjax: true
---

就可以在单独的这篇文章中使用 LaTeX 语法。

参考资料