How to create multi-line equation blocks in GitHub?

Question

GitHub supports the insertion of LaTeX like code in README's. I would like to add some equations spanning multiple lines:

Like in this image

So far I have tried:

1.

$$eqtn1 \\
eqtn2 \\
eqtn3$$

2. $$eqtn1 \\ eqtn2 \\ eqtn3$$
3. $$\begin{matrix}eqtn1 \\ eqtn2 \\ eqtn3 \end{matrix}$$
4. $$\begin{gather*}eqtn1 \\ eqtn2 \\ eqtn3 \end{gather*}$$

And lastly:

$$eqtn1, $$
$$eqtn2, $$
$$eqtn3$$

However, the first three don't render and in the last all three blocks get merged into one line unless I add text between them. Anyone know how I can get multiple lines in my equation block?

I'd like my code to be rendered

eqtn1
eqtn2
eqtn3

With 1 nothing renders. It appears that mathjax does not like the linebreaks. 2 doesn't render, I think mathjax does not like the \\. 3 and 4 don't render anything either. I assume because Mathjax does not support the gather and matrix keywords. And with the last codeblock the equations are rendered:

eqtn1, eqtn2, eqtn3

Any and all guidance is appreciated!

Answer 1

GitHub's implementation of MathJax is pretty wonky. Because Markdown notation and LaTeX notation don't interact well (for example, they both use \ and _ as special characters, but with very different meanings), GitHub tries to protect the special characters in LaTeX, but its algorithm for detecting them is badly broken. In particular, GitHub only properly protects \\ when it is at the end of a line, so you can't use it in the middle of a line, as you do with your examples 2, 3, and 4.

To overcome this, they have added new delimiters $` and `$ for inline math and

``` math
(your math here)  
```

for display math that will avoid most the of the Markdown/LaTeX interactions. So you should use those whenever possible. In particular, you can use \\ in the middle of a line this way. So

``` math
\begin{matrix}eqtn1 \\ eqtn2 \\ eqtn3 \end{matrix}
```

and

``` math
\begin{gather*}eqtn1 \\ eqtn2 \\ eqtn3 \end{gather*}
```

would both work. So would

``` math
\displaylines{eqtn1 \\ eqtn2 \\ eqtn3}
```

Your first and second examples won't work because GitHub uses MathJax v3, which doesn't support \\ for line breaks (only for array row terminators and within \displaylines).

As an aside, I mentioned that \\ is only properly protected when it appears at the end of a line, so you could do

$$
\begin{matrix}
eqtn1 \\
eqtn2 \\
eqtn3
\end{matrix}
$$

and it would work, but you would still face other potential interactions with Markdown and LaTeX. It is better to use ``` math to avoid them entirely.

Answer 2

My suggestion would be to use the aligned function functionality you would usually use in LaTeX, combined with the ```math code block syntax:

```math
\begin{aligned}
 y &= x+2 \\
   &= 2+x
\end{aligned}
```

In this way you can even align your equations using &=.