Exploring MathJax – Input Randomness

MathJax has become the modern standard for displaying mathematics on the web. Here, we will see how low the barrier to entry for using MathJax is if you already know \(\LaTeX\), and we will explore some the features it has to offer. I’ll also discuss some of the issues you may encounter in embedding MathJax in online platforms like WordPress or Blackboard LMS.

I am by no means an expert on MathJax or its underlying technologies, and this article does not aim to make you an expert either. But I hope that it provides new users enough information to work effectively with MathJax and be aware of some of its features and pitfalls. If you have comments or suggestions for improving this article, I welcome them!

Table of Contents

Some MathJax Examples

I can create “inline math” (i.e., math inside a sentence) using backslash-parentheses as delimiters. For example, \(f: X\rightarrow Y\) will display: \(f: X \rightarrow Y\). If I want “display math” (i.e. math set apart from a paragraph), then I can use backslash-square-brackets, as in \[ f(x) = y \iff f^{-1}(y) = x. \] to display: \[ f(x) = y \iff f^{-1}(y) = x. \]

Not Working?

If the above paragraph is not displaying properly typeset mathematics, it is likely that Javascript is not enabled in your browser. MathJax relies on Javascript, so you will want to ensure that it is enabled. If you are not sure how to do that, a quick web search for “enable javascript <my browser name>” should help.
I have noticed that in an older version of Safari, numbers did not appear, although other mathematical symbols did, for a certain output setting (CommonHTML). If this seems to be an issue for you, right-click (or long-press on mobile) on the mathematics to open the MathJax Context Menu, and select “Math Settings -> Math Renderer -> SVG” to have MathJax display the mathematics as images instead of HTML. This should fix this issue.

MathJax also can include some features from the amsmath package, which makes some things easier. For example, to easily create matrices surrounded by square brackets, we can use the bmatrix environment. We enter:

\[
  \begin{bmatrix} 
    a &amp; b \\ 
    c &amp; d 
  \end{bmatrix}
  \begin{bmatrix} 
    r\cos\theta \\ 
    r\sin\theta 
   \end{bmatrix} 
= 
  \begin{bmatrix} 
    a \cdot r\cos\theta + b \cdot r\sin\theta \\
    c \cdot r\cos\theta + d \cdot r\sin\theta
  \end{bmatrix}
\]

and we obtain:

\[\begin{bmatrix} a & b \\ c & d \end{bmatrix} \begin{bmatrix} r\cos\theta \\ r\sin\theta \end{bmatrix} = \begin{bmatrix} a \cdot r\cos\theta + b \cdot r\sin\theta \\ c \cdot r\cos\theta + d \cdot r\sin\theta \end{bmatrix}\]

If we replace bmatrix with pmatrix (where “b” for bracket becomes “p” for parentheses”) we obtain:

\[\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} r\cos\theta \\ r\sin\theta \end{pmatrix} = \begin{pmatrix} a \cdot r\cos\theta + b \cdot r\sin\theta \\ c \cdot r\cos\theta + d \cdot r\sin\theta \end{pmatrix}\]

Trying MathJax Out, Without Trying Too Hard

My goal for the moment is to show you how much you can get done if you already know LaTeX, without really having to learn anything else. If you are not sure you want to deal with the following steps to explore MathJax, you might instead start by checking out the Live Demo available at MathJax.org.

Step 0. As noted above, for MathJax to work, your web browser must have Javascript enabled. All major modern browsers support Javascript and should have it enabled by default.

Step 1. Don’t bother installing anything. To effectively use MathJax, you don’t need to install any software. There are sites online that host MathJax as a public service. If you have your own site and want to host it there, that option is available. Step 1 is just being aware that professional Content Delivery Networks will do all the heavy lifting of MathJax for you.

Step 2. Decide where you want to try MathJax.

The easiest approach for now may be to just open a file named something like mymathjaxtest.html for editing in a text editor. If you don’t already have a favorite text editor, you can use TextEdit on Mac or Notepad on Windows — both come with their respective operating systems — or you might find Notepad++ (Windows) or Atom (Windows and Mac) more to your liking. Note that you do not want a word processor, like Microsoft Word.
If you have a web platform in mind where you can post raw HTML content (like Blackboard LMS or your own web page), you can use that. The only other important requirement is that the platform you’re using does not prevent you from using Javascript. See the article \(\LaTeX\) and Learning Managment Systems for a thorough discussion of the contexts in which Blackboard might allow Javascript.

Step 3. Call MathJax! Copy the code below, and paste it in your file or as raw HTML in the edit box where you’ve decided to work. Keep this code at the top of your text.

<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-AMS_CHTML-full" type="text/javascript"></script>

Step 4. For this demo, don’t worry about any other HTML. You don’t need to bother with HTML tags at all unless you want to. Your web browser will call MathJax and render the math just fine, even though your file is not going to contain valid HTML. Note: This step is telling you that if later on, you want to see what some of your MathJax content will look like, you can always test it in a local file first to make sure it looks the way you expect.

Step 5. Add some math! Be as brave as you want in trying things out. Remember to enclose your math in either \( and \) for inline math or \[ and \] for math in a paragraph. If you’re not sure what to type, might I suggest:

\[ f_1(x^y) \circ g^3 \neq \left( p \atop r \right) \]

If \(x^2 = -1\) I'll eat my very complex hat.

Step 6. If you’re using a local file, save that file as an html file (ensuring it has the extension “.html” should be enough). Then open the with your favorite browser. Or, if editing online, click to submit the content and view the result. You should see:

The mathematic "\[ f_1(x^y) \circ g^3 \neq \left( p \atop r \right) \]
If \(x^2 = -1\) I'll eat my very complex hat" rendered with MathJax on Chrome. — Chrome’s rendering of the above sample code.

If you see math in your browser, then you’ve successfully used MathJax! All it takes is to make a call to a server that will handle the MathJax for you, and to include some LaTeX math (properly delimited) in your content. The rest of this document just explores some of the features, benefits, limitations, and ins-and-outs of MathJax.

If you did not see math, the two most likely issues are that Javascript is currently disabled in your web browser or that you have an error in the LaTeX you typed. If you’re sure Javascript is enabled and you do not have an error in your LaTeX, then try replacing the letters CHTML in the call to MathJax to SVG, leaving everything else the same. This loads the mathematics as an image file instead of as HTML.

Note: If you plan on using MathJax by including it in an edit box for an online platform, you can (on most platforms) add the MathJax script call at the top of content as raw HTML, and then leave the raw HTML and continue editing as normal in the rich-text editor, placing simple mathematics within delimiters as normal. But there are some potential issues to be on guard for, especially with more complicated mathematics, as noted in the Rich-Text Editors and MathJax Section.

How Does MathJax WorK?

Javascript

MathJax runs on Javascript, which is a programming language supported by all major modern web browsers. Javascript code is either embedded in, or called from, a web page; and when the browser encounters the code, it compiles and runs it. So your browser is doing all the actual work. You only need to have either (a) internet access so your browser can download the MathJax code from a CDN (content delivery network) server, or (b) MathJax installed locally. We won’t consider case (b) in this article, but MathJax has documentation for this.

Loading and Configuring MathJax

The HTML script tag that we used in the above demo called https://cdnjs.cloudflare.com and asked it to load the Javascript file

/ajax/libs/mathjax/2.7.7/MathJax.js

The file name is MathJax.js and everything else between slashes is just a directory (i.e. folder) in a file system. We don’t need know what ajax or libs refer to, but it is worth noting that the 2.7.7 means we are loading version 2.7.7 of MathJax. The website cdnjs.cloudflare.com is a CDN (content delivery network) which provides reliable libraries for Javascript files like MathJax.

MathJax is highly configurable, and whenever you call MathJax you need to provide some configuration information. We did this by including the argument ?config=TeX-AMS_CHTML-full in our call to MathJax. This loads one of the built-in “combined configuration files” that specifies we want to use TeX input with amsmath support, and we want the output to be HTML. (See the Output Section below for information what the “C” in “CHTML” refers to.)

Depending on your needs, you may find that you wish to use a different pre-built configuration file. Or, you may wish to specify the configuration inline with your own Javascript code. (Below, we’ll use some inline configuration options.) Be aware that if you use an inline configuration script, it must come before the script that calls MathJax, and as a separate script.

MathJax’s requirement that you specify configuration details ensures you only load and run what you need to, saving time.

MathJax Inputs and Outputs

As mentioned, MathJax is highly configurable and two of the primary things the configuration specifies are the types of input and output MathJax will use. The MathJax Documentation has extensive information on the options for inputs and outputs, but we’ll briefly mention them here, just to take note of what is possible.

Input

MathJax supports not only LaTeX, but AsciiMath and MathML; though you have to set the appropriate configurations to use them.

AsciiMath is a simpler, more restrictive, language for typesetting mathematics; it is generally easier to write and read than LaTeX, so if for example you have a situation where students are typing code for math, you might prefer AsciiMath to LaTeX.
MathML is a markup language designed for storage and transport of information about mathematics; it is not intended to be written or read by humans. Mostly, it is important that MathJax can output MathML because software like MathPlayer can read MathML, making your mathematics more accessible. If you have MathML from another source, you can use MathJax to convert it into readable HTML.

Output

MathJax is capable of outputting mathematics using “CommonHTML” (CHTML), HTML-CSS, MathML, or SVG. The MathJax Output Documentation provides a thorough overview of the differences; here we note some highlights.

CommonHTML is the current default/standard. It boasts a combination of consistent quality and speed.
HTML-CSS was the standard before CommonHTML.
As mentioned, MathJax can handle MathML as both input and output. But not all web browsers properly support MathML for visual rendering, so you likely do not want to use this option. Note that a user can always access the MathML code representing any math expression by selecting “Show Math As -> MathML” from the MathJax Context Menu.
An alternative to HTML rendering is SVG — scalable vector graphics. This is a modern standard for images that maintain their quality instead of becoming pixelated when you zoom in. For example, many of the mathematical images found on Wikipedia are SVG format.

Typesetting Math with MathJax

MathJax and HTML Special Characters

Notice that in the example code above, I typed “&” for & — it is important to note that &, <, and > are special characters in HTML. And the HTML in your webpage is rendered before MathJax interprets the LaTeX code. So, in your LaTeX code, and instance of &, <, or > should use &, <, or > — the web browser will convert the code into the appropriate character, and then MathJax will do its work. If you show the math as LaTeX commands, you will notice that only & appears.

MathJax Tricks for Fun and Profit

Here are some note which might enhance your MathJax writing experience:

Macros

MathJax supports the use of \newcommand to create LaTeX macros. For example, in the body of this page I have the following code:

<div class="hidden-content" style="display:none">
  \(\newcommand{\inv}{^{-1}}\)
</div>

This tells MathJax to interpret the string \inv (for inverse) as the code ^{-1} (superscript -1). I have a habit of using this macro for inverses of functions or group elements. Then, when I type something like \(s r s = r\inv \), the macro is translated properly, and the math displays properly: \(s r s = r\inv \). This can be handy for saving time by wrapping tedious and often-used LaTeX expressions into convenient macros. Notice, the macro must appear inside MathJax delimiters, which is different from standard LaTeX. TeX macros can also be included in inline configuration; read more in the documentation on macros.

Equation Auto-Numbering and Referencing

If you enable equation auto-numbering, you can label and reference equations in MathJax as illustrated in the examples below:

\[\begin{equation} a^{b+c} = a^b \cdot a^c \label{my_alg_eqn}\end{equation}\]

\[\begin{equation} g(x) = \int_{-3}^{x^2} x^2f(x)\,dx \label{my_calc_eqn}\end{equation}\]

Did you see Equation [\ref{my_alg_eqn}]? What about Equation \eqref{my_calc_eqn}?

The above mathematics, with labels and references was added using the following code:

<p>
  \[\begin{equation}
    a^{b+c} = a^b \cdot a^c 
    \label{my_alg_eqn}
  \end{equation}\]
</p>

<p>
  \[\begin{equation}
    g(x) = \int_{-3}^{x^2} x^2f(x)\,dx 
    \label{my_calc_eqn}
  \end{equation}\]
</p>

<p>Did you see Equation \eqref{my_alg_eqn}? What about Equation \eqref{my_calc_eqn}?</p>

Notes:

Equation numbering is not enabled by default, but you can enable it by adding the configuration script below before the MathJax call.
The \ref command provides the number without decoration (notice the square brackets were manually added and are not part of the link), while \eqref automatically includes parentheses.
The references link to the equations; but they are also MathJax displays and the default behavior is that clicking on a display zooms in. This prevents the link from activating (in my experience). The behavior can be changed so that the zoom is triggered by: “None”, “Click”, “Double-Click”, or “Hover”, with optional modifiers CTRL, Shift, ALT, or CMD. The configuration below sets the zoom trigger to ALT+Click. Each option for triggering zoom might interfere with typical browser functionality in some way; so if you use this, you may want to think about which option is best in your case.

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  menuSettings: { zoom: "Click", ALT:true },
  TeX: { equationNumbers: { autoNumber: "AMS" } }
});
</script>

See the MathJax Documentation on Equation Auto-Numbering for full details.

Math Fonts

MathJax supports standard math fonts. For example, I can add the following macros to my page:

<div class="hidden-content" style="display:none">
\[
  \newcommand{\reals}{\mathbb{R}}
  \newcommand{\integers}{\mathbb{Z}}
\]
</div>

and the line

 Let \( f: \reals \rightarrow \integers^+ \) be a function from the reals to the positive integers.

becomes: “Let \( f: \reals \rightarrow \integers^+ \) be a function from the reals to the positive integers.”

LaTeX Commands Supported By MathJax

The MathJax documentation includes a lengthy list of supported symbols and commands. Some may require loading an additional extension, which can be done via inline configuration if necessary.

Dynamically Rendering Mathematics

MathJax provides an API for rendering LaTeX dynamically after a page has loaded. The Live Demo available on MathJax.org illustrates this functionality, but we can test the API here, as well. In the box below, enter some LaTeX code, then press the “Render!” button; or unclick the “Wait before rendering” option and it should render shortly after you finish typing.

\text{Here is a matrix:}\\ \begin{pmatrix} a & b & c \\ d & e & f \\ g & h & i \end{pmatrix}\\ \ \\ \text{Here is a truth table: } \\ \begin{array}{|c|c||c|c||c|c||c|} \hline P & Q & \lnot P & \lnot Q & P \land \lnot Q & \lnot P \land Q & (P \land \lnot Q) \lor (\lnot P \land Q) \\ \hline T & T & F & & & F & \\ \hline T & F & F & T & & & \\ \hline F & T & & F & F & & T \\ \hline F & F & & & F & F & F \\ \hline \end{array}

Wait before rendering?

Let’s roll that beautiful math footage!:
\({}\)

Rich-Text Editors and MathJax

If you are using MathJax in a platform that provides a rich-text editor (such as Blackboard LMS or WordPress), then you can likely enter some of your mathematics using the rich-text interface. In this case, there are some things you can get away with but also some potential pitfalls to be aware of. Below, I include examples in both Blackboard and WordPress, but other platforms may behave differently.

Special Characters. The rich-text editor should automatically convert special characters to the appropriate HTML code (such as converting < to <), which means that you probably do not need to (and should not) use HTML escape codes as you would if you were editing raw HTML.

Generally, this makes your life a little easier. For example, this paragraph was writting in WordPress. In the sentence “Every school child knows that \( \infty + 5^0 > \infty \),” I typed “>”, which WordPress replaced with >. When you accessed the page, your web browser then converted that back to a “>”, which MathJax then included in the LaTeX code that it rendered. The good news is, you never have to think about this; just be aware of whether you are typing in a rich-text editor or in raw HTML.

Single Line vs. Multiline Math. A single-line math should be encapsulated within any HTML tags (as opposed to containing tags inside it), and so you should be able to type it into a rich-text editor and expect it to work with MathJax. But if your math requires multiple lines of LaTeX to be formatted for readability, then you are likely going to need to enter it as raw HTML. The rich-text editor will use <p> .. </p> (paragraph) tags to create new lines (or <br> (linebreak) at best), and this means you will be trying to place HTML tags inside your MathML LaTeX, which won’t work.

Similarly. copying & pasting multiline LaTeX code into a rich-text editor may cause problems, so it is safer to paste multi-line mathematics as raw HTML. The good news if you use WordPress is that MathJax and WordPress both respect the whitespace (i.e., line breaks and indenting) in your HTML. If you right-click the matrix multiplication MathJax output demoed in the Some MathJax Examples Section and select “Show Math As -> TeX Commands,” the LateX should appear with appropriate line breaks and nicely indented, as in the provided code. The bad news if you use Blackboard is that Blackboard immediately removes this white space; so if you re-open the HTML for editing in HTML, the spacing will be gone. Any effort you spent in making your LaTeX code readable would be wasted.

Potential HTML Tag and MathJax Conflicts. The rich-text editor is formatting your text with HTML tags, and those tags might interfere with the MathJax delimiters, preventing MathJax from working. This could be something you did accidentally, such as italicizing part of your text, as illustrated below; but it can also happen when the editor is trying to work behind the scenes introducing potentially invisible tags like <span>. So if your MathJax isn’t rendering, you may want to view the raw HTML to troubleshoot.

A line of text and delimited LaTeX with italicization that begins before the first delimiter and ends before the second delimiter. — When HTML tags overlap MathJax delimiters, the math will not be rendered, as is the case with this partially italicized code.

Potential Corruption. In addition to deleting your whitespace is also possible that the rich-text editor will corrupt script information. For example, Blackboard can corrupt your inline configuration code by translating characters with undesired escapes and adding unwanted CDATA tags. So depending on the inline configuration script you use (if any), you may have to fix it each time you re-open the editor to edit your content.

Human Readability. Another potential issue is that many rich-text editors do not care if the underlying HTML code is human-readable. It often looks like gobbledygook with extensive and unnecessary styling tags. If you find you need to deal with the raw HTML code, it can be tedious to read around this or delete the unnecessary content.

Keeping a Local File. For the above reasons, along with fact that Blackboard’s text editor can be buggy at the best of times, I prefer to first type up any lengthy post — or any post with significant math — in a text editor on my computer and store it as a local file. I don’t need to worry about standard HTML tags like <header> or <body>; I keep the file as “snippet” of HTML code containing just what I would type in the message I want to post, including the MathJax script call and any inline configuration at the top of the file. Then I can copy and paste the contents of file into the raw HTML editor and submit it. This has the added benefit of allowing me to minimize my interaction with the Blackboard text editor. If I need to revise the message, I can edit the local file and re-upload it, overwriting the old text. This also enables me to easily check that my snippet displays properly by opening the local file in a web browser. Even though it is not a complete valid HTML page, the browser should render the HTML and mathematics nicely.

MathJax Client Options

When viewing a web page with mathematics rendered via MathJax, the user can right-click (or long-press on mobile) to open the MathJax Context Menu. This menu offers a variety of settings, including:

accessing the original LaTeX code or the corresponding MathML code,
changing the math output between HTML, MathML, SVG, original LaTeX, among others
configuring how MathJax expression “triggered” zooming works,
triggering the default global scale for MathJax output, relative to the rest of the text on the page
setting accessibility options,
a few other options, such as language, “about MathJax”, and help.

It can be particularly helpful to have easy access to the original LaTeX, either to learn what LaTeX code provides certain desired math or to quickly copy LaTeX code for minor modifications.