@mdit/plugin-mathjax

Plugins to render math expressions with Mathjax.

Note

This plugin is based on @mdit/plugin-tex.

Usage Node.js runtime only

import MarkdownIt from "markdown-it";
import { createMathjaxInstance, mathjax } from "@mdit/plugin-mathjax";

const mathjaxInstance = await createMathjaxInstance(options);
const mdIt = MarkdownIt().use(mathjax, mathjaxInstance);

const html = mdIt.render("$E=mc^2$");
const style = mathjaxInstance.outputStyle();

const MarkdownIt = require("markdown-it");
const { createMathjaxInstance, mathjax } = require("@mdit/plugin-mathjax");

const mathjaxInstance = await createMathjaxInstance(options);
const mdIt = MarkdownIt().use(mathjax, mathjaxInstance);

const html = mdIt.render("$E=mc^2$");
const style = mathjaxInstance.outputStyle();

This plugin is a bit different from other plugins. It requires you to create a Mathjax instance with options first, and then pass it to the plugin.

You can set the following options:

interface MarkdownItMathjaxOptions {
  /**
   * Output syntax
   *
   * @default 'svg'
   */

  output?: "chtml" | "svg";

  /**
   * Math delimiter syntax to enable
   *
   * - `"brackets"`: Use `\(...\)` for inline math and `\[...\]` for display math (LaTeX style)
   * - `"dollars"`: Use `$...$` for inline math and `$$...$$` for display math (common Markdown style)
   * - `"all"`: Enable both bracket and dollar syntaxes
   *
   * @default "dollars"
   */
  delimiters?: "brackets" | "dollars" | "all";

  /**
   * Whether to allow inline math with spaces on ends
   *
   * @description NOT recommended to set this to true, because it will likely break the default usage of $
   *
   * @default false
   */
  allowInlineWithSpace?: boolean;

  /**
   * Whether parsed fence block with math language to display mode math
   *
   * @default false
   */
  mathFence?: boolean;

  /**
   * Enable A11y
   *
   * @default true
   */
  a11y?: boolean;

  /**
   * TeX input options
   */
  tex?: MathJaxTexInputOptions;

  /**
   * Common HTML output options
   */
  chtml?: MathjaxCommonHTMLOutputOptions;

  /**
   * SVG output options
   */
  svg?: MathjaxSVGOutputOptions;
}

The instance holds render content of each calls, so you should:

Call mathjaxInstance.reset() before each render in different pages, this ensure things like label are reset.
Call mathjaxInstance.outputStyle() after all rendering is done, to get final CSS content.
Call mathjaxInstance.clearStyle() to clear existing style cache if necessary.

We also have a package called @mdit/plugin-mathjax-slim which @mathjax/src is an optional peer dep.

For better performance and memory, the createMathjaxInstance function is asynchronous, allowing you to load only the packages you need dynamically, but if you must call the plugin in a synchronous flow, you can import a synchronous version of the createMathjaxInstance function from @mdit/plugin-mathjax/sync.

Syntax

The syntax depends on the delimiters option:

Default ("dollars"): Use $tex expression$ inline, and $$tex expression$$ for block.
LaTeX style ("brackets"): Use $tex expression$ inline, and \[tex expression\] for block.
Both ("all"): Both dollar and bracket syntaxes are supported.

Escaping

You can use \ to escape $ \( and \[:
```
Euler’s identity \$e^{i\pi}+1=0$
```
will be
Euler’s identity $e^{i\pi}+1=0$

Demo

Euler’s identity $e^{i π} + 1 = 0$ is a beautiful formula in $R^{2}$ .

\frac{\partial^{r}}{\partial ω^{r}} (\frac{y^{ω}}{ω}) = (\frac{y^{ω}}{ω}) {(\log y)^{r} + \sum_{i = 1}^{r} \frac{(- 1)^{I} r \dots (r - i + 1) (\log y)^{r i}}{ω^{i}}}

Demo

Euler’s identity $e^{i\pi}+1=0$ is a beautiful formula in $\mathbb{R}^2$.

$$
\frac {\partial^r} {\partial \omega^r} \left(\frac {y^{\omega}} {\omega}\right)
= \left(\frac {y^{\omega}} {\omega}\right) \left\{(\log y)^r + \sum_{i=1}^r \frac {(-1)^ Ir \cdots (r-i+1) (\log y)^{ri}} {\omega^i} \right\}
$$

Support List

Supported TeX/LaTeX commands

Cookbook

$T E X$ Cookbook