280 lines
12 KiB
ReStructuredText
280 lines
12 KiB
ReStructuredText
.. _configure-hub:
|
|
|
|
******************************
|
|
The Core Configuration Options
|
|
******************************
|
|
|
|
The options below control the MathJax Hub, and so determine the code
|
|
behavior of MathJax. They are given with their default values.
|
|
|
|
.. describe:: jax: ["input/TeX","output/HTML-CSS"]
|
|
|
|
A comma-separated list of input and output jax to initialize at
|
|
startup. Their main code is loaded only when they are actually
|
|
used, so it is not inefficient to include jax that may not
|
|
actually be used on the page. These are found in the ``MathJax/jax``
|
|
directory.
|
|
|
|
.. describe:: extensions: []
|
|
|
|
A comma-separated list of extensions to load at startup. The
|
|
default directory is ``MathJax/extensions``. The ``tex2jax`` and
|
|
``mml2jax`` preprocessors can be listed here, as well as a
|
|
``FontWarnings`` extension that you can use to inform your user
|
|
that mathematics fonts are available that they can download to
|
|
improve their experience of your site.
|
|
|
|
.. describe:: config: []
|
|
|
|
A comma-separated list of configuration files to load when MathJax
|
|
starts up, e.g., to define local macros, etc., and there is a
|
|
sample config file named ``config/local/local.js``. The default
|
|
directory is the `MathJax/config` directory. The ``MMLorHTML.js``
|
|
configuration is one such configuration file, and there are a
|
|
number of other pre-defined configurations (see :ref:`Using a
|
|
configuration file <config-files>` for more details).
|
|
|
|
.. describe:: styleSheets: []
|
|
|
|
A comma-separated list of CSS stylesheet files to be loaded when
|
|
MathJax starts up. The default directory is the `MathJax/config`
|
|
directory.
|
|
|
|
.. describe:: styles: {}
|
|
|
|
CSS styles to be defined dynamically at startup time. These are
|
|
in the form `selector:rules` (see :ref:`CSS Style Objects
|
|
<css-style-objects>` for complete details).
|
|
|
|
.. describe:: preJax: null and postJax: null
|
|
|
|
Patterns to remove from before and after math script tags. If you
|
|
are not using one of the preprocessors, you need to insert
|
|
something extra into your HTML file in order to avoid a bug in
|
|
Internet Explorer. IE removes spaces from the DOM that it thinks
|
|
are redundant, and since a ``<script>`` tag usually doesn't add
|
|
content to the page, if there is a space before and after a
|
|
MathJax ``<script>`` tag, IE will remove the first space. When
|
|
MathJax inserts the typeset mathematics, this means there will be
|
|
no space before it and the preceding text. In order to avoid
|
|
this, you should include some "guard characters" before or after
|
|
the math SCRIPT tag; define the patterns you want to use below.
|
|
Note that these are used as part of a regular expression, so you
|
|
will need to quote special characters. Furthermore, since they
|
|
are javascript strings, you must quote javascript special
|
|
characters as well. So to obtain a backslash, you must use ``\\``
|
|
(doubled for javascript). For example, ``"\\["`` represents the
|
|
pattern ``\[`` in the regular expression, or ``[`` in the text of
|
|
the web page. That means that if you want an actual backslash in
|
|
your guard characters, you need to use ``"\\\\"`` in order to get
|
|
``\\`` in the regular expression, and ``\`` in the actual text.
|
|
If both ``preJax`` and ``postJax`` are defined, both must be
|
|
present in order to be removed.
|
|
|
|
See also the ``preRemoveClass`` comments below.
|
|
|
|
Examples:
|
|
|
|
``preJax: "\\\\\\\\\"`` makes a double backslash the ``preJax`` text
|
|
|
|
``preJax: "\\[\\[", postJax: "\\]\\]"`` makes it so jax
|
|
scripts must be enclosed in double brackets.
|
|
|
|
.. describe:: preRemoveClass: "MathJax_Preview"
|
|
|
|
This is the CSS class name for math previews that will be removed
|
|
preceding a MathJax SCRIPT tag. If the tag just before the
|
|
MathJax ``<script>`` tag is of this class, its contents are
|
|
removed when MathJax processes the ``<script>`` tag. This allows
|
|
you to include a math preview in a form that will be displayed
|
|
prior to MathJax performing its typesetting. It also avoids the
|
|
Internet Explorer space-removal bug, and can be used in place of
|
|
``preJax`` and ``postJax`` if that is more convenient.
|
|
|
|
For example
|
|
|
|
.. code-block:: html
|
|
|
|
<span class="MathJax_Preview">[math]</span><script type="math/tex">...</script>
|
|
|
|
would display "[math]" in place of the math until MathJax is able
|
|
to typeset it.
|
|
|
|
See also the ``preJax`` and ``postJax`` comments above.
|
|
|
|
.. describe:: showProcessingMessages: true
|
|
|
|
This value controls whether the `Processing Math: nn%` messages are
|
|
displayed in the lower left-hand corner. Set to ``false`` to
|
|
prevent those messages (though file loading and other messages
|
|
will still be shown).
|
|
|
|
.. describe:: messageStyle: "normal"
|
|
|
|
This value controls the verbosity of the messages in the lower
|
|
left-hand corner. Set it to ``"none"`` to eliminate all messages,
|
|
or set it to ``"simple"`` to show "Loading..." and "Processing..."
|
|
rather than showing the full file name or the percentage of the
|
|
mathematics processed.
|
|
|
|
.. describe:: displayAlign: "center" and displayIndent: "0em"
|
|
|
|
These two parameters control the alignment and shifting of
|
|
displayed equations. The first can be ``"left"``, ``"center"``,
|
|
or ``"right"``, and determines the alignment of displayed
|
|
equations. When the alignment is not ``"center"``, the second
|
|
determines an indentation from the left or right side for the
|
|
displayed equations.
|
|
|
|
|
|
.. describe:: delayStartupUntil: "none"
|
|
|
|
Normally MathJax will perform its startup commands (loading of
|
|
configuration, styles, jax, and so on) as soon as it can. If you
|
|
expect to be doing additional configuration on the page, however,
|
|
you may want to have it wait until the page's onload handler is
|
|
called. If so, set this to ``"onload"``. You can also set this to
|
|
``"configured"``, in which case, MathJax will delay its startup until
|
|
you explicitly call :meth:`MathJax.Hub.Configured()`. See
|
|
:ref:`Configuring MathJax after it is loaded <delayStartupUntil>` for more
|
|
details.
|
|
|
|
.. describe:: skipStartupTypeset: false
|
|
|
|
Normally MathJax will typeset the mathematics on the page as soon
|
|
as the page is loaded. If you want to delay that process, in
|
|
which case you will need to call :meth:`MathJax.Hub.Typeset()`
|
|
yourself by hand, set this value to ``true``.
|
|
|
|
.. describe:: elements: []
|
|
|
|
This is a list of DOM element ID's that are the ones to process for
|
|
mathematics when any of the Hub typesetting calls (``Typeset()``, ``Process()``,
|
|
``Update()``, etc.) are called with no element specified, and during
|
|
MathJax's initial typesetting run when it starts up. This lets you
|
|
restrict the processing to particular containers rather than scanning
|
|
the entire document for mathematics. If none are supplied, the complete
|
|
document is processed.
|
|
|
|
.. describe:: positionToHash: true
|
|
|
|
Since typesetting usually changes the vertical dimensions of the
|
|
page, if the URL contains an anchor position, then after the page
|
|
is typeset, you may no longer be positioned at the correct
|
|
position on the page. MathJax can reposition to that location
|
|
after it completes its initial typesetting of the page. This
|
|
value controls whether MathJax will reposition the browser to the
|
|
``#hash`` location from the page URL after typesetting for the page.
|
|
|
|
|
|
.. describe:: showMathMenu: true
|
|
showMathMenuMSIE: true
|
|
|
|
These control whether to attach the MathJax contextual menu to the
|
|
expressions typeset by MathJax. Since the code for handling
|
|
MathPlayer in Internet Explorer is somewhat delicate, it is
|
|
controlled separately via ``showMathMenuMSIE``, but the latter is
|
|
now deprecated in favor of the MathJax contextual menu settings
|
|
for MathPlayer (see below).
|
|
|
|
If ``showMathMenu`` is ``true``, then right-clicking (on Windows
|
|
or Linux) or control-clicking (on Mac OS X) will produce a MathJax
|
|
menu that allows you to get the source of the mathematics in
|
|
various formats, change the size of the mathematics relative to
|
|
the surrounding text, get information about MathJax, and configure
|
|
other MathJax settings.
|
|
|
|
Set this to ``false`` to disable the menu. When ``true``, the
|
|
``MathMenu`` configuration block determines the operation of the
|
|
menu. See :ref:`the MathMenu options <configure-MathMenu>` for
|
|
more details.
|
|
|
|
These values used to be listed in the separate output jax, but
|
|
have been moved to this more central location since they are
|
|
shared by all output jax. MathJax will still honor their values
|
|
from their original positions, if they are set there.
|
|
|
|
.. describe:: menuSettings: { ... }
|
|
|
|
This block contains settings for the mathematics contextual menu
|
|
that act as the defaults for the user's settings in that menu.
|
|
The possible values are:
|
|
|
|
.. describe:: zoom: "None"
|
|
|
|
This indicates when typeset mathematics should be zoomed. It
|
|
can be set to ``"None"``, ``"Hover"``, ``"Click"``, or
|
|
``"Double-Click"`` to set the zoom trigger.
|
|
|
|
.. describe:: CTRL: false, ALT: false, CMD: false, Shift: false
|
|
|
|
These values indicate which keys must be pressed in order for
|
|
math zoom to be triggered. For example, if ``CTRL`` is set to
|
|
``true`` and ``zoom`` is ``"Click"``, then math will be zoomed
|
|
only when the user control-clicks on mathematics (i.e., clicks
|
|
while holding down the `CTRL` key). If more than one is
|
|
``true``, then all the indicated keys must be pressed for the
|
|
zoom to occur.
|
|
|
|
.. describe:: zscale: "200%"
|
|
|
|
This is the zoom scaling factor, and it can be set to any of
|
|
the values available in the `Zoom Factor` menu of the
|
|
`Settings` submenu of the contextual menu.
|
|
|
|
.. describe:: context: "MathJax"
|
|
|
|
This controls what contextual menu will be presented when a
|
|
right click (on a PC) or CTRL-click (on the Mac) occurs over a
|
|
typeset equation. When set to ``"MathJax"``, the MathJax
|
|
contextual menu will appear; when set to ``"Browser"``, the
|
|
browser's contextual menu will be used. For example, in
|
|
Internet Explorer with the MathPlayer plugin, if this is set
|
|
to ``"Browser"``, you will get the MathPlayer contextual menu
|
|
rather than the MathJax menu.
|
|
|
|
.. describe:: texHints: true
|
|
|
|
This controls whether the "Show Source" menu item includes
|
|
special class names that help MathJax to typeset the
|
|
mathematics that was produced by the TeX input jax. If these
|
|
are included, then you can take the output from "Show Source"
|
|
and put it into a page that uses MathJax's MathML input jax
|
|
and expect to get the same results as the original TeX.
|
|
(Without this, there may be some spacing differences.)
|
|
|
|
There are also settings for ``format``, ``renderer``, ``font``,
|
|
``mpContext``, and ``mpMouse``, but these are maintained by
|
|
MathJax and should not be set by the page author.
|
|
|
|
.. describe:: errorSettings: { ... }
|
|
|
|
This block contains settings that control how MathJax responds to
|
|
unexpected errors while processing mathematical equations. Rather
|
|
than simply crash, MathJax can report an error and go on. The
|
|
options you can set include:
|
|
|
|
.. describe:: message: ["[Math Processing Error]"]
|
|
|
|
This is an HTML snippet that will be inserted at the location
|
|
of the mathematics for any formula that causes MathJax to
|
|
produce an internal error (i.e., an error in the MathJax code
|
|
itself). See the :ref:`description of HTML snippets
|
|
<html-snippets>` for details on how to represent HTML code in
|
|
this way.
|
|
|
|
.. describe:: style: {color:"#CC0000", "font-style":"italic"}
|
|
|
|
This is the CSS style description to use for the error
|
|
messages produced by internal MathJax errors. See the section
|
|
on :ref:`CSS style objects <css-style-objects>` for details on
|
|
how these are specified in JavaScript.
|
|
|
|
.. describe:: v1.0-compatible: true
|
|
|
|
This controls whether MathJax issues the warning about not having an
|
|
explicit configuration in the event that the `jax` array is empty
|
|
after configuration is complete. If you really intend that array to
|
|
be empty, set this flag to ``false``. Note that setting this to false
|
|
does **not** cause a default configuration file to be loaded.
|