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**变成<strong>text</strong>,而不能变成<html><body><strong></strong></body></html>。如
果令mjpageConfig.fragment=true,会输出正确的html的内容,但是css样式信息会丢失(css样式位于document.body.head)。

为了兼顾这两个问题,我们不使用mjpagecallback参数,而是使用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()
    })
  })

推荐阅读更多精彩内容