Fork me on GitHub

mathlive

Use MathLive to render and edit mathematical formulas in your browser.

This module exports some functions and the MathField class.

See USAGE_GUIDE the Usage Guide for more details on how to get started.

// To invoke the functions in this module, import the `mathlive` module.

import mathlive from 'dist/mathlive.mjs';

console.log(mathlive.latexToMarkup('e^{i\\pi}+1=0'));

Methods

astToLatex(ast: object, options: [string]:any): string

Converts an Abstract Syntax Tree (MathJSON) to a LaTeX string.

See: MathJSON

ast : object

The Abstract Syntax Tree as an object literal (MathJSON).

options : [string]:any
options.precision : number = 14

The number of digits used in the representation of numbers. Default = 14.

options.decimalMarker : string = '.'

The character used as the decimal marker. Default = ".".

options.groupSeparator : string = '\\, '

The character used to separate group of numbers, typically thousands. Default = "\\, "

options.product : string = '\\cdot '

The character used to indicate product. Other option would be "\\times ". Default = "\\cdot "

options.exponentProduct : string = '\\cdot '

The character used before an exponent indicator. Default = "\\cdot "

options.exponentMarker : string = ''

The character used to indicate an exponent. Default = ""

options.scientificNotation : "auto" | "engineering" | "on" = 'auto'

The format used for numbers using the scientific notation. Default = "auto"

options.beginRepeatingDigits : string = '\\overline{'

The string used at the begining of repeating digits. Default = "\\overline{"

options.endRepeatingDigits : string = '}'

The string used at the end of repeating digits. Default = "}"

: string   

The LaTeX representation of the Abstract Syntax Tree, if valid.

getOriginalContent(element: string | HTMLElement | MathField, options?: object): string

After calling renderMathInElement or makeMathField the original content can be retrieved by calling this function.

Given the following markup:

<span id='equation'>$$f(x)=sin(x)$$</span>

The following code:

MathLive.renderMathInElement('equation');
console.log(MathLive.getOriginalContent('equation'));

will output:

$$f(x)=sin(x)$$
element : string | HTMLElement | MathField

A DOM element ID, a DOM element or a MathField.

options : object = {}
options.namespace : string = ""

The namespace used for the data- attributes. If you used a namespace with renderMathInElement(), you must use the same namespace here.

: string   

the original content of the element.

latexToAST(latex: string, options: [string]:any): object

Converts a LaTeX string to an Abstract Syntax Tree (MathJSON)

See: MathJSON

latex : string

A string of valid LaTeX. It does not have to start with a mode token such as a $$ or \(.

options : [string]:any
options.macros : object

A dictionary of LaTeX macros

: object   

The Abstract Syntax Tree as an object literal using the MathJSON format.

latexToMarkup(text: string, mathstyle: "displaystyle" | "textstyle", format?: "mathlist" | "span" | "html"): string

Converts a LaTeX string to a string of HTML markup.

text : string

A string of valid LaTeX. It does not have to start with a mode token such as $$ or \(.

mathstyle : "displaystyle" | "textstyle"

If 'displaystyle' the "display" mode of TeX is used to typeset the formula, which is most appropriate for formulas that are displayed in a standalone block.

If 'textstyle' is used, the "text" mode of TeX is used, which is most appropriate when displaying math "inline" with other text (on the same line).

format : "mathlist" | "span" | "html" = 'html'

For debugging purposes, this function can also return a text representation of internal data structures used to construct the markup.

: string   

latexToMathML(latex: string, options: object): string

Converts a LaTeX string to a string of MathML markup.

latex : string

A string of valid LaTeX. It does not have to start with a mode token such as a $$ or \(.

options : object
options.generateID : boolean = false

If true, add an "extid" attribute to the MathML nodes with a value matching the atomID. This can be used to map items on the screen with their MathML representation or vice-versa.

: string   

latexToSpeakableText(latex: string, options: [string]:any): string

Converts a LaTeX string to a textual representation ready to be spoken

latex : string

A string of valid LaTeX. It does not have to start with a mode token such as a $$ or \(.

options : [string]:any
options.textToSpeechRules : "mathlive" | "sre" = 'mathlive'

The set of text to speech rules to use.

A value of "mathlive" (the default) indicates that the simple rules built into MathLive should be used.

A value of "sre" indicates that the Speech Rule Engine from Volker Sorge should be used. Note that SRE is not included or loaded by MathLive and for this option to work SRE should be loaded separately.

options.textToSpeechMarkup : string = ''

The markup syntax to use for the output of conversion to spoken text.

Possible values are ssml for the SSML markup or mac for the MacOS markup (e.g. "[[ltr]]")

options.textToSpeechRulesOptions : [string]:any = {}

A set of key/value pairs that can be used to configure the speech rule engine.

Which options are available depends on the speech rule engine in use. There are no options available with MathLive's built-in engine. The options for the SRE engine are documented [here]{@link:https://github.com/zorkow/speech-rule-engine}

: string   

The spoken representation of the input LaTeX.

console.log(MathLive.latexToSpeakableText('\\frac{1}{2}'));
// ➡︎'half'

makeMathField(element: HTMLElement | string, config?: MathFieldConfig): MathField

Convert a DOM element into an editable mathfield.

After the DOM element has been created, the value element.mathfield will return a reference to the mathfield object. This value is also returned by makeMathField

element : HTMLElement | string

A DOM element, for example as obtained by document.getElementById(), or the ID of a DOM element as a string.

config : MathFieldConfig = {}

See Configuration options for details.

: MathField   

Given the HTML markup:

<span id='equation'>$f(x)=sin(x)$</span>

The following code will turn the span into an editable mathfield.

import MathLive from 'dist/mathlive.mjs';
MathLive.makeMathField('equation');

pauseReadAloud()

Pauses a read aloud operation if one is in progress.

See speak

playReadAloud(token?: string, count?: number)

If a Read Aloud operation is in progress, read from a specified token

See speak

token : string
count : number

The number of tokens to read.

readAloud(element: DOMElement, text: string, config: object)private

"Read Aloud" is an asynchronous operation that reads the reading with synchronized highlighting

element : DOMElement

The DOM element to highlight

text : string

The text to speak

config : object

readAloudStatus(): "ready" | "playing" | "paused" | "unavailable"

Returns the status of a Read Aloud operation (reading with synchronized highlighting).

Possible values are:

  • "ready"
  • "playing"
  • "paused"
  • "unavailable"

See speak

: "ready" | "playing" | "paused" | "unavailable"   

renderMathInElement(element: HTMLElement | string, options?: object, renderToMarkup?: function, renderToMathML?: function, renderToSpeakableText?: function)

Transform all the children of element, recursively, that contain LaTeX code into typeset math.

See: Usage Guide/Start Here

element : HTMLElement | string

An HTML DOM element, or a string containing the ID of an element.

options : object = {}
options.namespace : string = ''

Namespace that is added to data- attributes to avoid collisions with other libraries.

It is empty by default.

The namespace should be a string of lowercase letters.

options.macros : object[] = {}

Custom LaTeX macros

options.skipTags : string[] = ['noscript', 'style', 'textarea', 'pre', 'code', 'annotation', 'annotation-xml']

an array of tag names whose content will not be scanned for delimiters (unless their class matches the processClass pattern below.

options.ignoreClass : string = 'tex2jax_ignore'

a string used as a regular expression of class names of elements whose content will not be scanned for delimiters

options.processClass : string = 'tex2jax_process'

a string used as a regular expression of class names of elements whose content will be scanned for delimiters, even if their tag name or parent class name would have prevented them from doing so.

options.processScriptType : string = "math/tex"

<script> tags of the indicated type will be processed while others will be ignored.

options.renderAccessibleContent : string = 'mathml'

The format(s) in which to render the math for screen readers:

  • 'mathml' MathML
  • 'speakable-text' Spoken representation

You can pass an empty string to turn off the rendering of accessible content.

You can pass multiple values separated by spaces, e.g 'mathml speakable-text'

options.preserveOriginalContent : boolean = true

if true, store the original textual content of the element in a data-original-content attribute. This value can be accessed for example to restore the element to its original value:

     elem.innerHTML = elem.dataset.originalContent;

options.readAloud : boolean = false

if true, generate markup that can be read aloud later using speak

options.TeX.processEnvironments : boolean = true

if false, math expression that start with \begin{ will not automatically be rendered.

options.TeX.delimiters.inline : Array.<Array.<string>> = [['\\(','\\)']]

arrays of delimiter pairs that will trigger a render of the content in 'textstyle'

options.TeX.delimiters.display : Array.<Array.<string>> = [['$$', '$$'], ['\\[', '\\]']]

arrays of delimiter pairs that will trigger a render of the content in 'displaystyle'.

renderToMarkup : function

a function that will convert any LaTeX found to HTML markup. This is only useful to override the default MathLive renderer

renderToMathML : function

a function that will convert any LaTeX found to MathML markup.

renderToSpeakableText : function

a function that will convert any LaTeX found to speakable text markup.

resumeReadAloud()

Resumes a read aloud operation if one was paused.

See speak

revertToOriginalContent(element: string | HTMLElement | MathField, options?: [string]:any)

element : string | HTMLElement | MathField
options : [string]:any = {}
options.namespace : string

The namespace used for the data- attributes. If you used a namespace with renderMathInElement, you must use the same namespace here.

highlightAtomID(atomID: string)inner

Highlights the span corresponding to the specified atomID.

This is used for text-to-speech with synchronized highlighting (read aloud)

atomID : string

renderMathInDocument(options?: object.<string, any>)inner

Transform all the elements in the document body that contain LaTeX code into typeset math.

Note: This is a very expensive call, as it needs to parse the entire DOM tree to determine which elements need to be processed. In most cases this should only be called once per document, once the DOM has been loaded. To render a specific element, use renderMathInElement()

See: Usage Guide/Start Here

options : object.<string, any> = {}

See renderMathInElement() for details

import MathLive from 'dist/mathlive.mjs';
document.addEventListener("load", () => {
    MathLive.renderMathInDocument();
});