rehype-mathjax

rehype plugin to render <span class=math-inline> and <div class=math-display> with MathJax.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • unified().use(rehypeMathjaxSvg[, options])
• CSS
• Syntax tree
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a unified (rehype) plugin to render math. You can combine it with remark-math for math in markdown or add math-inline and math-display classes in HTML.

unified is a project that transforms content with abstract syntax trees (ASTs). rehype adds support for HTML to unified. hast is the HTML AST that rehype uses. This is a rehype plugin that transforms hast.

When should I use this?

This project is useful as it renders math with MathJax at compile time, which means that there is no client side JavaScript needed.

A different plugin, rehype-katex, is similar but uses KaTeX instead.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install rehype-mathjax

In Deno with esm.sh:

import rehypeMathjax from 'https://esm.sh/rehype-mathjax@4'

In browsers with esm.sh:

<script type="module">
  import rehypeMathjax from 'https://esm.sh/rehype-mathjax@4?bundle'
</script>

Use

Say we have the following file example.html:

<p>
  Lift(<span class="math math-inline">L</span>) can be determined by Lift Coefficient
  (<span class="math math-inline">C_L</span>) like the following equation.
</p>

<div class="math math-display">
  L = \frac{1}{2} \rho v^2 S C_L
</div>

And our module example.js looks as follows:

import {read} from 'to-vfile'
import {unified} from 'unified'
import rehypeParse from 'rehype-parse'
import rehypeMathjax from 'rehype-mathjax'
import rehypeStringify from 'rehype-stringify'

const file = await unified()
  .use(rehypeParse, {fragment: true})
  .use(rehypeMathjax)
  .use(rehypeStringify)
  .process(await read('example.html'))

console.log(String(file))

Now running node example.js yields:

<p>
  Lift(<span class="math math-inline"><mjx-container class="MathJax" jax="SVG"><!--…--></mjx-container></span>) can be determined by Lift Coefficient
  (<span class="math math-inline"><mjx-container class="MathJax" jax="SVG"><!--…--></mjx-container></span>) like the following equation.
</p>

<div class="math math-display"><mjx-container class="MathJax" jax="SVG" display="true"><!--…--></mjx-container></div>
<style>
mjx-container[jax="SVG"] {
  direction: ltr;
}
/* … */
</style>

API

This package exports no identifiers. The default export is rehypeMathjaxSvg.

unified().use(rehypeMathjaxSvg[, options])

Transform <span class="math-inline"> and <div class="math-display"> with MathJax.

This package includes three plugins, split out because MathJax targets have a big memory and bundle size footprint: SVG, CHTML, and browser:

SVG

Render math as SVG (import rehypeMathjaxSvg from 'rehype-mathjax/svg.js', default). About 566kb minzipped.

CHTML

Render math as CHTML (import rehypeMathjaxChtml from 'rehype-mathjax/chtml.js'). About 154kb minzipped. Needs a fontURL to be passed.

Browser

Tiny wrapper that expects MathJax to do work client side (import rehypeMathjaxBrowser from 'rehype-mathjax/browser.js'). About 1kb minzipped.

Uses options.displayMath (default: ['\\[', '\\]']) for display math and options.inlineMath (default: ['\\(', '\\)']) for inline math.

You need to load MathJax on the client yourself and start it with corresponding markers. Options are not passed to MathJax: do that yourself on the client.

options

All options, except when using the browser plugin, are passed to MathJax.

options.tex

These options are passed to the TeX input processor. The browser plugin uses the first delimiter pair in tex.displayMath and tex.inlineMath to instead wrap math.

options.chtml

These options are passed to the CommonHTML output processor. Passing fontURL is required! For example:

  // …
  .use(rehypeMathjaxChtml, {
    chtml: {
      fontURL: 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/output/chtml/fonts/woff-v2'
    }
  })
  // …

options.svg

These options are passed to the SVG output processor.

CSS

The HTML produced by MathJax does not require any extra CSS to render correctly.

Syntax tree

This plugin transforms elements with a class name of either math-inline and/or math-display.

Types

This package is fully typed with TypeScript. An extra Options type is exported, which models the accepted options.

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with unified version 6+ and rehype version 4+.

Security

Using rehype-mathjax should be safe assuming that you trust MathJax. Any vulnerability in it could open you to a cross-site scripting (XSS) attack. Always be wary of user input and use rehype-sanitize.

When you don’t trust user content but do trust MathKax, you can allow the classes added by remark-math while disallowing anything else in the rehype-sanitize schema, and run rehype-katex afterwards. Like so:

import rehypeSanitize, {defaultSchema} from 'rehype-stringify'

const mathSanitizeSchema = {
  ...defaultSchema,
  attributes: {
    ...defaultSchema.attributes,
    div: [
      ...defaultSchema.attributes.div,
      ['className', 'math', 'math-display']
    ],
    span: [
      ['className', 'math', 'math-inline']
    ]
  }
}

// …

unified()
  // …
  .use(rehypeSanitize, mathSanitizeSchema)
  .use(rehypeMathjax)
  // …

Related

• rehype-katex — same but with KaTeX
• rehype-highlight — highlight code blocks
• rehype-autolink-headings — add links to headings
• rehype-sanitize — sanitize HTML
• rehype-document — wrap a document around the tree

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © TANIGUCHI Masaya