TeX Input Processor Options

The options below control the operation of the TeX input processor that is run when you include 'input/tex' or 'input/tex-base' in the load array of the loader block of your MathJax configuration, or if you load a combined component that includes the TeX input jax. They are listed with their default values. To set any of these options, include a tex section in your MathJax global object.

The Configuration Block

MathJax = {
  tex: {
    packages: ['base'],              // extensions to use
    inlineMath: [                    // start/end delimiter pairs for in-line math
      ['\\(', '\\)']
    ],
    displayMath: [                   // start/end delimiter pairs for display math
      ['$$', '$$'],
      ['\\[', '\\]']
    ],
    processEscapes: true,            // use \$ to produce a literal dollar sign
    processEnvironments: true,       // process \begin{xxx}...\end{xxx} outside math mode
    processRefs: true,               // process \ref{...} outside of math mode
    numberPattern:                   // pattern for recognizing numbers
       /^(?:[0-9]+(?:\{,\}[0-9]{3})*(?:\.[0-9]*)?|\.[0-9]+)/,
    initialDigit: /[0-9.,]/,         // pattern for initial digit or decimal point for a number
    identifierPattern: /^[a-zA-Z]+/, // pattern for multiLetterIdentifiers in \mathrm, etc.
    initialLetter: /[a-zA-Z]/,       // pattern for initial letter in identifiers
    tags: 'none',                    // or 'ams' or 'all'
    tagSide: 'right',                // side for \tag macros
    tagIndent: '0.8em',              // amount to indent tags
    tagAlign: 'baseline',            // The rowalign value to use for tag cells
    useLabelIds: true,               // use label name rather than tag for ids
    ignoreDuplicateLabels: false,    // prevent error messages for duplicate label ids?
    mathStyle: 'TeX',                // one of TeX, ISO, French, or upright
    maxBuffer: 5 * 1024,             // maximum size for the internal TeX string (5K)
    maxTemplateSubtitutions: 10000,  // maximum number of array template substitutions
    baseURL:                         // URL for use with links to tags (when there is a <base> tag in effect)
       (document.getElementsByTagName('base').length === 0) ?
        '' : String(document.location).replace(/#.*$/, ''),
    formatError:                     // function called when TeX syntax errors occur
       (jax, err) => jax.formatError(err),
    preFilters: [],                  // A list of pre-filters to add to the TeX input jax
    postFilters: [],                 // A list of post-filters to add to the TeX input jax
  }
};

Note that some extensions make additional options available. See the TeX Extension Options section below for details.

Note

The default for processEscapes has changed from false in version 2 to true in version 3 and above.

Note

Prior to version 3.2, the multlineWidth option used to be in the main tex block, but it is now in the ams sub-block of the tex block. Version 3.2 includes code to move the configuration from its old location to its new one, but that backward-compatibility code has been removed in version 4.

Note

The digits option has been renamed numberPattern in version 4.

Additional options are described in the Options Common to All Input Processors section.

Option Descriptions

packages: ['base']

This array lists the names of the packages that should be initialized by the TeX input processor. The input/tex and input/tex-base components automatically add to this list the packages that they load. If you explicitly load additional tex extensions, you should add them to this list. For example:

MathJax = {
  loader: {load: ['[tex]/enclose']},
  tex: {
    packages: {'[+]': ['enclose']}
  }
};

This loads the enclose extension and activates it by including it in the package list.

You can remove packages from the default list using '[-]' rather than [+], as in the following example:

MathJax = {
  tex: {
    packages: {'[-]': ['noundefined']}
  }
};

This would disable the noundefined extension, so that unknown macro names would cause error messages rather than be displayed in red.

If you need to both remove some default packages and add new ones, you can do so by including both within the braces:

MathJax = {
  loader: {load: ['[tex]/enclose']},
  tex: {
    packages: {'[-]': ['noundefined', 'autoload'], '[+]': ['enclose']}
  }
};

This disables the noundefined and autoload extensions, and adds in the enclose extension.

inlineMath: [['\$','\$']]

This is an array of pairs of strings that are to be used as in-line math delimiters. The first in each pair is the initial delimiter and the second is the terminal delimiter. You can have as many pairs as you want. For example,

inlineMath: {'[+]': [['$','$']]}

would add dollar sign delimiters to the default list, causing MathJax to look for $...$ and $...$ as delimiters for in-line mathematics. Note that the single dollar signs are not enabled by default because they are used too frequently in normal text, so if you want to use them for math delimiters, you must specify them explicitly.

Warning

The delimiters can’t look like HTML tags (i.e., can’t include the less-than sign), as these would be turned into tags by the browser before MathJax has the chance to run. You can only include text, not tags, as your math delimiters. It is possible, however, to use a custom render action to look for such tags. The Changes in the MathJax API section includes an example of how to do this for the v2-style <script type="math/tex"> tags.

displayMath: [ ['$$','$$'], ['\\[','\\]'] ]: This is an array of pairs of strings that are to be used as delimiters for displayed equations. The first in each pair is the initial delimiter and the second is the terminal delimiter. You can have as many pairs as you want.

Warning

The delimiters can’t look like HTML tags (i.e., can’t include the less-than sign), as these would be turned into tags by the browser before MathJax has the chance to run. You can only include text, not tags, as your math delimiters. It is possible, however, to use a custom render action to look for such tags. The Changes in the MathJax API section includes an example of how to do this for the v2-style <script type="math/tex"> tags.

processEscapes: true: When set to true, you may use \$ to represent a literal dollar sign, rather than using it as a math delimiter, and \\ to represent a literal backslash (so that you can use \\\$ to get a literal \$ or \\$...$ to get a backslash just before in-line math). When false, \$ will not be altered, and its dollar sign may be considered part of a math delimiter. Typically this is set to true if you enable the $ ... $ in-line delimiters, so you can type \$ and MathJax will convert it to a regular dollar sign in the rendered document.

processRefs: true: When set to true, MathJax will process \ref{...} and \eqref{} macros outside of math mode.

processEnvironments: true: When true, MathJax looks not only for the in-line and display math delimiters, but also for LaTeX environments (\begin{something}...\end{something}) and marks them for processing by the TeX input jax. When false, LaTeX environments will not be processed outside of math mode. Note that any environment will be picked up this way, and initiates display-style mathematics, not just those that would do so in LaTeX.

numberPattern: /^(?:[0-9]+(?:\{,\}[0-9]{3})*(?:\.[0-9]*)?|\.[0-9]+)/

This gives a regular expression that is used to identify numbers during the parsing of your TeX expressions. By default, the decimal point is . and you can use {,} between every three digits before that. If you want to use {,} as the decimal indicator, use

MathJax = {
  tex: {
    digits: /^(?:[0-9]+(?:\{,\}[0-9]*)?|\{,\}[0-9]+)/
  }
};

initialDigit: /[0-9.,]/: This gives a regular expression that tells what characters can appear as the first character in a number. Once one of these characters has been found, the numberPattern above is applied to the input string to see if a number is found.

identifierPattern: /^[a-zA-Z]+/: This gives a regular expression that determines what constitutes a single identifier within one of the macros that specifies a font style, like \mathrm{} or \mathcal{}, or within \operatorname{}. A string that matches this pattern will produce a single <mi> element in the internal MathML representation of your formula. Thus, \operatorname{max} will produce <mi>max</mi> rather than three separate <mi>, one for each letter.

initialLetter: /[a-zA-Z]/: This gives a regular expression that specifies what letters can initiate a multi-letter identifier inside macros like \\mathrm{} or \operatorname(). Once one of these characters has been found, the identifierPattern above ks applied to the input string to see if a multi-letter identifier is found.

tags: 'none': This controls whether equations are numbered and how. By default it is set to 'none' to be compatible with earlier versions of MathJax where auto-numbering was not performed (so pages will not change their appearance). You can change this to 'ams' for equations numbered as the AMSmath package would do, or 'all' to get an equation number for every displayed equation.

tagSide: 'right': This specifies the side on which \tag{} macros will place the tags, and on which automatic equation numbers will appear. Set it to 'left' to place the tags on the left-hand side.

tagIndent: "0.8em": This is the amount of indentation (from the right or left) for the tags produced by the \tag{} macro or by automatic equation numbers.

tagAlign: 'baseline': This specifies how equation tags should be vertically aligned with equations that include line breaks. Its value can be 'baseline', 'top', 'center', or 'bottom'. The default is baseline, which is usually the baseline of the top line of the equation.

useLabelIds: true: This controls whether element id attributes for tags use the \label name or the equation number. When true, use the label, when false, use the equation number.

ignoreDuplicateLabels: false: Normally, if MathJax typesets two expressions that have the same \label, that will generate an error for the second equation indicating the duplicate label. Setting this to true, however, will prevent the error message from occurring. That can be useful in a setting where you have removed the previous equation, such as in an editor where you are retypesetting the same equation when the content is edited.

mathStyle: 'TeX'

This determines how single-letter upper- and lower-case Latin and Greek variable names are typeset. The value can be 'TeX', 'ISO', 'French', or 'upright', and the result is as describe in the following table:

mathStyle	latin	Latin	greek	Greek
TeX	italic	italic	italic	upright
ISO	italic	italic	italic	italic
French	italic	upright	upright	upright
upright	upright	upright	upright	upright

maxBuffer: 5 * 1024: Because a definition of the form \def\x{\x aaa} \x would loop infinitely, and at the same time stack up lots of a’s in MathJax’s equation buffer, the maxBuffer constant is used to limit the size of the string being processed by MathJax. It is set to 5KB, which should be sufficient for any reasonable equation.

maxTemplateSubstitutions: 10000: In an array environment preamble, it is possible to make a column declaration that loops infinitely. For example, \begin{array}{c@{\\}c} a&b \end{array} would cause MathJax to loop. This value prevents this from looping infinitely by limiting the number of template substitutions that can be applied to an array.

baseURL: URL: This is the base URL to use when creating links to tagged equations (via \ref{} or \eqref{}) when there is a <base> element in the document that would affect those links. You can set this value by hand if MathJax doesn’t produce the correct link. By default, it is either the URL for the current document if there is a <base> element, or an empty string if not.

formatError: (jax, err) => jax.formatError(err)

This is a function that is called when the TeX input jax identifies a syntax or other error in the TeX that it is processing. The default is to generate an <merror> MathML element with the message indicating the error that occurred. You can override the function to perform other tasks, like recording the message, replacing the message with an alternative message, or throwing the error so that MathJax will stop at that point (you can catch the error using promises or a try/catch block). Your function should return the MathML tree that is used for the error, in MathJax’s internal format. The jax.mmlFactory.create() function can be used to create such trees. For example,

jax.mmlFactory.create('mtext', {mathvariant: 'bold'}, [
  jax.mmlFactory.text('An error occurred!')
]);

would create the internal representation for

<mtext mathvariant="bold">
An error occurred!
</merror>

preFilters: []

This specifies a list of functions to run as pre-filters for the TeX input jax. Each entry is either a function, or an array consisting of a function followed by a number, which is the priority of the pre-filter (lower priorities run first). The functions are passed an object with three properties: math, giving the MathItem being processed, document giving the MathDocument for the math item, and data giving the ParseOptions object that holds the details of the input jax configuration. The pre-filters are executed when the TeX input jax is asked to parse a TeX expression, and before the TeX string is processed, so you can use a pre-filter to adjust the TeX string prior to it being parsed. The math item’s math property is the original TeX string.

See the MathJax Pre- and Post-Filters section for examples of pre-filters.

postFilters: []

This specifies a list of functions to run as post-filters for the TeX input jax. Each entry is either a function, or an array consisting of a function followed by a number, which is the priority of the pre-filter (lower priorities run first). The functions are passed an object with three properties: math, giving the MathItem being processed, document giving the MathDocument for the math item, and data giving the ParseOptions object that holds the details of the input jax configuration. The post-filters are executed when the TeX input jax has finished parsing the TeX expression and has converted it to the internal MathML format. The math item’s root property holds the root of the parsed MathML tree (the internal representation of the <math> element).

See the MathJax Pre- and Post-Filters section for examples of post-filters.

Developer Options

In addition to the options listed above, low-level options intended for developers include the following:

FindTeX: null: The FindTeX object instance that will override the default one. This allows you to create a subclass of the FindTeX class, create an instance of it, and pass that to the TeX input jax to use instead of the usual one. A null value means use the default FindTeX class and make a new instance of that.

TeX Extension Options

Several of the TeX extensions make additional options available in the tex block of your MathJax configuration. These are described below. Note that the input/tex component, and the combined components that load the TeX input jax, include a number of these extensions automatically, so some these options will be available by default.

For example, the configmacros package adds a macros block to the tex configuration block that allows you to pre-define macros for use in TeX expressions:

MathJax = {
  tex: {
    macros: {
      R: '\\mathbf{R}'
    }
  }
}

The options for the various TeX packages (that have options) are described in the links below:

Setting Options from within TeX Expressions

It is sometimes convenient to be able to change the value of a TeX or TeX extension option from within a TeX expression. For example, you might want to change the tag side for an individual expression. The setoptions extension allows you to do just that. It defines a \setOptions macro that allows you to change the values of options for the TeX parser, or the options for a given TeX package.

Because this functionality can have potential adverse consequences on a page that allows community members to enter TeX notation, this extension is not loaded by default, and can’t be loaded by \require{}. You must load it and add it to the tex package list explicitly in order to allow the options to be set. The extension has configuration parameters that allow you to control which packages and options can be modified from within a TeX expression, and you may wish to adjust those if you are using this macro in a community setting.