A hexo plugin that uses MathJax to render math equations. (WARNING: not actively maintained)
CoffeeScript JavaScript
Latest commit 8feff20 Aug 2, 2016 @akfish Bump up version to 3.0.2


hexo-math Build Status

A hexo plugin that uses MathJax/KaTeX to render math equations. Features:

  • Dynamic MathJax/KaTeX injection on demand
  • Provide support to both inline math syntax and math tags
  • Server-side rendering with KaTeX (new in 3.0.0)

New in 3.0.0: Server-side rendering with KaTeX

Since 3.0.0, hexo-math added support to KaTeX .

It has serval advantages over MathJax:

  • Server-side rendering
  • Faster and smaller

Current limitations are:

  • It supports less commands than MathJax. Check out this list for more information.
  • hexo-math will only render math tags with KaTeX


npm install hexo-math --save

See Migration Note if you are upgrading from an older version.


In your site's _config.yml:

  engine: 'mathjax' # or 'katex'
    src: custom_mathjax_source
      # MathJax config
    css: custom_css_source
    js: custom_js_source # not used
      # KaTeX config

Your config will be merged into default config:

const DEFAULT_OPTS = {
  engine: 'mathjax',
  mathjax: {
    src: "//cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML",
    config: {
      tex2jax: {
        inlineMath: [ ['$','$'], ["\\(","\\)"] ],
        skipTags: ['script', 'noscript', 'style', 'textarea', 'pre', 'code'],
        processEscapes: true
      TeX: {
        equationNumbers: {
          autoNumber: "AMS"
  katex: {
    css: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.5.1/katex.min.css",
    js: "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.5.1/katex.min.js",
    config: {
      throwOnError: false,
      errorColor: "#cc0000"


You can use inline math syntax directly. But always remember to escape any special characters by adding a \ before it. LaTex equations usually contains tones of special characters like \, which makes it painful to escape them one by one. In such cases, you can use hexo-math's tags to make your life easier.


Simple inline $a = b + c$.


$$\frac{\partial u}{\partial t}
= h^2 \left( \frac{\partial^2 u}{\partial x^2} +
\frac{\partial^2 u}{\partial y^2} +
\frac{\partial^2 u}{\partial z^2}\right)$$


Single line content will be parsed as inline math (same as $...$):

This equation {% math %}\cos 2\theta = \cos^2 \theta - \sin^2 \theta =  2 \cos^2 \theta - 1 {% endmath %} is inline.

Multiple line content will be parsed as block math (same as $$...$$)

{% math %}
\dot{x} & = \sigma(y-x) \\
\dot{y} & = \rho x - y - xz \\
\dot{z} & = -\beta z + xy
{% endmath %}

Deprecated since 2.0.0

Tag Block:

{% math_block %}
\dot{x} & = \sigma(y-x) \\
\dot{y} & = \rho x - y - xz \\
\dot{z} & = -\beta z + xy
{% endmath_block %}

Migration Note

Migrating to 3.0.0

  • mathjax should be moved under math section in your _config.yml

Migrating to 2.1.0

  • math_block is removed

Migrating to 2.0.0

  • math_block is deprecated (but still usable. This won't break your site)
  • math block is used to handle both inline and block math due to breaking changes made since Hexo 3.x. (This will break your site if you're using math block)

Since Hexo 3.x, nunjucks is used as tag engine instead of swig. Syntax like this won't work any more:

{% math \frac{|ax + by + c|}{\sqrt{a^{2}+b^{2}}} %}

Instead, you should use open and close tag since this version:

{% math %}\frac{|ax + by + c|}{\sqrt{a^{2}+b^{2}}} {% endmath %}

Change all your math tags accordingly.

Migrating to 1.0.6


Since 1.0.6, hexo-math uses a diffrent approach to inject MathJax into your site. MathJax will be injected on-the-fly and on-demand. This means:

  • You are no longer required to run hexo math install
  • MathJax will not be loaded on pages without math tags allowing faster loading speed.

If you have run hexo math install before, please do run:

$ hexo math

This will clean up previous installation. Or you can re-install your theme if for some reason this does not work.

From 1.0.4 to 1.0.5 (Support Hexo 3.0)

Hexo 3.0 introduces multiple breaking changes. Versions before 1.0.5 won't work with it. The following changes are made since 1.0.5 to adapt the new 3.0 API:

  • Block math tag renamed from math-block to math_block

From 1.0.3 and before

Since 1.0.4, MathJax scripts will be injected in <body> section instead of <head> section. Before you update hexo-math to newer version, you should run:

$ hexo math uninstall

After hexo-math is updated, run install again:

$ hexo math install



To run the test suit, first you should install dependencies for the test site:

> $ cd .test-site
> $ npm install

Then run npm test from hexo-math's root dir.

Add post specs

In .test-site/source/_post folder, add a pair of file for each test cases:

  • [test-case-name].md
  • [test-case-name].md.expected

The .md file contains the Markdown source of a post and the .expected file contains expected HTML rendered from the source.

If a test case is added to address certain issues, the issue id should be added to the .md's front matter section:

title: "Tag Escpae"
date: 2015-04-21 02:47:19
- 10
{% math %} |a|<1 {% endmath %}