Hexo + Mathjax: 公式离线渲染

原文在我的博客：Hexo + Mathjax: 公式离线渲染

目前我的博客上的 Mathjax 公式是在客户端渲染的。这种方式实现比较便利，主题 NexT 已经帮我们实现了，我们只需要打开配置开关就可以了。但是客户端渲染的方式有如下两个比较严重的问题：

1. Mathjax 的前端脚本会产生为数不少的资源请求
2. 在公式比较多的页面中（我的 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"], 
      }
    }
  }

这里要注意这么几个配置：

1. singleDollars: 决定了是否支持行内公式，确保这一项为true
2. fragment: 这决定了渲染的输出是一个完整的html文件内容，还是只是渲染内容（即document.body.innerHTML）。【~不过后面我们没有采用API中的回调函数接口来获取渲染结果，原因后面会说明。】
3. cssInline: 确保带上css样式信息。

至于mjnodeConfig，使用默认的配置就可以了。

渲染的输入与输出

现在我们来找到渲染的输入输出内容。输入的问题很好解决，使用 data.content 即可，data 是过滤器函数提供的参数。data.content 是对源文件进行渲染的直接结果，即将要插入div.post-body中的内容。我们可以将这个字符串内容直接交给mjpage来处理。

不过怎么处理输出是一个问题。当input的输出内容是字符串时，输出，即callback的输入参数也会是字符串。若mjpageConfig.fragment=false，输出的会是一个具有html, body的完整 html 内容，这不符合我们的要求。渲染过程的输出，应该永远只是针对源文件的直接渲染结果。例如将**text**变成text，而不能变成。如
果令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 = ``
      resolve()
    })
  })

模板渲染

最后的问题是模板渲染。所谓模板渲染是指将博客源文件的内容嵌入到swig模板中。这里我们除了html的内容以外，还需要将css样式也渲染进模板。为了解决这个问题，我们将css信息单独放到data.head中，然后在NexT的模板文件layout/_layout.swig中，做如下修改：

  ...

  {{ page.head }}



...

完整脚本

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 = ``
      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()
    })
  })