LaTeX on Github Pages+minimal mistakes+MathJax

To have $\LaTeX$ equations on this website, which is run on Github Pages using Jekyll and AcademicPages (a fork of Minimal Mistakes), I had to make a few guesses, so here are the secrets.

Setting up MathJax

First, the LaTeX code is interpreted using MathJax, which is loaded and configured in the file:

_includes/head/custom.html

I modified the default configuration of MathJax to use ‘$$’ instead of ‘$’ to delimitate LaTeX code (but there is a catch) or adding some commands (macros) for quantum mechanics.

On the original repository, the version 2.7.4 is loaded by default, I changed it to the 2.7.7 just to have something more recent. I tried the version 3.0.5 and all the equations disappeared, so I did not insist. The modified part of the file looks like this:

<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    tex2jax: {
      inlineMath: [ ['$$','$$'], ["\\(","\\)"] ],
      displayMath: [ ['$$','$$'], ["\\(","\\)"] ],
    },
    TeX: {
      Macros: {
        bra: ["\\langle{#1}|", 1],
        ket: ["|{#1}\\rangle", 1],
        braket: ["\\langle{#1}\\rangle", 1],
        bk: ["\\langle{#1}|{#2}|{#3}\\rangle", 3]
     }
   }
  });
</script>

<script src='https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-MML-AM_CHTML' async></script>

The file mentioned is already included in the header of the default layout for pages which can be found at:

_layouts/default.html

Any page based on this layout or another layout based on it will benefit from MathJax automatically. At that point the only tricky part is to write equations that will be properly interpreted.

Writing interpretable \(\LaTeX\)

It took me hours to figure out how to have aligned equations and matrices with the system powering this website, so here is what I believe I understood:

• You need to tell Markdown (the language of the .md files) when LaTeX code starts and ends.
• Markdown accepts both LaTeX code surrounded by \$\$ or directly between \\begin{...} and \\end{...} statements.
• Something I do not understand will wrap any LaTeX code surrounded by ‘$$’ that contains an ampersand (‘\&’) with a ‘CODATA’ which will comment out the code by accident.
• LaTeX code directly between ‘begin’ and ‘end’ statements (no dollar sings) can contain ampersands if it is formatted as follows:

\begin{equation}
\begin{aligned}
  ...
\end{aligned}
\end{equation}

The trick is the use of the ‘aligned’ environment from AMS. Why it is like that? I have no idea.

There are some additional rules that I had to guess. For example, between dollar signs underscores are interpreted directly as LaTeX code, but without the dollar signs Markdown seems to mess with them in some cases as shown below:

$$ {X}_{0} $$ (works)
$$ X_0 $$ (works)

\begin{equation}
\begin{aligned}
  {X}_{0} (does not always work)
  {X}\_{0} (works)
  X_0 (works)
  \hat{a}_{b} (does not always work)
  \hat{a}_b (works)
  \hat{a}_{b+c} (works)
\end{aligned}
\end{equation}

A challenging part was to guess how to deal with spaces, linebreaks, and ampersands. In the example below, because there are no dollar signs for the reason explained above, the usual two backslashes must be quadrupled. From what I understood, there are escape backslashes for Markdown and other things and so many of them will disappear before the LaTeX code is interpreted by MathJax.

\begin{equation}
\begin{aligned}
  {\sigma}_{1} =  
  \begin{pmatrix}
    0 & 1 \\\\\\\\
    1 & 0
  \end{pmatrix} 
\end{aligned}
\end{equation}

Finally, the last trick is for having, for example, a sum of matrices. No blank space is allowed at the end of each line, like in:

\begin{equation}
\begin{aligned}
  X_0 \otimes X_1 =  
  \begin{pmatrix}
    0\begin{pmatrix} 
      0 & 1 \\\\\\\\
      1 & 0
    \end{pmatrix} & 1\begin{pmatrix}
                      0 & 1 \\\\\\\\
                      1 & 0
                     \end{pmatrix} \\\\\\\\
    1\begin{pmatrix} 
      0 & 1 \\\\\\\\
      1 & 0
     \end{pmatrix} & 0\begin{pmatrix}
                       0 & 1 \\\\\\\\
                       1 & 0
                      \end{pmatrix} 
  \end{pmatrix} = 
  \begin{pmatrix}
    0 & 0 & 0 & 1 \\\\\\\\
    0 & 0 & 1 & 0 \\\\\\\\
    0 & 1 & 0 & 0 \\\\\\\\
    1 & 0 & 0 & 0 
  \end{pmatrix}
\end{aligned}
\end{equation}

I hope this will help a few people.