micromark-extension-math
Advanced tools
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.
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);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 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.
micromark extensions to support math ($C_L$).
This package contains two extensions that add support for math syntax
in markdown to micromark.
As there is no spec for math in markdown, this extension follows how code (fenced and text) works in Commonmark, but uses dollars.
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.
You can use these extensions when you are working with micromark
already.
When you need a syntax tree, you can combine this package with
mdast-util-math.
All these packages are used remark-math, which focusses on
making it easier to transform content by abstracting these internals away.
This package is ESM only. In Node.js (version 14.14+), install with npm:
npm:
npm install micromark-extension-math
In Deno with esm.sh:
import {math, mathHtml} from 'https://esm.sh/micromark-extension-math@2'
In browsers with esm.sh:
<script type="module">
import {math, mathHtml} from 'https://esm.sh/micromark-extension-math@2?bundle'
</script>
Say our document example.md contains:
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 fs from 'node:fs/promises'
import {micromark} from 'micromark'
import {math, mathHtml} from 'micromark-extension-math'
const output = micromark(await fs.readFile('example.md'), {
extensions: [math()],
htmlExtensions: [mathHtml()]
})
console.log(output)
…now running node example.js 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>
This package exports the identifiers math and
mathHtml.
There is no default export.
The export map supports the development condition.
Run node --conditions development module.js to get instrumented dev code.
Without this condition, production code is loaded.
math(options?)Create an extension for micromark to enable math syntax.
options (Options, optional)
— configurationExtension for micromark that can be passed in extensions, to enable math
syntax (Extension).
mathHtml(options?)Create an extension for micromark to support math when serializing to HTML.
👉 Note: this uses KaTeX to render math.
options (HtmlOptions, optional)
— configurationExtension for micromark that can be passed in htmlExtensions, to support
math when serializing to HTML (HtmlExtension).
OptionsConfiguration (TypeScript type).
singleDollarTextMath (boolean, default: true)
— whether to support math (text) with a single dollar.
Single dollars work in Pandoc and many other places, but often interfere
with “normal” dollars in text.
If you turn this off, you can use two or more dollars for text math.HtmlOptionsConfiguration for HTML output (optional).
👉 Note: passed to
katex.renderToString.displayModeis overwritten by this plugin, tofalsefor math in text, andtruefor math in flow.
type Options = Omit<import('katex').KatexOptions, 'displayMode'>
When authoring markdown with math, keep in mind that math doesn’t work in most
places.
Notably, GitHub currently has a really weird crappy client-side regex-based
thing.
But on your own (math-heavy?) site it can be great!
You can use code (fenced) with an info string of math to improve this, as
that works in many places.
Math (flow) does not relate to HTML elements.
MathML, which is sort of like SVG but for math, exists but it doesn’t work
well and isn’t widely supported.
Instead, this uses KaTeX, which generates MathML as a fallback but also
generates a bunch of divs and spans so math look pretty.
The KaTeX result is wrapped in <div> and <span> elements, with two classes:
math and either math-display or math-inline.
When turning markdown into HTML, each line ending in math (text) are turned into a space.
The HTML produced by KaTeX requires CSS to render correctly.
You should use katex.css somewhere on the page where the math is shown to
style it properly.
At the time of writing, the last version is:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.css">
Math forms with the following BNF:
; Restriction: the number of markers in the closing sequence must be equal
; to the number of markers in the opening sequence.
math_text ::= sequence_text 1*byte sequence_text
math_flow ::= fence_open *( eol *line ) [ eol fence_close ]
; Restriction: not preceded or followed by the marker.
sequence_text ::= 1*'$'
fence_open ::= sequence_flow meta
; Restriction: the number of markers in the closing fence sequence must be
; equal to or greater than the number of markers in the opening fence
; sequence.
fence_close ::= sequence_flow *space_or_tab
sequence_flow ::= 2*'$'
; Restriction: the marker cannot occur in `meta`
meta ::= 1*line
; Character groups for informational purposes.
byte ::= 0x00..=0xFFFF
eol ::= '\n' | '\r' | '\r\n'
line ::= byte - eol
The above grammar shows that it is not possible to create empty math (text). It is possible to include the sequence marker (dollar) in math (text), by wrapping it in bigger or smaller sequences:
Include more: $a$$b$ or include less: $$a$b$$.
It is also possible to include just one marker:
Include just one: $$ $ $$.
Sequences are “gready”, in that they cannot be preceded or followed by more markers. To illustrate:
Not math: $$x$.
Not math: $x$$.
Escapes work, this is math: \$$x$.
Escapes work, this is math: $x$\$.
Yields:
<p>Not math: $$x$.</p>
<p>Not math: $x$$.</p>
<p>Escapes work, this is math: $<span>…</span>.</p>
<p>Escapes work, this is math: <span>…</span>$.</p>
That is because, when turning markdown into HTML, the first and last space, if both exist and there is also a non-space in the math, are removed. Line endings, at that stage, are considered as spaces.
As the math (flow) construct occurs in flow, like all flow constructs, it must be followed by an eol (line ending) or eof (end of file).
The above grammar does not show how indentation of each line is handled.
To parse math (flow), let x be the number of space_or_tab characters
before the opening fence sequence, after interpreting tabs based on how many
virtual spaces they represent.
Each line of text is then allowed (not required) to be indented with up
to x spaces or tabs, which are then ignored as an indent instead of being
considered as part of the content.
This indent does not affect the closing fence.
It can be indented up to a separate 3 real or virtual spaces.
A bigger indent makes it part of the content instead of a fence.
The meta part is interpreted as the string content
type.
That means that character escapes and character references are allowed.
The optional meta part is ignored: it is not used when parsing or
rendering.
This package is fully typed with TypeScript.
It exports the additional types HtmlOptions
and Options.
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+. Our projects sometimes work with older versions, but this is not guaranteed.
These extensions work with micromark version 3+.
This package is safe assuming that you trust KaTeX. Any vulnerability in it could open you to a cross-site scripting (XSS) attack.
remark-math
— remark (and rehype) plugins to support mathmdast-util-math
— mdast utility to support mathSee 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.
FAQs
micromark extension to support math (`$C_L$`)
We found that micromark-extension-math demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.