232 lines
9.1 KiB
Plaintext
232 lines
9.1 KiB
Plaintext
.. _installation:
|
||
|
||
******************************
|
||
Installing and Testing MathJax
|
||
******************************
|
||
|
||
MathJax can be loaded from a public web server or privately from your hard drive
|
||
or other local media. To use MathJax in either way, you will need to obtain a
|
||
copy of MathJax and its font package. There are three ways to do this: via
|
||
``git``, ``svn``, or via a pre-packaged archive. We recommend git or svn, as it
|
||
is easier to keep your installation up to date with these tools.
|
||
|
||
|
||
.. _getting-mathjax-git:
|
||
|
||
Obtaining MathJax via Git
|
||
=========================
|
||
|
||
The easiest way to get MathJax and keep it up to date is to use the `Git
|
||
<http://git-scm.com/>`_ version control system to access our `GitHub repository
|
||
<http://github.com/mathjax/mathjax>`_. Use the commands
|
||
|
||
.. code-block:: sh
|
||
|
||
git clone git://github.com/mathjax/MathJax.git mathjax
|
||
|
||
to obtain and set up a copy of MathJax. Note that there is no longer
|
||
a ``fonts.zip`` file, and that the ``fonts`` directory is now part of
|
||
the repository itself.
|
||
|
||
Whenever you want to update MathJax, you can now use
|
||
|
||
.. code-block:: sh
|
||
|
||
cd mathjax
|
||
git remote show origin
|
||
|
||
to check if there are updates to MathJax (this will print several
|
||
lines of data, but the last line should tell you if your copy is up to
|
||
date or out of date). If MathJax needs updating, use
|
||
|
||
.. code-block:: sh
|
||
|
||
cd mathjax
|
||
git pull origin
|
||
|
||
to udpate your copy of MathJax to the current release version. If you
|
||
keep MathJax updated in this way, you will be sure that you have the
|
||
latest bug fixes and new features as they become available.
|
||
|
||
This gets you the current development copy of MathJax, which is the
|
||
"bleeding-edge" version that contains all the latest changes to
|
||
MathJax. At times, however, these may be less stable than the
|
||
"release" version. If you prefer to use the most stable version (that
|
||
may not include all the latest patches and features), use ``git tag
|
||
-l`` to see all versions and use ``git checkout <tag_name>`` to
|
||
checkout that version of MathJax. When you want to upgrade to a new
|
||
release, you will need to repeat this for the latest release tag.
|
||
|
||
|
||
.. _getting-mathjax-svn:
|
||
|
||
Obtaining MathJax via SVN
|
||
=========================
|
||
|
||
If you are more comfortable with the `subversion
|
||
<http://subversion.apache.org/>`_ source control system, you may want
|
||
to use GitHub's ``svn`` service to obtain MathJax. If you want to get the
|
||
latest revision using ``svn``, use the commands
|
||
|
||
.. code-block:: sh
|
||
|
||
svn checkout http://svn.github.com/mathjax/MathJax.git mathjax
|
||
|
||
to obtain and set up a copy of MathJax. Note that there is no longer
|
||
a ``fonts.zip`` file, and that the ``fonts`` directory is now part of
|
||
the repository itself.
|
||
|
||
Whenever you want to update MathJax, you can now use
|
||
|
||
.. code-block:: sh
|
||
|
||
cd mathjax
|
||
svn status -u
|
||
|
||
to check if there are updates to MathJax. If MathJax needs updating,
|
||
use
|
||
|
||
.. code-block:: sh
|
||
|
||
cd mathjax
|
||
svn update
|
||
|
||
to udpate your copy of MathJax to the current release version. If you
|
||
keep MathJax updated in this way, you will be sure that you have the
|
||
latest bug fixes and new features as they become available.
|
||
|
||
This gets you the current development copy of MathJax, which is the
|
||
"bleeding-edge" version that contains all the latest changes to
|
||
MathJax. At times, however, these may be less stable than the
|
||
"release" version. If you prefer to use one of the tagged releases
|
||
instead, then either use ``git`` as described above, or one of the
|
||
archive files as described below. You can use
|
||
|
||
.. code-block:: sh
|
||
|
||
svn checkout http://svn.github.com/mathjax/MathJax.git@nnn mathjax
|
||
|
||
to check out revision number `nnn`, but it is not easy to tell what
|
||
svn revision number is associated with a particular release. GitHub's
|
||
``svn`` service doesn't appear to allow you to sepecify a particular
|
||
tagged version.
|
||
|
||
|
||
.. _getting-mathjax-zip:
|
||
|
||
Obtaining MathJax via an archive
|
||
================================
|
||
|
||
Release versions of MathJax are available in archive files from the
|
||
`MathJax download page <http://www.mathjax.org/download/>`_ or the
|
||
`GitHub downloads <http://github.com/mathjax/mathjax/>`_ (click the
|
||
big download button on the right), where you can download the archive
|
||
that you need.
|
||
|
||
You should download the v1.1 archive (which will get you a file with a
|
||
name like ``mathjax-MathJax-v1.1-X-XXXXXXXX.zip``, where the X's are
|
||
some sequence of random-looking letters and numbers), then simply unzip
|
||
it. Once the MathJax directory is unpacked, you should move it to the
|
||
desired location on your server (or your hard disk, if you are using
|
||
it locally rather then through a web server). One natural location is
|
||
to put it at the top level of your web server's hierarchy. That would
|
||
let you refer to the main MathJax file as ``/MathJax/MathJax.js`` from
|
||
within any page on your server.
|
||
|
||
From the `MathJax GitHub download link
|
||
<http://github.com/mathjax/mathjax/>`_ (the big download button at the
|
||
right), you can also select the ``Download .tar.gz`` or ``Download
|
||
.zip`` buttons to get a copy of the current "bleeding-edge" version of
|
||
MathJax that contains all the latest changes and bug-fixes.
|
||
|
||
|
||
Testing your installation
|
||
=========================
|
||
|
||
Use the HTML files in the ``test`` directory to see if your
|
||
installation is working properly::
|
||
|
||
test/
|
||
index.html # Tests default configuration
|
||
index-images.html # Tests image-font fallback display
|
||
sample.html # Sample page with lots of pretty equations
|
||
|
||
Open these files in your browser to see that they appear to be working
|
||
properly. If you have installed MathJax on a server, use the web
|
||
address for those files rather than opening them locally. When you
|
||
view the ``index.html`` file, you should see (after a few moments) a
|
||
message that MathJax appears to be working. If not, you should check
|
||
that the files have been transferred to the server completely, that
|
||
the fonts archive has been unpacked in the correct location, and that
|
||
the permissions allow the server to access the files and folders that
|
||
are part of the MathJax directory (be sure to verify the MathJax
|
||
folder's permissions as well). Checking the server logs may help
|
||
locate problems with the installation.
|
||
|
||
|
||
.. _cross-domain-linking:
|
||
|
||
Notes about shared installations
|
||
================================
|
||
|
||
Typically, you want to have MathJax installed on the same server as
|
||
your web pages that use MathJax. There are times, however, when that
|
||
may be impractical, or when you want to use a MathJax installation at
|
||
a different site. For example, a departmental server at
|
||
``www.math.yourcollege.edu`` might like to use a college-wide
|
||
installation at ``www.yourcollege.edu`` rather than installing a
|
||
separate copy on the departmental machine. MathJax can certainly
|
||
be loaded from another server, but there is one imporant caveat ---
|
||
Firefox's same-origin security policy for cross-domain scripting.
|
||
|
||
Firefox’s interpretation of the same-origin policy is more strict than
|
||
most other browsers, and it affects how fonts are loaded with the
|
||
`@font-face` CSS directive. MathJax uses this directive to load
|
||
web-based math fonts into a page when the user doesn't have them
|
||
installed locally on their own computer. Firefox's security policy,
|
||
however, only allows this when the fonts come from the same server as
|
||
the web page itself, so if you load MathJax (and hence its web fonts)
|
||
from a different server, Firefox won't be able to access those web
|
||
fonts. In this case, MathJax will pause while waiting for the font to
|
||
download (which will never happen) and will time out after about 15
|
||
seconds for each font it tries to access. Typically that is three or
|
||
four fonts, so your Firefox users will experience a minute or so
|
||
delay before mathematics is displayed, and then it will probably
|
||
display incorrectly because the browser doesn't have access to the
|
||
correct fonts.
|
||
|
||
There is a solution to this, however, if you manage the server where
|
||
MathJax is installed, and if that server is running the `Apache web
|
||
server <http://www.apache.org/>`_. In the remote server's
|
||
``MathJax/fonts/HTML-CSS/TeX/otf`` folder, create a file called
|
||
``.htaccess`` that contains the following lines: ::
|
||
|
||
<FilesMatch "\.(ttf|otf|eot)$">
|
||
<IfModule mod_headers.c>
|
||
Header set Access-Control-Allow-Origin "*"
|
||
</IfModule>
|
||
</FilesMatch>
|
||
|
||
and make sure the permissions allow the server to read this file.
|
||
(The file's name starts with a period, which causes it to be an
|
||
"invisible" file on unix-based operating systems. Some systems,
|
||
particularly graphic user interfaces, may not allow you to create such
|
||
files, so you might need to use the command-line interface to
|
||
accomplish this.)
|
||
|
||
This file should make it possible for pages at other sites to load
|
||
MathJax from this server in such a way that Firefox will be able to
|
||
download the web-based fonts. If you want to restrict the sites that
|
||
can access the web fonts, change the ``Access-Control-Allow-Origin``
|
||
line to something like::
|
||
|
||
Header set Access-Control-Allow-Origin "http://www.math.yourcollege.edu"
|
||
|
||
so that only pages at ``www.math.yourcollege.edu`` will be able to
|
||
download the fonts from this site. See the open font library
|
||
discussion of `web-font linking
|
||
<http://openfontlibrary.org/wiki/Web_Font_linking_and_Cross-Origin_Resource_Sharing>`_
|
||
for more details.
|
||
|
||
|