Math for Hexo

The issue of type-setting Math formulae in Hexo-based GitHub site. This is more twisted than I expected.

Trial 1: kramed + MathJax

First, the mathjax support is needed. If not supported by the theme, mathjax can be installed by,

npm install hexo-renderer-mathjax --save

Then, the renderers for markdown and mathjax have known conflict. To resolve the issue, an alternative renderer for markdown is needed,

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

This solution works fine locally. However, it does not work on GitHub when it is deployed. The reason is probably that the renderer for MathJax requires the calling of external js scripts, which is banned by the GitHub for safety issues.

Similar thing happened before, when this site was started. There was an external javascript that randomly generates some quotes to be displayed on the main webpage. It did not work on GitHub. Eventually, I replaced it with my own local version.

Trial 2: pandoc + MathJax

After some googling, I encountered with another solution based on pandoc. This is essentially using an alternative renderer for Markdown, with the hope that the Math formulae can be generated “statically”.

npm install hexo-renderer-pandoc --save

Some files have to be added to the theme, as indicated by the webpage above.

Yet, this solution does not work for me for the same reason as the first solution.

Trial 3: pandoc + KaTeX

So looks like the problem is with MathJax. What about a different processor for Math formulae, like KaTeX?

The support for KaTeX is straight forward,

npm install hexo-katex --save

Then add the following to _config.yml

pandoc:
  mathEngine: katex

And it works! It seems the Math is directly injected into the html file, so the calling of external javascript can be avoided.

pandoc has a slightly different way in rendering Markdown, which introduces more flavors. For example, the newcommand in LaTeX can be enabled by adding extensions in the preamble area of the markdown file,

variant: markdown+latex_macros

Testing

Inline math: $x=y+1$

Between line: $\displaystyle \frac{x}{y}=f$ Another line

Verify if the conflict is resolved: $\displaystyle \int_a^bf_1dx$

Katex supports the newcommand directives. However, using a user-defined command inside newcommand will result in an error.

Additional references:

1. Trial 1
2. Trial 2
3. Trial 3