markdown-it-math

!Coverage

Note This library defaults to rendering your equation with an
AsciiMath dialect. If you want to use LaTeX, follow the instructions
below.

Note [mathup][mathup] or [temml][temml] are optional peer
dependencies, you must explicitly install either of them if you plan
to use the default renderer (see [installation][#Installation] below).

``md
Pythagorean theorem is $a^2 + b^2 = c^2$.

Bayes theorem:

$$
P(A | B) = (P(B | A)P(A)) / P(B) .
$$
`

!Preview of the results from above

Installation

`bash
npm install markdown-it-math --save

Optional (use the default AsciiMath renderer)

npm install mathup --save

Optional (use a LaTeX renderer instead)

npm install temml --save
`

$3

Use an [importmap][importmap]. Change /path/to/modules to the
location of your modules.

`html


`

Note Adding [mathup][mathup] or [temml][temml] to your import map
is optional. Only add mathup if you want to use it as the default
AsciiMath renderer. Add Temml if you want to use it as the LaTeX
renderer.

Usage

$3

`js
import markdownIt from "markdown-it";
import markdownItMath from "markdown-it-math";

// Optional (with defaults)
const options = {
inlineDelimiters: ["$", ["$", "$"]],
inlineAllowWhiteSpacePadding: false,
blockDelimiters: "$$",
mathupOptions,
inlineCustomElement, // see below
inlineRenderer, // see below
blockCustomElement, // see below
blockRenderer, // see below
};

const md = markdownIt().use(markdownItMath, options);
`

`js
md.render(
A text $1+1=2$ with math.

$$
bf A._(3 xx 3) =
[a_(1 1), a_(1 2), a_(1 3)
a_(2 1), a_(2 2), a_(2 3)
a_(3 1), a_(3 2), a_(3 3)]
$$
);
`

You may also want to include the stylesheet from mathup. See
[mathup][mathup] for reference and usage instructions about the
default renderer.

$3

`bash


install temml as a peer dependency


npm install --save temml
`

`js
import markdownIt from "markdown-it";
import markdownItMathTemml from "markdown-it-math/temml";

// Optional, if you want macros to persit across equations.
const macros = {};

const md = markdownIt().use(markdownItMathTemml, {
temmlOptions: { macros },
});
`

Note that the markdown-it-math/temml export supports the same
options as above, except mathupOptions, you can use temmlOptions
instead.

`js
md.render(String.raw
A text $1+1=2$ with math.

$$
\underset{3 \times 3}{\mathbf{A}} =
\begin{bmatrix}
a_{1 1} & a_{1 2} & c_{1 3} \\
a_{2 1} & a_{2 2} & c_{2 3} \\
a_{3 1} & a_{3 2} & c_{3 3}
\end{bmatrix}
$$
);
`

You may also want to include the stylesheets and fonts from Temml. See
[Temml][temml] for reference and usage instructions about the
default renderer.

$3

markdown-it-math/no-default-renderer is the minimal export. Use
this if you want to provide your own renderer.

Note: The other two exports use top-level await to dynamically
import the respective peer dependency. If your environment does not
support that, this export is recommended, in which case you should
manually supply the renderers.

`js
import markdownIt from "markdown-it";
import markdownItMath from "markdown-it-math/no-default-renderer";

const md = markdownIt().use(markdownItMath, {
inlineRenderer: customInlineMathRenderer,
blockRenderer: customBlockMathRenderer,
});
`

$3

- inlineDelimiters: A string, or an array of strings (or pairs of
strings) specifying delimiters for inline math expressions. If a
string, the same delimiter is used for open and close. If a pair of
strings, the first string opens and the second one closes. Empty
strings or pairs containing empty strings are ignored. If no valid
strings or pairs are provided, it will turn off the rule.
Default ["$", ["$", "$"]].
- inlineAllowWhiteSpacePadding: Whether to allow whitespace
immediately after the opening delimiter and immediately before the
closing delimiter. You may want this if you use e.g. $...$ or
\(...\) as delimiters where the risk of non-intended math
expression is low.
- blockDelimiters: Same as above, but for block expressions. Default "$$".
- mathupOptions: The options passed to the default mathup renderer. Ignored
if you use a custom renderer. Default {}.
- temmlOptions: The options passed to the temml renderer. Only available if
you import from markdown-it-math/temml Ignored if you use a custom renderer.
Default {}.
- inlineCustomElement:
Specify "tag-name" or ["tag-name", { some: "attrs" }] if you want to
render inline expressions to a custom element. Ignored if you provide a
custom renderer.
- inlineRenderer:
Provide a custom inline math renderer. Accepts the source content, the
parsed markdown-it token, and the markdown-it instance. Default:

`js
import mathup from "mathup";

function defaultInlineRenderer(src, token, md) {
return mathup(src, mathupOptions).toString();
}
`

- blockCustomElement:
Specify "tag-name" or ["tag-name", { some: "attrs" }] if you want to
render block expressions to a custom element. Ignored if you provide a
custom renderer.
- blockRenderer:
Provide a custom block math renderer. Accepts the source content, the
parsed markdown-it token, and the markdown-it instance. Default:

`js
import mathup from "mathup";

function defaultBlockRenderer(src, token, md) {
return mathup(src, {
...mathupOptions,
display: "block",
}).toString();
}
`

Alternatives

- [@mdit/plugin-katex][@mdit/plugin-katex] -
Renders expressions to KaTeX rather than MathML
- [markdown-it-mathspan][markdown-it-mathspan] and
[markdown-it-mathblock][markdown-it-mathblock] -
Uses commonmark inspired delimiters with customiable renderer.

Examples

$3

`js
import markdownIt from "markdown-it";
import markdownItMath from "markdown-it-math";

const md = markdownIt().use(markdownItMath, {
mathupOptions: { decimalMark: "," },
});

md.render("$40,2$");
//

$\mathrm{40,2}$


`

$3

Refer to [temml-custom-element][temml-custom-element] for usage
instructions about the custom element.

`js
import markdownIt from "markdown-it";
import markdownItMath from "markdown-it-math";

const md = markdownIt().use(markdownItMath, {
inlineCustomElement: "la-tex",
blockCustomElement: ["la-tex", { display: "block" }],
});

md.render(String.raw
$\sin(2\pi)$.
$$
\int_{0}^{\infty} E[X]
$$
);
//

\sin(2\pi).


// \int_{0}^{\infty} E[X]
`

$3

`js
import markdownIt from "markdown-it";
import markdownItMath from "markdown-it-math";

const md = markdownIt().use(markdownItMath, {
inlineDelimiters: "",
});
`

`md
Only block math is allowed. $a^2$ will not render into inline math.

But this will render into block math:

$$
a^2
$$
`

$3

`js
import markdownIt from "markdown-it";
import markdownItMath from "markdown-it-math";

const md = markdownIt().use(markdownItMath, {
inlineDelimiters: [["\\(", "\\)"]],
blockDelimiters: [["\\[", "\\]"]],
});
`

Note there are restrictions on what inline delimiters you can use,
based on optimization for the markdown-it parser [see here for
details][why-my-inline-rule-is-not-executed].

Unlike LaTeX, block level math must be on its own lines.


`markdown
Some text with inline math \(a^2 + b^2 = c^2\)

And block math:
\[ e = sum_(n=0)^oo 1 / n! \]

This expression \[P(x \in X) = 0\] will not render.
`

$3

`js
import markdownIt from "markdown-it";
import markdownItMath from "markdown-it-math";
import mathup from "mathup";
import temml from "temml";

const md = markdownIt().use(markdownItMath, {
inlineDelimiters: ["$", ["\\(", "\\)"]],
inlineRenderer(src, token) {
if (token.markup === "$") {
return mathup(src).toString();
}

return temml.renderToString(src);
},

blockDelimiters: ["$$", ["\\[", "\\]"]],
blockRenderer(src, token) {
if (token.markup === "$$") {
return mathup(src, { display: "block" }).toString();
}

return temml.renderToString(src, { displayMode: true });
},
});
`

Now you can use both $"AsciiMath"$ and \(\latex\) expressions:


`md
Some text with inline AsciiMath $a^2 + b^2 = c^2$
and inline LaTeX math \(\sin \theta\)

And AsciiMath:
$$
e = sum_(n=0)^oo 1 / n!
$$

And LaTeX math:
\[
e = \sum_{n=0}^{\infty} \frac{1}{n!}
\]
`

$3

`js
import markdownIt from "markdown-it";
import markdownItMathTemml from "markdown-it-math/temml";
import temml from "temml";

// An object to keep all the global macros.
const macros = {};

const md = markdownIt().use(markdownItMathTemml, {
temmlOptions: { macros },

blockDelimiters: ["$$", ["$$ preample", "$$"]],
blockRenderer(src, token) {
if (token.markup === "$$ preample") {
// Add these defs to the global macros.
Object.assign(macros, temml.definePreamble(src));

// Don’t render anything.
return "";
}

return temml.renderToString(src, { displayMode: true, macros });
},
});
`


`md


The Expected value

$$ preample
\def\E{\mathbb{E}}
\newcommand\d[0]{\operatorname{d}\!}
$$

Now we can use the macros defined above.

$$
\E[X] = \int_{-\infty}^{\infty} xf(x) \d{x}
$$
`

Note that this plugin does not support info
strings but the open
delimiter can be customized to look like an info string (see
below). Consider [markdown-it-mathblock][markdown-it-mathblock] if you
need commonmark compliant info strings.

Deprecated Options

- inlineOpen and inlineClose (since v5.0.0): Deprecated in favor
of inlineDelimiters:
`diff
markdownIt().use(markdownItMath, {
- inlineOpen: "$",
- inlineClose: "$",
+ inlineDelimiters: "$",
});
`
- blockOpen and blockClose (since v5.0.0): Deprecated in favor
of blockDelimiters:
`diff
markdownIt().use(markdownItMath, {
- blockOpen: "$$",
- blockClose: "$$",
+ blockDelimiters: "$$",
});
`
- defaultRendererOptions (since v5.2.0): Deprecated in favor of
mathupOptions:
`diff
markdownIt().use(markdownItMath, {
- defaultRendererOptions: { decimalMark: "," },
+ mathupOptions: { decimalMark: "," },
});
`

Upgrading From v4

Version 5 introduced some breaking changes, along with dropping legacy platforms.

- The default delimiters changed from $$ and $$$ for inline and
block math respectively to $ and $$. If you want to keep the
thicker variants, you must set the relevant options:
`js
markdownIt().use(markdownItMath, {
inlineDelimiters: "$$",
blockDelimiters: "$$$",
});
`
- The options passed into the default mathup renderer has been renamed
from renderingOptions to mathupOptions:
`diff
markdownIt().use(markdownItMath, {
- renderingOptions: { decimalMark: ",", },
+ mathupOptions: { decimalMark: ",", },
});
`
- The default math renderer has been changed from Ascii2MathML to it’s
successor mathup. There is a minor syntax and some output
differences, so this may brake some of your old expressions: If you
are afraid this happens you can opt into the legacy renderer:

`bash
npm install ascii2mathml
`

`js
import ascii2mathml from "ascii2mathml";

// The old renderingOptions settings must be explicitly passed in.
const mathRendererOptions = { decimalMark: "," };

markdownIt().use(markdownItMath, {
inlineRenderer: ascii2mathml(mathRendererOptions),
blockRenderer: ascii2mathml({ ...mathRendererOptions, display: "block" }),
});
``

[@mdit/plugin-katex]: https://mdit-plugins.github.io/katex.html
[importmap]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap
[markdown-it]: https://github.com/markdown-it/markdown-it
[markdown-it-mathblock]: https://github.com/runarberg/markdown-it-mathblock
[markdown-it-mathspan]: https://github.com/runarberg/markdown-it-mathspan
[mathml]: https://www.w3.org/TR/MathML/
[mathup]: https://mathup.xyz/
[Temml]: https://temml.org
[temml-custom-element]: https://github.com/runarberg/temml-custom-element
[why-my-inline-rule-is-not-executed]: https://github.com/markdown-it/markdown-it/blob/master/docs/development.md#why-my-inline-rule-is-not-executed