@mdast2docx/math

@m2d/math

@m2d/math: LaTeX Math to Word DOCX plugin for @m2d/core. Transforms inline and block math into native editable Word OpenXML equations.

---

Features

• Native Word Equations: Converts LaTeX math into native docx.Math structures (MathRun, MathFraction, MathRadical, MathSuperScript, MathSubScript) — completely editable in Microsoft Word with crisp vector rendering.
• Rich Mathematical Macros: Comprehensive support for fractions (\frac), roots (\sqrt), superscripts (^), subscripts (_), summations (\sum), integrals (\int), products (\prod), Greek letters, and standard mathematical relations.
• Delimiter Boundary Guards: Protects against runaway parsing caused by unescaped currency symbols or unclosed delimiters by checking for structural markdown markers.
• Flexible Error Modes: Choose between styled inline/block warning badges (warn), raw monospace code fallbacks (raw), or strict pipeline errors (throw).
• Lightweight & Fast: Zero browser or heavy rendering engine overhead — converts LaTeX AST to Word OpenXML in pure TypeScript.

---

Installation

This package (@mdast2docx/math) is an official alias of @m2d/math.

Why does this exist?

We provide this package to offer shorter import paths and improved discoverability. While both packages provide identical functionality, @m2d/math is the primary source of truth.

Which one should I use?

• Use @mdast2docx/math if you prefer the shorter name or specific branding or ESM Only.
• Use @m2d/math for the most stable long-term reference and standard alignment.

Feature	@m2d/math	@mdast2docx/math
Source Code	Primary	Proxy
Updates	Immediate	Synchronized (Immediately)
Bundle Size	100%	100% (Zero overhead)
Format	ESM + CJS	ESM Only
Maintenance	Primary	Proxy (inherits)
Security	Primary	Proxy (inherits)

Maintenance & Support

Security: Security audits are performed on the canonical package; this alias inherits all security patches automatically.

---

$ pnpm add @m2d/math remark-math @m2d/core docx

or

$ npm install @m2d/math remark-math @m2d/core docx

or

$ yarn add @m2d/math remark-math @m2d/core docx

---

Quick Start

import { toDocx } from "@m2d/core";
import { mathPlugin } from "@m2d/math";
import remarkMath from "remark-math";
import remarkParse from "remark-parse";
import { unified } from "unified";

const markdown = `
# Physics Notes

Einstein's mass-energy equivalence is expressed as $E = mc^2$.

A quadratic formula:

$
x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}
$
`;

// 1. Parse markdown with remark-math to generate math AST nodes
const mdast = unified().use(remarkParse).use(remarkMath).parse(markdown);

// 2. Convert to DOCX with the math plugin
const docxBlob = await toDocx(mdast, {}, {
  plugins: [mathPlugin()],
});

---

Plugin Options

export interface IMathPluginOptions {
  /**
   * Error handling strategy when LaTeX parsing fails or runaway syntax is detected.
   * - "warn": Emits a styled warning text badge: `⚠️ [Math Syntax Error: ...]`
   * - "raw": Emits the raw formula string as monospace code text
   * - "throw": Re-throws the underlying parse error
   * @default "warn"
   */
  errorMode?: "warn" | "raw" | "throw";

  /**
   * Maximum character length allowed for inline equations.
   * Prevents runaway AST nodes when unclosed dollar signs occur.
   * @default 1000
   */
  maxInlineLength?: number;
}

---

Deep Dive Guides

• LaTeX Syntax & Symbols Guide: Detailed documentation of supported operators, fractions, radicals, and Greek symbols.
• Resiliency & Error Modes Guide: Error handling strategies, delimiter boundary protection, and runaway length guards.

---

License

This library is licensed under the MIT open-source license.

---

with by Mayank Kumar Chaudhari