There are many solutions to support MathJax in Jekyll on the web, but few of them could meet my requirement. After spending a whole day to google the solution, at last I solve the problem. My solution is not perfect, but it works well for me.

Suppose that you have correctly installed and configured the Jekyll for your site. If you don’t know how to do that, goolge it by yourself. The following instructions will help you to use MathJax in Jekyll.

### Use the correct Markdown processor

I have tried almost all the markdown processors. For example, kramdown, which was said to have build-in support of math. But actually it has some problems for the inline math formula with special characters (say, a pipe character like this `$$|\psi\rangle$$`

), and it have to leave a blank line before and after the display math formula.

At last I found that the default markdown processor maruku was the only one meet my requirement. And most importantly, it is officially supported by the Github Pages.

Change your `_config.yml`

as follows to use the maruku processor:

`markdown: maruku`

### Modify the page template

Now we have to modify the page template to add the support of MathJax.

Create a file named with `mathjax_support`

in your `_include`

directory as follows:

```
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
TeX: {
equationNumbers: {
autoNumber: "AMS"
}
},
tex2jax: {
inlineMath: [ ['$','$'], ['\(', '\)'] ],
displayMath: [ ['$$','$$'] ],
processEscapes: true,
}
});
</script>
<script type="text/javascript"
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
```

Note that the above configuration enables the support of automatic equation numbering (the line around `autoNumber: "AMS"`

). If you do not need equation numbering, remove the corresponding codes.

Next, modify the layout template of your pages like follows:

```
<!DOCTYPE html>
<html>
<head>
{% include html_meta %}
<title>How to use MathJax in Jekyll generated Github pages -- Haixing Hu's Homepage</title>
<link href="/bootstrap/css/bootstrap.2.2.2.min.css" rel="stylesheet">
<link href="/css/style.css" rel="stylesheet" type="text/css" media="all">
{% if page.use_math %}
{% include mathjax_support %}
{% endif %}
</head>
<body>
{% include navigation_bar %}
<div class="container-narrow">
<div class="content">
{{ content }}
</div>
<hr/>
{% include footer %}
</div>
{% include JB/analytics %}
</body>
</html>
```

Note the lines around `include mathjax_support`

, those lines include the file `mathjax_support`

you just created in the `_include`

directory, if the post’s front-matter contains a configuration `use_math : true`

.

### Typeset math formula in post

In order to use the math formula in a post, the front-matter of the post must have a variable `use_math`

and set its value to `true`

.

For example, the following is a post using math:

```
layout: post
title: "Test math"
author: Haixing Hu
category: misc
tags: [test]
use_math: true
```

```
Let's test some inline math $x$, $y$, $x_1$, $y_1$.
Now a inline math with special character: $|\psi\rangle$, $x'$, $x^\*$.
Test a display math:
$$
|\psi_1\rangle = a|0\rangle + b|1\rangle
$$
Is it O.K.?
Test a display math with equation number:
\begin{equation}
|\psi_1\rangle = a|0\rangle + b|1\rangle
\end{equation}
Is it O.K.?
Test a display math with equation number:
$$
\begin{align}
|\psi_1\rangle &= a|0\rangle + b|1\rangle \\\\
|\psi_2\rangle &= c|0\rangle + d|1\rangle
\end{align}
$$
Is it O.K.?
And test a display math without equaltion number:
$$
\begin{align\*}
|\psi_1\rangle &= a|0\rangle + b|1\rangle \\\\
|\psi_2\rangle &= c|0\rangle + d|1\rangle
\end{align\*}
$$
Is it O.K.?
Test a display math with equation number:
\begin{align}
|\psi_1\rangle &= a|0\rangle + b|1\rangle \\\\
|\psi_2\rangle &= c|0\rangle + d|1\rangle
\end{align}
Is it O.K.?
And test a display math without equaltion number:
\begin{align\*}
|\psi_1\rangle &= a|0\rangle + b|1\rangle \\\\
|\psi_2\rangle &= c|0\rangle + d|1\rangle
\end{align\*}
Is it O.K.?
```

Here are some notes about the above example:

- The inline formula is between
`$ ... $`

. - The display formula is between
`$$ ... $$`

. - You can use the math envrionment directly, for example,
`\begin{equation}...\end{equation}`

or`\begin{align}...\end{align}`

. - Whenever in the inline math or display math, the star character
`'*'`

**must**be escaped. - In the multi-lines display math, the line break symbol double-backslash
`'\\'`

should be escaped, i.e., use four backslash`'\\\\'`

. - If you found error while typeseting math formula, try to escape some special characters.

### Effect of example

Here is the effect of the above example:

Let’s test some inline math $x$, $y$, $x_1$, $y_1$.

Now a inline math with special character: $|\psi\rangle$, $x’$, $x^*$.

Test a display math: $$ |\psi_1\rangle = a|0\rangle + b|1\rangle $$ Is it O.K.?

Test a display math with equation number: \begin{equation} |\psi_1\rangle = a|0\rangle + b|1\rangle \end{equation} Is it O.K.?

Test a display math with equation number: $$ \begin{align} |\psi_1\rangle &= a|0\rangle + b|1\rangle \\ |\psi_2\rangle &= c|0\rangle + d|1\rangle \end{align} $$ Is it O.K.?

And test a display math without equaltion number: $$ \begin{align*} |\psi_1\rangle &= a|0\rangle + b|1\rangle \\ |\psi_2\rangle &= c|0\rangle + d|1\rangle \end{align*} $$ Is it O.K.?

Test a display math with equation number: \begin{align} |\psi_1\rangle &= a|0\rangle + b|1\rangle \\ |\psi_2\rangle &= c|0\rangle + d|1\rangle \end{align} Is it O.K.?

And test a display math without equaltion number: \begin{align*} |\psi_1\rangle &= a|0\rangle + b|1\rangle \\ |\psi_2\rangle &= c|0\rangle + d|1\rangle \end{align*} Is it O.K.?

OK, that’s all. Have fun with math!