MathFmt

A tiny ASCIIMath renderer. Outputs directly to MathML, as the majority of browsers support it to varying degrees.

• Fast! Runs around 4-6x faster than ASCIIMathML (the main project) and around 20x faster than MathJax.
• Tiny! The full library is around 15 KiB minimized, and has no external runtime dependencies.
• Supports the entire ASCIIMath syntax, along with some extensions and bugfixes.
• Compatible with server-side rendering: Unlike the official repo, we assemble HTML strings directly instead of leaning on browser-only HTML entity objects. This means that this library can be trivially embedded in contexts (such as Vue components) that might be called either in a browser, or in a Node.js server.

Usage

The library is available from NPM:

npm install mathfmt

Pre-built libraries are also available from the releases page.

This library provides an intoMathML function, that parses ASCIIMath, and produces a MathML string.

// CommonJS
const { intoMathML } = require("mathfmt");

// ES Modules
import { intoMathML } from "mathfmt";

const result = intoMathML("sum_{i=0}^oo");

The intoMathML function also accepts a second option argument with these attributes:

| Option | Default | Description | | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | -- | An id string, that will be attached to the root <math> element in the result. | | class | -- | A class name, that will be attached to the root <math> element in the result. | | style | -- | A CSS style string, that will be attached to the root <math> element in the result. This value will be HTML-escaped, but then placed verbatim in the output. If any of the CSS values themselves are from untrusted sources, be sure to escape them. | | inline | false | Set this to true if the resulting MathML is expected to be inlined with normal text. In that case, the MathML renderer will attempt to draw certain figures in a more vertically-compact manner. The default is false, to draw figures in a taller (and more visually appealing) manner. |

Example:

intoMathML("x = (-b +- sqrt(b^2-4ac)) / (2a)", {
  id: "fig-123",
  class: "math-formula",
  inline: false,
});
// => '<math id="fig-123" class="math-formula" display="block"><mi>x</mi><mo>=</mo> ...'

ASCIIMath Syntax

ASCIIMath is a simple format: it is parsed left to right without any real operator precedence. It will simply look for 'symbols', which are short strings with special significance. (For example, typing 'beta' will put a 'β' symbol in the output.) If a symbol can't be found at the current place in the source text, the current character is treated as as simple single-character identifier, and we move on.

A few characters have special significance:

• _ will add a subscript. (eg:beta_0 will output )
• ^ will add a superscript. (eg: x^3 will output )
• / will add a fraction. (eg: a/b will output )

Most of the language will simply work like that - running from left-to-right, assembling a Math string from the symbols encountered. If you want to group some of those symbols together (eg: you want alpha to the power of x + 1) you can use parentheses / braces to group symbols. For example, alpha^(x + 1) will result in: . ASCIIMath supports a wide range of brace types - you can read more about those below.

Some symbols come with special formatting rules. For example, sqrt is a 'unary' symbol, which will draw a square-root bar around the symbol / parenthesized group that follows it. For example: sqrt (x^2 + y^2) results in: There are a large number of unaries available, described below. There are also a few 'binary' symbols, which apply some effect to the next TWO symbols / groups. Those are also described below.

Literal strings and numbers can also be included. Strings (aka: text blocks) are surrounded by double quote characters, like: "text here". If you want double quotes within that string, put two double quotes in a row: "". Literal numbers can be included as well, and will look like: 123 or 12.34.

All of these rules can be combined together to create complex formulas:

Symbols

Greek Letters

Most greek letters can be simply referenced by name. A few extra mathematically significant variations of these symbols are also available.

| Upper Case | Lower case | Variant | | ----------------------------------------- | ----------------------------------------- | -------------------------- | | Α: Alpha | α: alpha | | Β: Beta | β: beta | | Γ: Gamma | γ: gamma | | Δ: Delta | δ: delta | | Ε: Epsilon | ε: epsilon epsi | ɛ: varepsilon | | Ζ: Zeta | ζ: zeta | | Η: Eta | η: eta | | Θ: Theta | θ: theta | ϑ: vartheta | | Ι: Iota | ι: iota | | Κ: Kappa | κ: kappa | | Λ: Lambda Lamda | λ: lambda lamda | | Μ: Mu | μ: mu | | Ν: Nu | ν: nu | | Ξ: Xi | ξ: xi | | Ο: Omicron | ο: omicron | | Π: Pi | π: pi | ϖ: varpi | | Ρ: Rho | ρ: rho | ϱ: varrho | | Σ: Sigma | σ: sigma | ς: varsigma | | Τ: Tau | τ: tau | | Υ: Upsilon | υ: upsilon | | Φ: Phi | ϕ: phi | φ: varphi | | Χ: Chi | χ: chi | | Ψ: Psi | ψ: psi | | Ω: Omega | ω: omega |

Other Math Identifiers

| Symbols | Output | | ------------------------------------- | ------ | | CC | ℂ | | hbar | ℏ | | NN | ℕ | | QQ | ℚ | | RR | ℝ | | ZZ | ℤ | | aleph | ℵ | | O/ emptyset | ∅ | | oo infty | ∞ |

Standard Functions and Other Identifiers

ASCIIMath knows about a number of basic identifiers and functions, and will describe these symbols to MathML in a way that is appropriate. For example, identifiers like 'dx' will be presented to MathML as a single identifier, while functions like 'sin' or 'tan' will be rendered as operators, and will have some special spacing + grouping rules applied with their arguments.

Identifiers

dt dx dy dz

Standard Functions

arccos Arccos arccot arccsc arcsec arcsin Arcsin arctan Arctan cos Cos cosh Cosh cot Cot coth csc Csc csch det dim exp gcd glb ker lcm ln Ln log Log lub mod sec Sec sech sin Sin sinh Sinh tan Tan tanh Tanh

Basic Op symbols

A large number of basic op symbols are available.

| Symbols | Output | | ------------------------------------------------------------------------------------- | ------ | | + | + | | , | , | | - | - | | / | / | | :∣: | ∣ | | < lt | < | | = | = | | > gt | > | | ^ | ^ | | _ | _ | | and | and | | if | if | | or | or | | neg not | ¬ | | +- pm | ± | | xx times | × | | -: div divide | ÷ | | dag dagger | † | | ddag ddagger | ‡ | | ... ldots | … | | ' prime | ′ | | <- larr leftarrow | ← | | uarr uparrow | ↑ | | -> to rarr rightarrow | → | | darr downarrow | ↓ | | <-> harr leftrightarrow | ↔ | | ->> twoheadrightarrow | ↠ | | >-> rightarrowtail | ↣ | | ∣-> mapsto | ↦ | | rightleftharpoons | ⇌ | | lArr Leftarrow | ⇐ | | rArr implies Rightarrow | ⇒ | | dArr Downarrow | ⇓ | | <=> iff hArr Leftrightarrow | ⇔ | | AA forall | ∀ | | del partial | ∂ | | EE exists | ∃ | | grad nabla | ∇ | | in | ∈ | | !in notin | ∉ | | // | ∕ | | \\ setminus backslash | ∖ | | ** ast | ∗ | | @ circ | ∘ | | prop propto | ∝ | | /_ angle | ∠ | | ^^ wedge | ∧ | | vv vee | ∨ | | nn cap | ∩ | | uu cup | ∪ | | :. therefore | ∴ | | :' because | ∵ | | ~ sim | ∼ | | ~= cong | ≅ | | ~~ approx | ≈ | | != ne | ≠ | | -= equiv | ≡ | | !-= notequiv | ≢ | | <= le | ≤ | | >= ge | ≥ | | ll mlt | ≪ | | gg mgt | ≫ | | -< prec | ≺ | | >- succ | ≻ | | sub subset | ⊂ | | sup supset | ⊃ | | !sub notsubset | ⊄ | | !sup notsupset | ⊅ | | sube subseteq | ⊆ | | supe supseteq | ⊇ | | !sube notsubseteq | ⊈ | | !supe notsupseteq | ⊉ | | o+ oplus | ⊕ | | o- ominus | ⊖ | | ox otimes | ⊗ | | o. odot | ⊙ | | ∣-- vdash | ⊢ | | TT top | ⊤ | | ∣ bot | ⊥ | | ∣== models | ⊨ | | diamond | ⋄ | | * cdot | ⋅ | | *** star | ⋆ | | ∣><∣ bowtie | ⋈ | | ∣>< ltimes | ⋉ | | ><∣ rtimes | ⋊ | | vdots | ⋮ | | cdots | ⋯ | | ddots | ⋱ | | ∣~ lceiling | ⌈ | | ~∣ rceiling | ⌉ | | ∣__ lfloor | ⌊ | | __∣ rfloor | ⌋ | | frown | ⌢ | | square | □ | | /_\ triangle | △ | | >->> twoheadrightarrowtail | ⤖ | | -<= preceq | ⪯ | | >-= succeq | ⪰ |

Parenthesis and Other Braces

A number of different braces are supported, and can be (with one exception) freely mix-and-matched, just so long as left braces are paired with right braces.

The brace symbols are usually visible, but can sometimes be made invisible due to certain features of the formula's structure. For example:

If you want to keep those braces in the output, add another set of braces around each section - the outside ones will be hidden, the inside ones will be shown.

If you WANT the braces to be hidden in a situation where they'd normally be shown, use the {: and :} braces - they'll be invisible in the output.

| Left Brace Symbols | Right Brace Symbols | Output | | --------------------------------------------------------- | --------------------------------------------------------- | --------------- | | ( left( | ) right) | ( ... ) | | [ left[ | ] right] | [ ... ] | | { | } | { ... } | | (: << langle | :) >> rangle | ⟨ ... ⟩ | | ∣: | :∣ | ∣ ... ∣ | | {: | :} | ... |

Additionally, | braces without the : bits are also supported, but hey differ from the other braces, and they cannot be mix-and-matched with other braces. They MUST be paired with another | brace.

| Left Brace Symbols | Right Brace Symbols | Output | | ------------------ | ------------------- | --------------- | | ∣ | ∣ | ∣ ... ∣ |

"Stacked" Operator Symbols

A stacked symbol will render the superscript and subscripts above and below the operator, which looks pretty neat.

| Symbols | Example | Output | | -------------------------------------- | ---------------------------- | ------------------------------------------ | | lim | lim_{x->oo} | | | Lim | Lim_{x->oo} | | | max | max_x | | | min | min_x | | | prod | prod_{i=0}^n | | | sum | sum_{i=0}^n | | | ^^^ bigwedge | ^^^_{i=0}^n | | | vvv bigvee | vvv_{i=0}^n | | | nnn bigcap | nnn_{i=0}^n | | | uuu bigcup | uuu_{i=0}^n | |

"Stretchy" Operator Symbols

A few other symbols are "stretchy" - in that, they'll stretch to match the height of the formula next to it.

| Symbols | Example | Output | | ----------------- | -------------------- | ---------------------------------- | | int | int_0^n | | | oint | oint_C | |

Unary Symbols

A unary is a symbol that will apply some sort of effect to the symbol / term immediately after it, which is called the 'argument'.

| Unary Symbols | Example | Output | | ------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------- | | abs Abs | abs x | | | bar overline | bar x | | | cancel | cancel x | | | ceil | ceil x | | | ddot | ddot x | | | dot | dot x | | | floor | floor x | | | hat | hat x | | | norm | norm x | | | obrace overbrace | obrace (m*x + b)^"linear" | | | overarc overparen | overarc x | | | sqrt | sqrt x | | | mbox text | text(Hello "World") | | | tilde | tilde x | | | ubrace underbrace | ubrace (x^2 - 2x + 1)_"quadratic" | | | ul underline | ul x | | | vec | vec x | |

Note: cancel depends on the non-standard <menclose> tag. Support between browsers varies.

Binary Symbols

A binary is a symbol that will apply some sort of special layout action using the next two symbols / terms after it, which are called the 'arguments'. Which effect is applied varies based on the symbol:

| Binary Symbols | Example | Output | | ------------------------------------------ | --------------------------------------- | ------------------------------------------ | | color | color(red)(M = E-e*sin E) | | | frac | frac(d vec L) dt | | | overset stackrel | overset x y | | | root | root 3 x | | | underset | underset x y | |

A few additional notes:

• For color, textual color names, #rgb, #rrggbb and #rrggbbaa strings are all supported.
• For root, Chrome-based browsers render these VERY poorly when the enclosed segment is more than 1 line tall. Firefox gets it right, however.

There are also two special HTML-oriented binary symbols available: id and class, which allows you to set the id / class name of a particular element in the formula.

| Binary HTML Symbols | Example | Description | | ------------------- | -------------------------- | ------------------------------------------------------------------------- | | id | id (special-id) (x^2) | Will set the id of the HTML entity that contains 'x^2' to 'special-id' | | class | class (class-name) (x^2) | Will set the class of the HTML entity that contains 'x^2' to 'class-name' |

Unicode Lettering Styles

A number of different lettering styles can be applied to strings or terms using the special "font" unary symbols.

These styles are applied by transforming the characters in the argument into the 'Mathematical Alphanumeric Symbols' Unicode block. All styles support the latin upper/lowercase letters. Some might additionally support numbers, or the greek alphabet - it's all up to what is defined within that Unicode block.

| Letter Style Symbols | Example | | --------------------------------------- | ------------------------------------- | | bb mathbf | 𝐓𝐡𝐞 𝐅𝐢𝐯𝐞 𝐁𝐨𝐱𝐢𝐧𝐠 𝐖𝐢𝐳𝐚𝐫𝐝𝐬 𝐉𝐮𝐦𝐩 𝐐𝐮𝐢𝐜𝐤𝐥𝐲. | | bbb mathbb | 𝕋𝕙𝕖 𝔽𝕚𝕧𝕖 𝔹𝕠𝕩𝕚𝕟𝕘 𝕎𝕚𝕫𝕒𝕣𝕕𝕤 𝕁𝕦𝕞𝕡 ℚ𝕦𝕚𝕔𝕜𝕝𝕪. | | bbcc | 𝓣𝓱𝓮 𝓕𝓲𝓿𝓮 𝓑𝓸𝔁𝓲𝓷𝓰 𝓦𝓲𝔃𝓪𝓻𝓭𝓼 𝓙𝓾𝓶𝓹 𝓠𝓾𝓲𝓬𝓴𝓵𝔂. | | bbfr | 𝕿𝖍𝖊 𝕱𝖎𝖛𝖊 𝕭𝖔𝖝𝖎𝖓𝖌 𝖂𝖎𝖟𝖆𝖗𝖉𝖘 𝕵𝖚𝖒𝖕 𝕼𝖚𝖎𝖈𝖐𝖑𝖞. | | bbit | 𝑻𝒉𝒆 𝑭𝒊𝒗𝒆 𝑩𝒐𝒙𝒊𝒏𝒈 𝑾𝒊𝒛𝒂𝒓𝒅𝒔 𝑱𝒖𝒎𝒑 𝑸𝒖𝒊𝒄𝒌𝒍𝒚. | | bbsf | 𝗧𝗵𝗲 𝗙𝗶𝘃𝗲 𝗕𝗼𝘅𝗶𝗻𝗴 𝗪𝗶𝘇𝗮𝗿𝗱𝘀 𝗝𝘂𝗺𝗽 𝗤𝘂𝗶𝗰𝗸𝗹𝘆. | | bbsfit | 𝙏𝙝𝙚 𝙁𝙞𝙫𝙚 𝘽𝙤𝙭𝙞𝙣𝙜 𝙒𝙞𝙯𝙖𝙧𝙙𝙨 𝙅𝙪𝙢𝙥 𝙌𝙪𝙞𝙘𝙠𝙡𝙮. | | cc mathcal | 𝒯𝒽ℯ ℱ𝒾𝓋ℯ ℬℴ𝓍𝒾𝓃ℊ 𝒲𝒾𝓏𝒶𝓇𝒹𝓈 𝒥𝓊𝓂𝓅 𝒬𝓊𝒾𝒸𝓀𝓁𝓎. | | fr mathfrak | 𝔗𝔥𝔢 𝔉𝔦𝔳𝔢 𝔅𝔬𝔵𝔦𝔫𝔤 𝔚𝔦𝔷𝔞𝔯𝔡𝔰 𝔍𝔲𝔪𝔭 𝔔𝔲𝔦𝔠𝔨𝔩𝔶. | | italic mathit | 𝑇ℎ𝑒 𝐹𝑖𝑣𝑒 𝐵𝑜𝑥𝑖𝑛𝑔 𝑊𝑖𝑧𝑎𝑟𝑑𝑠 𝐽𝑢𝑚𝑝 𝑄𝑢𝑖𝑐𝑘𝑙𝑦. | | sf mathsf | 𝖳𝗁𝖾 𝖥𝗂𝗏𝖾 𝖡𝗈𝗑𝗂𝗇𝗀 𝖶𝗂𝗓𝖺𝗋𝖽𝗌 𝖩𝗎𝗆𝗉 𝖰𝗎𝗂𝖼𝗄𝗅𝗒. | | sfit | 𝘛𝘩𝘦 𝘍𝘪𝘷𝘦 𝘉𝘰𝘹𝘪𝘯𝘨 𝘞𝘪𝘻𝘢𝘳𝘥𝘴 𝘑𝘶𝘮𝘱 𝘘𝘶𝘪𝘤𝘬𝘭𝘺. | | tt mathtt | 𝚃𝚑𝚎 𝙵𝚒𝚟𝚎 𝙱𝚘𝚡𝚒𝚗𝚐 𝚆𝚒𝚣𝚊𝚛𝚍𝚜 𝙹𝚞𝚖𝚙 𝚀𝚞𝚒𝚌𝚔𝚕𝚢. |

These styles can either be applied to text (eg: bb"Text"), but can also be applied directly to groups of symbols.

Spacing Symbols

A few symbols exist to introduce whitespace into the rendered formula.

| Spacing Symbols | Output | | ------------------------------------------- | ----------------------------------------------------- | | \ thinspace | <mspace width="0.25em"/> | | enspace | <mspace width="0.5em"/> | | quad mspace | <mspace width="1em"/> | | qquad | <mspace width="2em"/> |

Matrixes

Parenthesized lists of lists are treated as Matrixes, and rendered in a grid. The outer-most braces are stretched to match the height of the full matrix.

Each 'row' in a matrix needs the same number of items it it, so that the number of columns in the matrix is consistent. However, the cells in the matrix can be arbitrarily complex.

( (1,     x_1,   x_1^2, cdots, x_1^{n-1}),
  (1,     x_2,   x_2^2, cdots, x_2^{n-1}),
  (1,     x_3,   x_3^2, cdots, x_3^{n-1}),
  (vdots, vdots, vdots, ddots, vdots    ),
  (1,     x_n,   x_n^2, cdots, x_n^{n-1}) )

Augmented matrixes can be drawn by filling a column with | symbols.

Note: The main ASCIIMathML project uses the 'columnlines' attribute to draw a solid line through the augmented matrix. This looks really pretty, but sadly, Chrome doesn't support that feature, and this leaves the matrix without any visible separator, which is very confusing. (Honestly, Chrome's MathML support is pretty lacking, generally.) So this library instead uses an extra-tall unicode bar character, and tweaks the column spacing to draw the separator column a little tighter. This doesn't look AS good, but still looks alright. Plus, it'll yield a drawing that is more visually understandable whenever the browser only supports a subset of MathML.

Language Grammar

In EBNF, ASCIIMath looks like:

expr := term*;
term := simp ('_' simp)? ('^' simp)? ('/' term)?;
simp := paren | unary | binary | leaf;
paren := ('(' | '[' | ...) expr (')' | ']' | ...);
unary := ('sqrt' | 'floor' | ...) simp;
binary := ('root' | 'frac' | ...) simp simp;
leaf := (str literal) | (num literal) | (symbol) | (char);

Where:

• (str literal) is a "double quoted string", with internal "" sequences becoming literal " characters.
• (num literal) is an integer or floating-point string. Leading / trailing decimal point characters are allowed. (ie: 123. and .123 are both fine.)
• (symbol) is one of the many special symbols described in this document.
• (char) is a single character, which will be used as a math identifier.

Differences from main ASCIIMath

• This library defines entries for ALL the greek characters, upper and lower case, plus a few extras. There are a few notable gaps in the original spec.
• Text blocks can now contain double-quotes by using the "" symbol. (ie: "hello ""world""" -> hello "world")
• Matrixes have a slightly more forgiving syntax: The final bracket can be omitted, and the final row can have fewer entries, to make incremental renders while typing succeed more often.
• This library also handles unicode characters more gracefully. The original library's parser worked in a way that could break surrogate pairs if encountered. This would result in diagrams with broken unicode in them. This library will always pick single characters from the text based on their unicode encoding, so larger unicode sequences (such as emojis) will still render correctly.