About six weeks ago, on May 19, 2022, GitHub released Math support on Markdown. At the time of the release, it received criticism for being ill-designed and buggy. I, too, wrote a blog post about it.

In the weeks following the release, GitHub have tried to address the issues. Let’s take a look at where math on GitHub stands now.

(Note: Most examples can be found on my GitHub math test repo.)

Fixed issues

  • Kerning

    At the time of the release, kerning between symbols in LaTeX blocks was completely off. This was probably a simple math font config bug, and was fixed swiftly after release.

    Before:

    After:

  • Math in lists, tables, headers works now.

Markdown vs. math

One, if not the major issue with GitHub’s math support is its syntax. They’re using the old familiar $...$ for inline and $$...$$ for display math. This is easy for users but unfortunately does not integrate well with Markdown at all. Whatever Markdown tools run on a text file, they’ll see everything between $-signs as regular text. This means that certain symbols are sanitized away, other symbols are forcibly \-escaped etc. Let’s review some of the math that failed to display correctly right after the release.

  • $\{n\in\mathbb{N}:\: n \text{even}\}$

    This is still fails to display correctly. The curly brackets are removed, the \: isn’t displayed a space but as a :. Workaround: Double-escaping LaTeX commands that don’t start with a letter:

    $\{n\in\mathbb{N}:\: n \text{even}\}$

    You’d have to go back to singly-escaped brackets and spaces though once the issue is fixed. I’m not sure when or if this will happen. Not sure what to recommend here.

  • $a <b > c$

    This still doesn’t get rendered as math as <b > is recognized as an HTML opening bold tag.

  • $[a+b](c+d)$

    Also still doesn’t get rendered as math. The problem: [...](...) is accidentally the syntax for Markdown links. It’s recognized as such, and math is skipped.

  • $U$

    Again, the interior is recognized as Markdown code, and math is not rendered.

It seems that GitHub haven’t been able to tackle any of the syntactical issues yet. That’s no surprise: Math was added as an afterthought, and if the Markdown sanitizer is applied first, you’d have to drill that one open. This is a costly endeavor and I’m not sure if GitHub want to go down that path. So far, they don’t.

$ vs. dollar bugs

GitHub might have taken inspiration from StackExchange which also uses $...$ as math syntax delimiters. In contrast to StackExchange, though, GitHub wanted “regular” dollar signs to continue rendering as such. What is a regular dollar sign though? That’s where it gets confusing and, consequently, buggy.

GitHub still renders

An apple costs $1, a mango $2.

as dollar signs. This, however,

An apple costs 1$, a mango 2$.

is math. This too:

An apple costs $1, a mango $ 2.

It seems to be that the terminating $ is only treated as a LaTeX-toggle if not immediately followed by an alphanumeric character. If it is followed by an alphanumeric, the opening $ is also treated as a regular dollar. It’s unclear to me how it works exactly. Experience shows: The clearer the syntax, the fewer bugs appear. The syntax here is not clear, so you have plenty of bugs:

  • $x + $2 $

    renders as

    The rest has somehow disappeared.

  • where $T$ is lookback; $\tau$ is horizon.

    This line is rendered as

    Whoops! What happened here?

  • $x = \text{my $y$}$

    Dollar signs within LaTeX completely throw off the parser.

  • $x =\$$

    Although properly escaped, the parser gets confused with the dollar sign.

Note that StackExchange doesn’t have those problems: There, $ toggles math, always. If you want a regular dollar sign, you’ll have to escape it, \$.

The remedy

As outlined in the previous blog post, and as done by GitLab and my browser extension xhub, a clean fix for all of the above problems is to use a different syntax, e.g.,

$`a + b = c`$

for inline math and

```math
a + b = c
```

for display math. This only looks half-TeXy at first, but it’s easy enough to type and integrates nicely with Markdown. Thanks to the backticks, (which indicate to Markdown parsers that what follows is “code”) its contents never messed with. There is no confusion with dollar signs either.

Conclusion

GitHub’s current choice of syntax goes against the Markdown grain. Fixing bugs is here hard, as highlighted by the fact that none of the initial syntax issues could be fixed yet. It’ll continue to be an uphill battle for GitHub engineers, and I’m afraid such math support will never be reliable, let alone complete. This hinders technical innovation. (For example, I’m working on a LaTeX-to-Markdown converter that requires robust math support.)

Backtick math is a viable alternative, proven to work in practice. When coming from the TeX world (like me), typing backticks might feel unfamiliar at first, but it’s easy to get used to, especially in a Markdown context. Since it eliminates all the issues described above, it is, in my opinion, the syntax that GitHub should have adopted. Perhaps it’s not too late to make a switch.

Comments

Comments welcome on Hacker News!