入门指南

MathJax允许你在你的网页中包含公式,无论是使用LaTeX、MathML或者AsciiMath符号,这些公式都会被javascript处理为HTML、SVG或者MathML符号。

这里有三种方法获取MathJax:最简单的方法就是使用分布式网络服务中的MathJax的副本,它位于 cdn.mathjax.org ,但是你也可以下载并安装一个MathJax的副本到你的服务器,或者使用在你本地硬盘的副本(这样是不需要使用网络)。这三种方法接下来的内容中都有详细的描述。这个页面描述了最简单快捷的设置MathJax并在你的页面运行的方法,但是你也许需要阅读更多细节以帮助你为你的网页定制一些设置。

使用MathJax的内容发布网络(CDN)

使用我们的服务器使用MathJax,你需要做两件事情:

  1. 链接MathJax到要包含公式的网页中。
  2. 将公式放入网页让MathJax可以展示它。

要完成第一步,你可以放置

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

到页面的 <head> 块中。如果需要的话也可以放置到 <body> 块中,但是head是更好的选择。这样就会从分发服务器中加载最新版本的MathJax,并配置它识别用Tex和MathML符号书写的公式。如果浏览器原生支持MathML格式,MathJax就会生成用MathML输出,不然的话就用HTML和CSS去显示公式。这是最常见的配置,它可以满足大部分人的需求。但是其他配置也是可以用的,你可以提供参数去配置MathJax,使其更满足你的要求。更多的细节可以从 加载和配置MathJax 中获得.

cdn.mathjax.org 的使用是由 terms of service 约束的,所以请在链接MathJax内容分发服务之前阅读它。

要了解如何在你的网页中添加公式,请参考 在网页中添加公式

安全链接到内容分发服务

当使用 http://cdn.mathjax.org 连接到MathJax的CDN时,数据是通过一个普通的、不安全的HTTP连接下载的。 这引入了安全风险,一个充满敌意的第三方可能拦截MathJax数据并替换它。 这种情况有时候被称为 中间人攻击攻击

为了预防这种攻击,可以通过安全的HTTP连接访问MathJax的CDN。 使用以下的 <script> 标签代替上文提到的即可:

<script type="text/javascript"
  src="https://d3eoax9i5htok0.cloudfront.net/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

目前,MathJax CDN使用的Amazon云端服务不支持使用便于记忆的名称,如 cdn.mathjax.org 进行安全连接访问。但是,上面给出的地址是固定而且安全的。

安装你自己的MathJax副本

我们强烈推荐你使用MathJax的内容分发服务,但是你也可以在你的服务器上安装MathJax的副本,或者直接使用你硬盘上的副本。

这样你需要做以下几件事:

  1. 获取MathJax的副本并放置在硬盘上。
  2. 配置MathJax以适合自己站点的需要。
  3. 链接MathJax到要包括公式的web页面。
  4. 将公式写入页面以便MathJax显示它们。

获取并安装MathJax

最简单的方法就是从 MathJax下载页面 获取MathJax 2.0版本的归档。你需要获取名字像 mathjax-MathJax-v2.0-X-XXXXXXXX.zip 的文件,其中X是数字或者字母。这个归档包含MathJax的代码和字体,是你唯一需要的文件。请注意v1.0版本还有更早的版本的不同之处,它们的字体和代码是分开的。

解压归档并将内容放到你的服务器上你可以很方便引用到的位置。比如在服务器上创建 MathJax 的顶级目录就是一个不错的选择。这样你就可以用通过 /MathJax/MathJax.js 在网页上链接MathJax文件了。

注意: 虽然这是最简单的方法,但是如果你希望你的MathJax是最新的,这里有一个更好的方法。使用 Git 版本控制系统,详细的说明可以在 安装MathJax 中找到。如果你更喜欢使用 Subversion ,你也可以使用它获取MathJax的副本,详细说明参见 通过SVN安装MathJax

一旦你在服务器上设置了MathJax,你可以使用 MathJax/test 目录中文件进行测试。如果你讲MathJax放置在服务器上,使用网络地址加载它们到你的浏览器,而不是使用文件地址。例如使用 http:// 而不是 file:// 。当你访问 index.html ,稍等一会儿以后你就可以看见一个信息表明MathJax开始工作了。如果没有出现,请检查服务器上的文件是否完整、是否有权限访问到MathJax文件夹中的文件。检查服务器日志中所有关于MathJax的部分,这样可能会帮助你更快的发现并排除问题。

配置你的MathJax副本

当按照上文的方法在网页中引入了MathJax,它将会加载文件 config/TeX-AMS-MML_HTMLorMML.js (名为 config/TeX-AMS-MML_HTMLorMML.js 的文件在 config 目录中)。这个文件预加载了很多MathJax常用组件,可以处理Tex、LaTex或者MathML格式的数学公式。如果浏览器原生支持MathML格式,它会先将其转为MathML格式进行处理。否则就是用HTML和CSS进行渲染。

这里还有很多其他预构建的配置文件可以选择,或者你可以使用默认配置 config/default.js 并添加一些自定义设置。关于配置文件的更多细节,请参考 常见配置 ,更多的配置细节请参考 配置选项

注意:配置的处理方式在v1.0和v1.1版本有变化。如果你原有页面使用MathJax v1.0,在使用新版本时需要修改配置文件以适应新的配置方式。详见 安装和配置MathJax

链接你的MathJax副本到一个页面

你可以链接MathJax到你的网页通过将以下代码:

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

放置到你的文档 <head> 块中。其中 path-to-MathJax 代表你的MathJax主目录位置,如果你放置 MathJax 目录到页面服务器的根目录中,你可以使用:

<script type="text/javascript" src="/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

让页面加载MathJax。简单来说,你的页面大致应该像这样:

<html>
    <head>
        ...
        <script type="text/javascript" src="/MathJax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
    </head>
    <body>
        ...
    </body>
</html>

如果你安装MathJax的服务器使用和页面服务器不同的域名,请仔细阅读 跨域引用 <cross-domain-linking> 。在这种情况下,推荐你使用 MathJax内容分发服务 <mathjax-cdn> 而不是安装副本到服务器。

在网页中添加公式

要在网页中添加公式,你可以使用 TeXLaTeX 、:term:MathMLAsciiMath 或者混合使用它们。MathJax配置文件告知MathJax你使用的格式语言。在例子中的配置文件告知MathJax处理的页面同时使用Tex和MathML。接下来是这几种格式的详细描述。

TeX和LaTeX

使用 TeXLaTeX 格式的公式使用 公式分隔符 环绕公式,即告知MathJax页面哪个部分代码公式和它的基本格式。 这里有两种形式的公式:

  1. 包含在段落之中的
  2. 独立于其他文字的

默认的公式分隔符是 $$...$$\[...\] ,还有 \(...\) 常用于段落中的公式。请特别注意, \(...\) 分隔符 不是 默认使用的。美元符号$常常在其他情况下使用,这会导致本文被错误的当做公式解析了。

例如,使用美元分隔符的情况下, ”... the cost is $2.50 for the first one, and $2.00 for each additional one ...” 会被处理为 “2.50 for the first one, and” 。因为介于美元符号之间的文字内容被当做公式处理了。基于这样的理由,如果你想使用美元分隔符,请在配置文件中显示声明

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

查看 config/default.js 文件或者参考 tex2jax配置 options 页面来为 tex2jax 处理器指定更多的参数。 参考 TeX和LaTeX 页面了解更多MathJax对Tex格式的支持和美元符号的使用问题。

这是一个完整的使用TeX公式的页面例子(在线查看 test/sample-tex.html ):

<!DOCTYPE html>
<html>
<head>
<title>MathJax TeX Test Page</title>
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});
</script>
<script type="text/javascript"
  src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
</head>
<body>
When $a \ne 0$, there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
</body>
</html>

一旦在页面中包含了TeX符号,在键入公式时请牢记几个问题。 特别小心小于符号的使用,浏览器可能将其解析为HTML标签。 在小于符号的两侧添加空格,参考`TeX和LaTeX支持 <TeX-support>` 。

如果你在Blog、Wiki或者其他内容管理系统中使用MathJax,系统使用的标记语言可能干扰MathJax。 例如,如果你的博客使用 Markdown 符号来创作页面,TeX用来定义下标的下划线可能和Markdown用来定义斜体的下划线混淆。 查看 TeX和LaTeX支持 获取这个问题的解决方法。

文件 TeX-AMS-MML_HTMLorMML 中加载了一些TeX的输入处理器。

  • TeX/AMSmath.js, 定义了AMS数学环境和宏,
  • TeX/AMSsymbols.js, 定义了在 msam10msbm10 中字体符号的宏,
  • TeX/noErrors.js, 在解析发生错误时,显示TeX代码而不是错误码,
  • TeX/noUndefined.js, 当出现为定义宏时显示名称而不是错误码,

其他扩展可以在需要时加载 参考 TeX和LaTeX支持 了解更多的可用扩展.

MathML

对于使用 MathML 符号编写的公式,使用 <math> 标签标注公式。其中 <math display="block"> 用于独立的公式。 <math display="inline"> 或者 <math> 用于段落内公式。

这样做不仅仅可以在XHML文件工作,也可以运行于HTML文件。同时web页面不需要配上任何特殊的mime类型。除非你使用XHML文件,不然你不需要包含 <math> 标签的命名空间。

尽管不是必须的,但是仍然推荐你包含在所有使用 <math> 标签的页面中引用 xmlns="http://www.w3.org/1998/Math/MathML" ,以使你的MathML使用更多情况。

这是一个完整的使用MathML公式的例子 (在线查看 test/sample-mml.html ):

<!DOCTYPE html>
<html>
<head>
<title>MathJax MathML Test Page</title>
<script type="text/javascript"
  src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>
</head>
<body>

<p>
When
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mi>a</mi><mo>&#x2260;</mo><mn>0</mn>
</math>,
there are two solutions to
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mi>a</mi><msup><mi>x</mi><mn>2</mn></msup>
  <mo>+</mo> <mi>b</mi><mi>x</mi>
  <mo>+</mo> <mi>c</mi> <mo>=</mo> <mn>0</mn>
</math>
and they are
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block">
  <mi>x</mi> <mo>=</mo>
  <mrow>
    <mfrac>
      <mrow>
        <mo>&#x2212;</mo>
        <mi>b</mi>
        <mo>&#x00B1;</mo>
        <msqrt>
          <msup><mi>b</mi><mn>2</mn></msup>
          <mo>&#x2212;</mo>
          <mn>4</mn><mi>a</mi><mi>c</mi>
        </msqrt>
      </mrow>
      <mrow> <mn>2</mn><mi>a</mi> </mrow>
    </mfrac>
  </mrow>
  <mtext>.</mtext>
</math>
</p>

</body>
</html>

当在页面输入MathML符号时,你 应该使用自闭合标签,而应该显示打开和关闭你的math元素。

例如,你应该使用

<mspace width="5pt"></mspace>

而不是 <mspace width="5pt" /> 。如果你使用自闭合标签,有些浏览器不会建立math的树形结构,而MathJax将会获取到一个错误的math结果,无法正常渲染。一般情况下,这会使你的表达式无法显示。不幸的是,一旦浏览器错误的打断标签MathJax将无法做出任何补救。

接受和处理MathML符号的组件名为 mml2jax 。它的配置选项比较少。参考 mml2jax配置选项 或者参考 MathML 获取更多MathJax对MathML的支持问题。

AsciiMath

MathJax v2.0支持一种新的输入格式 AsciiMath 。在于使用这种格式书写的公式,你需要用反勾号(?)标注表达式,例如 `...`

这是一个完整的使用AsciiMath公式的例子 (在线查看 test/sample-asciimath.html ):

<!DOCTYPE html>
<html>
<head>
<title>MathJax AsciiMath Test Page</title>
<script type="text/javascript"
  src="../MathJax.js?config=AM_HTMLorMML-full"></script>
</head>
<body>

<p>When `a != 0`, there are two solutions to `ax^2 + bx + c = 0` and
they are</p>
<p style="text-align:center">
  `x = (-b +- sqrt(b^2-4ac))/(2a) .`
</p>

</body>
</html>

识别asciimath符号的扩展名为 asciimath2jax ,它的配置选项参考 config/default.js 文件。你也可以从 asciimath2jax配置选项 获取关于配置项的情况或者查看 AsciiMath支持 了解更多MathML对AsciiMath的支持。

下一步

如果你完成了以上的教程指南,你现在应该在你的页面上安装并配置了MathJax了,并且可以在页面上显示数学公式。这个时候你可以开始书写更多包含美妙公式的页面了。

你可以阅读更多关于 自定义MathJax 的内容。

如果你尝试在Blog、Wiki或者内容管理系统(CMS)中使用MathJax,你可以阅读 在其他著名平台中使用MathJax

如果你在创建包含公式的动态页面,你也许可以看看 MathJax API 去了解如何在你的交互式页面中使用MathJax。

如果你对于让MathJax工作有疑惑,请参考 安装MathJax 或者 加载和配置MathJax

最后,如果你有问题或者希望得到帮助,你可以访问 MathJax社区论坛 或者 :ref:`MathJax Bug反馈 <community-tracker>`。