Document Options
The options below control the operation of the MathDocument
object
created by MathJax to process the mathematics in your web page. They
are listed with their default values. To set any of these options,
include an options
section in your MathJax
global object.
The Configuration Block
MathJax = {
options: {
skipHtmlTags: [ // HTML tags that won't be searched for math
'script', 'noscript', 'style', 'textarea', 'pre',
'code', 'annotation', 'annotation-xml'
],
includeHtmlTags: { // HTML tags that can appear within math
br: '\n', wbr: '', '#comment': ''
},
ignoreHtmlClass: 'tex2jax_ignore', // class that marks tags not to search
processHtmlClass: 'tex2jax_process', // class that marks tags that should be searched
compileError: function (doc, math, err) {doc.compileError(math, err)},
typesetError: function (doc, math, err) {doc.typesetError(math, err)},
renderActions: {...}
}
};
Option Descriptions
- skipHtmlTags: ['script', 'noscript', 'style', 'textarea',
- 'pre', 'code', 'annotation', 'annotation-xml']
This array lists the names of the tags whose contents should not be processed by MathJaX (other than to look for ignore/process classes as listed below). You can add to (or remove from) this list to prevent MathJax from processing mathematics in specific contexts. E.g.,
skipHtmlTags: {'[-]': ['code', 'pre'], '[+]': ['li']}
would remove
'code'
and'pre'
tags from the list, while adding'li'
tags to the list.
- includeHtmlTags: {br: '\n', wbr: '', '#comment': ''}
This object specifies what tags can appear within a math expression, and what text to replace them by within the math. The default is to allow
<br>
, which becomes a newline, and<wbr>
and HTML comments, which are removed entirely.
- ignoreHtmlClass: 'mathjax_ignore'
This is the class name used to mark elements whose contents should not be processed by MathJax (other than to look for the
processHtmlClass
pattern below). Note that this is a regular expression, and so you need to be sure to quote any regexp special characters. The pattern is inserted into one that requires your pattern to match a complete word, so settingignoreHtmlClass: 'class2'
would cause it to match an element withclass='class1 class2 class3'
but notclass='myclass2'
. Note that you can assign several classes by separating them by the vertical line character (|
). For instance, withignoreHtmlClass: 'class1|class2'
any element assigned a class of eitherclass1
orclass2
will be skipped. This could also be specified byignoreHtmlClass: 'class[12]'
, which matchesclass
followed by either a1
or a2
.
- processHtmlClass: 'mathjax_process'
This is the class name used to mark elements whose contents should be processed by MathJax. This is used to restart processing within tags that have been marked as ignored via the
ignoreHtmlClass
or to cause a tag that appears in theskipHtmlTags
list to be processed rather than skipped. Note that this is a regular expression, and so you need to be sure to quote any regexp special characters. The pattern is inserted into one that requires your pattern to match a complete word, so settingprocessHtmlClass: 'class2'
would cause it to match an element withclass='class1 class2 class3'
but notclass='myclass2'
. Note that you can assign several classes by separating them by the vertical line character (|
). For instance, withprocessHtmlClass: 'class1|class2'
any element assigned a class of eitherclass1
orclass2
will have its contents processed. This could also be specified byprocessHtmlClass: 'class[12]'
, which matchesclass
followed by either a1
or a2
.
- compileError: function (doc, math, err) {doc.compileError(math, err)}
This is the function called whenever there is an uncaught error while an input jax is running (i.e., during the document’s
compile()
call). The arguments are theMathDocument
in which the error occurred, theMathItem
for the expression where it occurred, and theError
object for the uncaught error. The default action is to call the document’s defaultcompileError()
function, which setsmath.root
to a math element containing an error message (i.e.,<math><merror><mtext>Math input error<mtext></merror></math>
). You can replace this with your own function for trapping run-time errors in the input processors.
- typesetError: function (doc, math, err) {doc.typesetError(math, err)}
This is the function called whenever there is an uncaught error while an output jax is running (i.e., during the document’s
typeset()
call). The arguments are theMathDocument
in which the error occurred, theMathItem
for the expression where it occurred, and theError
object for the uncaught error. The default action is to call the document’s defaulttypesetError()
function, which setsmath.typesetRoot
to a<span>
element containing the textMath output error
. You can replace this with your own function for trapping run-time errors in the output processors.
- renderActions: {...}
This is an object that specifies the actions to take during the
MathJax.typeset()
(and its underlyingMathJax.startup.document.render()
call), and the various conversion functions, such asMathJax.tex2svg()
(and their underlyingMathJax.startup.document.convert()
call). The structure of the object isname: value
pairs separated by commas, where thename
gives an identifier for each action, and thevalue
is an array consisting of a number and zero, one, or two functions, followed optionally by a boolean value.The number gives the priority of the action (lower numbers are executed first when the actions are performed). The first function gives the action to perform when a document is rendered as a whole, and the second a function to perform when an individual expression is converted or re-rendered. These can be given either as an explicit function, or as a string giving the name of a method to call (the first should be a method of a
MathDocument
, and the second of aMathItem
). If either is an empty string, that action is not performed. If the function is missing, the method name is taken from thename
of the action. The boolean value tells whether the second function should be performed during aconvert()
call (when true) or only during arerender()
call (when false).For example,
MathJax = { options: { renderActions: { compile: [MathItem.STATE.COMPILED], metrics: [MathItem.STATE.METRICS, 'getMetrics', '', false] } } };
specifies two actions, the first called
compile
that uses thecompile()
method of theMathDocument
andMathItem
, and the second calledmetrics
that uses thegetMetric()
call for theMathDocument
when the document is rendered, but does nothing during arerender()
orconvert()
call or an individualMathItem
.If the first function is given explicitly, it should take one argument, the
MathDocument
on which it is running. If the second function is given explicitly, it should take two arguments, theMathItem
that is being processed, and theMathDocument
in which it exists.The default value includes actions for the main calls needed to perform rendering of math:
find
,compile
,metrics
,typeset
,update
, andreset
. These find the math in the document, call the input jax on the math that was located, obtain the metric information for the location of the math, call the output jax to convert the internal format to the output format, insert the output into the document, and finally reset the internal flags so that a subsequent typesetting action will process properly.You can add your own actions by adding new named actions to the
renderActions
object, or override existing ones by re-using an existing name from above. See the MathML Support section for an example of doing this. The priority number tells where in the list your actions will be performed.Loading extensions may cause additional actions to be inserted into the list. For example, the ui/menu component inserts an action to add the menu event handlers to the math after it is inserted into the page.
Developer Options
- OutputJax: null
The
OutputJax
object instance to use for thisMathDocument
. If you are using MathJax components, the startup component will create this automatically. If you are writing a Node application accessing MathJax code directly, you will need to create the output jax yourself and pass it to the document through this option.
- InputJax: null
The
InputJax
object instance to use for thisMathDocument
. If you are using MathJax components, the startup component will create this automatically. If you are writing a Node application accessing MathJax code directly, you will need to create the input jax yourself and pass it to the document through this option.
- MmlFactory: null
The
MmlFactory
object instance to use for creating the internal MathML objects. This allows you to create a subclass ofMmlFactory
and pass that to the document. Anull
value means use the defaultMmlFactory
class and make a new instance of that.
- MathList: DefaultMathList
The
MathList
object class to use for managing the list ofMathItem
objects associated with theMathDocument
. This allows you to create a subclass ofMathList
and pass that to the document.
- MathItem: DefaultMathItem
The
MathItem
object class to use for maintaining the information about a single expression in aMathDocument
. This allows you to create a subclass ofMathItem
and pass that to the document. The documentHandler
object may define its own subclass ofMathItem
and use that as the default instead. For example, the HTML handler usesHTMLMathItem
objects for this option.