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 $ <latex math> $
block math via \[ <latex math> \] or $$ <math> $$
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 <smiles>OC(=O)c1cc(Cl)cs1</smiles> or

```smiles
OC(=O)c1cc(Cl)cs1
```

images (Markdown). Parse and render additional parameters such as width, height, alignment:

![foo](foo.png){ width=50% }
![foo](foo.png){ width="36px" }
![image](<src> "title"){width="20px",height="20px"}
![image](<src> "title"){width="20px",height="20px",right}
![image](<src> "title"){width="20px",height="20px", align="left"}

Image properties

theorems and proofs

\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}

Latex footnotes

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}

Latex underline

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!}

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:

$ npm install mathpix-markdown-it

yarn usage:

$ yarn add mathpix-markdown-it

How to use

React usage

mathpix-markdown-it components usage

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

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


class App extends Component {
  render() {
    return (
      <MathpixLoader>
          <MathpixMarkdown text="\\(ax^2 + bx + c = 0\\)"/>
          <MathpixMarkdown text="$x = \frac { - b \pm \sqrt { b ^ { 2 } - 4 a c } } { 2 a }$"/>
          ...
      </MathpixLoader>
    );
  }
}

MathpixMarkdownModel methods usage

Example of render() method usage

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 (
      <div className="App">
        <div className="content" dangerouslySetInnerHTML={{__html: html}}></div>
      </div>
    )
  }
}

export default App;

Example of markdownToHTML() method usage

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 (
      <div>
        <form onSubmit={this.handleSubmit}>
          <h1>Input Text with Latex:</h1>
          <textarea value={this.state.value} onChange={this.handleChange} />
          <input type="submit" value="Convert" />
        </form>
        <div id='preview-content' dangerouslySetInnerHTML={{__html: this.state.result}}/>
      </div>
    );
  }
}

Latex to mathml/asciimath/tsv conversion

Example of Latex to mathml/asciimath/tsv conversion

Rendering methods have the ability to convert Latex representation to such formats as: mathml, asciimath, tsv

const options = {
      outMath: { //You can set which formats should be included into html result
        include_mathml: true,
        include_asciimath: true,
        include_latex: true,
        include_svg: true, // sets in default
        include_tsv: true,
        include_table_html: true, // sets in default
      }
    };
const html = MathpixMarkdownModel.markdownToHTML(`$x^x$`, options);

markdownToHTML() returns an HTML string that will contain the formats specified in the options.

For Latex formulas, the result will be:

<span class="math-inline">
    <mathml style="display: none">...</mathml>
    <asciimath style="display: none">...</asciimath>
    <latex style="display: none">...</latex>
    <mjx-comtainer class="MathJax" jax="SVG">..</mjx-comtainer>
</span>

For tabular, the result will be:

<div class="table_ tabular">
    <table id="tabular">...</table>
    <tsv style="display: none">...</tsv>
</div>

Then calling the parseMarkdownByHTML(html) method will return all formats as a list from the incoming html string.

For Latex formulas:

[
    {
      "type": "mathml",
      "value": "<math>...</math>"
    },
    {
       "type": "asciimath",
       "value": "x^(x)"
     },
    {
       "type": "latex",
       "value": "x^x"
     },
    {
       "type": "svg",
       "value": "<sgv>...</svg>"
     }
]

For tabular:

[
    {
      "type": "html",
      "value": "<table>...</table>"
    },
    {
       "type": "tsv",
       "value": "<tsv>...</tsv>"
     }
]

Example of outMath option usage

For Latex formulas:

const options = {
      outMath: {
        include_mathml: false,
        include_asciimath: true,
        include_latex: false,
      }
    };
const latex = `$x^x$`;
const html = MathpixMarkdownModel.markdownToHTML(latex, options);
const parsed = MathpixMarkdownModel.parseMarkdownByHTML(html, false);

html:

<div>
    <span class="math-inline">
        <asciimath style="display: none;">x^(x)</asciimath>
        <mjx-comtainer class="MathJax" jax="SVG"><svg>...</svg></mjx-comtainer>
    </span>
</div>

parsed:

[
    {
       "type": "asciimath",
       "value": "x^(x)"
     },
    {
       "type": "svg",
       "value": "<sgv>...</svg>"
     }
]

For tabular:

const options = {
      outMath: {
        include_table_html: false,
        include_tsv: true,
      }
    };
const latex = `\\begin{tabular}{ l c r }
  1 & 2 & 3 \\\\
  4 & 5 & 6 \\\\
  7 & 8 & 9 \\\\
\\end{tabular}`;
const html = MathpixMarkdownModel.markdownToHTML(latex, options);
const parsed = MathpixMarkdownModel.parseMarkdownByHTML(html, false);

<div class="table_tabular " style="text-align: center">
  <tsv style="display: none">1    2       3
4       5       6
7       8       9</tsv>
</div>

parsed:

[
  { 
    type: 'tsv', 
    value: '1\t2\t3\n4\t5\t6\n7\t8\t9' 
  }
]

Example of the include_sub_math option usage for tables containing nested tables and formulas

parseMarkdownByHTML(html: string, include_sub_math: boolean = true)

By default, the include_sub_math option is enabled, and as a result will contain formats for the nested table and math.

const options = {
    outMath: {
        include_asciimath: true,
        include_mathml: true,
        include_latex: true,
        include_svg: true,
        include_tsv: true,
        include_table_html: true
    }
  };
const latex = `\\begin{tabular}{ l c r }
                 1 & {$x^1$} & 3 \\\\
                 4 & {$y^1$} & 6 \\\\
                 7 & {$z^1$} & 9 \\\\
               \\end{tabular}`;
const html = MathpixMarkdownModel.markdownToHTML(latex, options);
const parsed = MathpixMarkdownModel.parseMarkdownByHTML(html);

parsed:

[
  { 
    type: 'html',
    value: '<table>..</table>'
  },
  { type: 'tsv', value: '1\tx^(1)\t3\n4\ty^(1)\t6\n7\tz^(1)\t9' },
  
  { type: 'mathml', value: '<math xmlns="http://www.w3.org/1998/Math/MathML">\n  <msup>\n    <mi>x</mi>\n    <mn>1</mn>\n  </msup>\n</math>' },
  { type: 'asciimath', value: 'x^(1)' },
  { type: 'latex', value: 'x^1' },
  { type: 'svg', value: '<svg >..</svg>' },
    
  { type: 'mathml', value: '<math xmlns="http://www.w3.org/1998/Math/MathML">\n  <msup>\n    <mi>y</mi>\n    <mn>1</mn>\n  </msup>\n</math>' },
  { type: 'asciimath', value: 'y^(1)' },
  { type: 'latex', value: 'y^1' },
  { type: 'svg', value: '<svg ></svg>' },
      
  { type: 'mathml', value: '<math xmlns="http://www.w3.org/1998/Math/MathML">\n  <msup>\n    <mi>z</mi>\n    <mn>1</mn>\n  </msup>\n</math>' },
  { type: 'asciimath', value: 'z^(1)' },
  { type: 'latex', value: 'z^1' },
  { type: 'svg', value: '<svg