Skip to content

Guide: reducing size of a mathjax installation

Jump to bottom Edit New page
Peter Krautzberger edited this page Feb 7, 2014 · 8 revisions

While a complete MathJax installation is rather large, the MathJax footprint can be reduced, e.g., for inclusions in mobile apps or when targeting specific browsers.

Even though every app will have it's own needs, the basic process can be described.

The goal of this documentation is to allow developers to include MathJax efficiently in their projects.

Getting the code from github.

To start from scratch, we grab a fresh MathJax copy from github; at time of writing this is the v2.3-latest branch.

git clone https://github.com/mathjax/MathJax.git
git checkout -b v2.3-latest origin/v2.3-latest

The directory structure

In your clone you should expect the following content:

config/
docs/
extensions/
fonts/
images/
jax/
localization/
test/
unpacked/
LICENSE
MathJax.js
README.md

The size of the folder should be around 61MB.

Let's go through the folders.

  • config -- this folder contains combined configuration files such as TeX-AMS-MML_HTMLorMML-full.js
  • docs -- this folder contains information on the MathJax documentation
  • extensions -- this folder contains the MathJax extensions
  • fonts -- this folder contains all supported fonts, in multiple formats
  • images -- this folder contains two small images
  • localization -- this folder contains locales in different languages
  • jax -- this folder contains the core of MathJax, the javascript files for processing input and output.
  • test -- this folder contains a series of test files and samples (not to be confused with the MathJax test suite
  • unpacked -- this folder contains the uncompressed originals of the core MathJax files (config, extensions, jax and of course MathJax.js)

The three files are

  • .gitignore
  • LICENSE -- a copy of the Apache license
  • MathJax.js -- the core JavaScript file
  • README-branch.txt
  • README.md
  • bower.json

Trimming I -- removing files unnecessary for deployment

  • docs
  • test
  • unpacked
  • .gitignore
  • README-branch.txt
  • README.md
  • bower.json

Without these folders, the functionality of MathJax is not limited in any way. Keep in mind that the unpacked folder is useful for debugging purposes.

Trimming II -- not strictly necessary

MathJax offers a variety of options and a project can usually choose one and discard the rest.

  • configurations in config

The combined configuration files primarily designed to reduce load times by combining several components of MathJax into one file.

Since most projects will want just one customized MathJax configuration, the unused ones can be removed from config. Where a combined configuration file is around 100-300KB, a not-combined configuration file might be a few hundred bytes.

Keep in mind that if MathJax is delivered over a network connection, a combined configuration file will perform better. If you can use one of these configuration file, keep it (and then you can remove other components included in the combined file). You can also build your own combined file with the MathJax Dev Tools.

  • PNG-fonts in fonts/HTML-CSS/TeX/png/

Today, all browser engines support webfonts. Therefore, the PNG-fonts are not technically necessary -- at ~29,000 files and 8.8MB this is a large reduction.

Note If you remove the PNG fonts, you should include imageFont:null in your configuration to prevent font warning messages (cf. the HTML_CSS configuration documentation).

Note The MMLorHTML.js configuration might still be useful, cf. its documentation.

Note For Gecko with local files, make sure to work around the same-origin policy, see the docs.

  • Locales in `localization'

Most projects will prefer one language for the MathJax User Interface. In that case, all but one folder in localization can be removed.

If English is the preferred language, then the entire folder can be removed (English strings are embedded in the source as fallbacks).

Trimming III -- fonts

  • Font formats

Most likely, fonts in the Web Open Fonts Format will be sufficient since WOFF is supported by all modern rendering engines. Therefore only fonts/HTML-CSS/FONTNAME/woff is required and the other folders in each fonts/HTML-CSS/FONTNAME/ can be removed.

  • Fonts options.

Most projects will only need one font (and by default, MathJax does not allow for the user to switch fonts).

Therefore, only one folder in fonts/HTML-CSS/ will be needed and the rest can be removed. Similarly, only one folder in jax/output/SVG/fonts will be needed for SVG output.

Note Not all fonts provide the same level of character coverage. The STIX-web fonts offer virtually complete Unicode coverage (and the largest file size). The TeX fonts appear to have the smallest coverage but MathJax has built-in methods to cover more characters (by combining characters, e.g., quadrupal integrals, strike-through characters).

Trimming IV -- reducing input and output options

  • Reducing input options.

Many projects focus on one input format, MathML, TeX, or asciimath. For example, an epub3 reader application such as Readium might restrict the input method to MathML since MathML is the only mathematical markup language that is part of the epub3 standard.

The input jax'es are stored in jax/input and extraneous ones can be removed.

  • Reducing output options.

Similarly, a project might prefer one of the output options (HTML-CSS, SVG or MathML). In that case, two folders can be removed from jax/output/.

If SVG is used, the fonts folder can be removed completely (the SVG output jax has its pseudo-fonts in jax/output/SVG/fonts)

Note NativeMML output tweaks the MathML to work around Firefox/Geck and Safari/WebKit bugs and limitations. Keep in mind Gecko and WebKit have serious limitations in terms of MathML support and rendering quality (although Gecko can be considered production ready).

  • Reducing extensions

Depending on the trimming so far, some MathJax extensions can be removed.

extensions/HTML-CSS/ -- contains extensions only used in conjunction with the HTML-CSS output. extensions/MathML/ -- contains extensions only used in conjunction with the MathML input. extensions/TeX/ -- contains extensions only used in conjunction with the TeX input. extensions/asciimath2jax.js -- the asciimath preprocessor extensions/FontWarnings.js -- should not be removed extensions/HelpDialog.js -- should not be removed extensions/jsMath2jax.js -- the jsmath preprocessor extensions/MatchWebFonts.js -- an extension to improve font size matching extensions/MathEvents.js -- should not be removed extensions/MathMenu.js -- should not be removed extensions/MathZoom.js -- should not be removed extensions/mml2jax.js -- the MathML input preprocessor extensions/Safe.js -- an extension for limiting potentially harmful input extensions/tex2jax.js -- the TeX/LaTeX input preprocessor extensions/toMathML.js -- an extension for generating MathML

To sum up

Full size: ~61MB.

  • Trimming I: ~43MB
  • Trimming II: ~30MB
  • Trimming III: ~5.5MB (reduced to TeX fonts)
  • Trimming IV: ~1.7MB (MathML Input + SVG Output using TeX fonts); zipped: ~700KB.

Add a custom sidebar
Clone this wiki locally