Make Hexo Support Math (LaTeX) Again

Author Avatar
Nathaniel May 03, 2017

Some of you may already know that the framework behind this blog is called Hexo. It is a simple yet powerful framework. Most importantly, it’s pretty reliable, too. It works almost at all times.

However, today I suddenly found out that the math expressions on this blog stopped showing up. I didn’t update my blog for quite a few months, and I am pretty sure the last time when I checked, all the math expressions worked perfectly fine without a single issue.

That leads to an assumption that the problem must have not been caused by myself, or any static file that has been sitting on my sever. After spending the entire morning doing researches and experiments, I finally figured out how to make things work again.

Step 1: Use Kramed instead of Marked

First of all, let’s take a look at some facts:

  1. Kramed and Marked are both Markdown parsers/compilers written in JavaScript.
  2. Both are available on npm as Hexo plugins: hexo-renderer-kramed and hexo-renderer-marked.
  3. When Hexo is installed, Marked is used as the default Markdown renderer.

To be really honest, I don’t know why this step is necessary, or what exactly is missing in Marked. But what I do know is none of the following steps would work if we skip this step.

[If you are able to find out why, please leave a comment and I’ll update this section.]

So, to uninstall Marked and install Kramed, do the following:

$ npm uninstall hexo-renderer-marked --save
$ npm install hexo-renderer-kramed --save

Then, go to <your-project-dir>/node_modules/hexo-renderer-kramed/lib/renderer.js and change the following block from

// Change inline math rule
function formatText(text) {
    // Fit kramed's rule: $$ + \1 + $$
    return text.replace(/`\$(.*?)\$`/g, '$$$$$1$$$$');
}

to

// Change inline math rule
function formatText(text) {
    return text;
}

Step 2: Stop Using hexo-math

When it comes to redering math expressions, hexo-math has been the first choice for many developers, and there are bunch of tutorials on the Internet as well. However, the bad news is that hexo-math is already deprecated, and for some reasons it doesn’t work any more, which means we have to use another library.

First, if you have hexo-math installed, uninstall it.

$ npm uninstall hexo-math --save

Then, install a relatively newer package called hexo-renderer-mathjax, which does work.

$ npm install hexo-renderer-mathjax --save

Step 3: Update Mathjax CDN URL

In the previous step, we installed a Hexo plugin called hexo-renderer-mathjax, which is basically a wrapper around a Latex rendering library called Mathjax.

Previously, Mathjax was served by its developers on mathjax.org. However, recently they decided to stop serving the JavaScript file on their own server. As a result, all websites that are still using the original Mathjax CDN are broken, unless they switch to some other CDN, or simply serve this JavaScript file by themselves.

By today (May 3, 2017), the latest version of hexo-renderer-mathjax is still using the deprecated Mathjax CDN. So, we have to manually update it in the installed package source.

In order to do that, first, we need to locate and open the file that contains the actual CDN URL at <path-to-your-project>/node_modules/hexo-renderer-mathjax/mathjax.html.

Then, change the <script> tag that contains the CDN URL to the following:

<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML"></script>

Please note that by doing this we’re using a JavaScript file served publicly on CloudFlare. There are a few implications:

  1. Since this URL contains a version number, it will not be automatically pointed to the latest Mathjax version.
  2. CloudFlare may decide to stop serving this file any time in the future at their own discretion without notifying you. If they do, the math expressions on your website will certainly break again, and you’ll only be able to discover it when you manually inspect your site.
  3. You’re making an assumption that all your website’s visitors have access to cloudflare.com. If their ISPs block the traffic to CloudFlare domains for any reason, they will not be able to see your math expressions.

Under normal circumstances, none of these would be a real problem at all. However, you’re highly recommended to find a stable CDN that contains the right version of Mathjax for your webiste, or simply serve the file on your own server and change the URL accordingly. Anyway, do not let this part be the single point of failure of your website!

Finally, save and close the file.

Step 4: Remember to Activate Mathjax for Your Post

Although now the math feature has been properly configured, it is not activated in each of your posts by default. This is a feature instead of a bug. The Hexo team simply do not want any possible conflict between Markdown and Latex renderers.

So, if you decide enable Mathjax for a post, always remember to include the mathjax derivative and set it to true in the head section of that post. For example,

---
title: Testing Mathjax with Hexo
category: Uncategorized
date: 2017/05/03
mathjax: true
---

[Optional] Other Problems Caused by CloudFlare

If you are using CloudFlare as a CDN for your website, you may be tempted to enable all the acceleration features like I used to do. Unfortunately, some features provided by CloudFlare could also break our math expressions.

For example, you could never see a math expression with CloudFlare’s “Rocket Loader” feature turned on. Since I’m not a CloudFlare employee, I don’t know what black magic Rocket Loader is doing behing the scenes (even if I were a CloudFlare employee, I probably still couldn’t tell you that because it’s most likely a trade secret). However, based on my own experience, math expressions will start showing up again once the Rocket Loader is set to “Off” or “Manual”.

Examples

To view the source code behind each of the following equations, right click on the equation, right click → Show Math As → TeX Commands

Limits and Integrals

Large Operators

Binomial

Matrix

Sets