@notatki/math

A formatter for LaTeX math source, with no dependencies. It works on one math expression at a time, without its $ or \[ delimiters, and rewrites it to follow a consistent style. It is used by notatki format for math in notes, and by mathfmt for .tex files.

The formatter is a lenient parser and a printer, not a TeX engine. It does not expand macros, and it only changes things that it knows TeX reads the same way: optional whitespace, braces around single-token arguments, and \left/\right around parentheses. Formatting is idempotent.

Usage

import { format } from "@notatki/math";

format("x=1,\\int_0^1f\\,dx", { spacing: "padded" });
// "x = 1, \\int_0^1 f\\,dx"

format(src, options?) returns the formatted source. If src cannot be parsed, it is returned unchanged.

Options

All options default to "unchanged", so format(src) returns src as it was written.

| Option | Values | Effect | | --------------- | -------------------------------- | ------------------------------------------------ | | parens | add, normalize, unchanged | \left and \right around parentheses | | braceCommands | add, remove, unchanged | braces around arguments of \frac, \sqrt, ... | | braceScripts | add, remove, unchanged | braces around arguments of ^ and _ | | spacing | compact, padded, unchanged | whitespace that TeX ignores in math |

The values are also exported as the PARENS, BRACES and SPACINGS arrays.

parens

• add wraps plain parentheses around tall content such as fractions, integrals and sums: (\frac12) becomes \left(\frac12\right).
• normalize also removes \left and \right where they are not needed: \left(x\right)+\left(x^2\right) becomes (x)+\left(x^2\right). It is conservative: they stay unless the content is only letters, digits, punctuation and plain commands. Explicit sizes such as \bigl are never touched.

braceCommands and braceScripts

• add: \frac12 becomes \frac{1}{2}, and x^2 becomes x^{2}.
• remove: \frac{1}{2} becomes \frac12. Braces are removed only where TeX reads the argument the same way without them, that is around a single letter, digit or control word. x^{10} and x^{-1} keep theirs, and a space is added where a control word would swallow the next letter.

spacing

• compact removes optional whitespace: 1 + 2 = 3, (a, b) becomes 1+2=3,(a,b).
• padded removes it, then puts one space after commas and around relations, binary operators (not + and -) and \quad, and after \int-like operators and named functions: x=1,\int_0^1f becomes x = 1, \int_0^1 f. Scripts stay compact, and a&=b becomes a &= b.

Whitespace that matters is always kept: between a control word and a letter (\alpha x), between digits, around line breaks, and inside \text-like arguments.

Lower-level API

format is print(rewrite(parse(src), options)). These pieces are exported too:

• tokenize(src) splits the source into tokens, and throws LatexParseError on malformed input.
• parse(src) builds a tree of the node types in nodes.ts. print(parse(src)) reproduces src exactly.
• rewrite(tree, options) applies the options to a tree.
• resolveOptions(options) validates the options and fills in the defaults.