# hexo-math

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

## Install

npm install hexo-math --save

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

## Config

In your site's _config.yml:

Your config will be merged into default config:

## Usage

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.

Inline:

Block:

Tag:

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

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

Deprecated since 2.0.0

Tag Block:

{% math_block %} \begin{aligned} \dot{x} & = \sigma(y-x) \ \dot{y} & = \rho x - y - xz \ \dot{z} & = -\beta z + xy \end{aligned} {% 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:

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


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

Change all your math tags accordingly.

### Migrating to 1.0.6

!!!IMPORTANT!!!

Since 1.0.6, hexo-math uses a different 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

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

## Development

### Test

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

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

In .test-site/source/_post folder, add a pair of file for each test cases:
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: