mdast-util-math

mdast extension to parse and serialize math

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
mdast-util-math
1103.0.08 months ago3 years agoMinified + gzip package size for mdast-util-math in KB

Readme

mdast-util-math
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
mdast extensions to parse and serialize math ($C_L$).

Contents

*   [`mathFromMarkdown()`](#mathfrommarkdown)
*   [`mathToMarkdown(options?)`](#mathtomarkdownoptions)
*   [`InlineMath`](#inlinemath)
*   [`Math`](#math)
*   [`ToOptions`](#tooptions)
*   [Nodes](#nodes)
*   [Content model](#content-model)

What is this?

This package contains two extensions that add support for math syntax in markdown to mdast. These extensions plug into mdast-util-from-markdownmdast-util-from-markdown (to support parsing math in markdown into a syntax tree) and mdast-util-to-markdownmdast-util-to-markdown (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 mdast-util-from-markdown and mdast-util-to-markdown already.
When working with mdast-util-from-markdown, you must combine this package with micromark-extension-mathmicromark-extension-math.
When you don’t need a syntax tree, you can use micromarkmicromark directly with micromark-extension-mathmicromark-extension-math.
All these packages are used remark-mathremark-math, which focusses on making it easier to transform content by abstracting these internals away.
This utility adds fields on nodesfields so that the utility responsible for turning mdast (markdown) nodes into hast (HTML) nodes, mdast-util-to-hastmdast-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>.

Install

This package is ESM onlyesm. In Node.js (version 16+), install with npm:
npm install mdast-util-math

In Deno with esm.shesmsh:
import {mathFromMarkdown, mathToMarkdown} from 'https://esm.sh/mdast-util-math@3'

In browsers with esm.shesmsh:
<script type="module">
  import {mathFromMarkdown, mathToMarkdown} from 'https://esm.sh/mdast-util-math@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 'micromark-extension-math'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {mathFromMarkdown, mathToMarkdown} from 'mdast-util-math'
import {toMarkdown} from 'mdast-util-to-markdown'

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 mathFromMarkdownapi-math-from-markdown and mathToMarkdownapi-math-to-markdown. There is no default export.

mathFromMarkdown()

Create an extension for mdast-util-from-markdownmdast-util-from-markdown.
Returns
Extension for mdast-util-from-markdown (FromMarkdownExtensionfrom-markdown-extension).

mathToMarkdown(options?)

Create an extension for mdast-util-to-markdownmdast-util-to-markdown.
Parameters
— configuration
Returns
Extension for mdast-util-to-markdown (ToMarkdownExtensionto-markdown-extension).

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 mdast-util-to-hastmdast-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> elements.

Syntax

See Syntax in micromark-extension-frontmattersyntax.

Syntax tree

The following interfaces are added to mdast by this utility.

Nodes

Math

interface Math <: Literal {
  type: 'code'
  meta: string?
}

Math (Literaldfn-literal) represents a block of math, such as LaTeX mathematical expressions.
Math can be used where flowdfn-flow-content content is expected. Its content is represented by its value field.
This node relates to the
phrasingdfn-phrasing-content content concept InlineMathdfn-inline-math.
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 (Literaldfn-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 phrasingdfn-phrasing-content content is expected. Its content is represented by its value field.
This node relates to the
flowdfn-flow-content content concept Mathdfn-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 InlineMathapi-inline-math, Mathapi-math, and ToOptionsapi-to-options.
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, 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, mdast-util-math@^3, compatible with Node.js 16.
This plugin works with mdast-util-from-markdown version 2+ and mdast-util-to-markdown version 2+.

Related

— remark plugin to support math
— micromark extension to parse math

Contribute

See contributing.mdcontributing in syntax-tree/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MITlicense © Titus Wormerauthor