micromark-extension-temml

micromark extensions to support math ($C_L$) with Temml.

This package is a Temml-backed fork of micromark-extension-math. It keeps the same public API, syntax rules, and markdown behavior while using Temml instead of KaTeX for HTML output.

What is this?

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.

When to use this

Use this package when you already work with micromark and want to support LaTeX-style math in markdown while rendering with Temml.

When you need a syntax tree, you can combine this package with mdast-util-math.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install micromark-extension-temml

In Deno with esm.sh:

import {math, mathHtml} from 'https://esm.sh/micromark-extension-temml@3'

In browsers with esm.sh:

<script type="module">
  import {math, mathHtml} from 'https://esm.sh/micromark-extension-temml@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 {micromark} from 'micromark'
import {math, mathHtml} from 'micromark-extension-temml'

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

console.log(output)

Running node example.js yields abbreviated HTML such as:

<p>Lift(<span class="math math-inline"><math>...</math></span>) can be determined by Lift Coefficient (<span class="math math-inline"><math>...</math></span>) like the following equation.</p>
<div class="math math-display"><math display="block">...</math></div>

API

This package exports 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.

Parameters

• options (Options, default: {}) configures the syntax extension.

Returns

An Extension for micromark that can be passed in extensions.

mathHtml(options?)

Create an extension for micromark to support math when serializing to HTML.

Note: this uses Temml to render math.

Parameters

• options (HtmlOptions, default: {}) configures HTML rendering.

Returns

An HtmlExtension for micromark that can be passed in htmlExtensions.

HtmlOptions

Configuration for HTML output.

• Options are passed to temml.renderToString.
• throwOnError defaults to true to preserve the behavior of the upstream KaTeX-based package.
• displayMode is overwritten by this plugin, to false for inline math and true for block math.

Type

type HtmlOptions = Omit<import('temml').Options, 'displayMode'>

Options

Configuration for markdown syntax.

Fields

• singleDollarTextMath (boolean, default: true) controls whether inline math can open with a single dollar sign. Single dollars work in Pandoc and many other places, but often interfere with “normal” dollars in text.

HTML

Math (flow) does not relate directly to standard HTML elements. Instead, this package uses Temml, which generates MathML. The Temml result is wrapped in <div> (for flow, block) and <span> (for text, inline) elements, with two classes: math and either math-display or math-inline.

When turning markdown into HTML, each line ending in math (text) is turned into a space.

CSS

Temml output needs one of Temml’s CSS bundles to render correctly. Load the stylesheet that matches the font setup you want to use. For example:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/Temml-Latin-Modern.css">

Syntax

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.
mathText ::= sequenceText 1*byte sequenceText
mathFlow ::= fenceOpen *( eol *line ) [ eol fenceClose ]

; Restriction: not preceded or followed by the marker.
sequenceText ::= 1*"$"

fenceOpen ::= sequenceFlow 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.
fenceClose ::= sequenceFlow *spaceOrTab
sequenceFlow ::= 2*"$"
; Restriction: the marker cannot occur in `meta`
meta ::= 1*line

; Character groups for informational purposes.
byte ::= %x00-FFFF
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 one: $$a$ b$$.

Not everything between dollars is math. For example, a single dollar sign cannot open flow math:

$
a
$

The optional meta part of flow math is parsed as string content. That means character escapes and character references are allowed there, but the value is ignored by this package.

Types

This package is fully typed with TypeScript. It exports the additional types HtmlOptions and Options.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When a new major release is cut, support for unmaintained Node.js versions is dropped. This means we try to keep the current release line, micromark-extension-temml@^3, compatible with Node.js 16.

This package works with micromark version 3 and later.

Security

This package is safe assuming that you trust Temml. Any vulnerability in it could open you to a cross-site scripting (XSS) attack.

Related

• remark-math provides remark and rehype plugins for math.
• mdast-util-math provides mdast support for math.
• micromark-extension-math is the upstream KaTeX-based package this fork started from.

License

MIT © Titus Wormer