Resiliency & Error Modes

Mathematical expressions generated by Large Language Models or authored by users frequently contain unclosed delimiters, unescaped currency signs, or invalid LaTeX macros. @m2d/math provides multi-layered defenses to guarantee document generation never crashes unexpectedly.

Error Handling Strategies (errorMode)Copy Anchor Link

The errorMode option controls how @m2d/math reacts when equation parsing fails or delimiter boundaries are violated:

import { mathPlugin } from "@m2d/math";

// Configure error handling mode
const plugin = mathPlugin({
  errorMode: "warn", // "warn" (default) | "raw" | "throw"
});

1. errorMode: "warn" (Default)Copy Anchor Link

Emits a visually styled, non-breaking warning in the generated document:

• Inline: A crimson italicized badge: ⚠️ [Math Error: <message>]
• Block: A crimson italicized warning paragraph: ⚠️ [Math Syntax Error: <message>]

This allows human reviewers or editors to instantly spot flawed equations in the output DOCX without halting document generation.

2. errorMode: "raw"Copy Anchor Link

Emits the original raw LaTeX string as monospace code text using the Consolas font:

• Inline: Renders $formula$ inline.
• Block: Renders the block content as a clean paragraph in Consolas.

This mode is ideal for documentation pipelines where preserving raw text readability is preferred over warning badges.

3. errorMode: "throw"Copy Anchor Link

Immediately throws a JavaScript Error. This mode is recommended for automated build pipelines, test suites, or strict validation workflows where document compilation must halt on any equation defect.

Delimiter Boundary GuardsCopy Anchor Link

A notorious edge case in Markdown processing occurs when a document contains unescaped currency signs (for example, "Budget is $50 in Q1 and $100 in Q2") or an unclosed $$ block delimiter. Standard Markdown math parsers can greedily consume subsequent content across sections, absorbing tables, headings, and lists into a single broken math node.

@m2d/math inspects equation payloads for structural Markdown block markers:

• Headings (\n# , \n## , etc.)
• Horizontal rules (\n---, \n***)
• Markdown tables (\n|)
• Blockquotes (\n>)
• Bulleted and numbered lists (\n- , \n1. )

When these structural markers are detected inside an equation string, @m2d/math flags an unclosed equation delimiter error:

Unclosed equation delimiter: content contains structural markdown block markers

Depending on errorMode, it either warns, renders raw text, or throws, preventing subsequent document sections from being swallowed.

Inline Length Safeguards (maxInlineLength)Copy Anchor Link

Inline equations are typically short expressions. When an opening dollar sign ($) is not properly closed, remark-math may capture hundreds or thousands of characters across paragraphs.

The maxInlineLength option (default: 1000 characters) sets a strict threshold:

const plugin = mathPlugin({
  maxInlineLength: 500, // Maximum allowed characters for inline formulas
});

If an inline formula exceeds this character limit, @m2d/math flags it as runaway syntax.