## File: configuration.rst

package info (click to toggle)
mathjax-docs 2.7+20171212-1
 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493 .. _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 copy of MathJax that you are loading. For example, if you are using cdnjs _ as a distributed network service, the tag might be .. code-block:: html 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 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  for more details. When you load MathJax, it is common to request a specific configuration file as discussed in the section on :ref:Using a Configuration File  below, and in more detail in the :ref:Common Configurations  section. A typical invocation of MathJax would be .. code-block:: html 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 well enough, 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 on :ref:Using In-line Configuration Options  for details. 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. .. _loading-CDN: Loading MathJax from a CDN ========================== MathJax is available as a web service from various free CDN providers, so you can obtain MathJax from there without needing to install it on your own server. .. warning:: We retired our self-hosted CDN at cdn.mathjax.org in April, 2017. We recommend using cdnjs.com _ which uses the same provider. The use of cdn.mathjax.org was governed by its terms of service _. A 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. Most CDN services offer several versions of MathJax. For example, cdnjs hosts all tagged versions since v1.1 so you can link to the version you prefer. .. note:: Some CDN providers :ref:on our list  offer a "rolling release" link, i.e, a link that updates to each newer version of MathJax upon release. The URL that you use to obtain MathJax determines the version that you get. For example, cdnjs uses a URL that includes the version tag so you can load the current version via .. code-block:: sh https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js # the 2.7.2 release Pre-releases are also available on cdnjs. .. note:: If you wish to use the development version of MathJax, you will need to install your own copy; see :ref:Installing and Testing MathJax  for information on how to do that. Alternatively, you can load the develop branch via rawgit.com . If you wish to use a CDN but use your own configuration file rather than one of the pre-defined ones, see the information at the end of the :ref:Using a Local Configuration File  section below. Configuring MathJax =================== There are two ways to configure MathJax: via a configuration file, or by including configuration commands within 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 MathJax v1.0, version 1.1 and higher 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 easiest way to configure MathJax is to use a configuration file. MathJax comes with a number of pre-defined and pre-combined configuration files, which are stored in the MathJax/config directory. The contents of these files are explained in more detail in the :ref:Common Configurations  section. Considerations for using combined configuration files ----------------------------------------------------- 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 components 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_CHTML.js and TeX-AMS_CHTML-full.js, the latter includes the complete CommonHTML output processor. The "full" configuration files are substantially larger (on the order of 70KB more), so you need to decide whether it is worth loading the full configuration 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 older 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 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 to first load the main configuration, then the local modifications. .. _local-config-files: Using a local configuration file with a CDN =========================================== You can load MathJax from a CDN provider but still use a configuration from your own local server. For example, suppose you have a configuration file called local.js on your own server, in a directory called MathJax/config/local. Then you can load MathJax from a CDN and still use your configuration file as follows: .. code-block:: html Because the local.js file is not on the CDN server, you must give the complete URL to the local configuration file. Note that you also have to edit the :meth:loadComplete() call that is at the bottom of the configuration file to change it from [MathJax]/config/local/local.js to the complete URL as you give it in the config parameter. In the example above, it would be .. code-block:: javascript MathJax.Ajax.loadComplete("http://myserver.com/MathJax/config/local/local.js"); That is because the [MathJax] in the original URL refers to the root directory where MathJax.js was loaded, which is on the CDN, not your local server, and so you need to tell MathJax the actual location of your configuration file. .. _inline-config: Using in-line configuration options =================================== The second way to configure MathJax is through in-line configuration, which puts the configuration options within the web page itself. The use of in-line configuration with MathJax requires two separate  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 than other locally installed fonts (e.g., :term:STIX fonts). See the :ref:configuration options  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. 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** enable the TeX single-dollar in-line math delimiters by default. You can load one of the pre-defined configuration files that includes the TeX preprocessor, and use an in-line configuration block to enable the single-dollar signs, as in this example: .. code-block:: html .. _plainjs-config: Using plain JavaScript ====================== Starting with MathJax version 2.3, it is possible to set window.MathJax to a configuration object in any JavaScript code before MathJax's startup. MathJax will then use that object for its initial configuration. For instance the previous example becomes: .. code-block:: html Similarly to scripts with the custom type text/x-mathjax-config, you can enter arbitrary code to execute during the configuration phase. You just need to put that code in an AuthorInit function: .. code-block:: html Note that this initialization code runs before the MathJax.Hub.queue is set up, so if you want to queue additional actions during the AuthorInit function, use .. code-block:: html .. _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  in your theme's header file, and .. code-block:: html 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 loaded. In this way, 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. Note that :meth:MathJax.Hub.Configured() is not called by MathJax; you must make that call somewhere within the page yourself after the configuration blocks are set up. If you do not execute this function, MathJax will not process any of the math on the page. .. _queryString: Additional query string options =============================== MathJax will check the query string for several other parameters (beyond the config and delayStartupUntil parameter). - locale=... (e.g., locale=fr) determines the localization for the MathJax Menu. - noContribdisables the [Contrib] prefix path for loading :ref:third-party extensions  from the (retired) MathJax CDN. - noDOMContentEvent (obsolete) provided a work around for using the DOMContentLoaded event to start MathJax's processing phase - NoMathPlayer (obsolete) prevents MathJax from trying to use MathPlayer even if MathPlayer is available. 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 actions are the following: 1. Execute AuthorInit() from in-line MathJax = {...}. 2. Process any configuration file explicitly specified as a script parameter via config=. 3. Perform author configuration from in-line MathJax = {...} 4. Process the in-line script body (deprecated), if present. 5. If delayed startup is requested, wait for the indicated signal. 6. Process text/x-mathjax-config config blocks. 7. 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 you must request a delayed startup. 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. Similarly, window.MathJax must be created before MathJax.js is loaded. If you set the MathJax variable afterward, you will disable MathJax entirely!