Fetching contributors…
Cannot retrieve contributors at this time
283 lines (229 sloc) 11.6 KB

# 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 :data: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

.rst-content dl.describe > dt:first-child { margin-bottom: 0; } .rst-content dl.describe > dt + dt { margin-top: 0; border-top: none; padding-left: 6em; } .rst-content dl.describe > dt + dd { margin-top: 6px; }
.. describe:: 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.,

.. code-block:: javascript

skipHtmlTags: {'[-]': ['code', 'pre'], '[+]': ['li']}

would remove 'code' and 'pre' tags from the list, while
adding 'li' tags to the list.


.. describe:: 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.


.. describe:: 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 setting
ignoreHtmlClass: 'class2' would cause it to match an element with
class='class1 class2 class3' but not class='myclass2'.
Note that you can assign several classes by separating them by the
vertical line character (|).  For instance, with
ignoreHtmlClass: 'class1|class2' any element assigned a class of
either class1 or class2 will be skipped.  This could also
be specified by ignoreHtmlClass: 'class[12]', which matches
class followed by either a 1 or a 2.


.. describe:: 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 the skipHtmlTags
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 setting
processHtmlClass: 'class2' would cause it to match an element with
class='class1 class2 class3' but not class='myclass2'.
Note that you can assign several classes by separating them by the
vertical line character (|).  For instance, with
processHtmlClass: 'class1|class2' any element assigned a class of
either class1 or class2 will have its contents processed.
This could also be specified by processHtmlClass: 'class[12]',
which matches class followed by either a 1 or a 2.


.. describe:: 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
:meth:compile() call).  The arguments are the MathDocument in
which the error occurred, the MathItem for the expression where
it occurred, and the Error object for the uncaught error.  The
default action is to call the document's default
:meth:compileError() function, which sets :attr:math.root to a
math element containing an error message (i.e.,
$<merror><mtext>Math input error<mtext></merror>$).
You can replace this with your own function for trapping run-time
errors in the input processors.


.. describe:: 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
:meth:typeset() call).  The arguments are the MathDocument in
which the error occurred, the MathItem for the expression where
it occurred, and the Error object for the uncaught error.  The
default action is to call the document's default
:meth:typesetError() function, which sets
:attr:math.typesetRoot to a <span> element containing the
text Math output error.  You can replace this with your own
function for trapping run-time errors in the output processors.


.. describe:: renderActions: {...}

This is an object that specifies the actions to take during the
:meth:MathJax.typeset() (and its underlying
:meth:MathJax.startup.document.render() call), and the various
conversion functions, such as :meth:MathJax.tex2svg() (and their
underlying :meth:MathJax.startup.document.convert() call).  The
structure of the object is name: value pairs separated by
commas, where the name gives an identifier for each action, and
the value 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 a MathItem).  If either is an empty string, that
action is not performed.  If the function is missing, the method
name is taken from the name of the action.  The boolean value
tells whether the second function should be performed during a
:meth:convert() call (when true) or only during a
:meth:rerender() call (when false).

For example,

.. code-block:: javascript

MathJax = {
options: {
renderActions: {
compile: [MathItem.STATE.COMPILED],
metrics: [MathItem.STATE.METRICS, 'getMetrics', '', false]
}
}
};

specifies two actions, the first called compile that uses the
:meth:compile() method of the MathDocument and MathItem,
and the second called metrics that uses the :meth:getMetric()
call for the MathDocument when the document is rendered, but
does nothing during a :meth:rerender() or :meth:convert() call
or an individual MathItem.

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,
the MathItem that is being processed, and the MathDocument
in which it exists.

The default value includes actions for the main calls needed to
perform rendering of math: find, compile, metrics,
typeset, update, and reset.  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.

renderActions object, or override existing ones by re-using an
existing name from above.  See the :ref:mathml-output section for
an example of doing this.  The priority number tells where in the
list your actions will be performed.

the list.  For example, the :ref:menu-component component inserts
an action to add the menu event handlers to the math after it is
inserted into the page.



## Developer Options

.. describe:: OutputJax: null

The OutputJax object instance to use for this
MathDocument.  If you are using MathJax components, the
:ref:startup-component 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.


.. describe:: InputJax: null

The InputJax object instance to use for this
MathDocument.  If you are using MathJax components, the
:ref:startup-component 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.


.. describe:: MmlFactory: null

The MmlFactory object instance to use for creating the internal
MathML objects. This allows you to create a subclass of
MmlFactory and pass that to the document.  A null value
means use the default MmlFactory class and make a new instance
of that.


.. describe:: MathList: DefaultMathList

The MathList object class to use for managing the list of
MathItem objects associated with the MathDocument.  This
allows you to create a subclass of MathList and pass that to
the document.


.. describe:: MathItem: DefaultMathItem

The MathItem object class to use for maintaining the
information about a single expression in a MathDocument.  This
allows you to create a subclass of MathItem and pass that to
the document.  The document Handler object may define its own
subclass of MathItem and use that as the default instead.  For
example, the HTML handler uses HTMLMathItem objects for this
option.



You can’t perform that action at this time.