加载和配置MathJax

优质

小牛编辑

130浏览

2023-12-01

你可以通过引用MathJax的主Javascript文件加载MathJax。你可以用 <script> 标签链接 MathJax.js 文件。通过将下面一行代码放置到网页的 <head> 块中。

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

其中 path-to-MathJax 是你要加载的MathJax的路径。如果你使用CDN服务的话，标签代码应该如下：

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

如果你自己安装了MathJax， path-to-MathJax 就是你的MathJax主目录地址。如果你的MathJax安装在根目录，那么标签代码就应该如下：

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

如果你安装MathJax的服务器和页面服务器不是同一个，那么这里就一些问题。仔细阅读以获取更多细节。

当你加载MathJax时，常常会请求一个配置文件，配置文件的问题我们将在中讨论, 你也可以在中找到。一个典型的配置调用如下：

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

这样会加载一个通用配置，支持TeX、LaTeX、MathML。如果你的浏览器原生支持MathML的话就会先转为MathML格式，否则就会使用HTML和CSS进行渲染。如果不加载一个配置文件的话就需要使用内嵌配置来声明MathJax如何读取和显示页面的公式。阅读来获取更多内容。

最佳加载MathJax文件的方法就是在 <head> 块。但是如果需要的话也可以在 <body> 块中加载。如果你这样做的话，请尽可能早的加载它以加快处理速度。因为MathJax在被引入页面后才开始加载它的组件。MathJax默认认定有一个 <head> 块，请保证有一个如果你在 <body> 中加载MathJax。

可以页面加载完成后动态加载MathJax。比如通过 It is also possible to load MathJax dynamically after the page has GreaseMonkey 脚本，或者一个专门准备的 bookmarklet <http://en.wikipedia.org/wiki/Bookmarklet>`_。这里有一个高级用法的话题 :ref:`Loading MathJax Dynamically <ajax-mathjax> 。

从CDN加载MathJax

MathJax可以通过 ``cdn.mathjax.org``的web服务获取，所以你可以从这里加载MathJax而不用安装到你自己的服务器上。这个CDN是云网络的一部分，所以它可以被世界各地的服务器响应。这意味着你将从离你最近的节点获取，这样会让连接更快更稳定。

CDN托管了MathJax的最新版本和旧版本。所以你可以一直连接到MathJax，也可以连接到一个固定的版本以便你的页面可以一直使用同一个版本。

获取MathJax的Url决定了获取到的版本。CDN的目录结构如下：

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

每一个目录相当于MathJax官方的发行版本。但是当必要时补丁会应用于发型分支中。换言之， 1.1-latest 最开始带包的1.1版本，但是随着时间推移它会升级，其版本会变成1.1a,1.1b等等。目录中也会有测试版本，但是那都是临时的。当正式版发布时它就会移除。

如果要加载一个特定版本，使用对应的目录就行了。比如

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

将会加载v1.1版本。即使其他更高的版本发布也不会改变。而

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

总会加载最新版本。它会自动升级，比如从v1.1到v2.0。请注意，CDN上面的版本都是稳定版本，正在开发的版本不会托管于其中。如果你需要使用正在开发的版本，请自行安装其副本。参考获得更多信息。

cdn.mathjax.org 使用受 terms of service 的约束。请确认你使用CDN之前阅读了它。

如果你想使用MathJax的CDN，又想使用自己的配置文件而不是预制的，参考。

配置MathJax

这里有两种配置MathJax的方法：通过配置文件，或者通过内嵌在Web页面的配置命令。这两种方法可以独立使用，也可以混合使用。比如你加载一个预制的配置文件，但是在页面中使用配置命令进行一些调整。

但是你必须使用其中的一种。与v1.0不同，v1.1和更新的版本不会自动加载默认配置文件。你可以通过 config 参数去加载。接下来会详细说明：

使用配置文件

第一种配置Mahtjax的方法就是使用配置文件。MathJax附带了很多种预制配置文件。它们存储在 MathJax/config 目录。主要有其中以下几个：

default.js: 这个文件包含了所有MathJax可用的配置选项，并附有注释和说明，你可以编辑它们来满足你的需要。

TeX-AMS-MML_HTMLorMML.js: 允许使用 , , 或者符号书写公式。如果浏览器支持就处理为MathML，否则就使用Html和Css渲染。

TeX-AMS_HTML.js: 允许使用或者符号书写公式。使用Html和Css渲染。

MML_HTMLorMML.js: 允许使用符号书写公式。如果浏览器支持就处理为MathML，否则就使用Html和Css渲染。

AM_HTMLorMML.js: 允许使用符号书写。如果浏览器支持就处理为MathML，否则就使用Html和Css渲染。

TeX-AMS-MML_SVG.js: 允许使用 , , 或者符号书写公式。使用SVG产生输出。

TeX-MML-AM_HTMLorMML.js: 允许使用 , , ,或者符号书写公式。如果浏览器支持就处理为MathML，否则就使用Html和Css渲染。

第一个文件是提供给你修改的。它基本上包含了MathJax的所有配置选项，同时有注释解释。其他的文件就是我们联合配置文件。它们不仅仅配置Mathjax,还预加载了一些配置所需的文件。这些文件内容在联合配置中有详细的解释。

通常MathJax只在需要的时候才加载组件，但是一个组件需要一个单独的文件去加载，这样就会出现一些延迟。

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_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 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 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

<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

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

to first load the main configuration, then the local modifications.

Using a local configuration file with the CDN

You can load MathJax from the MathJax CDN server 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 the CDN and still use your configuration file as follows:

<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>

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 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

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.

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 <script> tags: one for specifying the configuration settings and one for loading of 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 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 need, and MathJax will process them in the order in which they appear in the document.

For instance,

<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 and 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., fonts). See the section (or the comments in the config/default.js file) for more information about the configuration options that you can include in the 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:

<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>

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 MathJax.Hub.Configured() method is called. This allows you to delay startup until later on the page, but then restart the MathJax configuration process as soon as possible rather than waiting for the entire page to load. For example, you could use

<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

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

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:

Process any configuration file explicitly specified as a script parameter.
Process the in-line script body (deprecated), if present.
If delayed startup is requested, wait for the indicated signal.
Process text/x-mathjax-config config blocks.
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.