Markdown-it Katex

Markdown It plugin that adds KaTeX rendering. This is used by MarkEdit-preview to render math in Markdown.

Originally forked from @microsoft/vscode-markdown-it-katex

Usage

Install markdown-it

npm install markdown-it

Install the plugin

npm install markedit-katex

Use it in your javascript

const md = require("markdown-it")();
const mk = require("markedit-katex").default;

md.use(mk);

// double backslash is required for javascript strings, but not html input
const result = md.render("# Math Rulez! \n  $\\sqrt{3x-1}+(1+x)^2$");

ES modules use a native default import:

import MarkdownIt from "markdown-it";
import mk from "markedit-katex";

const md = new MarkdownIt().use(mk);

The ESM build imports KaTeX's ESM entry so bundlers can share it with other ESM consumers. CommonJS continues to use require("markedit-katex").default.

Include the KaTeX stylesheet in your html, matching the version of the renderer:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/katex@0.19.0/dist/katex.min.css"
/>

If you're using the default markdown-it parser, I also recommend the github stylesheet:

<link
  rel="stylesheet"
  href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/4.0.0/github-markdown.min.css"
/>

KaTeX options can be supplied with the second argument to use.

md.use(mk, { throwOnError: false, errorColor: " #cc0000" });

Supported Math Delimiters

By default, the following delimiters are supported:

• Inline math: $...$ and \(...\)
• Display (block) math: $$...$$ and \[...\]

You can customize the delimiters by providing a delimiters option:

md.use(mk, {
  delimiters: [
    { left: "$$", right: "$$", display: true },
    { left: "$", right: "$", display: false },
    // Add custom delimiters
    { left: "\\[", right: "\\]", display: true },
    { left: "\\(", right: "\\)", display: false }
  ]
});

Examples

Inline

Surround your LaTeX with a single $ on each side for inline rendering.

$\sqrt{3x-1}+(1+x)^2$

You can also use \( and \) for inline math:

\(E = mc^2\)

Block

Use two ($$) for block rendering. This mode uses bigger symbols and centers the result.

$$\begin{array}{c}

\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &
= \frac{4\pi}{c}\vec{\mathbf{j}}    \nabla \cdot \vec{\mathbf{E}} & = 4 \pi \rho \\

\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} & = \vec{\mathbf{0}} \\

\nabla \cdot \vec{\mathbf{B}} & = 0

\end{array}$$

You can also use \[ and \] for block math:

\[
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
\]

Using your own version of KaTeX

import MarkdownIt from "markdown-it";
import mk from "markedit-katex";
import katex from "katex";

// Load some katex extensions
import "katex/contrib/mhchem";
import "katex/contrib/copy-tex";

const md = new MarkdownIt();
md.use(mk, { katex });

const result = md.render("# Math Rulez! \n  $\\sqrt{3x-1}+(1+x)^2$");
const chemResult = md.render("$\\ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-}$");
console.log(result);
console.log(chemResult);

Syntax

Math parsing in markdown is designed to agree with the conventions set by pandoc:

Anything between two $ characters will be treated as TeX math. The opening $ must
have a non-space character immediately to its right, while the closing $ must
have a non-space character immediately to its left, and must not be followed
immediately by a digit. Thus, $20,000 and $30,000 won’t parse as math. If for some
reason you need to enclose text in literal $ characters, backslash-escape them and
they won’t be treated as math delimiters.

Math Syntax Support

KaTeX is based on TeX and LaTeX. Support for both is growing. Here's a list of currently supported functions:

Things that KaTeX does not (yet) support

Development

Run npm run compile after changing the source or compiler configuration, and commit the updated files in dist/ so Git installs receive the latest build. Compilation and npm run watch produce both CommonJS and ESM builds, with an ESM declaration copied from types.d.ts. Both builds include source maps. Run npm test to check rendering, both package entry points, and their types. Run npm run verify-dist after compilation to check for modified, deleted, or untracked build files. Both CI and the release pipeline run this check. Source maps embed the TypeScript source for debugging without shipping src/ separately. Source files use LF line endings on all platforms so the embedded source remains reproducible.