micromark-extension-math

micromark-extension-math adds math syntax to the micromark Markdown parser, letting authors write inline math with single or double dollar signs ($C_L$) and block math with fenced double-dollar delimiters ($$ ... $$). It ships two independent extensions: one that teaches micromark’s tokenizer to recognize the math constructs, and a separate HTML-compiler extension that renders the parsed math to <span>/<div> elements using KaTeX.

Because it plugs directly into micromark’s low-level construct system rather than post-processing rendered HTML, it produces spec-consistent parsing that respects escaping, fence-length matching, and CommonMark’s flow/text boundaries. It is a foundational building block for the unified/remark ecosystem’s remark-math plugin and for any project that wants first-class math support without leaving the Markdown pipeline.

What You Get

• An inline math tokenizer supporting one, two, or more dollar-sign delimiters, matching CommonMark’s fenced-code escaping rules
• A block (flow) math tokenizer for $$ ... $$ fences with optional meta strings, mirroring how fenced code blocks are parsed
• A separate HTML-compiler extension (mathHtml) that renders parsed math to <span class="math math-inline">/<div class="math math-display"> using KaTeX
• A singleDollarTextMath option to disable single-dollar inline math when it conflicts with literal dollar signs in prose
• Full TypeScript types for both extensions with 100% enforced type coverage

Common Use Cases

• Adding LaTeX-style math notation to a static site or docs generator built on remark/unified
• Extending a custom Markdown-to-HTML pipeline with scientific or mathematical notation support
• Building a Markdown editor or CMS that needs live math rendering without leaving the Markdown syntax
• Composing with mdast-util-math to get a math syntax tree for custom (non-KaTeX) renderers

Under The Hood

Architecture The package’s entry point (index.js) re-exports math from lib/syntax.js and mathHtml from lib/html.js, keeping parsing and rendering as two independently pluggable layers, matching micromark’s own separation between extensions (tokenizers) and htmlExtensions (compiler hooks). syntax.js is a thin dispatcher that wires the dollar-sign character code to two constructs: mathFlow (block) in math-flow.js and mathText (inline) in math-text.js. math-flow.js implements a full state-machine tokenizer for fenced math blocks — opening/closing sequence matching, optional meta strings, indentation handling, and non-lazy-continuation checks — deliberately mirroring how micromark’s built-in fenced code blocks are tokenized. math-text.js implements the inline construct with its own resolveMathText resolver that trims padding and merges adjacent data tokens after the fact, the same post-processing pattern micromark uses for inline code. html.js is a standalone compiler extension using enter/exit callbacks and an internal buffer to collect raw math content before handing it to katex.renderToString. If micromark’s core flow/text dispatch mechanism changed, this package’s tokenizers would need updates in lockstep; conversely, the HTML extension could be swapped out entirely (as mdast-util-math does) without touching the syntax layer. Tech Stack The package is plain, dependency-light JavaScript authored as ESM-only (type: module) with types supplied entirely through JSDoc comments and enforced via tsc --build plus the type-coverage tool (configured for 100% strict coverage). Its only runtime dependencies are other micromark utility packages (micromark-factory-space, micromark-util-character, micromark-util-symbol, micromark-util-types), devlop for dev-only assertions that are stripped in production builds, and katex for HTML rendering. The build step uses micromark-build to produce the published lib//index.js output from the dev/ sources, and formatting/linting runs through remark-cli with remark-preset-wooorm, prettier, and xo. Code Quality Tests live in test/index.js using Node’s built-in node:test and assert/strict, covering default multi-dollar behavior, the singleDollarTextMath option, escaped-dollar handling, and the disable.null extension-disabling mechanism — run against both production and development export conditions and measured with c8 --100, meaning the test suite is contractually required to hit full statement coverage. Error handling favors devlop’s dev-only assert calls (stripped from production bundles) over runtime exceptions, keeping the shipped bundle minimal. Naming is consistent and every function carries JSDoc type annotations that double as the package’s type system. What Makes It Unique Rather than post-processing rendered Markdown HTML with a regex, this package authors math support at micromark’s lowest tokenizer level, reusing the same sequence-matching and escaping semantics CommonMark defines for fenced code — giving byte-accurate parsing of nested dollar signs, fence-length equivalence, and escape handling that regex-based math plugins typically get wrong. Splitting syntax detection from HTML rendering also lets the wider unified ecosystem (via mdast-util-math) swap KaTeX for another math renderer entirely.