How to use MathJax in Jekyll generated Github pages -- Haixing Hu's Homepage

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!