How to use jsMath with org-mode

Here are some advantages and disadvantages about using jsMath instead of images.

Advantages

• It's really pretty when you have all the fonts installed and you can zoom in without any loss of quality.
• No need to generate images when exporting
  • When you see the generated HTML page the jsMath script is run and replaces the latex code appropriately. Because the efficiency of the java-script engine in modern browsers are increasing more and more these replacements are usually fast even if there are a lot of equations in the generated page.
  • On the other hand, creating images when exporting can take considerable time when there are many equations.

Disadvantages

• It is more difficult to setup
  • you have to install jsMath for authors, since you are creating pages with it.
  • you have to install jsMath for users, that is, install the fonts that will be used. If this is not done, jsMath will use images for the equations. You won't need to generate the images when exporting, since jsMath already has all images (it just put the pieces together)
• It is more inconvenient to send the generated HTML page to a friend, since your friend will need to install the fonts used by jsMath.

First we need to download jsMath for authors as explained in http://www.math.union.edu/~dpvc/jsMath/download/jsMath.html. The necessary files are here. Download the latest version of jsMath and also the "jsMath Image Fonts"¹ file. Don't bother with the sprite fonts.

Unpack the jsMath and jsMath-image-fonts archives, and place the fonts folder from the second archive into the jsMath folder from the first archive. That is, the fonts folder should be in the same folder as the jsMath.js file.

The main configuration file for jsMath is the easy/load.js script. We need to tell org-mode to include this script in each generated HTML file. Assuming that the jsMath folder is in the same parent folder as the folder containing the .org files, we can just add

#+STYLE: <SCRIPT SRC="../jsMath/easy/load.js"></SCRIPT>

to the beginning of each org file. Alternatively, if org-publish is utilized we can put

:style "<link rel=\"stylesheet\" type=\"text/css\" href=\"../stylesheet.css\" />"

in the project definition.

With that, when the HTML generated by org-mode is viewed in the browser jsMath will replace the equations inside the math delimiters appropriately². By default, jsMath recognizes \( and \) as math delimiters for inline equations, and \[ and \] (in addition to $$) as math delimiters for display equations.

To recognize $ as math delimiters for inline equations change "processSingleDollars:" to 1 in the easy/load.js file.

You will probably want to load some additional plugins (for instance, AMSSymbols). In order to do that search for

loadFiles: [],

in the easy/load.js file and add each plugin name separated by comma. Here I use

loadFiles: ["extensions/AMSmath.js","extensions/AMSsymbols.js", "extensions/autobold.js", "extensions/eqn-number.js"],

The plugins AMSmath and AMSSymbols are self-explanatory and you will need them if you are using symbols or environments provided by AMS such as the symbol \triangleq.

The plugin eqn-number is really nice. It will number equations that have a label and allow you to reference them later with the ref command. For instance

\[
\label{a_label}
x=2*y
\]
Bla bla bla from equation \(\ref{a_label}\)

will create a numbered equation that can be referred as showed in the example³. The reference is a link to the equation.

The plugin autobold causes jsMath to use \boldsymbol{...} around mathematics that appears within <B>…</B> tags or has font-weight:bold applied via CSS rule.

Look in the extensions folder for other plugins (some of them are loaded automatically by jsMath and it is not necessary to include them in the loadFiles).

As last, if the browser freezes when jsMath is being loaded, try disable the autoload feature in the easy/load.js file.

(Updated 2010-01-07 by CM)

Because we are going to process the latex code with jsMath, we must ensure that Org-mode leaves the latex code intact. This can now be done by setting the variable org-export-with-LaTeX-fragments to verbatim, e.g. by including this line at the beginning of the Org file:

#+OPTIONS: LaTeX:verbatim

(Previously, the same effect was achieved with the lines

#+OPTIONS: ^:nil
#+OPTIONS: LaTeX:nil

but this had the side effect of turning off sub- and superscripts in all non-latex text. The new verbatim option can be used with ^:t.)

jsMath should be working with org-mode by now, but it is using the image fonts and warns the user with a red frame at the top of the page. That means that the "installation for authors" part is done and now we only need to install some .ttf fonts available at the jsMath website. Download the file TeX-fonts-linux.tgz in the website. and extract the files to ~/.fonts.

The package TeX-fonts-linux has the most common ones, but it is also good to install the extra fonts (to see, for instance, the "mathcal" symbols).

Some additional fonts available in the extra fonts page are useful. Download the zip file for authors (for instance bbold10.zip) and extract it to the jsMath/fonts folder. Then download the corresponding .ttf file to the ~/.fonts (I prefer the light version because the dark version may be confused with bold). You don't need to install all of the extra fonts. The ones I found useful are bbold10, cmbsy10, cmmib10, msam10 and msbm10⁴.