Markdown math is one of those features that looks simple on the surface and becomes very renderer-dependent in practice.
If you only remember one thing, remember this:
math is not part of core CommonMark.
That means the exact behavior of $...$, $$...$$, and \[...\] depends on your preview engine, renderer, and export pipeline.
Inline Math vs Display Math
The two most common math styles are:
Inline math
Use inline math when the formula belongs inside a sentence:
Energy and mass are related by $E = mc^2$.
Inline math should read like part of the paragraph, not like a separate block.
Display math
Use display math when the formula needs emphasis or its own line:
$$
\nabla \cdot \vec{E} = \frac{\rho}{\varepsilon_0}
$$
Display math is better for:
- equations that need visual separation
- multi-step derivations
- formulas that are hard to read inline
$$...$$ vs \[...\]
This is where many Markdown answers become too vague.
In practice, both forms are often used to mark display math, but they are not identical in every pipeline.
In md2word's editor/export flow, \[...\] is normalized so the math pipeline can process it more consistently. That is useful, but it also means:
- the original source format is not the only thing that matters
- preview and export may use different internal representations
- portable writing still benefits from sticking to one convention
For most authoring workflows, $$...$$ is the safest display-math baseline to remember.
KaTeX vs MathJax
Many users hear “math renderer” and assume every browser engine behaves the same. It does not.
KaTeX
KaTeX is a fast browser math renderer. In md2word, site-rendered guide pages use KaTeX through remark-math and rehype-katex, while the editor preview uses its own KaTeX-based front-end path.
Useful practical properties:
- it renders quickly
- it supports inline and display math
- it can be strict about unsupported commands or malformed expressions
MathJax
MathJax is another browser math engine. It supports TeX/LaTeX input as well, but it is a different engine with different behavior and configuration.
Why the difference matters:
- a formula can work in one renderer and fail or look different in another
- the same delimiter choice may be treated differently
- preview fidelity does not automatically guarantee export fidelity
So the question is not “does Markdown support math?” The real question is:
which renderer is handling the math in this specific environment?
What md2word Actually Does
This is the part that matters most for this project.
Browser preview
The browser preview path is KaTeX-based, which means math is rendered on the front end before export.
Export path
Before Pandoc export, md2word normalizes display math brackets:
\[ ... \]
becomes $$...$$ internally before export, so the Pandoc side sees one consistent display-math form.
The Pandoc command also includes --mathml, which means the export chain is not just “raw Markdown passed through.” It is a math-aware conversion pipeline.
That makes md2word stronger than a plain Markdown parser, but it also means that math should be written with the pipeline in mind.
If a formula is central to the document argument, give it enough visual space and heading context to survive export review. A dense paragraph packed with inline math is much harder to debug than a document with clear headings and one obvious display-math block.
Practical md2word Advice
1. Prefer one math style consistently
If you can, use $$...$$ for display math and $...$ for inline math consistently across a document.
2. Keep formulas isolated when they are important
Put complicated equations on their own lines instead of burying them inside long paragraphs.
3. Do not trust preview alone
If the formula matters in the final DOCX or PDF, perform one real export and inspect the output.
4. Watch unsupported commands
KaTeX and Pandoc do not accept every LaTeX command equally. A command that works in one math environment may fail in another.
5. Normalize display math when migrating old content
If you are bringing in older Markdown from other systems, check whether it uses \[...\], $$...$$, or a renderer-specific extension before you assume it will behave the same way here.
Common Mistakes
1. Writing math like it is universal Markdown
It is not.
2. Mixing inline math and display math without intention
That makes the document harder to scan.
3. Assuming KaTeX and MathJax are interchangeable
They are not.
4. Assuming \[ and $$ are always identical
They are often close, but not guaranteed to be identical in every renderer or export path.
5. Trusting preview output for a publication-critical formula
Always test the final export.
FAQ
Is math part of standard Markdown?
No. Math support depends on the renderer or extension chain, not on core CommonMark.
Should I use $...$ or $$...$$?
Use $...$ for inline math and $$...$$ for display math.
Is \[...\] safe?
It can work in some systems, and md2word normalizes it for export, but $$...$$ is the clearer baseline to prefer in new content.
Why does my math look right in preview but wrong in export?
Preview and export may use different engines or conversion steps. In this project, preview is KaTeX-based while export goes through a Pandoc math pipeline.
What is the safest math workflow for Word/PDF export?
Use clear inline/display delimiters, keep equations isolated when possible, and inspect one real exported file before relying on the result.
Further Reading
Changelog
- 2026-03-18: Initial high-value release with verified guidance on math delimiters, KaTeX vs MathJax,
\[...\]normalization, and export-aware writing formd2word. - 2026-03-19: Clarified the different preview paths used by site pages and editor preview, and added stronger guidance on giving important formulas enough structure.
Next steps: Explore Markdown Export Tips, Markdown Cheat Sheet, Markdown Heading Guide, Markdown Mermaid Guide, and Markdown Code Block Guide.