Make Hexo Support Math Again

You may already know that the framework behind this blog is called Hexo.

Hexo is simple, powerful, and it works almost at all times. However, today I suddenly found the math expressions on this blog stopped showing up. I didn’t update my blog for quite some time, and last time when I checked, all the math expressions worked perfectly without any problem.

So, I was pretty sure that there must be some problem with the third-party libraries. After doing some research, I finally figured out how to make it 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. Each of them is available on npm as a Hexo plugin: hexo-renderer-kramed and hexo-renderer-marked.
  3. When Hexo is installed, Marked is used as the default Markdown renderer.

Honestly, I don’t really know why this step is necessary, or what exactly is missing in Marked for Hexo. But the following steps worked only AFTER I replaced Marked with Kramed.

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:

// 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

hexo-math was considered as the first choice for rendering math expressions by a lot of developers, and it was introduced in a lot of online tutorials as well. However, the bad news is that hexo-math is already deprecated, and it doesn’t work no more.

So first, if you have hexo-math installed, uninstall it:

$ npm uninstall hexo-math --save

Then, install a relatively newer package hexo-renderer-mathjax that 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 that is basically a wrapper for a Latex renderer 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, and all websites that are using Mathjax better switch to the new CDN URL provided by CloudFlare instead.

By today (May 3, 2017), the latest version of hexo-renderer-mathjax is still using the deprecated CDN URL, so we have to manually update it in the package that was installed by npm early on.

First, open the file <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>

Finally, save the file and close.

Step 4: Remember to Activate Mathjax for Your Post

Although now Mathjax related feature has been properly configured, it is NOT activated in each of your posts by default. This was designed by the Hexo team to avoid possible conflicts between Markdown and Latex renderers.

However, if you do wanna use Mathjax for a specific post, remember to include the mathjax derivative and set it as true in the head of that post. For example,

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

Other Problems Caused by CloudFlare

If you are using CloudFlare CDN for your website, you may be tempted to enable all the acceleration features like I used to do.

However, after I did some research, I found that Mathjax can be interrupted by the Rocket Loader feature provided by CloudFlare. So, I’d recommend you set it as either “Off” or “Manual”.

Examples

To view the source code behind each of the following equations, right click on the equation, right clickShow Math AsTeX Commands

Limits and Integrals

Large Operators

Binomial

Matrix

Sets