mdastutilmath
mdast extensions to parse and serialize math ($C_L$
).
Contents
 What is this?
 When to use this
 Install
 Use
 API
 HTML
 Syntax
 Syntax tree
 Types
 Compatibility
 Related
 Contribute
 License
What is this?
This package contains two extensions that add support for math syntax in
markdown to mdast.
These extensions plug into
mdastutilfrommarkdown
(to support parsing
math in markdown into a syntax tree) and
mdastutiltomarkdown
(to support serializing
math in syntax trees to markdown).
When to 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.
You can use these extensions when you are working with
mdastutilfrommarkdown
and mdastutiltomarkdown
already.
When working with mdastutilfrommarkdown
, you must combine this package
with micromarkextensionmath
.
When you don’t need a syntax tree, you can use micromark
directly with
micromarkextensionmath
.
All these packages are used remarkmath
, which
focusses on making it easier to transform content by abstracting these
internals away.
This utility adds fields on nodes so that the utility responsible for
turning mdast (markdown) nodes into hast (HTML) nodes,
mdastutiltohast
, turns text (inline) math nodes into
<code class="languagemath mathinline">…</code>
and flow (block) math nodes
into <pre><code class="languagemath mathdisplay">…</code></pre>
.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install mdastutilmath
In Deno with esm.sh
:
import {mathFromMarkdown, mathToMarkdown} from 'https://esm.sh/mdastutilmath@3'
In browsers with esm.sh
:
<script type="module">
import {mathFromMarkdown, mathToMarkdown} from 'https://esm.sh/mdastutilmath@3?bundle'
</script>
Use
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 {math} from 'micromarkextensionmath'
import {fromMarkdown} from 'mdastutilfrommarkdown'
import {mathFromMarkdown, mathToMarkdown} from 'mdastutilmath'
import {toMarkdown} from 'mdastutiltomarkdown'
const doc = await fs.readFile('example.md')
const tree = fromMarkdown(doc, {
extensions: [math()],
mdastExtensions: [mathFromMarkdown()]
})
console.log(tree)
const out = toMarkdown(tree, {extensions: [mathToMarkdown()]})
console.log(out)
…now running node example.js
yields (positional info and data removed for
brevity):
{
type: 'root',
children: [
{
type: 'paragraph',
children: [
{type: 'text', value: 'Lift('},
{type: 'inlineMath', value: 'L', data: {/* … */}},
{type: 'text', value: ') can be determined by Lift Coefficient ('},
{type: 'inlineMath', value: 'C_L', data: {/* … */}},
{type: 'text', value: ') like the following\nequation.'}
]
},
{type: 'math', meta: null, value: 'L = \\frac{1}{2} \\rho v^2 S C_L', data: {/* … */}}
]
}
Lift($L$) can be determined by Lift Coefficient ($C_L$) like the following
equation.
$$
L = \frac{1}{2} \rho v^2 S C_L
$$
API
This package exports the identifiers
mathFromMarkdown
and mathToMarkdown
.
There is no default export.
mathFromMarkdown()
Create an extension for mdastutilfrommarkdown
.
Returns
Extension for mdastutilfrommarkdown
(FromMarkdownExtension
).
mathToMarkdown(options?)
Create an extension for mdastutiltomarkdown
.
Parameters

options
(ToOptions
, optional) — configuration
Returns
Extension for mdastutiltomarkdown
(ToMarkdownExtension
).
InlineMath
Math (text) (TypeScript type).
Type
import type {Data, Literal} from 'mdast'
interface InlineMath extends Literal {
type: 'inlineMath'
data?: InlineMathData  undefined
}
export interface InlineMathData extends Data {}
Math
Math (flow) (TypeScript type).
Type
import type {Data, Literal} from 'mdast'
interface Math extends Literal {
type: 'math'
meta?: string  null  undefined
data?: MathData  undefined
}
export interface MathData extends Data {}
ToOptions
Configuration (TypeScript type).
Fields

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 still use two or more dollars for text math
HTML
This plugin integrates with mdastutiltohast
.
When mdast is turned into hast the math nodes are turned into
<code class="languagemath mathinline">…</code>
and
<pre><code class="languagemath mathdisplay">…</code></pre>
elements.
Syntax
See Syntax in micromarkextensionfrontmatter
.
Syntax tree
The following interfaces are added to mdast by this utility.
Nodes
Math
interface Math <: Literal {
type: 'code'
meta: string?
}
Math (Literal) represents a block of math, such as LaTeX mathematical expressions.
Math can be used where flow content is expected.
Its content is represented by its value
field.
This node relates to the phrasing content concept InlineMath.
A meta
field can be present.
It represents custom information relating to the node.
For example, the following markdown:
$$
L = \frac{1}{2} \rho v^2 S C_L
$$
Yields:
{
type: 'math',
meta: null,
value: 'L = \\frac{1}{2} \\rho v^2 S C_L',
data: {/* … */}
}
InlineMath
interface InlineMath <: Literal {
type: 'inlineMath'
}
InlineMath (Literal) represents a fragment of computer code, such as a file name, computer program, or anything a computer could parse.
InlineMath can be used where phrasing content
is expected.
Its content is represented by its value
field.
This node relates to the flow content concept Math.
For example, the following markdown:
$L$
Yields:
{type: 'inlineMath', value: 'L', data: {/* … */}}
Content model
FlowContent
(math)
type FlowContentMath = Math  FlowContent
PhrasingContent
(math)
type PhrasingContentMath = InlineMath  PhrasingContent
Types
This package is fully typed with TypeScript.
It exports the additional types InlineMath
,
Math
, and ToOptions
.
It also registers the node types with @types/mdast
.
If you’re working with the syntax tree, make sure to import this utility
somewhere in your types, as that registers the new node types in the tree.
/**
* @typedef {import('mdastutilmath')}
*/
import {visit} from 'unistutilvisit'
/** @type {import('mdast').Root} */
const tree = getMdastNodeSomeHow()
visit(tree, function (node) {
// `node` can now be one of the nodes for math.
})
Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, mdastutilmath@^3
,
compatible with Node.js 16.
This plugin works with mdastutilfrommarkdown
version 2+ and
mdastutiltomarkdown
version 2+.
Related

remarkmath
— remark plugin to support math 
micromarkextensionmath
— micromark extension to parse math
Contribute
See contributing.md
in syntaxtree/.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.