@falcon0387/textlint-rule-math-helper

Collect and locate math regions in text for textlint rules.

Supported delimiters: $...$ $$...$$ \(...\) \[...\] \begin{...}...\end{...} (environments)

| Syntax | Backend | Notes | |--------|---------|-------| | "markdown" (default) | micromark + parse5 | Skips $100-style currency patterns. Excludes code spans, code blocks, link destinations/titles, raw HTML markup, and <code>/<pre>/<script>/<style> contents. | | "latex" | latex-utensils (peer dep) | Parses entire input. Returns [] on syntax errors. |

Install

bun add @falcon0387/textlint-rule-math-helper

# For LaTeX syntax
bun add latex-utensils

Usage

import {
  collectMathRegions,
  includesMathAt,
  redactMathRegions,
} from "@falcon0387/textlint-rule-math-helper";

const regions = collectMathRegions("Text $x+1$ more");
// => [{ start: 5, end: 10, contentStart: 6, contentEnd: 9, source: "$x+1$", kind: "inline", delimiter: "$" }]

const content = "Text $x+1$ more".slice(regions[0].contentStart, regions[0].contentEnd);
// => "x+1"

redactMathRegions("Text $x+1$ more", regions);
// => "Text xxxxx more"

includesMathAt(regions, 6);
// => true

// LaTeX syntax
collectMathRegions("text \\(x+1\\) more", { syntax: "latex" });

API

collectMathRegions(text, options?): readonly MathRegion[]

Returns all math regions sorted by start offset.

| Option | Type | Default | Description | |--------|------|---------|-------------| | syntax | "markdown" \| "latex" | "markdown" | Syntax mode | | markdown.excludedHtmlElementNames | readonly string[] | ["code", "pre", "script", "style"] | HTML elements whose contents are excluded from math detection |

shiftMathRegions(regions, offset): readonly MathRegion[]

Returns new regions with start/end/contentStart/contentEnd shifted by offset.

redactMathRegions(text, regions, replacement?): string

Replaces each math region with replacement (default "x"), preserving string length.

includesMathAt(regions, offset): boolean

Returns whether offset falls inside any region (binary search; requires sorted regions).

MathRegion

interface MathRegion {
  readonly start: number;                       // inclusive, includes delimiters
  readonly end: number;                         // exclusive, includes delimiters
  readonly contentStart: number;                // inclusive, excludes opening delimiter
  readonly contentEnd: number;                  // exclusive, excludes closing delimiter
  readonly source: string;                      // raw text including delimiters
  readonly kind: "inline" | "display";          // math mode
  readonly delimiter: "$" | "$$" | "\\(" | "\\[" | "\\begin";
  readonly environmentName: string | undefined; // e.g. "equation", "align*"
}

Supported LaTeX environments

Both syntaxes detect \begin{...}...\end{...} for these environments:

| Category | Environments | |----------|-------------| | Top-level | equation equation* align align* gather gather* multline multline* flalign flalign* alignat alignat* math displaymath eqnarray eqnarray* | | Inner | aligned alignedat cases cases* gathered split | | Matrix | matrix matrix* bmatrix bmatrix* pmatrix pmatrix* vmatrix vmatrix* Bmatrix Bmatrix* Vmatrix Vmatrix* smallmatrix | | Array | array |

Release

Automated via release-please. Merge the auto-generated Release PR to bump version, update CHANGELOG.md, and create a tag.