mathpix-markdown-it


What is Mathpix Markdown?

mathpix-markdown is a superset of Markdown that adds helpful syntax for the STEM community, such as advanced equation, table, and chemistry support. Wherever possible, we borrow syntax from LaTeX. In other cases (such as chemistry) we invent new syntax that is backward compatible with Markdown.

Here are the key benefits over plain Markdown:
- better equation support via LaTeX syntax (powered by MathJax), including equation numbering and referencing conventions from LaTeX
- better support for tables, via the LaTeX tabular syntax, which allows for complex, nested tables often seen in scientific publications
- advanced figure referencing via LaTeX syntax
- support for abstracts, author lists, and linkable sections; these are a fact of life for academic publications
- support for chemistry diagrams represented with SMILES markup, compatible with popular chemistry tools like ChemDraw

!Editing an MMD file in VS Code

Mathpix Markdown Syntax reference

Click here for the full syntax reference.

How to edit mmd files?

Mathpix Markdown is an open format with multiple implementations:

- you can use this Github repo and the mathpix-markdown-it npm library to render STEM content on your website
- you can use the VS Code plugin (see picture above) to edit mmd files
- use can use our web editor Snip Notes to edit, export, and publish mmd files (with exports to pdf and docx formats)
- you can use our experimental static site generator Spectra to edit local mmd files and see changes in real time

How is Mathpix Markdown different from regular Markdown?

Mathpix Markdown addresses these limitations by adding support for the following standard Latex syntax elements which are already familiar to the scientific community:

- inline math via \( \)
- block math via \[ \] or $$ $\$\$$
- tables via \begin{tabular} ... \end{tabular}
- figures and figure captions via \begin{figure} \caption{...} ... \end{figure}
- lists: unordered lists via \begin{itemize} ... \end{itemize} and ordered lists via \begin{enumerate} ... \end{enumerate}
- numbered and unnumbered equation enviornments \begin{elem} ... \end{elem} and \begin{elem} ... \end{elem} where elem=equation|align|split|gather
- equation, table, and figure references via \label, \ref, \eqref, \tag
- text formatting options \title{...}, \author{...}, \begin{abstract}...\end{abstract}, \section{Section Title}, \subsection{Section Title}, \subsubsection{Section Title}, \textit{italicized text}, \textbf{bold text}, \url{link}
- chemistry equation via OC(=O)c1cc(Cl)cs1 or
~~~
``smiles
OC(=O)c1cc(Cl)cs1
`
~~~
- images (Markdown). Parse and render additional parameters such as width, height, alignment:
~~~
!foo{ width=50% }
!foo{ width="36px" }
!image{width="20px",height="20px"}
!image{width="20px",height="20px",right}
!image{width="20px",height="20px", align="left"}
~~~
!Image properties

- theorems and proofs

`tex
\newtheorem{theorem}{Theorem}
\newtheorem{lemma}[theorem]{Lemma}

\begin{theorem}
Let \(f\) be a function whose derivative exists in every point, then \(f\)
is a continuous function.
\end{theorem}

\begin{lemma}
Given two line segments whose lengths are \(a\) and \(b\) respectively there
is a real number \(r\) such that \(b=ra\).
\end{lemma}

\begin{proof}
To prove it by contradiction try and assume that the statement is false,
proceed from there and at some point you will arrive to a contradiction.
\end{proof}
`

![](doc/images/theorems_and_proofs.png)

- Latex footnotes

`tex
Footnote marker without text. Auto increment counter to 1 \footnotemark{} should be 1.

Footnote marker with text. Auto increment counter to 2 \footnotemark{} be 2. \footnotetext{text should be 2}

Auto increment counter to 3 \footnote{text should be 3}

Auto increment counter to 4 \footnote{text should be 4}

Footnote marker without text. Auto increment counter to 5 \footnotemark{} should be 5.

Footnote marker with text. Auto increment counter to 6 \footnotemark{} should be 6. \footnotetext{text should be 6}

Auto increment counter to 7 \footnote{text should be 7}

Auto increment counter to 8 \footnote{text should be 8}
`

![](doc/images/latex-footnotes/latex-footnotes_01.png)

- Latex underline

`tex
Underline text: \underline{Underlined text!}
Underline text: \uline{Underlined text!}

Double underline text: \underline{\underline{Double underlined text!}}
Double underline text: \uuline{Double underlined text!}

Wavy underlined text: \uwave{This text is underlined with a wavy line!}

Dashed underline text: \dashuline{Dashed Underline}
Dotted underline text: \dotuline{Dotted Underline}

Strikethrough text: \sout{Text with a horizontal line through its center!}
Struck with Hatching text: \xout{Text with hatching pattern!}
`

![](doc/images/latex-underline/latex-underline_07.png)

- Latex lstlisting env

`tex
\begin{lstlisting}[language=C, mathescape]
/ the following code computes $\displaystyle\sum_{i=1}^{n}i$ /

for (i = 1; i <= limit; i++) {
sum += i;
}
\end{lstlisting}
`

![](doc/images/latex-lstlisting-env/latex-lstlisting-env-01.png)

What is mathpix-markdown-it?

mathpix-markdown-it is an open source implementation of the mathpix-markdown spec written in Typescript.

It relies on the following open source libraries:

- MathJax v3 (to render math with SVGs)
- markdown-it (for standard Markdown parsing)

Quickstart

Installation

npm usage:

`bash
$ npm install mathpix-markdown-it
`

yarn usage:

`bash
$ yarn add mathpix-markdown-it
`

How to use

React usage

$3

We provide React components which make rendering of mathpix-markdown-it easy for React applications:
Full example

`js
import {MathpixMarkdown, MathpixLoader} from 'mathpix-markdown-it';


class App extends Component {
render() {
return (



...

);
}
}
`

$3

#### Example of render() method usage

`js
import * as React from 'react';
import { MathpixMarkdownModel as MM } from 'mathpix-markdown-it';

class App extends React.Component {
componentDidMount() {
const elStyle = document.getElementById('Mathpix-styles');
if (!elStyle) {
const style = document.createElement("style");
style.setAttribute("id", "Mathpix-styles");
style.innerHTML = MM.getMathpixFontsStyle() + MM.getMathpixStyle(true);
document.head.appendChild(style);
}
}
render() {
const html = MM.render('$x = \\frac { - b \\pm \\sqrt { b ^ { 2 } - 4 a c } } { 2 a }$');
return (


`

#### Example of markdownToHTML() method usage

`js
class ConvertForm extends React.Component {
constructor(props) {
super(props);
this.state = {
value: '\\[\n' +
'y = \\frac { \\sum _ { i } w _ { i } y _ { i } } { \\sum _ { i } w _ { i } } , i = 1,2 \\ldots k\n' +
'\\]',
result: ''
};

this.handleChange = this.handleChange.bind(this);
this.handleSubmit = this.handleSubmit.bind(this);
}

handleChange(event) {
this.setState({value: event.target.value});
}

handleSubmit(event) {
event.preventDefault();
this.setState({result: MM.markdownToHTML(this.state.value)})
}

render() {
return (