The State of Math in Markdown

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`$
  
  ```math
  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 syntaxes¹:

  \(a + b = c\)
  
  \[
  f(x) = 1
  \]
  

• In December 2016, GitLab introduced math support using a backticked-syntax:

  $`a + b = c`$
  
  ```math
  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:

• GitHub
• GitLab
• Gitea

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.²

	GitHub $ (14%)	Github $` (41%)	GitLab $ (85%)	GitLab $` (96%)	Gitea $ (81%)	Gitea \( (85%)	Pandoc $ (98%)
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	yes
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

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. ↩