.. _loading:

*******************************
Loading and Configuring MathJax
*******************************

You load MathJax into a web page by including its main JavaScript file
into the page.  That is done via a ``<script>`` tag that links to the
``MathJax.js`` file.  To do that, place the following line in the ``<head>``
section of your document:

.. code-block:: html

    <script type="text/javascript" src="path-to-MathJax/MathJax.js"></script>

where ``path-to-MathJax`` is replaced by the URL of the copy of MathJax
that you are loading.  For example, if you are using the MathJax 
distributed network service, the tag might be

.. code-block:: html

    <script type="text/javascript" 
       src="http://cdn.mathjax.org/mathjax/latest/MathJax.js">
    </script>

If you have installed MathJax yourself, ``path-to-MathJax`` will be the
location of MathJax on your server, or (if you are using MathJax locally
rather than through a server) the location of that directory on your hard
disk.  For example, if the MathJax directory is at the top level of your
web server's directory hierarchy, you might use

.. code-block:: html

    <script type="text/javascript" src="/MathJax/MathJax.js"></script>

to load MathJax.

If you install MathJax on a server in a domain that is different from the
one containing the page that will load MathJax, then there are issues
involved in doing so that you need to take into consideration.  See the
:ref:`Notes About Shared Servers <cross-domain-linking>` for more details.

When you load MathJax, it is common to include additional parameters for
MathJax as part of the URL. These control MathJax's configuration, and are
discussed in the :ref:`Configuration Objects <configuration>` section.  A
typical invocation of MathJax would be

.. code-block:: html

    <script type="text/javascript" 
       src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
    </script>

which loads MathJax with a configuration file that includes everything you 
need in order to enter mathematics in either TeX, LaTeX, or MathML 
notation, and produces output using MathML if the browser supports that, 
or HTML-with-CSS otherwise.  If you **don't** load an explicit 
configuration file, you will need to include an in-line configuration 
block in order to tell MathJax how to read and display the mathematics on 
your pages.  See the section below for details.

It is best to load MathJax in the document's ``<head>`` block, but it
is also possible to load MathJax into the ``<body>`` section, if
needed.  If you do this, load it as early as possible, as
MathJax will begin to load its components as soon as it is included in
the page, and that will help speed up the processing of the
mathematics on your page.  MathJax does expect there to be a
``<head>`` section to the document, however, so be sure there is one
if you are loading MathJax in the ``<body>``.

It is also possible to load MathJax dynamically after the page has
been prepared, for example, via a `GreaseMonkey
<http://www.greasespot.net/>`_ script, or using a specially prepared
`bookmarklet <http://en.wikipedia.org/wiki/Bookmarklet>`_.  This is an
advanced topic, however; see :ref:`Loading MathJax Dynamically
<ajax-mathjax>` for more details.

.. _loading-CDN:

Loading MathJax from the CDN
============================

MathJax is now available as a web service from ``cdn.mathjax.org``, so you 
can obtain MathJax from there without needing to install it on your own 
server.  The CDN is part of a distributed "cloud" network, so it is 
handled by servers around the world.  That means that you should get access 
to a server geographically near you, for a fast, reliable connection.

The CDN hosts the most current version of MathJax, as well as older 
versions, so you can either link to a version that stays up-to-date as 
Mathjax is improved, or you can stay with one of the release versions so 
that you pages always use the same version of MathJax.

The URL that you use to obtain MathJax determines the version that you 
get.  The CDN has the following directory structure:

.. code-block::  sh

    mathjax/         # project-name
       1.0-latest/
       1.1-beta/     # temporary
       1.1-latest/   # the 1.1 release with any ciritical patches
       ...
       latest/       # the most current version (1.1-latest in this case)

Each directory corresponds to an official MathJax release; however,
hotfixes (urgent bug fixes) will be applied in each release branch as
necessary, even if new releases are not prepared.  In other words,
``1.1-latest`` will initially point to v1.1, but over time may be updated
with patches that would correspond to releases that might be numbers 1.1a,
1.1b, etc., even if such releases are not actually prepared for
distribution (they likely won't be).

We may occasionally introduce directories for betas, as indicated above,
but they will be temprorary, and will be removed after the official
release.

To load from a particular release, use the directory for that release.  
For example,

.. code-block:: html

    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/1.1-latest/MathJax.js"></script>

will load the stable v1.1 version, even if we release v1.2 or other later 
versions, while

.. code-block:: html

    <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>

will always be the most current stable release, so it will go from v1.1 to 
v1.2 automatically when that is released.  Note that all the versions 
available on the CDN are stable versions; the development version is not 
hosted on the CDN.

The use of ``cdn.mathjax.org`` is governed by its `terms of service
<http://www.mathjax.org/download/mathjax-cdn-terms-of-service/>`_, so be
sure to read that before linking to the MathJax CDN server.


Configuring MathJax
===================

There are two ways to configure MathJax:  via a configuration file, or by 
including configuration commands wthin the web page itself.  These can be 
used independently, or in combination.  For example, you can load a main 
pre-defined configuration file, but include in-line commands to 
adjust the configuration to your needs.

Note that you must use at least one of these two forms of configuration.
Unlike earlier versions of MathJax, version 1.1 does not load a default
configuration file.  If you have been using version 1.0's
``config/MathJax.js`` for your configuration, you will need to load that 
configuration file explicitly via a ``config`` parameter, as described 
below.


.. _config-files:

Using a configuration file
==========================

The first way to configure MathJax is to use a configuration file.
MathJax comes with a number of pre-defined configuration files, which are 
stored in the ``MathJax/config`` directory.  Among these are the following

.. describe:: default.js

    A file that contains nearly all the configuration options with comments
    describing them, which you can edit to suit your needs.

.. describe:: TeX-AMS-MML_HTMLorMML.js

    Allows math to be specified in TeX, LaTeX, or MathML notation, with the
    `AMSmath` and `AMSsymbols` packages included, producing output using
    MathML if the browser supports it, and HTML-with-CSS otherwise.

.. describe:: TeX-AMS_HTML.js

    Allows math to be specified in TeX or LaTeX notation (with the 
    `AMSmath` and `AMSsymbols` packages included, and produces output 
    using the HTML-CSS output processor.

.. describe:: MML_HTMLorMML.js

    Allows math to be specified using MathML notation, and produces MathML 
    output if the browser supports it, or HTML-CSS output otherwise.

.. describe:: Accessible.js

    Essentially the same as ``TeX-AMS-MML_HTMLorMML``, but with some 
    settings specified to make MathJax work better with assistive 
    technology (for the visually impaired).  This includes setting the 
    zoom trigger to be a double-click, and removing the MathMenu in 
    Internet Explorer (which can interfere with some screen readers).

The first of these is a file that you can edit to suit your needs.  It 
contains nearly all the configuration options that MathJax allows, and has 
comments explaining them.  The others are what are called `combined 
configuration files`, which not only configure MathJax, but also pre-load the 
various files that the configuration requires.  (The contents of these 
files are explained in more detail in the `Common Configurations 
<common-configurations>`_ section.)

Usually, MathJax loads its components only when they are needed, but each
component will require a separate file to be loaded, and that can cause
delays before the mathematics is displayed.  The combined configuration
files load the majority of the needed files all as one large file, reducing
the number of network requests that are needed.  That means you will
probably be getting the componets that MathJax needs faster than you would
without the combined file, but you may be loading components that are never
actually used; that is the trade off.

Each of the combined configuration files comes in two flavors:  the ones 
listed above, which only configure the output processors but don't include 
the main code, and a "full" version, that also includes the complete 
output processors.  For example, with ``TeX-AMS_HTML.js`` and 
``TeX-AMS_HTML-full.js``, the latter includes the complete HTML-CSS output 
processor.  The "full" configuration files are substantially larger (on 
the order of 70KB), so you need to decide whether it is worth loading the 
full configuraiton for your pages.

If most of your pages include mathematics, then it is to your advantage to
load the full version, but if you are including MathJax in a theme file for
a blog or wiki that only includes mathematics occasionally, then perhaps it
is better to use the standard configuration instead, in which case the
output processors are only loaded when they are actually needed, saving the
loading of 70KB for pages that don't.  Of course, if your server is
configured to compress the files it sends, the difference between the two
is considerably reduced.  Furthermore, most browsers will cache the
javascript they receive, so the download cost should only occur on the
first page a user views, so it may be best to use the "full" version after
all.  Note, however, that mobile devices sometimes have limits on the size
of files that they cache, so they may be forced to download the
configuration on every page.  You need to keep these issues in mind as you
decide on which configuration to use.

To load a configuration file, use ``config=filename`` (where ``filename``
is one of the names above without the ``.js``) as a parameter to the URL of
the ``MathJax.js`` file.  For example

.. code-block:: html

    <script type="text/javascript" 
       src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
    </script>

loads the ``config/TeX-AMS-MML_HTMLorMML.js`` configuration file from the 
MathJax distributed network service.

You can include more than one configuration file by separating them with
commas.  For example, if you have a locally defined configuration file
called ``MathJax/config/local/local.js`` that modifies the settings for the
``TeX-AMS_HML`` configuration, defines some new TeX macros, and so on, you
can use

.. code-block:: html

    <script type="text/javascript" 
       src="path-to-MathJax/MathJax.js?config=TeX-AMS_HTML,local/local">
    </script>

to first load the main configuraiton, then the local modifications.  You 
can also load MathJax from the CDN and a local configuration from your own 
server:

.. code-block:: html

    <script type="text/javascript" 
       src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML,http://myserver.com/MathJax/config/local/local.js">
    </script>


Using in-line configuration options
===================================

The second way to configure MathJax is through `in-line configuration`, 
that puts the configuration options within the web page itself.  This 
process has changed in version 1.1 to make it compatible with HTML5.  
Earlier versions of MathJax had in-line configuration included within the 
content of the ``<script>`` tag that loads ``MathJax.js``, but HTML5 makes 
it illegal to have content for a script with a ``src`` attribute.

MathJax solves this problem by using separate ``<script>`` tags to perform 
configuration for MathJax.  Because MathJax starts its configuration 
process as soon as it is loaded, the configuration script must come 
**before** the script tag that loads ``MathJax.js`` itself.  You do this 
by including a ``<script>`` with ``type="text/x-mathjax-config"``, whose
content will be run when MathJax performs its configuration.  Generally, 
this script will include a :meth:`MathJax.Hub.Config()` call to perform 
MathJax configuration, but it can also include other MathJax commands, 
such as registering signal actions, or any JavaScript commands that you 
want.  You can have as many such script tags as you want, and MathJax will 
process them in order as they appear in the document.

For instance,

.. code-block:: html

    <script type="text/x-mathjax-config">
      MathJax.Hub.Config({
        extensions: ["tex2jax.js"],
        jax: ["input/TeX", "output/HTML-CSS"],
        tex2jax: {
          inlineMath: [ ['$','$'], ["\\(","\\)"] ],
          displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
          processEscapes: true
        },
        "HTML-CSS": { availableFonts: ["TeX"] }
      });
    </script>
    <script type="text/javascript" src="path-to-MathJax/MathJax.js">

This example includes the `tex2jax` preprocessor and configures it to use
both the standard :term:`TeX` and :term:`LaTeX` math delimiters.  It uses
the `TeX` input processor and the `HTML-CSS` output processor, and forces the
HTML-CSS processor to use the TeX fonts rather that other locally installed
fonts (e.g., :term:`STIX` fonts).  See the :ref:`configuration options
<configuration>` section (or the comments in the ``config/default.js``
file) for more information about the configuration options that you can
include in the :meth:`MathJax.Hub.Config()` call.  Note that this 
configuration does **not** load any pre-defined configuration file.

Note that you can combine in-line configuration with file-based 
configuration, simply include ``text/x-mathjax-config`` scripts as above, 
but also include ``config=filename`` when you load the ``MathJax.js`` 
file.  For example, the `tex2jax` preprocessor does **not** the TeX 
single-dollar in-line math delimiters by default.  You can load one of the 
pre-defined configuration files that include the TeX preprocessor, and use 
an in-line configuration block to enable the single-dollar signs:

.. code-block:: html

    <script type="text/x-mathjax-config">
      MathJax.Hub.Config({
        tex2jax: {
          inlineMath: [ ['$','$'], ["\\(","\\)"] ],
          processEscapes: true
        }
      });
    </script>
    <script type="text/javascript" src="path-to-MathJax/MathJax.js?config=TeX-AMS_HTML">
    </script>


.. _delayStartupUntil:

Configuring MathJax after it is loaded
======================================

Because MathJax begins its configuration process immediately after it is
loaded (so that it can start loading files as quickly as it can), the
configuration blocks for MathJax must come before ``MathJax.js`` is loaded,
so they will be available to MathJax when it starts up.  There are
situations, however, when you might want to put off configuring MathJax
until later in the page.

One such situation is when you have a site that loads MathJax as part of a
theme or template, but want to be able to modify the configuration on
specific pages of the site.  To accomplish this, you need to ask MathJax 
to delay its startup configuration until some later time.  MathJax uses 
the ``delayStartupUntil`` parameter to control the timing of the startup 
sequence.  By default, it is set to ``none``, meaning there is no delay 
and MathJax starts configuration right away.  

You can set ``delayStartupUntil=onload`` in order to prevent MathJax from
continuing its startup process until the page's onLoad handler fires.  This
allows MathJax to find the ``text/x-mathjax-config`` blocks that occur
anywhere on the page, not just the ones that appear above the ``<script>``
that loads ``MathJax.js``.  It also means that MathJax will not begin 
loading any of the files that it needs until then as well, which may delay 
the displaying of your mathematics, since the onLoad handler doesn't 
execute until all the images and other media are available.  (If you have 
used a combined configuration file, however, it already includes all the 
main files that MathJax needs, so there is not much loss in delaying the 
startup.)

You can set ``delayStartupUntil=configured`` in order to delay the startup 
configuration until the :meth:`MathJax.Hub.Configured()` method is 
called.  This allows you to delay startup until later on the page, but 
then restart MathJax configuration process as soon as possible rather than 
waiting for the entire page to load.  For example, you could use

.. code-block:: html

    <script type="text/javascript"
       src="path-to-MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML&delayStartupUntil=configured">
    </script>

in your theme's header file, and

.. code-block:: html

    <script type="text/javascript">
      MathJax.Hub.Configured()
    </script>

in its footer, so that MathJax will delay setting up until the footer is 
reached, but will not have to wait until images and other files are 
laoded.  If you have ``text/x-mathjax-config`` script tags within the main 
body of the document, MathJax will read and process those before 
continuing its startup.  In this way you can use a default configuration 
that can be modified on a page-by-page basis.


Details of the MathJax configuration process
============================================

Since there are a number of different ways to configure MathJax, it is 
important to know how they interact.  The configuration process is the 
following:

1.  Process any configuration file explicitly specified as a script parameter.
2.  Process the in-line script body (deprecated), if present.
3.  If delayed startup is requested, wait for the indicated signal.
4.  Process ``text/x-mathjax-config`` config blocks.  
5.  Process any config files queued in the configuration's `config` array 
    by earlier config code.

Note that ``text/x-mathjax-config`` script blocks must either precede the
``MathJax.js`` script element, or startup must be delayed.  Otherwise, blocks
that follow the ``MathJax.js`` script element may or may not be available 
when MathJax runs, and browser-dependent erratic behavior will result.


