3 minute read

TLDR: Markdown + math is hard. GitHub is bad, Gitea better, GitLab best. Backticked syntax trumps $-syntax.

Math input is quite a common Markdown extension in Git services these days.

  • The first proper math implementation in Markdown is from Pandoc and dates back to at least 2014. Their tex_math_dollars syntax takes inspiration from TeX:

    $a + b = c$
    f(x) = 1

    It is now also possible to use the backticked tex_math_gfm syntax:

    $`a + b = c`$
    f(x) = 1

    One can choose between MathJax, KaTeX, and MathML as HTML renderers.

  • Gitea has had math support right from their 1.0 release in 2016. They offer TeX ($-$$) and LaTeX syntaxes1:

    \(a + b = c\)
    f(x) = 1
  • In December 2016, GitLab introduced math support using a backticked-syntax:

    $`a + b = c`$
    f(x) = 1
  • In May 2022, GitHub introduced their MathJax-based math, using the $-$$ syntax. After (persisting) problems with this, they first added math code blocks in June 2022, and $`a + b = c`$ for inline math in May 2023.

Feeding on bug reports and discussions, I’ve compiled a list of test cases for math in Markdown that seem to be easy to get wrong. The difficulty ranges from seemingly simple math in lists:

- $$
  f(x) = 1

to devious “HTML syntax” in math:

a <b > c

The samples can be compared on:

The table below gives an overview of what works and what doesn’t.

Key Takeaways

  • The older an implementation is, the fewer errors are present. Apparently, you can’t get around this even as a large company such as GitHub whose young math implementation performs relatively poorly still.

  • The backtick syntax is a great practical choice for online services. They outperform other math syntaxes everywhere and GitLab even gets almost all test cases right. Using backticks to blend in with Markdown avoids a whole array of pitfalls, especially if strict Markdown/HTML sanitizers are present. (A problem that Pandoc doesn’t have.)

From a math-centric point of view, even better-suited for inline math would be `$...$` (the dollar signs inside the “code” block). This allows parsers to only look at inline code contents for determining if it’s math or not. In general though, you’d probably want to keep allowing actual code that starts and ends in $.

Comparison table

Updated May 2024.2

  GitHub $ (14%) Github $` (41%) GitLab $ (85%) GitLab $` (96%) Gitea $ (81%) Gitea \( (85%) Pandoc $ (94%)
Basic example partial
Subsequent math no no
Indented math no no
Math in quote blocks partial partial
Escaped dollar sign no no
Inline and display math in same list no no
Math in footnotes no no
Math in links no no
Escaped symbols in math no
Images and math in the same list no no
Math in <details> no no
< without surrounding whitespace no no
Inline math preceeded by non-whitespace no partial partial
Inline math succeeded by non-whitespace partial partial partial partial
Inline math with %\n no no no no no no
Comments before bracket delimiters no no
Sum/product signs in inline mode or fractions no no
\operatorname no no
Math in stylized text no
Inline math at the end of stylized text no no
Dollar in \text no no no no
Math vs. HTML mix-ups no no partial
sqrt symbol around fractions no no
Matrix without line breaks no
50 or more colors in a block no no
100 or more bracketed exponents or subscripts no no


Comments welcome on Hacker News!

  1. $-toggles are original TeX notation, LaTeX introduced the begin-end \(...\) notation. It’s generally preferable as it’s easier to work with from a compiler’s standpoint, and gives you better info in case of an error. In fact the creator of TeX, Donald Knuth, perfers the begin-end syntax. 

  2. I will update the samples and table once in a while to keep track of new developments.