Writing Math Equations in Markdown

Writing mathematical equations in plain text has always been frustrating. You either settle for awkward approximations like x^2 + y^2 = r^2 or embed screenshots of formulas. Markdown solves this by supporting LaTeX math notation through rendering engines like KaTeX and MathJax, letting you write beautiful equations that display cleanly in browsers, documentation sites, and note-taking apps.

Inline and Display Math Syntax

LaTeX math in Markdown uses two delimiter styles. Inline math wraps expressions in single dollar signs and renders within a paragraph, while display math uses double dollar signs and renders on its own centered line.

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$, which
solves any quadratic equation $ax^2 + bx + c = 0$.

$$
\int_{0}^{\infty} e^{-x^2} \, dx = \frac{\sqrt{\pi}}{2}
$$

Some parsers also support \( and \) for inline math, and \[ and \] for display math. If you are writing for GitHub, stick with dollar signs — GitHub Flavored Markdown only recognizes $...$ and $$...$$ delimiters since its native math support launched in 2022.

A common pitfall is escaping. Markdown processors sometimes interpret underscores inside math as emphasis italics. To avoid this, wrap your math blocks in backticks or use a renderer that processes math before other Markdown transformations.

Common LaTeX Math Commands

The subset of LaTeX used in Markdown math is extensive but you will reach for the same commands repeatedly. Here is a practical reference for the most useful ones:

Matrices deserve special attention because their syntax is verbose:

$$
A = \begin{pmatrix}
a_{11} & a_{12} \\
a_{21} & a_{22}
\end{pmatrix}
$$

For aligned equations spanning multiple lines, use the aligned environment inside display math:

$$
\begin{aligned}
f(x) &= (x+1)^2 \\
     &= x^2 + 2x + 1
\end{aligned}
$$

KaTeX vs MathJax Rendering

KaTeX and MathJax are the two dominant rendering engines, and they differ in meaningful ways.

KaTeX, developed by Khan Academy, prioritizes speed. It renders math server-side or client-side with no reflow, making it ideal for pages with many equations. However, KaTeX supports a smaller subset of LaTeX commands. Advanced features like \cancel, \phase, and some tikz-cd diagrams are unsupported.

MathJax, the older and more complete engine, supports nearly the full LaTeX math vocabulary including \require, \newcommand, and automatic equation numbering. The tradeoff is rendering speed — MathJax processes equations asynchronously, which can cause visible reflow on long documents.

For static documentation sites built with Hugo, Docusaurus, or Nuxt Content, KaTeX is usually the better choice. The faster renders and smaller bundle improve page load metrics, and the missing LaTeX features rarely matter for technical documentation. For academic papers or interactive textbooks where equation numbering and macros are essential, MathJax remains the right tool.

Setting Up Math in Popular Platforms

Most modern platforms support math out of the box or with minimal configuration:

• GitHub: Native $...$ and $$...$$ support in READMEs, issues, and discussions since 2022. Rendered with MathJax.
• VS Code: Install the Markdown Math extension for live preview of LaTeX math in .md files.
• Obsidian: Built-in math rendering using MathJax. No plugins needed.
• Hugo: Add the katex or mathjax shortcode to your templates.
• Docusaurus: Enable the remark-math and rehype-katex plugins in your configuration.

When testing your math locally, use a Markdown preview tool that matches your production renderer. Syntax that works in Obsidian might render differently on GitHub if KaTeX and MathJax handle an edge case differently.

One reliable workflow is to compose and preview your Markdown with math in a dedicated editor like our Markdown preview tool, which renders equations in real time so you can catch delimiter errors before publishing. Try it at /tools/markdown-preview to verify your LaTeX expressions render correctly across different contexts.