or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-remark-math

remark plugin to parse and stringify math expressions using LaTeX-style syntax with dollar delimiters

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/remark-math@6.0.x

To install, run

npx @tessl/cli install tessl/npm-remark-math@6.0.0

index.mddocs/

remark-math

remark-math is a unified remark plugin that extends markdown parsing and serialization to support mathematical expressions using LaTeX-style syntax with dollar delimiters ($..$ for inline and $$...$$ for block math). It integrates seamlessly with the unified ecosystem, particularly remark-rehype for HTML transformation, converting math nodes into properly structured HTML elements with appropriate CSS classes for downstream rendering by KaTeX, MathJax, or other math rendering engines.

Package Information

  • Package Name: remark-math
  • Package Type: npm
  • Language: JavaScript (ES Module)
  • Installation: npm install remark-math

Core Imports

import remarkMath from 'remark-math';

For TypeScript projects:

import remarkMath from 'remark-math';
// Note: Options type is available via JSDoc but not as named export

For CommonJS environments (though package is ES Module only):

const remarkMath = require('remark-math').default;

Basic Usage

import rehypeKatex from 'rehype-katex';
import rehypeStringify from 'rehype-stringify';
import remarkMath from 'remark-math';
import remarkParse from 'remark-parse';
import remarkRehype from 'remark-rehype';
import {unified} from 'unified';

const processor = unified()
  .use(remarkParse)
  .use(remarkMath)
  .use(remarkRehype)
  .use(rehypeKatex)
  .use(rehypeStringify);

const markdown = `
Lift ($C_L$) can be determined by the following equation:

$$
L = \\frac{1}{2} \\rho v^2 S C_L
$$
`;

const result = await processor.process(markdown);
console.log(String(result));

Architecture

remark-math follows the unified plugin architecture:

  • Micromark Extension: Uses micromark-extension-math for low-level parsing
  • MDAST Utilities: Uses mdast-util-math for AST transformation
  • Node Types: Creates inlineMath and math nodes in the MDAST syntax tree
  • HTML Integration: Adds hast properties for remark-rehype conversion to HTML
  • Lazy Evaluation: Math expressions are parsed but not rendered until HTML conversion

Capabilities

Math Plugin Function

The main plugin function that adds math support to unified processors.

/**
 * Add support for math expressions in markdown
 * @param {Options | null | undefined} [options] - Configuration options
 * @returns {undefined} - Returns nothing, modifies processor in place
 */
function remarkMath(options?: Options): undefined;

Usage Example:

import remarkMath from 'remark-math';
import {unified} from 'unified';
import remarkParse from 'remark-parse';

const processor = unified()
  .use(remarkParse)
  .use(remarkMath, { singleDollarTextMath: false });

Configuration Options

interface Options {
  /**
   * Whether to support text math (inline) with a single dollar
   * Single dollars work in Pandoc but often interfere with normal dollars in text
   * @default true
   */
  singleDollarTextMath?: boolean;
}

Configuration Examples:

// Default behavior - single dollar inline math enabled
.use(remarkMath)

// Disable single dollar inline math (only $$ works for inline)
.use(remarkMath, { singleDollarTextMath: false })

Syntax Support

Inline Math

  • Single Dollar: $expression$ (configurable, enabled by default)
  • Double Dollar: $$expression$$ (always supported)
The formula $E = mc^2$ shows mass-energy equivalence.

Block Math

  • Fenced Format: $$\nexpression\n$$ (on separate lines)
  • Indented Support: Up to 3 spaces of indentation allowed
$$
\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}
$$

Escape Sequences

  • Escaped Dollars: \\$ prevents math parsing
  • Within Code: Dollar signs inside code blocks are ignored
The price is \\$5.99 (not math)
`$variable` in code (not math)

HTML Output

When used with remark-rehype, math nodes are converted to HTML with semantic CSS classes:

Inline Math HTML

<code class="language-math math-inline">E = mc^2</code>

Block Math HTML

<pre><code class="language-math math-display">\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}</code></pre>

These HTML structures are designed to work with:

  • KaTeX: For client-side math rendering
  • MathJax: For server-side or client-side rendering
  • Custom renderers: Any system that processes .language-math classes

Error Handling

remark-math handles malformed math gracefully:

  • Unclosed delimiters: Treated as regular text
  • Empty expressions: $$ with no content ignored
  • Nested delimiters: Inner delimiters escaped automatically
  • Invalid LaTeX: Passed through to renderer (KaTeX/MathJax handles errors)

Syntax Tree Nodes

The plugin creates two new MDAST node types:

InlineMath Node

interface InlineMath {
  type: 'inlineMath';
  value: string;
  data?: {
    hName: 'code';
    hProperties: {
      className: ['language-math', 'math-inline'];
    };
    hChildren: Array<{ type: 'text'; value: string }>;
  };
}

Math Node (Block)

interface Math {
  type: 'math';
  value: string;
  meta: null;
  data?: {
    hName: 'pre';
    hChildren: Array<{
      type: 'element';
      tagName: 'code';
      properties: {
        className: ['language-math', 'math-display'];
      };
      children: Array<{ type: 'text'; value: string }>;
    }>;
  };
}