← All guides

Rendering LaTeX math in Markdown PDF exports

If your Markdown exports to PDF with equations showing as raw text ($E = mc^2$ instead of a typeset formula), the cause is that math is not part of core Markdown: a formula only renders when the converter includes a math engine (KaTeX or MathJax) and your delimiters match what that engine expects. Fix it by using a converter with math support and writing $...$ for inline and $$...$$ for display math. A second, subtler failure: the math renders but a specific command comes out wrong or errors, which usually means you hit the boundary of what KaTeX supports (it covers a large subset of LaTeX math, roughly 300 functions, not the full set). PDFMoka's markdown to PDF converter renders math with KaTeX in your browser; here is how to get formulas to show up and what to do when a command is not supported.

Cause 1: no math engine (formula shows as plain text)

Markdown itself does not render math. If your $...$ expression appears verbatim in the PDF, the converter simply has no math engine wired in. Different tools handle this differently, GitHub and Jupyter use MathJax, VS Code and Obsidian use KaTeX, and a plain Markdown-to-PDF path may include neither.

Fix: use a converter that includes a math engine, and use the standard delimiters:

Inline: energy is $E = mc^2$.

Display:
$$
\nabla \cdot \vec{E} = \frac{\rho}{\varepsilon_0}
$$

PDFMoka's markdown to PDF includes KaTeX, so these render to the PDF without any configuration.

Cause 2: the dollar-sign conflict (currency breaks your math)

The most common silent breakage: $ is both the math delimiter and the currency symbol. A line like "the plan costs 50andtheupgradecosts50 and the upgrade costs 100" can be misparsed, with everything between the two dollar signs swallowed as a broken formula.

Fixes:

  • Most parsers (following pandoc's convention) require a non-space character immediately after the opening $ and before the closing $, so $50 and ... $100 with spaces is usually left alone, while $x^2$ parses. Writing currency as \$50 (escaped) removes all ambiguity.
  • For documents heavy in both math and money, prefer $$...$$ for display math so inline $ is rarer.

verify against your build: confirm how your specific converter handles the $50 currency case before publishing, delimiter heuristics vary slightly between parsers (remark-math, markdown-it-katex, pandoc). State the actual observed behavior.

Cause 3: the command isn't supported (KaTeX subset boundary)

If math mostly renders but one expression fails or looks wrong, you have likely used a command outside KaTeX's supported set. KaTeX deliberately implements a subset of LaTeX math for speed, roughly 300 functions versus MathJax's 800-plus, so some things behave differently:

  • align is not supported; use the aligned environment instead (KaTeX follows real LaTeX here, where align is not valid in math mode).
  • \class, \cssId, \style become \htmlClass, \htmlId, \htmlStyle in KaTeX.
  • Obscure packages (tikz for diagrams, mhchem for chemistry, commutative-diagram packages) are generally MathJax-with-extensions territory, not KaTeX.
  • Smart-quotes preprocessing can turn ' into ’, breaking primes like f'; disable smart quotes for math-heavy documents.

For the vast majority of non-specialist math (fractions, integrals, sums, matrices, Greek letters, standard operators), KaTeX renders it perfectly and faster than MathJax. The boundary only bites for advanced or package-dependent LaTeX.

verify against your build: the exact list of unsupported commands depends on the KaTeX version your converter ships. Before publishing a definitive "not supported" list, check it against the KaTeX "Support Table" and "Common Issues" docs for the version you actually integrate, and test the specific commands you plan to call out. Do not assert support for a command you have not verified in your own build.

If you need full LaTeX (not just a subset)

When your document genuinely needs full LaTeX, advanced packages, tikz diagrams, chemical equations, then a KaTeX-based (or any HTML-based) converter is the wrong tool, and you should render through an actual LaTeX pipeline (pandoc with a LaTeX engine, or a real .tex workflow). This is an honest limitation: browser math engines trade complete LaTeX coverage for speed and zero-install rendering. For most Markdown documents that is the right trade; for a package-heavy academic paper it is not. See Markdown to PDF: Pandoc vs online for when the LaTeX pipeline is worth it.

Quick checklist

  1. Is a math engine present? If the formula is plain text, the converter has no KaTeX/MathJax.
  2. Are delimiters right? $...$ inline, $$...$$ display, no space just inside the $.
  3. Any currency $ nearby? Escape it as \$ to avoid misparsing.
  4. Did a specific command fail? Check it against the KaTeX subset (use aligned not align, \htmlClass not \class).
  5. Need full LaTeX packages? Use a real LaTeX pipeline, not a browser math engine.

For the related "needs JavaScript to render" problem with diagrams, see why mermaid diagrams don't render in PDF.

References