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 tables

Updated December 2025.

GitHub

	GitHub $ (38.5%)	Github $` (59.4%)	Github $$ (42.2%)	Github ```math (59.4%)
Basic example	✓	✓	✓	✓
Consecutive math	partial	✓	✓	✓
Indented math	✓	✓	✓	✓
Math in quote blocks	✓	✓	✓	✓
Escaped dollar sign	partial	partial	partial	✓
Math in footnotes	no	no
Math in links	no	no
Escaped symbols in math	no	✓	no	✓
Math in <details>	✓	✓	no	✓
< without surrounding whitespace	✓	✓	no	no
Inline math preceeded by non-whitespace	no	partial
Inline math succeeded by non-whitespace	partial	✓
Inline math with %\n	✓	no
Comments before bracket delimiters	no	no
Small sum/product signs	✓	✓	✓	✓
\operatorname	no	no	no	no
Inline math in stylized text	partial	✓
Inline math at the end of stylized text	partial	partial
Dollar in \text	no	✓	✓	no
Math vs. HTML mix-ups	no	✓	no	✓
sqrt symbol around fractions	no	no	no	no
Matrix without line breaks	no	partial	no	partial
50 colors in a block	no	no	no	no
100 bracketed exponents or subscripts	no	no	no	no

GitLab

	GitLab $ (74.0%)	GitLab $` (78.1%)	GitLab $$ (100.0%)	GitLab ```math (100.0%)
Basic example	✓	✓	✓	✓
Consecutive math	✓	✓	✓	✓
Indented math	✓	✓	✓	✓
Math in quote blocks	✓	✓	✓	✓
Escaped dollar sign	partial	partial	✓	✓
Math in footnotes	partial	partial
Math in links	✓	✓
Escaped symbols in math	✓	✓	✓	✓
Math in <details>	✓	✓	✓	✓
< without surrounding whitespace	✓	✓	✓	✓
Inline math preceeded by non-whitespace	no	no
Inline math succeeded by non-whitespace	no	no
Inline math with %\n	no	no
Comments before bracket delimiters	no	no
Small sum/product signs	partial	partial	✓	✓
\operatorname	partial	partial	✓	✓
Inline math in stylized text	✓	✓
Inline math at the end of stylized text	✓	✓
Dollar in \text	no	✓	✓	✓
Math vs. HTML mix-ups	✓	✓	✓	✓
sqrt symbol around fractions	✓	✓	✓	✓
Matrix without line breaks	✓	✓	✓	✓
50 colors in a block	✓	✓	✓	✓
100 bracketed exponents or subscripts	✓	✓	✓	✓

Gitea

	Gitea $ (75.0%)	Gitea $` (91.7%)	Gitea $$ (100.0%)	Gitea ```math (100.0%)
Basic example	✓	✓	✓	✓
Consecutive math	no	✓	✓	✓
Indented math	✓	✓	✓	✓
Math in quote blocks	✓	✓	✓	✓
Escaped dollar sign	✓	✓	✓	✓
Math in footnotes	✓	✓
Math in links	no	✓
Escaped symbols in math	✓	✓	✓	✓
Math in <details>	✓	✓	✓	✓
< without surrounding whitespace	✓	✓	✓	✓
Inline math preceeded by non-whitespace	partial	✓
Inline math succeeded by non-whitespace	partial	✓
Inline math with %\n	no	no
Comments before bracket delimiters	no	no
Small sum/product signs	✓	✓	✓	✓
\operatorname	✓	✓	✓	✓
Inline math in stylized text	✓	✓
Inline math at the end of stylized text	no	✓
Dollar in \text	✓	✓	✓	✓
Math vs. HTML mix-ups	✓	✓	✓	✓
sqrt symbol around fractions	✓	✓	✓	✓
Matrix without line breaks	✓	✓	✓	✓
50 colors in a block	✓	✓	✓	✓
100 bracketed exponents or subscripts	✓	✓	✓	✓

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