npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

micromark-extension-math

v3.1.0

Published

micromark extension to support math (`$C_L$`)

Downloads

1,926,221

Readme

micromark-extension-math

Build Coverage Downloads Size Sponsors Backers Chat

micromark extensions to support math ($C_L$).

Contents

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

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.

Install

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

npm:

npm install micromark-extension-math

In Deno with esm.sh:

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

In browsers with esm.sh:

<script type="module">
  import {math, mathHtml} from 'https://esm.sh/micromark-extension-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 {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>) can be determined by Lift Coefficient (<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></span></div>

API

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.

Parameters
  • options (Options, default: {}) — configuration
Returns

Extension 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.

Parameters
Returns

Extension for micromark that can be passed in htmlExtensions, to support math when serializing to HTML (HtmlExtension).

HtmlOptions

Configuration for HTML output (optional).

👉 Note: passed to katex.renderToString. displayMode is overwritten by this plugin, to false for math in text (inline), and true for math in flow (block).

Type
type Options = Omit<import('katex').KatexOptions, 'displayMode'>

Options

Configuration (TypeScript type).

Fields
  • singleDollarTextMath (boolean, default: true) — whether to support math (text, inline) 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 use two or more dollars for text math.

Authoring

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.

HTML

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> (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

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/[email protected]/dist/katex.min.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.
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.

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 we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, micromark-extension-math@^3, compatible with Node.js 16.

This package works with micromark version 3 and later.

Security

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

Related

Contribute

See 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.

License

MIT © Titus Wormer