Math Equations in Markdown: LaTeX Syntax with KaTeX and MathJax

Quick answer

Markdown has no native syntax for math. What you're actually writing is LaTeX, wrapped in delimiters — usually $...$ for inline math and $$...$$ for a block equation — and a JavaScript engine like KaTeX or MathJax typesets it in the browser afterward. The Markdown file itself just stores plain-text LaTeX between two markers; nothing renders until a page loads that engine. Below: the exact delimiter syntax, how KaTeX and MathJax differ, and when setting this up is worth the trouble.

How it actually works

Why math isn't in Markdown's core spec

CommonMark — the spec most Markdown flavors build on — leaves math out on purpose. The characters you'd want for delimiters, \(, \), \[, \], already mean something: they're how you escape a literal parenthesis or bracket in Markdown. A bare $ runs into a messier problem — it's also how people write prices. The CommonMark community debated `$...$` heuristics at length and never adopted one into the core spec, partly because of real breakage: Electrical Engineering Stack Exchange dropped $ math delimiters specifically so a plain-text "400$" wouldn't get misread as an equation. It's the same underlying issue covered in why the same Markdown file renders differently across parsers — math support lives entirely in extensions, not the base language, so what renders depends on which tool is reading the file.

The delimiter syntax you'll actually type

GitHub's flavor of Markdown is the most common reference point, and its rules are representative of what you'll find elsewhere:

Inline: The area of a circle is $A = \pi r^2$.

Block:
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

GitHub also supports a fenced ` ```math ` code block as a third option for block equations — same result, no $$ needed. One thing worth knowing before you rely on $: if a literal dollar sign shows up in the same line as math but isn't part of the equation, it needs escaping (\$), or the renderer may try to parse it as another delimiter. Same instinct as escaping special characters in Markdown generally — anywhere a character does double duty as both literal text and syntax, you have to tell the parser which one you mean.

KaTeX vs. MathJax

Once the LaTeX is on the page, something has to turn it into typeset math. That's KaTeX or MathJax's job — and they make different trade-offs.

MathJax accepts more input formats (LaTeX, MathML, AsciiMath), covers a wider set of LaTeX commands, and can output MathML — which matters for accessibility, since that's the format screen readers consume directly. KaTeX trades some of that breadth for speed: it renders synchronously in a single pass instead of MathJax's multi-step typesetting, and ships a smaller bundle. The cost shows up in coverage — KaTeX doesn't support `\label` or `\eqref` for cross-referencing numbered equations, which matters if you're writing something long enough to reference "equation 3" later. Don't pick one on reputation alone, though: MathJax 3 has closed most of the old performance gap, so speed isn't the deciding factor it used to be. Feature coverage and accessibility are.

When to use it (and when to skip it)

Reach for LaTeX math when you're writing equations that actually need to be read as equations — technical notes, coursework, a paper, documentation with real formulas. A fraction, a summation, a matrix: these are just clearer typeset than typed out in prose.

Skip it for everyday notes. Most writing doesn't need it, the same way most Markdown documents never touch definition lists or the other extras most editors skip — they exist for the specific cases that call for them, not as a default. Math rendering is another GFM-only extension in that same category: useful when the content genuinely needs it, invisible overhead when it doesn't.

There's also real setup cost outside of GitHub's built-in support. Static site generators don't render math themselves — Hugo passes LaTeX through untouched via its Goldmark extension and expects you to wire up MathJax or KaTeX yourself in a template; Pandoc offers five different math-to-HTML strategies depending on whether you want live JS rendering, native MathML, or image fallback. None of it is automatic the way bold or italic text is. And if your notes mix real math with plain-text prices or other legitimate uses of $, Hugo's own docs recommend MathJax over KaTeX for exactly that reason — its delimiter handling is more forgiving of the ambiguity.

Frequently Asked Questions

Does plain Markdown support math equations?

No — CommonMark and base GFM have no native math syntax. Math rendering comes from an extension layer (GitHub's MathJax integration, a static-site plugin, or a note app's own renderer) that recognizes $ and $$ delimiters and hands the enclosed LaTeX to a JavaScript engine. The Markdown file itself just stores plain-text LaTeX between delimiters.

What's the difference between KaTeX and MathJax?

KaTeX renders faster in a single synchronous pass and ships a smaller bundle, but supports a narrower slice of LaTeX — no \label or \eqref for cross-references, for instance. MathJax accepts more input formats (LaTeX, MathML, AsciiMath), covers more LaTeX commands, and can output accessible MathML for screen readers. MathJax 3 has closed most of the historical speed gap, so the choice is mostly about feature coverage and accessibility, not raw performance.

How do I write inline vs. block math in Markdown?

The common convention across GitHub, Pandoc, Hugo, and MkDocs Material is: single dollar signs or \(...\) for inline math within a sentence, and double dollar signs or \[...\] on their own line for block or display equations. Some tools also support a fenced `math code block for block equations without dollar delimiters.

Why does $ sometimes break my Markdown formatting?

A bare $ is ambiguous — it could open a math expression or just be a currency symbol. Tools that use $ as a math delimiter require escaping it (\$) anywhere it appears outside real math, which is exactly why CommonMark never adopted $ into its core spec — it would silently break plain-text prices in existing documents.

How Carets fits in

Carets keeps every note as plain text, so LaTeX math markup round-trips cleanly — the $...$ and $$...$$ you write is just text, portable to whatever renderer you point it at later, without a proprietary format holding it hostage. Markdown, plain text, and code share one editor, so a note with an equation sits right next to your regular writing and your code snippets, organized into files, projects, and tags instead of scattered across separate apps for separate formats.

One honest caveat: Carets doesn't render LaTeX, KaTeX, or MathJax output inline today — it's a fast, native editor for the source, not a typesetting engine. If you need the equation itself to render while you write, you'll still hand the file to a tool that runs KaTeX or MathJax. What Carets gives you is a place to draft, organize, and carry that plain-text math safely between the tools that do.

Get Carets on iPhone, iPad, and Mac.