remark-math

remark-math is a plugin for the unified/remark ecosystem that teaches markdown to understand math. It parses inline math wrapped in single dollar signs and block equations wrapped in double dollars, adding the syntax extension and the mdast nodes needed to carry LaTeX through the processing pipeline.

Because it only annotates the syntax tree, remark-math pairs cleanly with a rendering plugin such as rehype-katex or rehype-mathjax, which turn the parsed math into HTML at compile time. This keeps client bundles free of runtime math libraries and makes it a natural fit for static sites, documentation, and scientific writing.

What You Get

• A remark plugin that parses inline ($...$) and block ($$...$$) math in markdown
• mdast inlineMath and math nodes that flow through the unified pipeline
• Seamless pairing with rehype-katex and rehype-mathjax for compile-time HTML rendering
• Configurable options (such as singleDollarTextMath) passed through to the underlying math extension
• Full TypeScript type definitions shipped via JSDoc and generated .d.ts files

Common Use Cases

• Rendering LaTeX equations in documentation sites built on Astro, Next.js, or Gatsby
• Adding math support to markdown-driven blogs and scientific writing
• Producing static HTML math with no client-side JavaScript by rendering at build time
• Feeding parsed math nodes into custom remark/rehype transforms

Under The Hood

Architecture - remark-math is a thin, delegation-first plugin. The published entry index.js simply re-exports lib/index.js, whose default remarkMath(options) function attaches three extension arrays to the unified processor’s shared data(): micromarkExtensions, fromMarkdownExtensions, and toMarkdownExtensions. It pushes math() from micromark-extension-math for tokenizing, and mathFromMarkdown()/mathToMarkdown() from mdast-util-math for building and serializing the math and inlineMath mdast nodes. All real parsing lives in those sibling packages, so remark-math itself is essentially wiring.

Tech Stack - The package is pure ES-module JavaScript (type: module, single exports entry) targeting unified 11. Its runtime dependencies are mdast-util-math, micromark-extension-math, unified, and @types/mdast. Types are authored as JSDoc annotations and emitted to .d.ts; tooling is xo plus prettier, and it declares sideEffects: false for tree-shaking.

Code Quality - Quality is high for its size. The core lib/index.js is a few dozen well-commented lines with careful null-handling of the options object and defensive initialization of the extension arrays. The package ships a substantial test.js (~24KB) exercising parsing and stringifying across inline and block cases, and every export is fully typed. Naming follows unified conventions consistently.

API Design - The developer experience is idiomatic unified: a single default-exported plugin registered with .use(remarkMath, options) and one optional configuration object. There is no boilerplate beyond composing it into a processor alongside a rehype renderer, and the readme documents installation, usage, options, syntax, security, and related plugins thoroughly, making it approachable for anyone already using remark.