Math on GitHub Pages

Goal

I have been searching a process to display math formulas, written in LaTeX in a website for a long time. Now I think I can share my knowledge, hoping it can help other people to divulge math.

Using MathJax

This is the preferred method, cause MathJax is more complete than KaTeX and it is supported on GitHub Pages, see Jekyll Math Support section.

Just make sure you use the kramdown markdown processor, which is the default. If you don’t know what I mean, it is ok, it means that you are using the default provided by GitHub Pages so you don’t need to worry about it.

Just use a double dollar sign $$ to escape LaTeX formulas

you can use an inline formula $$\forall x \in R$$ like this one

you can use an inline formula \(\forall x \in R\) like this one

or display a centered formula like this

$$
M = \left( \begin{array}{ccc}
x_{11} & x_{12} & \ldots \\
x_{21} & x_{22} & \ldots \\
\vdots & \vdots & \ldots \\
\end{array} \right)
$$

To let MathJax do its magic, add this script in your page

<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>

For example in my thesis website I created an _includes/lib/mathjax.html I can use in any page with a Jekyll include like

{% include lib/mathjax.html %}

NOTA BENE formulas are not rendered in the GitHub website but on your GitHub Pages website, emh like this one you are reading right now.

Using KaTeX

I am going to show how to render math snippets server side with KaTeX in order to import them in your GitHub Pages static web site using Jekyll include feature. Note that client side rendering is also possible, but it is not in the scope of this article, by now.

This is an updated version of the original article, that contained a different solution using MathJax and Redcarpet markdown. That solution is obsolete, I found KaTeX and server side rendering, a far better solution.

What is KaTeX?

KaTeX is a fast, easy-to-use JavaScript library for TeX math rendering on the web.

Install katex cli, with npm do

npm install katex -g

Create two folders that will contain inline and display snippets

mkdir -p tex-snippets/inline
mkdir -p tex-snippets/display

An inline snippet, like $\forall x \in R$ , does not break its row.

A snippet in display mode will be centered, usually it is a formula, for example

$M = \left( \begin{array}{ccc} x_{11} & x_{12} & \ldots \\ x_{21} & x_{22} & \ldots \\ \vdots & \vdots & \ldots \\ \end{array} \right)$

Create file tex-snippets/inline/for-any-real.tex with the following content

\forall x \in R

Create file tex-snippets/display/matrix.tex with the following content

M = \left( \begin{array}{ccc}
x_{11} & x_{12} & \ldots \\
x_{21} & x_{22} & \ldots \\
\vdots & \vdots & \ldots \\
\end{array} \right)

Create two folders that will contain inline and display rendered output in your Jekyll includes folder

mkdir -p _includes/math/inline
mkdir -p _includes/math/display

Generate html output

cat tex-snippets/display/matrix.tex | katex --display-mode > _includes/math/display/matrix.html
cat tex-snippets/inline/for-any-real.tex | katex > _includes/math/inline/for-any-real.html

Finally, add KaTeX CSS to your html page.

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.5.1/katex.min.css">

If you read KaTeX Usage, there is also a JavaScript tag to add, but it is required only for client side rendering.

Now you can include the snippets in your website using Jekyll include tags

• {% include math/inline/for-any-real.html %}
• {% include math/display/matrix.html %}