micromark-extension-math

What is micromark-extension-math?

The micromark-extension-math package is an extension for micromark, a Markdown parser, that adds support for parsing and rendering mathematical expressions written in LaTeX. This package is particularly useful for developers who need to include mathematical notation in their Markdown documents.

What are micromark-extension-math's main functionalities?

Inline Math

This feature allows you to include inline mathematical expressions within your Markdown content using the $...$ syntax. The code sample demonstrates how to parse and render an inline math expression.

const micromark = require('micromark');
const math = require('micromark-extension-math');

const content = 'This is an inline math expression: $E=mc^2$';
const html = micromark(content, { extensions: [math()] });
console.log(html);

Display Math

This feature allows you to include display mathematical expressions using the $$...$$ syntax. Display math is typically rendered on its own line and centered. The code sample shows how to parse and render a display math expression.

const micromark = require('micromark');
const math = require('micromark-extension-math');

const content = 'This is a display math expression: $$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$';
const html = micromark(content, { extensions: [math()] });
console.log(html);

Other packages similar to micromark-extension-math

remark-math

remark-math is a plugin for remark, another Markdown processor, that adds support for parsing and rendering LaTeX math expressions. It is similar to micromark-extension-math but is used within the remark ecosystem. Both packages offer similar functionalities, but the choice depends on whether you are using micromark or remark for your Markdown processing.

markdown-it-texmath

markdown-it-texmath is a plugin for markdown-it, a different Markdown parser, that enables the parsing and rendering of LaTeX math expressions. Like micromark-extension-math, it supports both inline and display math. The main difference is that markdown-it-texmath is designed to work with the markdown-it parser.

README

micromark-extension-math

micromark extension to support math ($C_L$).

As there is no spec for math in markdown, this extension stays as close to code in text and fenced code in flow in CommonMark, but using dollar signs.

When to use this

If you’re using micromark or mdast-util-from-markdown, use this package. Alternatively, if you’re using remark, use remark-math.

Syntax

Math (text) can start with one or more dollar signs, so long as they match:
With one: $\alpha$, two: $$\beta$$, or three: $$$\gamma$$$.

This is useful, because like code, typical markdown escapes don’t work.
For dollars inside math, use more dollars around it: $$\raisebox{0.25em}{$\frac
a b$}$$.

If the math starts and ends with a space (or EOL), those are removed: $$ \$ $$.

Math (flow) starts at two or more dollars:

$$
\Delta
$$

You can hide some stuff in the meta of the opening fence (but no dollars):

$$hidden information
$$

Math that doesn’t have a closing fence, still works, like fenced code:

> $$
> this is
> all math

…but at the end of their container (block quote, list item, or document), they
are closed.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install micromark-extension-math

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 script, example.js, looks as follows:

import fs from 'fs'
import {micromark} from 'micromark'
import {math, mathHtml} from 'micromark-extension-math'

const output = micromark(fs.readFileSync('example.md'), {
  extensions: [math()],
  htmlExtensions: [mathHtml()]
})

console.log(output)

Now, running node example yields (abbreviated):

<p>Lift(<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 class="katex">…</span></div>

API

This package exports the following identifiers: math, mathHtml. There is no default export.

The export map supports the endorsed development condition. Run node --conditions development module.js to get instrumented dev code. Without this condition, production code is loaded.

math(options?)

mathHtml(htmlOptions?)

A function to create an extension for micromark to parse math (can be passed in extensions) and a function that can be called to get an extension to compile them to HTML with KaTeX (can be passed in htmlExtensions).

options

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.

htmlOptions

Passed to katex.renderToString. displayMode is overwritten by this plugin, to false for math in text, and true for math in flow.

Related

• remarkjs/remark — markdown processor powered by plugins
• remarkjs/remark-math — remark plugin using this to support math
• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• syntax-tree/mdast-util-math — mdast utility to support math
• syntax-tree/mdast-util-from-markdown — mdast parser using micromark to create mdast from markdown
• syntax-tree/mdast-util-to-markdown — mdast serializer to create markdown from mdast

Contribute

See contributing.md in micromark/.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 © Titus Wormer