.. _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 `` where ``path-to-MathJax`` is replaced by the URL of the MathJax directory 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 to load MathJax. Although it is possible to load MathJax from a site other than your own web server, there are issues involved in doing so that you need to take into consideration. See the :ref:`Notes About Shared Servers ` for more details. Please do **not** link to the copy of MathJax at ``www.mathjax.org``, as we do not have the resources to act as a web service for all the sites on the web that would like to display mathematics. If you are able to run MathJax from your own server, please do so (this will probably give you better response time in any case). It is best to load MathJax in the document's ```` block, but it is also possible to load MathJax into the ```` 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 ```` section to the document, however, so be sure there is one if you are loading MathJax in the ````. It is also possible to load MathJax dynamically after the page has been prepared, for example, via a `GreaseMonkey `_ script, or using a specially prepared `bookmarklet `_. This is an advanced topic, however; see :ref:`Loading MathJax Dynamically ` for more details. Configuring MathJax =================== There are several ways to configure MathJax, but the easiest is to use the ``config/MathJax.js`` file that comes with MathJax. See the comments in that file, or the :ref:`configuration details ` section, for explanations of the meanings of the various configuration options. You can edit the ``config/MathJax.js`` file to change any of the settings that you want to customize. When you include MathJax in your page via .. code-block:: html it will load ``config/MathJax.js`` automatically as one of its first actions. Alternatively, you can configure MathJax efficiently by calling :meth:`MathJax.Hub.Config()` when you include MathJax in your page, as follows: .. code-block:: html This example includes the ``tex2jax`` preprocessor and configures it to use both the standard TeX and 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 ` section (or the comments in the ``config/MathJax.js`` file) for more information about the configuration options that you can include in the :meth:`MathJax.Hub.Config()` call. Note that if you configure MathJax using this in-line approach, the ``config/MathJax.js`` file is **not** loaded. Finally, if you would like to use several different configuration files (like ``config/MathJax.js``, but with different settings in each one), you can copy ``config/MathJax.js`` to ``config/MathJax-2.js``, or some other convenient name, and use .. code-block:: html to load the alternative configuration file ``config/MathJax-2.js`` from the MathJax ``config`` directory. In this way, you can have as many distinct configuration files as you need. .. _common-configurations: Common Configurations ===================== The following examples show configurations that are useful for some common situations. This is certainly not an exhaustive list, and there are variations possible for any of them. Again, the comments in the ``config/MathJax.js`` file can help you decide what settings to include, even if you are using the in-line configuration method. The TeX setup ------------- This example calls the ``tex2jax`` preprocessor to identify mathematics in the page by looking for TeX and LaTeX math delimiters. It uses ``$...$`` and ``\(...\)`` for in-line mathematics, while ``$$...$$`` and ``\[...\]`` mark displayed equations. Because dollar signs are used to mark mathematics, if you want to produce an actual dollar sign in your document, you must "escape" it using a slash: ``\$``. This configuration also loads the ``AMSmath`` and ``AMSsymbols`` extensions so that the macros and environments they provide are defined for use on the page. .. code-block:: javascript MathJax.Hub.Config({ extensions: ["tex2jax.js","TeX/AMSmath.js","TeX/AMSsymbols.js"], jax: ["input/TeX","output/HTML-CSS"], tex2jax: { inlineMath: [['$','$'],["\\(","\\)"]], processEscapes: true, }, }); Other extensions that you may consider adding to the `extensions` array include: ``TeX/noErrors.js``, which shows the original TeX code if an error occurs while processing the mathematics (rather than an error message), ``TeX/noUndefined.js``, which shows undefined macros names in red (rather than producing an error), and ``TeX/autobold.js``, which automatically inserts ``\boldsymbol{...}`` around your mathematics when it appears in a section of your page that is in bold. Most of the other TeX extensions are loaded automatically when needed, and so do not need to be included explicitly in your `extensions` array. See the :ref:`tex2jax configuration ` section for other configuration options for the ``tex2jax`` preprocessor, and the :ref:`TeX input jax configuration ` section for options that control the TeX input processor. The MathML setup ---------------- This example calls the ``mml2jax`` preprocessor to identify mathematics in the page that is in :term:`MathML` format, which uses ```` to indicate displayed equations, and ```` or simply ```` to mark in-line formulas. .. code-block:: javascript MathJax.Hub.Config({ extensions: ["mml2jax.js"], jax: ["input/MathML","output/HTML-CSS"] }); Note that this will work in HTML files, not just XHTML files (MathJax works with both), and that the web page need not be served with any special MIME-type. Also note that, unless you are using XHTML rather than HTML, you should not include a namespace prefix for your ```` tags; for example, you should not use ```` except in a file where you have tied the ``m`` namespace to the MathML DTD. See the :ref:`mml2jax configuration ` section for other configuration options for the ``mml2jax`` preprocessor, and the :ref:`MathML input jax configuration ` section for options that control the MathML input processor. Both TeX and MathML ------------------- This example provides for both TeX and MathML input in the same file. It calls on both the ``tex2jax`` and ``mml2jax`` preprocessors and the TeX and MathML input jax to do the job. .. code-block:: javascript MathJax.Hub.Config({ extensions: ["tex2jax.js", "mml2jax.js"], jax: ["input/TeX", "input/MathML", "output/HTML-CSS"], }); Notice that no ``tex2jax`` configuration section is included, so it uses its default options (no single dollar signs for in-line math). The majority of the code for the TeX and MathML input processors are not loaded until they are actually needed by the mathematics on the page, so if this configuration is used on a page that include only MathML, the TeX input processor will not be loaded. Thus it is reasonably efficient to specify both input processors even if only one (or neither one) is used. TeX input with MathML output ---------------------------- This example configures MathJax to use the ``tex2jax`` preprocessor and TeX input processor, but the choice of output format is determined by MathJax depending on the capabilities of the user's browser. The is performed by the ``MMLorHTML.js`` configuration file that is loaded in the `config`` array. .. code-block:: javascript MathJax.Hub.Config({ config: ["MMLorHTML.js"], extensions: ["tex2jax.js"], jax: ["input/TeX"] }); With this setup, Firefox or Internet Explorer with the `MathPlayer plugin `_ installed will use the NativeMML output processor, while all other browsers will use the HTML-CSS output processor. Since native MathML support is faster than MathJax's HTML-CSS processor, this will mean that the web pages will display faster for Firefox and IE than they would otherwise. This speed comes at the cost, however, as you are now relying on the native MathML support to render the mathematics, and that is outside of MathJax's control. There may be spacing or other display differences (compared to MathJax's HTML-CSS output) when the NativeMML output processor is used. See :ref:`MathJax Output Formats ` for more information on the NativeMML and HTML-CSS output processors. See the :ref:`MMLorHTML configuration ` section for details on the options that control the ``MMLorHTML`` configuration. MathML input and output in all browsers --------------------------------------- This example configures MathJax to look for MathML within your page, and to display it using the browser's native MathML support, if possible, or its HTML-CSS output if not. .. code-block:: javascript MathJax.Hub.Config({ config: ["MMLorHTML.js"], extensions: ["mml2jax.js"], jax: ["input/MathML"] }); Using this configuration, MathJax finally makes MathML available in all modern browsers. See the :ref:`MMLorHTML configuration ` section for details on the options that control the ``MMLorHTML`` configuration file, the :ref:`MathML configuration ` section for the options that control the MathML output processor, and the :ref:`mml2jax configuration ` section for the options that control the ``mml2jax`` preprocessor. .. _configuration: Configuration Objects ===================== The various components of MathJax, including its input and output processors, its preprocessors, its extensions, and the MathJax core, all can be configured through the ``config/MathJax.js`` file, or via a :meth:`MathJax.Hub.Config()` call (indeed, if you look closely, you will see that ``config/MathJax.js`` is itself one big call to :meth:`MathJax.Hub.Config()`). Anything that is in ``config/MathJax.js`` can be included in-line to configure MathJax. The structure that you pass to :meth:`MathJax.Hub.Config()` is a JavaScript object that includes name-value pairs giving the names of parameters and their values, with pairs separated by commas. Be careful not to include a comma after the last value, however, as some browsers (namely Internet Explorer) will fail to process the configuration if you do. The MathJax components, like the TeX input processor, have their own sections in the configuration object, labeled by the component name, and using an configuration object as its value. The object is itself a configuration object made up of name-value pairs that give the configuration options for the component. For example, .. code-block:: javascript MathJax.Hub.Config({ showProcessingMessages: false, jax: ["input/TeX", "output/HTML-CSS"], TeX: { TagSide: "left", Macros: { RR: '{\\bf R}', bold: ['{\\bf #1}',1] } } }); is a configuration that includes two settings for the MathJax Hub (one for `showProcessingMessages` and one of the `jax` array), and a configuration object for the TeX input processor. The latter includes a setting for the TeX input processor's `TagSide` option (to set tags on the left rather than the right) and a setting for `Macros`, which defines new TeX macros (in this case, two macros, one called ``\RR`` that produces a bold "R", and one called ``\bold`` that puts is argument in bold face). The ``config/MathJax.js`` file is another example that shows nearly all the configuration options for all of MathJax's components. Configuration Options by Component ================================== The individual options are explained in the following sections, which are categorized by the component they affect. .. toctree:: :maxdepth: 1 The core options .. toctree:: :maxdepth: 1 The tex2jax preprocessor options The mml2jax preprocessor options The jsMath2jax preprocessor options .. toctree:: :maxdepth: 1 The TeX input processor options The MathML input processor options The HTML-CSS output processor options The NativeMML output processor options The MMLorHTML configuration options .. toctree:: :maxdepth: 1 The MathMenu options The MathZoom options The FontWarnings options