mdast extensions to parse and serialize math ($C_L$
).
- What is this?
- When to use this
- Install
- Use
- API
- HTML
- Syntax tree
- Types
- Compatibility
- Related
- Contribute
- License
This package contains extensions that add support for math to
mdast-util-from-markdown
and
mdast-util-to-markdown
.
These tools are all rather low-level.
In most cases, you’d want to use remark-math
with remark
instead.
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.
When working with mdast-util-from-markdown
, you must combine this package with
micromark-extension-math
.
This utility adds fields on nodes so that the utility responsible for
turning mdast (markdown) nodes into hast (HTML) nodes,
mdast-util-to-hast
, turns text (inline) math nodes into
<code class="language-math math-inline">…</code>
and flow (block) math nodes
into <pre><code class="language-math math-display">…</code></pre>
.
This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:
npm install mdast-util-math
In Deno with esm.sh
:
import {mathFromMarkdown, mathToMarkdown} from 'https://esm.sh/mdast-util-math@2'
In browsers with esm.sh
:
<script type="module">
import {mathFromMarkdown, mathToMarkdown} from 'https://esm.sh/mdast-util-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 {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {math} from 'micromark-extension-math'
import {mathFromMarkdown, mathToMarkdown} from 'mdast-util-math'
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', e: 'C_L', data: {/* … */}},
{type: 'text', value: ') like the following equation.'}
]
},
{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
$$
This package exports the identifiers mathFromMarkdown
and mathToMarkdown
.
There is no default export.
Function that can be called to get an extension for
mdast-util-from-markdown
.
Function that can be called to get an extension for
mdast-util-to-markdown
.
Configuration (optional).
Whether to support text math (inline) with a single dollar (boolean
, default:
true
).
Single dollars work in Pandoc and many other places, but often interfere with
“normal” dollars in text.
This plugin integrates with mdast-util-to-hast
.
When mdast is turned into hast the math nodes are turned into
<code class="language-math math-inline">…</code>
and
<pre><code class="language-math math-display">…</code></pre>
.
The following interfaces are added to mdast by this utility.
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: {/* … */}
}
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: {/* … */}}
type FlowContentMath = Math | FlowContent
type PhrasingMath = InlineMath | PhrasingContent
This package is fully typed with TypeScript.
It exports the additional types Math
, InlineMath
, 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('mdast-util-math')}
*/
import {visit} from 'unist-util-visit'
/** @type {import('mdast').Root} */
const tree = getMdastNodeSomeHow()
visit(tree, (node) => {
// `node` can now be one of the nodes for math.
})
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 mdast-util-from-markdown
version 1+ and
mdast-util-to-markdown
version 1+.
remarkjs/remark-math
— remark plugin to support mathmicromark/micromark-extension-math
— micromark extension to parse math
See contributing.md
in syntax-tree/.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.