@akepinski/remark-math

remark-math

remark plugin to support math ($C_L$).

Contents

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

What is this?

This package is a unified (remark) plugin to add support for math. You can use this to add support for parsing and serializing this syntax extension.

unified is a project that transforms content with abstract syntax trees (ASTs). remark adds support for markdown to unified. mdast is the markdown AST that remark uses. micromark is the markdown parser we use. This is a remark plugin that adds support for the math syntax and AST to remark.

When should I use this?

This project is useful when you want to support math in markdown. Extending markdown with a syntax extension makes the markdown less portable. LaTeX equations are also quite hard. But this mechanism works well when you want authors, that have some LaTeX experience, to be able to embed rich diagrams of math in scientific text.

Install

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

npm install remark-math

In Deno with esm.sh:

import remarkMath from 'https://esm.sh/remark-math@5'

In browsers with esm.sh:

<script type="module">
  import remarkMath from 'https://esm.sh/remark-math@5?bundle'
</script>

Use

Say we have the following file example.md:

Lift($L$) can be determined by Lift Coefficient ($C_L$) like the following
equation.

$$
L = \frac{1}{2} \rho v^2 S C_L
$$

And our module example.js looks as follows:

import {read} from 'to-vfile'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkMath from 'remark-math'
import remarkRehype from 'remark-rehype'
import rehypeKatex from 'rehype-katex'
import rehypeStringify from 'rehype-stringify'

const file = await unified()
  .use(remarkParse)
  .use(remarkMath)
  .use(remarkRehype)
  .use(rehypeKatex)
  .use(rehypeStringify)
  .process(await read('example.md'))

console.log(String(file))

Now running node example.js yields:

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

API

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

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

Plugin to support math.

options

Configuration (optional).

options.singleDollarTextMath

Whether to support math (text) with a single dollar (boolean, default: true). Single dollars work in Pandoc and many other places, but often interfere with “normal” dollars in text.

Syntax

This plugin applies a micromark extensions to parse the syntax. See its readme for parse details:

• micromark-extension-math

👉 Note: $math$ works similar to `code`. That means escapes don’t work inside math but you can use more dollars around the math instead: $$\raisebox{0.25em}{$\frac a b$}$$

HTML

This plugin integrates with remark-rehype. When mdast (markdown AST) is turned into hast (the HTML AST) the math nodes are turned into <span class=math-inline> and <div class=math-block> elements.

Syntax tree

This plugin applies one mdast utility to build and serialize the AST. See its readme for the node types supported in the tree:

• mdast-util-math

Types

This package is fully typed with TypeScript. It exports an extra Options type which models the interface of the accepted options.

If you’re working with the syntax tree, make sure to import this plugin somewhere in your types, as that registers the new node types in the tree.

/** @typedef {import('remark-math')} */

import {visit} from 'unist-util-visit'

/** @type {import('unified').Plugin<[], import('mdast').Root>} */
export default function myRemarkPlugin() => {
  return (tree) => {
    visit(tree, (node) => {
      // `node` can now be one of the nodes for math.
    })
  }
}

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 remark version 14+. The previous major (version 4) worked with remark 13.

Security

Use of remark-math itself does not open you up to cross-site scripting (XSS) attacks. Always be wary of user input and use rehype-sanitize.

Related

• remark-gfm — support GFM (autolink literals, footnotes, strikethrough, tables, tasklists)
• remark-frontmatter — support frontmatter (YAML, TOML, and more)
• remark-directive — support directives
• remark-mdx — support MDX (JSX, expressions, ESM)

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 © Junyoung Choi