mathpix-markdown-it: rendering a LaTeX-flavoured Markdown for STEM

A Markdown superset aimed at technical writing

Mathpix Markdown is described as a superset of Markdown that adds syntax for the STEM community, and the design rule is stated up front: wherever possible the syntax is borrowed from LaTeX, and where LaTeX has no equivalent, as with chemistry, new syntax is invented that stays backward compatible with Markdown. The listed benefits over plain Markdown are specific. Equations are better supported through LaTeX syntax powered by MathJax, including the equation numbering and referencing conventions from LaTeX. Tables use the LaTeX tabular syntax, which allows the complex, nested tables seen in scientific publications. Figure referencing works through LaTeX syntax. There is support for abstracts, author lists and linkable sections, described as a fact of life for academic publications, and for chemistry diagrams written in SMILES markup, compatible with tools such as ChemDraw. The argument is not that Markdown is bad, but that the pieces technical writing actually needs were not in it.

The syntax the parser actually handles

The list of supported constructs is long enough to be worth reading as a feature matrix. Inline math uses the `\(...\)` form, and block math uses `\[...\]` or the `$$ ... $$` form. Tables use the tabular environment, and figures with captions use the figure environment. Lists can be written as itemize and enumerate environments rather than Markdown syntax. Numbered and unnumbered equation environments are supported for equation, align, split and gather, with the starred form for the unnumbered variant. Cross references use label, ref, eqref and tag, which is the mechanism behind the equation and figure referencing. Text formatting options include title, author, abstract, section, subsection and subsubsection, plus textit, textbf and url. The list also covers theorems and proofs, LaTeX footnotes, LaTeX underline variants, and the lstlisting environment for code. The chemistry extension is the odd one out, since it has no LaTeX equivalent, and it is written as a SMILES string in a tag:

Chemical structures as inline markup

The chemistry support is the most distinctive feature of the format, and the README shows it in two forms. In prose, a structure is written as a SMILES string inside a smiles tag, for example `<smiles>OC(=O)c1cc(Cl)cs1</smiles>`. In a fenced block, the language is smiles and the body is the SMILES string itself:

OC(=O)c1cc(Cl)cs1

The point of using SMILES is interoperability. ChemDraw and other chemistry tools speak SMILES, so a structure written in the Mathpix Markdown format is a structure in a form that tooling already understands, rather than an image or a bespoke encoding. The repository carries an `assets/` directory with a screenshot of the format being edited in VS Code, and the tag approach keeps the extension inert in a plain Markdown parser, since a plain parser will simply treat the tag as text and the surrounding document still reads correctly.

Two dependencies do the work

mathpix-markdown-it is an open source implementation of the mathpix-markdown spec written in TypeScript, and it deliberately stands on two open source libraries. MathJax v3 renders the math as SVGs, and markdown-it handles standard Markdown parsing. That is the whole architecture, and it has a practical consequence for anyone evaluating it: the quality of the equation rendering is MathJax's quality, and the breadth of the Markdown handling is markdown-it's, so this project is the layer that adds the LaTeX-flavoured extensions. The package itself pulls in a larger set of dependencies than that, visible in package.json: markdown-it-deflist, markdown-it-emoji, markdown-it-footnote, markdown-it-ins, markdown-it-mark, markdown-it-multimd-table and markdown-it-sub alongside markdown-it itself, plus js-yaml, htmlparser2, highlight.js, chai for tests, deepmerge, copy-to-clipboard and the `@mathpix/domino` DOM implementation. The keyword list mentions MathJax, markdown-it, svg, mathml, tex, latex, asciimath, conversion, react and tabular, which is a fair summary of the surface.

Installing and using it

The package is on npm, and the README gives both package managers:

$ npm install mathpix-markdown-it

$ yarn add mathpix-markdown-it

The main entry point is `lib/index.js`, and the repository keeps the TypeScript sources in `src/`, the compiled output in `lib/` and an `es5/` directory, with a `tsconfig.json` and webpack configuration for a bundled build. The scripts in package.json are `compile` running tsc, `build` running tsc and a production webpack build, a `dev` script for watch mode, and a test script running mocha over the tests directory. There is React support, with the README pointing at React components that make rendering easy in React applications and a full example under `examples/react-app/`. The example directories give a good sense of the intended surfaces, covering a React app, a Next.js example, plain HTML output, a node example set, a format comparison directory, and `examples/app.js` with `examples/appPositions.js`.

One format, several editors, and where it breaks down

A format is only as good as the tools around it, and the README describes Mathpix Markdown as an open format with multiple implementations. You can use this repository and the npm library to render STEM content on your own site. You can use the VS Code plugin to edit mmd files. You can use the Snip Notes web editor to edit, export and publish them, with exports to PDF and DOCX. And there is an experimental static site generator, Spectra, to edit local mmd files and see changes in real time. That spread of tooling is the strongest argument for adopting the format. The limits are the flip side. The format is heavily LaTeX-shaped, so a document that does not come from a LaTeX heritage will feel verbose, and the chemistry extension is not standard in the wider Markdown ecosystem, so a document using it is tied to implementations that understand it. There is also a question of what happens to a document in a tool that knows nothing about Mathpix Markdown: it will render the LaTeX as literal text, which is exactly the failure mode the format is trying to avoid elsewhere.

Version 3 and what the project still owes its users

The version story is short but consequential. Version 3.0.0 was released on 2026-06-25, following 2.0.12 in March 2025 and 2.0.0 in August 2024, and the package metadata in the repository declares version 3.0.1, so the working tree is again ahead of the last tag. The 3.0 major bump signals a breaking change, and with a library that a site depends on for rendering, a major version is where you check your integration rather than assume it. The last push was on 2026-10-13, so the work continues. Two things are worth watching. The first is the size of the runtime, since MathJax v3 is a large dependency to ship to a browser, and the README's own emphasis on SVG rendering means you pay for the renderer in the page. The second is the direction of the project. Mathpix is a company whose commercial products sit on top of this format, and the open repository is the part that other people can rely on, so the maintenance level and the priorities are the company's priorities, not the community's.

Editorial conclusion

mathpix-markdown-it suits a product that has to render scientific documents written in LaTeX-flavoured Markdown, especially if those documents already use tabular, figure environments, cross references and theorem blocks, because implementing that syntax on top of a general Markdown parser is the expensive part it absorbs. It is the wrong choice for a team that only needs inline math, since a standard Markdown plus MathJax setup is simpler, and it is the wrong choice if you need the reverse direction, since this is a renderer and not a converter. Before you adopt it, read the syntax reference linked from the README, check that the features your authors actually use are covered, and plan for the MathJax payload that comes with it. The last push was on 2026-10-13, version 3.0.0 was released on 2026-06-25, and the licence is MIT.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Mathpix/mathpix-markdown-it on GitHub
4. README
5. Releases