AsciiMath Parser

displayMode off

What’s this?

A JavaScript implementation of simple mathematical formula markup language. It is more readable and easy to learn compared with $\LaTeX$ .

How to Use

API

You can use either asciimath-parser or asciimath-parser-nearley. This documentation is for the former, while the latter has some differences. Please refer to its README.

Basic Usage

Install the package with npm/yarn/pnpm.

pnpm i -D asciimath-parser

Import it and create an instance of Asciimath, then use the toTex method to generate LaTeX code.

import { AsciiMath } from 'asciimath-parser'
const am = new AsciiMath()
console.log(am.toTex('sum_(n=1)^(+oo)1/n^2=pi^2/6'))
// \displaystyle{ \sum _{ n = 1 } ^{ + \infty } \frac{ 1 }{ n ^{ 2 } } = \frac{ \pi ^{ 2 } }{ 6 } }

Configuration and Custom Tokens

The following is the type declaration of AsciiMath config.

type ReplaceLaw = [RegExp | string, string | ((substring: string, ...args: any[]) => string)]

interface AsciiMathConfig {
  display?: boolean
  replaceBeforeTokenizing?: ReplaceLaw[]
  symbols?: Array<[string, SymbolValueType]> | Record<string, SymbolValueType>
}

`display`

Specify whether the generated formula is wrapped in \displaystyle environment. The default value is true.

`replaceBeforeTokenizing`

Replace the matched strings with the target strings respectively before the formula is parsed by AsciiMath.

Click to show details.

For example, if you specify it like below:

const cfg: AsciiMathConfig = {
  replaceBeforeTokenizing: [
    [/d0/g, '{:"d"theta:}'],
    [/x(\d+)/g, (_, $1) => `x^(${$1})`],
  ]
}
const am = new AsciiMath(cfg)
console.log(am.toTex('...'))

All of the d0 will be replaced with {:"d"theta:}, and then be parsed into { \text{d} \theta } by AsciiMath.
Strings like x2 and x10 will be replaced with x^(2) and x^(10), and then be parsed into x^{ 2 } and x^{ 10 }, respectively. (I think no one should write them like this, though ¯\_(ツ)_/¯)

`symbols`

Specify the extended tokens. If you want to view all of the token types, please refer to symbols.ts. However, it is not recommended to extend all of them. The following lists the recommended token types for extension

enum TokenTypes {
  Const, // transform matched string into tex
  OperatorOA, // with unary operand, like `abs(a)`
  OperatorOAB, // with binary operands, like `frac(a)(b)`
  OperatorAOB, // infix operator, like `a / b`
  OperatorAO, // suffix operator, like factorial `n!`
}

Click to show details.

You can specify it below

const cfg: AsciiMathConfig = {
  symbols: {
    dx: { type: TokenTypes.Const, tex: '{\\mathrm{d}x}' },
    rm: { type: TokenTypes.OperatorOA, tex: '\\mathrm{$1}', eatNext: true },
    frac: { type: TokenTypes.OperatorOAB, tex: '\\frac{ $1 }{ $2 }' },
    over: { type: TokenTypes.OperatorAOB, tex: '{ $1 \\over $2 }' },
  }
}
const am = new AsciiMath(cfg)
console.log(am.toTex('...'))

Then dx, rm, frac and over will be recognized as tokens of AsciiMath, and the results will be

dx into {\mathrm{d}x}
rm(absc) into \mathrm{absc}, where $1 will be replaced with absc

If eatNext is set to true, then the next word will be “eaten” by tokenizer and recognized as a literal string even if there is any token in it. In the example above, absc contains the token abs, but the program just simply read the word and put absc at the $1.

Without eatNext, you will get \mathrm{ \left|c\right| }.

If you want to read a longer sentense, just wrap it with doublequotes " or parens ( ) like rm "here is a mathrm block"

eatNext is only recommended to be used with OperatorOA and OperatorOAB.
frac(m)(n) into \frac{ m }{ n }, where $1 and $2 will be replaced with m and n, respectively
a over b into { a \over b }, where $1 and $2 will be replaced with a and b, respectively

Cli

Install the cli locally or globally.

pnpm add -g asciimath-parser-cli

Transform input files with inline asciimath formulas (wrapped with backticks) to LaTeX formulas.

am-parse input.txt
# It will yield input_parsed_xxx.tex

User Story

Display formulas in the DOM with KaTeX or mathjax.
Use Obsidian with the plugin obsidian-asciimath.
Use the cli to convert asciimath formulas in the file to LaTeX formulas.

Caution

This library is refactored by me, which means that some of the syntax may be inconsistent with asciimath.org, especially the matrix.
Asciimath parser itself does not depend on DOM or mathml, it simply parses your input code into LaTeX code. If you want to display formulas, please work it out with KaTeX or mathjax (for websites) or LaTeX (for articles).

Special Thanks

zmx0142857’s note and his great help.

Report an Issue

Go to GitHub issue and provide a template that can reproduce the problem you ran into.

Examples

Theme	output	source
Super and subscript	$\displaystyle{ a _{ 1 } ^{ 2 } + b _{ 1 } ^{ 2 } = c _{ 1 } ^{ 2 } }$	a_1^2 + b_1^2 = c_1^2
Text	$\displaystyle{ \text{hello world} }$	"hello world"
Fraction	$\displaystyle{ \frac{ a }{ b } , a {/} b }$	a/b, a//b
Square root	$\displaystyle{ \sqrt{ n } , \sqrt[ n ]{ x } , \frac{ a ^{ 2 } }{ \sqrt{ b } } }$	sqrt n, root n x, a^2/sqrt b
Limit	$\displaystyle{ \lim _{ n \to \infty } \left( 1 + \frac{ 1 }{ n } \right) ^{ n } }$	lim_(n->oo) (1+1/n)^n
Integral	$\displaystyle{ \int _{ a } ^{ b } f \left( x \right) {\text{d}x} }$	int_a^b f(x) dx
Hidden parens	$\displaystyle{ \sin { \frac{ x }{ 2 } } }$	sin {: x/2 :}
Differential	$\displaystyle{ \frac{ {\text{d}y} }{ {\text{d}x} } , \frac{ \text{d} r }{ \text{d} \theta } , f ^{\prime\prime} \left( x \right) }$	dy/dx, ("d"r)/("d"theta), f''(x)
Differential (exprimental)	$\displaystyle{ \frac{ \mathrm{d} f }{ \mathrm{d} x } , \frac{ \mathrm{d} ^{ 2 } f }{ \mathrm{d} x ^{ 2 } } , \ddot{ x } }$	ddfx , dd^2 f x , ddot x
Partial	$\displaystyle{ \frac{ \partial f }{ \partial x } , \frac{ \partial ^{ 3 } f }{ \partial x \partial y ^{ 2 } } }$	(del f)/(del x), (del^3 f)/(del x del y^2)
Partial (experiment)	$\displaystyle{ \frac{ \partial f }{ \partial x } , \frac{ \partial ^{ 3 } f }{ \partial x \partial y ^{ 2 } } , \frac{ \partial { } }{ \partial x } }$	ppfx, pp^3 f (x y^2), pp {::} x
Matrix	$\displaystyle{ \left[ \begin{array}{cc} a & b \\ c & d \end{array} \right] , \left[ \begin{array}{cc\|c} a & b & c \\ d & e & f \end{array} \right] }$	[a, b; c, d], [a, b \| c; d, e \| f]
Piecewise function	$\displaystyle{ \left\| x \right\| = \left\lbrace \begin{array}{ll} x & \text{if}\quad x > 0 \\ - x & \text{otherwise}\quad \end{array} \right. }$	\|x\| = { x, if x > 0; -x, otherwise :}

Manual

Greek Alphabet

output	source	output	source	output	source	output	source
$\displaystyle{ \alpha }$	alpha	$\displaystyle{ \beta }$	beta	$\displaystyle{ \chi }$	chi	$\displaystyle{ \delta }$	delta
$\displaystyle{ \Delta }$	Delta	$\displaystyle{ \varepsilon }$	epsi	$\displaystyle{ \epsilon }$	epsilon	$\displaystyle{ \eta }$	eta
$\displaystyle{ \gamma }$	gamma	$\displaystyle{ \Gamma }$	Gamma	$\displaystyle{ \iota }$	iota	$\displaystyle{ \kappa }$	kappa
$\displaystyle{ \lambda }$	lambda	$\displaystyle{ \Lambda }$	Lambda	$\displaystyle{ \mu }$	mu	$\displaystyle{ \nu }$	nu
$\displaystyle{ \omega }$	omega	$\displaystyle{ \Omega }$	Omega	$\displaystyle{ \phi }$	phi	$\displaystyle{ \varphi }$	varphi
$\displaystyle{ \Phi }$	Phi	$\displaystyle{ \varPhi }$	varPhi	$\displaystyle{ \pi }$	pi	$\displaystyle{ \Pi }$	Pi
$\displaystyle{ \psi }$	psi	$\displaystyle{ \Psi }$	Psi	$\displaystyle{ \rho }$	rho	$\displaystyle{ \sigma }$	sigma
$\displaystyle{ \Sigma }$	Sigma	$\displaystyle{ \tau }$	tau	$\displaystyle{ \theta }$	theta	$\displaystyle{ \vartheta }$	vartheta
$\displaystyle{ \Theta }$	Theta	$\displaystyle{ \upsilon }$	upsilon	$\displaystyle{ \xi }$	xi	$\displaystyle{ \Xi }$	Xi
$\displaystyle{ \zeta }$	zeta

Paren

output	source	output	source	output	source	output	source
$\displaystyle{ \left( \right. }$	(	$\displaystyle{ ) }$	)	$\displaystyle{ \left. \right. }$	{:	$\displaystyle{ . }$	:}
$\displaystyle{ \left[ \right. }$	[	$\displaystyle{ ] }$	]	$\displaystyle{ \left\lbrace \right. }$	{	$\displaystyle{ \rbrace }$	}
$\displaystyle{ \left\langle \right. }$	(:	$\displaystyle{ \rangle }$	:)	$\displaystyle{ \left\lfloor \right. }$	\|__	$\displaystyle{ \rfloor }$	__\|
$\displaystyle{ \left\lceil \right. }$	\|~	$\displaystyle{ \rceil }$	~\|	$\displaystyle{ \mid }$	\|	$\displaystyle{ \left\| x \right\| }$	abs(x)
$\displaystyle{ \left\\| \mathbf{ v } \right\\| }$	norm(bb(v))	$\displaystyle{ \left\lfloor \frac{ x }{ 2 } \right\rfloor }$	floor(x/2)	$\displaystyle{ \left\lceil \frac{ x }{ 3 } \right\rceil }$	ceil(x/3)

Operator

output	source	output	source	output	source	output	source
$\displaystyle{ + }$	+	$\displaystyle{ - }$	-	$\displaystyle{ \cdot }$	*	$\displaystyle{ \ast }$	**
$\displaystyle{ {/} }$	//	$\displaystyle{ \backslash }$	\\	$\displaystyle{ \times }$	xx	$\displaystyle{ \div }$	-:
$\displaystyle{ \circ }$	@	$\displaystyle{ \oplus }$	o+	$\displaystyle{ \otimes }$	ox	$\displaystyle{ \odot }$	o.
$\displaystyle{ \sum }$	sum	$\displaystyle{ \prod }$	prod	$\displaystyle{ \wedge }$	^^	$\displaystyle{ \bigwedge }$	^^^
$\displaystyle{ \vee }$	vv	$\displaystyle{ \bigvee }$	vvv	$\displaystyle{ \cap }$	nn	$\displaystyle{ \bigcap }$	nnn
$\displaystyle{ \cup }$	uu	$\displaystyle{ \bigcup }$	uuu	$\displaystyle{ \% }$	%

Relation Symbol

output	source	output	source	output	source	output	source
$\displaystyle{ = }$	=	$\displaystyle{ \ne }$	!=	$\displaystyle{ \equiv }$	-=	$\displaystyle{ \not\equiv }$	!-=
$\displaystyle{ \cong }$	~=	$\displaystyle{ \approx }$	~~	$\displaystyle{ < }$	lt	$\displaystyle{ > }$	gt
$\displaystyle{ \ge }$	ge	$\displaystyle{ \le }$	le	$\displaystyle{ \leqslant }$	<=	$\displaystyle{ \geqslant }$	>=
$\displaystyle{ \prec }$	-<	$\displaystyle{ \succ }$	>-	$\displaystyle{ \in }$	in	$\displaystyle{ \notin }$	!in
$\displaystyle{ \subset }$	sub	$\displaystyle{ \supset }$	sup	$\displaystyle{ \subseteq }$	sube	$\displaystyle{ \supseteq }$	supe
$\displaystyle{ \not\subseteq }$	!sube	$\displaystyle{ \subsetneqq }$	subne	$\displaystyle{ \unlhd }$	normal	$\displaystyle{ \unrhd }$	rnormal
$\displaystyle{ \lhd }$	lhd	$\displaystyle{ \rhd }$	rhd	$\displaystyle{ ∽ }$	S~	$\displaystyle{ \propto }$	prop
$\displaystyle{ \complement }$	complement

Logical Operator

output	source	output	source	output	source	output	source
$\displaystyle{ \text{ and } }$	and	$\displaystyle{ \text{ or } }$	or	$\displaystyle{ \neg }$	not	$\displaystyle{ \Rightarrow }$	rArr
$\displaystyle{ \text{if}\quad }$	if	$\displaystyle{ \iff }$	iff	$\displaystyle{ \forall }$	AA	$\displaystyle{ \exists }$	EE
$\displaystyle{ \bot }$	_\|_	$\displaystyle{ \top }$	TT	$\displaystyle{ \vdash }$	\|--	$\displaystyle{ \models }$	\|==

Others

output	source	output	source	output	source	output	source
$\displaystyle{ \int }$	int	$\displaystyle{ \iint }$	iint	$\displaystyle{ \iiint }$	iiint	$\displaystyle{ \oint }$	oint
$\displaystyle{ \partial }$	del	$\displaystyle{ \nabla }$	grad	$\displaystyle{ \pm }$	+-	$\displaystyle{ \varnothing }$	O/
$\displaystyle{ \infty }$	oo	$\displaystyle{ \aleph }$	aleph	$\displaystyle{ \angle }$	/_	$\displaystyle{ \therefore }$	:.
$\displaystyle{ \because }$	:'	$\displaystyle{ \ldots }$	...	$\displaystyle{ \cdots }$	cdots	$\displaystyle{ \vdots }$	vdots
$\displaystyle{ \ddots }$	ddots	$\displaystyle{ \square }$	square	$\displaystyle{ \mathbb{N} }$	NN	$\displaystyle{ \mathbb{Q} }$	QQ
$\displaystyle{ \mathbb{R} }$	RR	$\displaystyle{ \mathbb{C} }$	CC	$\displaystyle{ \mathbb{Z} }$	ZZ	$\displaystyle{ { N \choose k } }$	N choose k

Math Function

output	source	output	source	output	source	output	source
$\displaystyle{ \sin }$	sin	$\displaystyle{ \cos }$	cos	$\displaystyle{ \tan }$	tan	$\displaystyle{ \cot }$	cot
$\displaystyle{ \sec }$	sec	$\displaystyle{ \csc }$	csc	$\displaystyle{ \sinh }$	sinh	$\displaystyle{ \cosh }$	cosh
$\displaystyle{ \tanh }$	tanh	$\displaystyle{ \coth }$	coth	$\displaystyle{ \operatorname{csch} }$	csch	$\displaystyle{ \operatorname{sech} }$	sech
$\displaystyle{ \arcsin }$	arcsin	$\displaystyle{ \arccos }$	arccos	$\displaystyle{ \arctan }$	arctan	$\displaystyle{ \log }$	log
$\displaystyle{ \ln }$	ln	$\displaystyle{ \det }$	det	$\displaystyle{ \dim }$	dim	$\displaystyle{ \lim }$	lim
$\displaystyle{ \operatorname{mod} }$	mod	$\displaystyle{ \gcd }$	gcd	$\displaystyle{ \operatorname{lcm} }$	lcm	$\displaystyle{ \min }$	min
$\displaystyle{ \max }$	max	$\displaystyle{ \operatorname{sgn} }$	sgn	$\displaystyle{ \sup }$	Sup	$\displaystyle{ \inf }$	inf
$\displaystyle{ \exp }$	exp

Arrow

output	source	output	source	output	source	output	source
$\displaystyle{ \uparrow }$	uarr	$\displaystyle{ \downarrow }$	darr	$\displaystyle{ \rightarrow }$	rarr	$\displaystyle{ \leftarrow }$	larr
$\displaystyle{ \to }$	->	$\displaystyle{ \mapsto }$	\|->	$\displaystyle{ \leftrightarrow }$	harr	$\displaystyle{ \Rightarrow }$	rArr
$\displaystyle{ \Leftarrow }$	lArr	$\displaystyle{ \Leftrightarrow }$	hArr	$\displaystyle{ \twoheadrightarrow }$	->>	$\displaystyle{ \rightarrowtail }$	>->
$\displaystyle{ \curvearrowleft }$	curvArrLt	$\displaystyle{ \curvearrowright }$	curvArrRt	$\displaystyle{ \circlearrowleft }$	circArrLt	$\displaystyle{ \circlearrowright }$	circArrRt
$\displaystyle{ \rightsquigarrow }$	~>	$\displaystyle{ \nrightarrow }$	-/->	$\displaystyle{ \nleftarrow }$	<-/-	$\displaystyle{ \nleftrightarrow }$	<-/->

Font

output	source	output	source	output	source	output	source
$\displaystyle{ \mathbf{ A } }$	bb A	$\displaystyle{ \boldsymbol{ A } }$	bm A	$\displaystyle{ \mathbb{ A } }$	bbb A	$\displaystyle{ \mathcal{ A } }$	cc A
$\displaystyle{ \mathtt{ A } }$	tt A	$\displaystyle{ \mathfrak{ A } }$	fr A	$\displaystyle{ \mathsf{ A } }$	sf A	$\displaystyle{ \mathscr{ A } }$	scr A

Notation

output	source	output	source	output	source	output	source
$\displaystyle{ \hat{ x } }$	hat x	$\displaystyle{ \bar{ x } }$	bar x	$\displaystyle{ \underline{ x } }$	ul x	$\displaystyle{ \vec{ x } }$	vec x
$\displaystyle{ \dot{ x } }$	dot x	$\displaystyle{ \ddot{ x } }$	ddot x	$\displaystyle{ \stackrel{\frown}{ x } }$	arc x	$\displaystyle{ \tilde{ x } }$	tilde x
$\displaystyle{ \overrightarrow{ A B } }$	Vec(AB)	$\displaystyle{ \widehat{ A B } }$	Hat(AB)	$\displaystyle{ \widetilde{ A B } }$	Tilde(AB)

Superposition

output	source	output	source
$\displaystyle{ \overset{ \text{bala} }{ x } }$	overset("bala")(x)	$\displaystyle{ \overbrace{ 12345 } ^{ n } }$	overbrace(12345)^n
$\displaystyle{ \underbrace{ 12345 } _{ n } }$	underbrace(12345)_n	$\displaystyle{ \xlongequal[ 123 ]{ 456 } }$	==_(123)^(456)
$\displaystyle{ \xrightarrow[ a ]{ b } }$	-->_(a)^(b)	$\displaystyle{ { a \atop b } }$	a atop b

Special

output	source	output	source
$\displaystyle{ \text{I'm here} }$	text(I'm here)	$\displaystyle{ \hbar }$	tex"\hbar"
$\displaystyle{ { \color{red} ab c } }$	color(red)(abc)	$\displaystyle{ \text{hello world} }$	"hello world"

Escape

output	source	output	source	output	source	output	source
$\displaystyle{ \# }$	\#	$\displaystyle{ \$ }$	\$	$\displaystyle{ @ }$	\@	$\displaystyle{ \_ }$	\_

output	source	output	source
$\displaystyle{ {\tiny \text{text} } }$	tiny "text"	$\displaystyle{ {\small \text{text} } }$	small "text"
$\displaystyle{ {\large \text{text} } }$	large "text"	$\displaystyle{ {\huge \text{text} } }$	huge "text"

Syntax Sugar

output	source	output	source	output	source	output	source
$\displaystyle{ {\text{d}x} }$	dx	$\displaystyle{ {\text{d}y} }$	dy	$\displaystyle{ {\text{d}z} }$	dz	$\displaystyle{ {\text{d}t} }$	dt

Use `#` to insert `displaystyle`

output	source
$\displaystyle{ \left[ \begin{array}{cc} \displaystyle \frac{ \partial ^{ 2 } f }{ \partial x ^{ 2 } } & \frac{ \partial ^{ 2 } f }{ \partial x \partial y } \\ \frac{ \partial ^{ 2 } f }{ \partial y \partial x } & \displaystyle \frac{ \partial ^{ 2 } f }{ \partial y ^{ 2 } } \end{array} \right] }$	[#part^2 f x, part^2 f (x y); part^2 f (y x), #part^2 f y]

With `aligned` environment

f(x) & = x "e"^x
                            <-- a blank line here
f'(x) & = (x + 1) "e"^x
                            <-- a blank line here
f''(x) & = (x + 2) "e"^x

\displaystyle{ \begin{aligned}f \left( x \right) & = x \text{e} ^{ x } \\ f ^{\prime} \left( x \right) & = \left( x + 1 \right) \text{e} ^{ x } \\ f ^{\prime\prime} \left( x \right) & = \left( x + 2 \right) \text{e} ^{ x }\end{aligned} }

Caution The & acts as & in aligned env, and the blank lines act as \\ in LaTeX.

Spaces

output	source	width
$\displaystyle{ a \quad b }$	a quad b	1 em
$\displaystyle{ a \qquad b }$	a qquad b	2 em
$\displaystyle{ a \enspace b }$	a enspace b	0.5 em
$\displaystyle{ a \; b }$	a \; b	5/18 em
$\displaystyle{ a \: b }$	a \: b	4/18 em
$\displaystyle{ a \, b }$	a \, b	3/18 em
$\displaystyle{ a \! b }$	a \! b	-3/18 em
$\displaystyle{ a \hspace{12pt} b }$	a hspace(12pt) b	12 pt