Markdown math
Markdown has no maths of its own. What every renderer that supports it agreed on instead is LaTeX between dollar signs: one either side for a formula inside a sentence, two for one on its own line.
The area of a circle is , which follows from the integral.
Two dollar signs, and the formula is centred on a line of its own.
The syntax is LaTeX, and that is the hard part
The dollar signs are the easy half. What goes between them is LaTeX, a typesetting language older than the web and considerably larger than markdown: \frac{a}{b} for a fraction, \sum_{i=1}^{n} for a sum, \alpha for a Greek letter. Nobody memorises it. Everybody looks it up.
What renderers actually run is KaTeX or MathJax, and neither implements all of LaTeX. If a macro works in a paper and not in your README, that is usually why.
Dollars in prose are usually money
The rule renderers settled on is that the opening dollar must be followed by something other than a space, the closing one preceded by something other than a space, and the closing one not followed by a digit. So $5 and $10 stays as prices, and $x + y$ becomes maths. Where you need a literal dollar next to a number inside a document that also has maths, escape it: \$.
What usually goes wrong
- Not part of CommonMark and not part of GitHub-flavoured markdown either. It is a convention that several renderers adopted separately, so support is per platform rather than per specification.
- A block needs the
$$on their own lines. Inline$$on the same line as text is treated as inline maths by some renderers and as nothing by others. - Chat platforms have none of it. Discord and Slack show the dollars and the LaTeX exactly as typed.
- Underscores and asterisks inside a formula are LaTeX, not emphasis, and a renderer without maths will read them as markdown and mangle the formula.
Where it behaves differently
It renders as written on GitLab, Obsidian and VS Code preview. Everywhere else in this table it does something else, and that is worth reading before you paste.
| Platform | Behaviour |
|---|---|
| GitHub | $...$ and $$...$$, and also $ ... $ and a ``` `math ``` fence. Rendered with MathJax. |
| Notion | Its documentation does not say, so neither do we. |
| Discord | Not supported. The syntax arrives as its own punctuation. |
| Slack | Not supported. The syntax arrives as its own punctuation. |
Questions
Why does my formula work on GitHub but not on my site?
Because the site is not running a maths renderer. GitHub, GitLab and Obsidian each ship one; a static site generator usually needs a plugin turned on, and a plain markdown-to-HTML step has none. The dollars come through as dollars.
KaTeX or MathJax?
KaTeX is faster and covers most of what people write. MathJax is slower and covers more of LaTeX. Platforms mostly ship KaTeX, which is why an exotic macro from a paper is the thing most likely to fail.
Does this viewer render it?
Yes, as MathML, and only for documents that contain maths: the typesetter is a separate download and most documents have no use for it. Nothing is uploaded to do it, as with everything else here.
Sources
Everything above was read from these, not from memory. If a page here disagrees with one of them, the vendor is right and this page is out of date.
For the .md file that arrives in Mail
Not released yetA markdown file on a phone is the worst case: no editor, no preview, and a share sheet full of apps that want to import it into a library. The iPhone and iPad app opens it where it landed, renders it, and lets you edit and save it back.
For iPhone and iPad. It is not in the App Store, so there is nothing to download from this page yet.Digital Sandbox, who are building it →