--- title: "Writing maths in Markdown" author: Pedro Thomaz source: https://coffeetext.app/blog/math-equations-in-markdown --- # Writing maths in Markdown > Checked November 2026 against [GitHub's docs on mathematical expressions](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions), [VS Code's Markdown docs](https://code.visualstudio.com/docs/languages/markdown) and the [pandoc manual](https://pandoc.org/MANUAL.html). Coffee isn't affiliated with any of them. Markdown has no maths of its own. The common convention, borrowed from LaTeX, is to put TeX between dollar signs: `$…$` for maths inside a sentence and `$$…$$` for a formula on its own line. Whether it's drawn as a formula depends entirely on the app or site that shows the file. Everywhere else it stays as readable text, which is the point. ## Inline and block maths Inline maths sits in a sentence: ``` The area of a circle is $\pi r^2$. ``` Block maths gets its own lines, with `$$` above and below: ``` $$ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$ ``` Some tools also accept the block on one line, as `$$ x^2 + y^2 = z^2 $$`. Keep the dollar signs tight against the maths for inline use. Pandoc, for one, treats `$x$` as maths but not `$ x $`, so that a price followed by a space isn't mistaken for a formula. ## The TeX you'll actually use You don't need to learn LaTeX to write most formulas. This short list covers a lot of everyday maths: | To get | Write | |---|---| | Superscript, subscript | `x^2`, `a_n`, `x^{10}`, `a_{ij}` | | Fraction | `\frac{a}{b}` | | Square root, nth root | `\sqrt{x}`, `\sqrt[3]{x}` | | Greek letters | `\alpha`, `\beta`, `\pi`, `\Sigma` | | Operators | `\times`, `\div`, `\pm`, `\leq`, `\geq`, `\neq`, `\approx` | | Sum and integral with limits | `\sum_{i=1}^{n} i`, `\int_0^1 x\,dx` | | Limit | `\lim_{x \to 0} \frac{\sin x}{x}` | | Brackets that grow | `\left( \frac{a}{b} \right)` | | Words inside maths | `\text{if } x > 0` | | Number sets | `\mathbb{R}`, `\mathbb{N}` | | Binomial | `\binom{n}{k}` | Braces group things. `x^10` puts only the 1 up high, while `x^{10}` raises both digits. Spaces inside TeX are mostly ignored, so `\,` adds a thin space where you want one. ### Matrices and cases A matrix uses `&` between columns and `\\` between rows: ``` $$ \begin{pmatrix} 1 & 0 \\ 0 & 1 \end{pmatrix} $$ ``` `pmatrix` gives round brackets, `bmatrix` square ones, `vmatrix` vertical bars, and plain `matrix` none. For a function defined in pieces, use `cases`: ``` $$ |x| = \begin{cases} x & \text{if } x \geq 0 \\ -x & \text{if } x < 0 \end{cases} $$ ``` ## Where it renders - **GitHub** renders [both forms](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions) in Markdown files, issues, pull requests, discussions and wikis, using MathJax. It also accepts inline maths wrapped in a dollar sign and a backtick on each side, for maths that clashes with Markdown, and a fenced code block marked `math` for blocks. - **VS Code's** built-in preview [renders maths with KaTeX](https://code.visualstudio.com/docs/languages/markdown). - **Pandoc** reads `$` and `$$` maths through its `tex_math_dollars` extension, described in [its manual](https://pandoc.org/MANUAL.html), and can turn it into proper maths in HTML, Word, EPUB or PDF. - **Many Markdown editors** draw it, often with an option to turn it on. Check yours. Where none of that happens, such as a plain text editor or a site without maths support, the reader sees the TeX. That's readable enough for simple formulas and the reason to keep them tidy. ## The dollar-sign trap The catch with `$` is money. A line like "tickets cost $5 or $10" contains two dollar signs, and a careless renderer will treat `5 or ` as a formula. Most tools apply rules to avoid it. Pandoc's, for example, need a character other than a space just inside each `$`, and no digit straight after the closing one. Other tools' rules differ. GitHub's advice is to write `\$` for a literal dollar sign inside a formula, and to wrap one in `$` when it shares a line with maths. If a note mixes prices and maths, check how it looks wherever it's going to be read. ## In Coffee Coffee draws `$$` blocks as formulas, under the block, while you write. A block is a `$$` line, the TeX lines, then a closing `$$` line, or `$$ … $$` on one line. It draws them itself, without a web view, and the formula appears in PDF, print, HTML, Word and EPUB exports too. It covers what's in the table above: Greek letters, operators, scripts, `\frac`, `\sqrt` and `\sqrt[n]`, sums and integrals with limits, `\lim`, `\left` and `\right`, accents, `\text`, `\mathbb`, `\binom`, and the `matrix`, `pmatrix`, `bmatrix`, `vmatrix` and `cases` environments. TeX it doesn't know is left showing as source rather than drawn wrongly. Some limits to know: - **Inline `$…$` isn't drawn.** It's shown in italic, so it stands out from the sentence, but it stays as TeX. Put anything that matters in a block. - **Prices stay prices.** `$5 or $10` is left as money. - **It's everyday TeX, not all of LaTeX.** There's no LaTeX export, and Coffee doesn't use pandoc. For a thesis full of maths, a LaTeX workflow may suit you better. The file keeps exactly what you typed, so the same note renders on GitHub or through pandoc later. Exports carry the drawn formula, so a [PDF](https://coffeetext.app/blog/markdown-to-pdf-mac) or an [EPUB](https://coffeetext.app/blog/markdown-to-epub-mac) shows the maths properly. Coffee's [calculations](https://coffeetext.app/blog/timesheet-hours-plain-text) are a different thing, worked out beside ordinary lines rather than typeset. ## Questions ### How do I write an equation in Markdown? Put TeX between dollar signs: `$x^2$` inside a sentence, or `$$` on the lines above and below a formula of its own. Whether it's drawn depends on the app or site showing the file. ### Does GitHub support maths in Markdown? Yes. GitHub renders `$…$` inline maths and `$$…$$` blocks with MathJax, in Markdown files, issues, pull requests, discussions and wikis. ### How do I write a dollar sign without starting maths? On GitHub, write `\$` inside a formula, or wrap the dollar sign in a span when it shares a line with maths. Other tools have their own rules, so check how a price looks before publishing. ### Does Coffee render inline maths? No. Inline `$…$` is shown in italic but stays as TeX. Coffee draws `$$` blocks as formulas, in the editor and in exports. --- Written by Pedro Thomaz, who makes Coffee, a Markdown editor for the Mac on macOS 15 or later. It's free for 14 days with no card or account, then €3 a month, €29 a year, or €79 once with two years of updates. More at https://coffeetext.app/llms-full.txt