Finally! On May 19, 2022, GitHub released one of its most requested features:
Math support on
Markdown! Many had
been anticipating this for years, including myself, so much in fact that I
wrote a browser extension to get there early.
(xhub, it can do a few other things so check
it out.)

The syntax GitHub has chosen is the $-based TeX syntax.

Inline math: $a+b$

Display math:
$$
a + b
$$

It’s well-known and popular among scientists although the more modern LaTeX
syntax with (...) for inline and [...] for display math is actually
recommended in now.
(See here for an explanation.)

The Good

The best thing is that something is finally there. This

#### Cauchy's Theorem

Let $U$ be an open subset of the complex plane $mathbb{C}$, and suppose the closed
disk $D$ defined as

$$
D = {z:|z-z_{0}|leq r}
$$

is completely contained in $U$. Let $f: Utomathbb{C}$ be a holomorphic function,
and let $gamma$ be the circle, oriented counterclockwise, forming the boundary of
$D$. Then for every $a$ in the interior of $D$,

$$
f(a) = frac{1}{2pi i} oint_{gamma}frac{f(z)}{z-a} dz.
$$

gives you

You’ll notice that not everything is working here:

• The curly brackets are missing in the first indented code block. (bug
  report here)

• The math font is a really small, particularly the

  every a in

  towards the end.

• The spacing between the math characters is wrong. (bug report
  here)

• The syntax highlighting in the above code block is off.

Apart from that: Great! This works in README.mds, issues, discussions,
including the Preview tab. Also cool: newcommands are global, so you can
define a command in one block, and use it everywhere in the page:

$$
newcommandmyexp[1]{e^{#1}}
$$

$myexp{i}$
$$myexp{i}$$

The Bad

The syntax

Getting only one of Markdown and LaTeX rendering right is a big challenge.
Mixing them together gets you in all kinds of trouble.

What I think GitHub does now is the following:

1. Render the entire page as Markdown, produce the HTML.
2. Look for $$...$$, and determine somehow if they toggle math mode or if
   they should render as dollar signs.
3. Try the same for $...$ pairs.

This logic brings two fundamental problems.

Competing Markdown and math renderer

As part of step 1, the Markdown is “sanitized”. This means the removal of HTML
tags unless they are
allowed, or the
removal of unless they are right before a letter.

The contents of code blocks are unaffected of course, but $ or $$ blocks
aren’t code blocks as far as Markdown is concerned. This means that, e.g.,

• ${ninmathbb{N}:: n text{even}}$
  

  gets transformed to

  ${ninmathbb{N}:: n text{even}}$
  

  which as math renders like

  

• $frac{f}{a}$
  

  This gets rendered as math because Markdown transforms the &dolla