原文在我的博客：Hexo + Mathjax: 公式离线渲染
目前我的博客上的 Mathjax 公式是在客户端渲染的。这种方式实现比较便利，主题 NexT 已经帮我们实现了，我们只需要打开配置开关就可以了。但是客户端渲染的方式有如下两个比较严重的问题：
- Mathjax 的前端脚本会产生为数不少的资源请求
- 在公式比较多的页面中（我的 Academic 版块的公式就非常多），渲染效率会比较慢，这意味着公式需要好几秒才能渲染，这在写作的时候非常不利。因为为了确保公式格式正确，我在每编写一个公式之后，都会刷新页面查看渲染结果。如果每次刷新都要等待这么长的时间会非常严重。另外，对于访问我的博客的用户来说，太长的渲染时间也是一个问题。
这篇文章旨在使用离线渲染的方式解决这个问题。
渲染流程介入
所谓离线渲染是指让 Hexo 在生成静态网站未见时就完成 Mathjax 的渲染。目前 NexT 是不支持这个功能的，需要我们自己写脚本实现。我们可以通过 Hexo 的事件系统介入渲染流程。
首先我们在博客的根目录下的 scripts 文件夹下面新建一个 Javascript 脚本。这个脚本的名字没有限制，Hexo 会加载这个目录下的所有 Javascript 脚本。例如可以命名为 mathRender.js。我们在这个文件夹中监听 Hexo 渲染过程中的事件。显然，公式的渲染应该在所有其他的渲染完成以后进行。因此我们可以选择注册一个 Hexo 的过滤器([Filter]{.i})。
hexo.extend.filter.register('after_post_render', function (data) {
// do something
})
我们的主体功能实现就放在这个函数里面。
Mathjax in Node.js
mathjax-node-page
Mathjax 是一个非常庞杂的项目，因此我们需要依赖一些对 Mathjax 进行了良好封装的包来处理 Mathjax 渲染的问题，不然光一个配置环节都会非常麻烦。我们这里选择 pkra/mathjax-node-page 这个项目。这个项目将 Mathjax 的渲染处理为一个单一的函数 mjpage。这个函数接受四个参数：
mjpage(input, mjpageConfig, mjnodeConfig, callback)
其中第一个是渲染的输入内容。第二项是页面配置，你可以认为这个配置是 Mathjax 的前端配置的一个包装。第三项则是传递 mathjax-node 的参数。mathjax-node 是一个更加底层一些封装，我们这里不太需要关注这个封装的细节。最后一个参数是完成渲染之后的回调。由于接口形式是异步的，因此我们在上一个章节中注册的after_post_render的处理函数也应该是异步的，即代码整体应该有如下的特点：
hexo.extend.filter.register('after_post_render', async function (data) {
// do something
return new Promose((resolve, reject) => {
mjpage(input, mjpageConfig, mjnodeConfig, (output) => {
resolve()
})
})
})
配置
这里我们的配置信息的目的，是还原前端渲染场景中的配置，对于其他内容我们不用太在意。在mjpageConfig中，专门有一个字段Mathjax负责传递前端配置。这大大简化了我们的配置操作。这里我的配置内容如下：
const mjpageConfig = {
format: ["TeX"],
ouptut: "html",
singleDollars: true,
fragment: false,
cssInline: true,
fontURL: "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/fonts/HTML-CSS",
displayErrors: false,
MathJax: {
tex2jax: {
inlineMath: [ ['$', '$'], ['\\(', '\\)'] ],
processEscapes: true,
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
},
TeX: {
extensions: data.mathjaxext,
equationNumbers: {
autoNumber: 'all'
},
}
,
"HTML-CSS": {
preferredFont: "TeX",
availableFonts: ["TeX"],
}
}
}
这里要注意这么几个配置：
-
singleDollars: 决定了是否支持行内公式，确保这一项为true -
fragment: 这决定了渲染的输出是一个完整的html文件内容，还是只是渲染内容（即document.body.innerHTML）。【~不过后面我们没有采用API中的回调函数接口来获取渲染结果，原因后面会说明。】 -
cssInline: 确保带上css样式信息。
至于mjnodeConfig，使用默认的配置就可以了。
渲染的输入与输出
现在我们来找到渲染的输入输出内容。输入的问题很好解决，使用 data.content 即可，data 是过滤器函数提供的参数。data.content 是对源文件进行渲染的直接结果，即将要插入div.post-body中的内容。我们可以将这个字符串内容直接交给mjpage来处理。
不过怎么处理输出是一个问题。当input的输出内容是字符串时，输出，即callback的输入参数也会是字符串。若mjpageConfig.fragment=false，输出的会是一个具有html, body的完整 html 内容，这不符合我们的要求。渲染过程的输出，应该永远只是针对源文件的直接渲染结果。例如将**text**变成<strong>text</strong>，而不能变成<html><body><strong></strong></body></html>。如
果令mjpageConfig.fragment=true，会输出正确的html的内容，但是css样式信息会丢失（css样式位于document.body.head）。
为了兼顾这两个问题，我们不使用mjpage的callback参数，而是使用MjPageJob提供的beforeSerialization事件。这个事件发生在渲染完成之后，调用callback回调之前。而事件的响应函数的两个参数分别为完成的DOM（JSDOM对象）和css样式（字符串）。故渲染如下：
return new Promise((resolve, reject) => {
mjpage(data.content, mjpageConfig, mjnodeConfig, function(output) {
}).on("beforeSerialization", function(document, css) {
data.content = document.body.innerHTML
data.head = `<style type="text/css">${css}</style>`
resolve()
})
})
模板渲染
最后的问题是模板渲染。所谓模板渲染是指将博客源文件的内容嵌入到swig模板中。这里我们除了html的内容以外，还需要将css样式也渲染进模板。为了解决这个问题，我们将css信息单独放到data.head中，然后在NexT的模板文件layout/_layout.swig中，做如下修改：
<html class="{{ html_class | lower }}" lang="{{ config.language }}">
<head>
...
{{ page.head }}
</head>
...
</html>
完整脚本
const mjpage = require("mathjax-node-page").mjpage
hexo.extend.filter.register('after_post_render', async function (data) {
if (!data.offlineMath) {
return
}
const mjpageConfig = {
format: ["TeX"],
ouptut: "html",
singleDollars: true,
fragment: false,
cssInline: true,
fontURL: "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/fonts/HTML-CSS",
displayErrors: false,
MathJax: {
tex2jax: {
inlineMath: [ ['$', '$'], ['\\(', '\\)'] ],
processEscapes: true,
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code']
},
TeX: {
extensions: data.mathjaxext,
equationNumbers: {
autoNumber: 'all'
},
}
,
"HTML-CSS": {
preferredFont: "TeX",
availableFonts: ["TeX"],
}
}
}
return new Promose((resolve, reject) => {
mjpage(input, mjpageConfig, {}, (output) => {})
.on("beforeSerialization", function(document, css) {
data.content = document.body.innerHTML
data.head = `<style type="text/css">${css}</style>`
resolve()
})
})
})
style标签的处理
使用过程中发现一个问题。如果我们在博客的的正文中使用了style标签定义样式，那么mjpage在处理后，会将这部分内容移动到head部分，故回调函数中document.body.innerHTML中就不会再包含这些内联样式，导致样式丢失。为了继续支持内联样式，我们需要将docuemnt.head中的内容插入到输出中。因此，上一个章节的代码中最后的return需要做如下修改:
return new Promose((resolve, reject) => {
mjpage(input, mjpageConfig, {}, (output) => {})
.on("beforeSerialization", function(document, css) {
data.content = document.body.innerHTML
data.head = document.head.innerHTML
resolve()
})
})
