@streamdown/math

The @streamdown/math plugin renders mathematical expressions using KaTeX.

• Fast LaTeX rendering (2-3x faster than MathJax)
• Inline and block math support
• MathML output for accessibility
• Configurable error color and single-dollar syntax

Install

npm install @streamdown/math

Usage

import { math } from '@streamdown/math';
import 'katex/dist/katex.min.css';

<Streamdown plugins={{ math }}>
  {markdown}
</Streamdown>

Syntax

Streamdown uses double dollar signs ($$) to delimit mathematical expressions. Unlike traditional LaTeX, single dollar signs ($) are not used by default to avoid conflicts with currency symbols in regular text.

Inline Math

Wrap inline mathematical expressions with $$:

The quadratic formula is $$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$ for solving equations.

Renders as: The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ for solving equations.

Block Math

For display-style equations, place $$ delimiters on separate lines:

$$
E = mc^2
$$

This renders the equation centered and larger:

Common Mathematical Expressions

Fractions

$$\frac{numerator}{denominator}$$

Example: $\frac{1}{2}$, $\frac{a + b}{c - d}$

Square Roots

$$\sqrt{x}$$ or $$\sqrt[n]{x}$$

Example: $\sqrt{16} = 4$, $\sqrt[3]{27} = 3$

Exponents and Subscripts

$$x^2$$ or $$x_i$$ or $$x_i^2$$

Example: $a^2 + b^2 = c^2$, $x_1, x_2, \ldots, x_n$

Greek Letters

$$\alpha, \beta, \gamma, \delta, \theta, \pi, \sigma, \omega$$
$$\Gamma, \Delta, \Theta, \Pi, \Sigma, \Omega$$

Common letters: $\alpha, \beta, \gamma, \delta, \epsilon, \pi, \sigma, \phi, \omega$

Summations

$$\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$$

The sum of first $n$ natural numbers: $\sum_{i=1}^{n} i = \frac{n(n+1)}{2}$

Integrals

$$\int_{a}^{b} f(x) \, dx$$

Definite integral: $\int_{0}^{1} x^2 \, dx = \frac{1}{3}$

Limits

$$\lim_{x \to \infty} \frac{1}{x} = 0$$

Example: $\lim_{x \to 0} \frac{\sin x}{x} = 1$

Matrices

$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
$$

A 2×2 matrix:

Advanced Examples

The Quadratic Formula

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

Euler's Identity

$$
e^{i\pi} + 1 = 0
$$

Normal Distribution

$$
f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^2}
$$

The probability density function:

Taylor Series

$$
e^x = \sum_{n=0}^{\infty} \frac{x^n}{n!} = 1 + x + \frac{x^2}{2!} + \frac{x^3}{3!} + \cdots
$$

Integration by Parts

$$
\int u \, dv = uv - \int v \, du
$$

Special Operators and Symbols

Comparison Operators

$$\leq$$ $$\geq$$ $$\neq$$ $$\approx$$ $$\equiv$$

$x \leq y$, $a \geq b$, $x \neq 0$, $\pi \approx 3.14$, $a \equiv b \pmod{n}$

Set Notation

$$\in$$ $$\notin$$ $$\subset$$ $$\subseteq$$ $$\cup$$ $$\cap$$ $$\emptyset$$

$x \in A$, $y \notin B$, $A \subset B$, $A \cup B$, $A \cap B$, $\emptyset$

Logic Symbols

$$\land$$ $$\lor$$ $$\neg$$ $$\implies$$ $$\iff$$ $$\forall$$ $$\exists$$

$p \land q$, $p \lor q$, $\neg p$, $p \implies q$, $p \iff q$, $\forall x$, $\exists y$

Calculus Notation

$$\frac{dy}{dx}$$ $$\frac{\partial f}{\partial x}$$ $$\nabla$$ $$\infty$$

Derivative: $\frac{dy}{dx}$, Partial: $\frac{\partial f}{\partial x}$, Gradient: $\nabla f$, Infinity: $\infty$

Configuration

Custom Error Color

Customize how errors are displayed using createMathPlugin:

import { Streamdown } from 'streamdown';
import { createMathPlugin } from '@streamdown/math';
import 'katex/dist/katex.min.css';

const math = createMathPlugin({
  errorColor: '#dc2626',
});

export default function Page() {
  return (
    <Streamdown plugins={{ math }}>
      {markdown}
    </Streamdown>
  );
}

Complete Configuration Example

import { Streamdown } from 'streamdown';
import { createMathPlugin } from '@streamdown/math';
import 'katex/dist/katex.min.css';

const math = createMathPlugin({
  singleDollarTextMath: true, // Enable $...$ syntax (default: false)
  errorColor: '#dc2626',      // Custom error color (default: "var(--color-muted-foreground)")
});

export default function Page() {
  return (
    <Streamdown plugins={{ math }}>
      {markdown}
    </Streamdown>
  );
}

Get CSS Path

Use getStyles() to get the CSS path programmatically:

import { math } from '@streamdown/math';

const cssPath = math.getStyles?.();
// "katex/dist/katex.min.css"

Streaming Considerations

Incomplete Equations

Streamdown's unterminated block parser handles incomplete equations gracefully:

$$
E = mc^

During streaming, the parser detects the incomplete block-level equation and adds the closing $$ delimiter, ensuring proper rendering even before the equation is complete.

Inline vs Block Detection

The parser distinguishes between inline and block math:

• Inline: $E = mc^2$ (same line)
• Block: Separate lines with newlines

This is inline $$E = mc^2$$ math.

$$
E = mc^2
$$

This is block math.

Common Issues

Escaping Backslashes

In JavaScript/TypeScript strings, backslashes need to be escaped:

// ❌ Wrong
const markdown = "$\frac{1}{2}$";

// ✅ Correct
const markdown = "$$\\frac{1}{2}$$";

// ✅ Or use template literals
const markdown = `$$\frac{1}{2}$$`;

Currency vs Math

Streamdown uses $$ for math to avoid conflicts with currency:

This item costs $5 and that one costs $10. (These are currency symbols)

This equation $$x = 5$$ is mathematical notation. (This is math)

Spacing in Equations

Use \, for thin space, \: for medium space, \; for thick space:

$$\int f(x) \, dx$$

Better spacing: $\int f(x) \, dx$

Accessibility

Mathematical expressions rendered by KaTeX include:

• MathML - Machine-readable math representation
• Title Attributes - LaTeX source in tooltips
• Semantic HTML - Proper structure for screen readers
• Scalable Typography - Math scales with text size settings

Plugin Interface

The Math plugin implements the MathPlugin interface:

interface MathPlugin {
  name: "katex";
  type: "math";
  remarkPlugin: Pluggable;  // remark-math for parsing
  rehypePlugin: Pluggable;  // rehype-katex for rendering
  getStyles?: () => string; // Returns "katex/dist/katex.min.css"
}

Best Practices

Keep Equations Readable

Break complex equations into steps:

Start with the equation:

$$
f(x) = ax^2 + bx + c
$$

Complete the square:

$$
f(x) = a\left(x + \frac{b}{2a}\right)^2 + c - \frac{b^2}{4a}
$$

Add Context

Explain your equations:

The Pythagorean theorem states that for a right triangle:

$$
a^2 + b^2 = c^2
$$

where $$a$$ and $$b$$ are the legs and $$c$$ is the hypotenuse.

Use Block Math for Complex Expressions

Reserve inline math for simple expressions:

✅ Good: The slope is $$m = \frac{y_2 - y_1}{x_2 - x_1}$$

❌ Avoid: $$\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}$$ in the middle of text

✅ Better:

$$
\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
$$

Resources

• KaTeX Documentation - Complete list of supported functions
• KaTeX Support Table - Feature compatibility
• LaTeX Math Symbols - Symbol reference

Related Features

• Typography - Text styling that complements mathematical content
• Unterminated Block Parsing - How streaming works with equations
• GitHub Flavored Markdown - Extended Markdown features