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_dollarssyntax takes inspiration from TeX:$a + b = c$ $$ f(x) = 1 $$It is now also possible to use the backticked
tex_math_gfmsyntax:$`a + b = c`$ ```math f(x) = 1 ```One can choose between
MathJax,KaTeX, andMathMLas 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`$ ```math f(x) = 1 ``` -
In May 2022, GitHub introduced their MathJax-based math, using the
$-$$syntax. After (persisting) problems with this, they first addedmathcode blocks in June 2022, and$`a + b = c`$for inline math in May 2022.
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 Nov 2023.2
Comments
Comments welcome on Hacker News!
-
$-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. ↩ -
I will update the samples and table once in a while to keep track of new developments. ↩