Adding Math/Equations to Your Joomla Article

In the process of writing an article about something that happened to me in the distant past (just over 25 years ago), I needed to put equations into an article. Not very complicated stuff, mind you, just some quantum mechanics. I promise QM is much easier to look at than some other, more elementary stuff that is much more complicated to typeset.

I wondered what the best approach would be. The original equations were typeset in TeX and fairly easy to reproduce in that language. I could do that, generate an image, and use it in the article. But you know me, the enemy of the good enough and focus on things at hand. I started looking at all the different options there were for inline equation typesetting in HTML. And man, there were tons of options!

Long story short, I settled on AsciiMath. It’s a really wonderful package, as it not only allows you typeset the equations you want, but also allows you to do so in a very intuitive way, without all the weird syntax you need to use in the other systems.

For instance, the equation I needed to typeset looks like this:{inlmath}

`Psi (vec x, t=0) = cos alpha u_1(vec x) + sin alpha u_2(vec x), 0<alpha<pi/2`

The code for it is simply:

Psi (vec x, t=0) = cos alpha u_1(vec x) + sin alpha u_2(vec x), 0<alpha<pi/2

For you math guys, it possibly seems impossible that such short input would generate the output above it. After all, you are probably used to the complexities of the equation editor in Word, or Latex’s bizarre syntax, or even worse, MathML. But this solution is incredibly elegant and smart. If you want Einstein’s famous equation, `E-mc^2`, you really just type in E=mc^2.

Possible Approaches

There are many different approaches to math typesetting on HTML pages:

  • Pre-rendering, typically as an image that is embedded into the HTML page
  • Backend real-time rendering, also typically as an image
  • Frontend rendering, in a variety of ways:
    • as regular HTML using extended CSS and tricks
    • as MathML, for browsers capable of rendering that (Firefox mostly)
    • as inline image, usually as SVG (since it’s vector-based)

Each approach has advantages and disadvantages. Pre-rendering is the least resource-intensive, since it’s done once when the page is created and the images from then on live statically on the web server. Unfortunately, it is also the least flexible: every change to the original equation requires a re-generation of the static images. Also, every time you change the images, you have to ensure they are not cached.

Backend rendering in real-time is the most flexible of solutions: it requires no assumptions in the browser, it handles changes to the original text very easily and consistently, and is overall charming and beautiful. The problem is that it consumes an unreasonable amount of server resources – either yours or someone else’s. In fact, that’s such a problem that most open backend renderers have shut down access.

Frontend rendering is sneaky. Essentially, the browser pays in CPU cycles for the privilege of having easy-to-read equations. This solution is extremely flexible – provided JavaScript is available. If that’s not the case, then you get no typesetting. The advantage is that the equation is typeset at the destination, making use of the rendering abilities of the browser. If your browser knows MathML, with this approach that support can be used to get you the best possible rendering. If the browser supports SVG, rendering can use that. And if all else fails, your browser knows CSS and tables, and then those will be used.

Joomla and Math Pre-rendering

The easiest way to deal with Joomla and equations is pre-rendering. You generate the images of the equations beforehand, upload them to your server, and then link them into your article as needed.

You can pre-render equations in a variety of ways:

  • using regular TeX/LaTeX, converting to DVI, then to image
  • using an equation editor, like Word’s, and take screenshots or print to image, then crop and upload
  • using one of the many online equation editors/generators.

One of the particularly sweet online generators, MathURL allows you to create tiny URLs. You enter the equation, look at the results, and click on Make MathURL. You can then embed that URL just like a regular image. For instance:

math url

(In reality, this approach is somewhere between pre-rendering and backend rendering, since you get the short URL only after you pre-render. So, while the image is generated on-demand, you have to go back and enter each change to the equation anew.)

Joomla and Math Backend Rendering

Backend rendering can be performed by yourself and your web server, or alternately by a third party. In either case, the rendering requires CPU cycles and is open to abuse. I guess that’s the reason why open renderers have shut down or disallowed large volume linking.

The basic idea here is that you specify the equation you want rendered as the argument to a CGI script. A typical example of this would be MimeTex (distributed with Ubuntu: sudo apt-get install mimetex). Say you place MimeTex at http://yourhost.com/cgi-bin/mimetex.cgi. Then by simply calling http://yourhost.com/cgi-bin/mimetex.cgi?x^2+y^2 you get the equation you wanted as a GIF file.

I suppose the choice of GIF already tells you this method is slightly antiquated. It stems from a time when it was hard to get something up and running on the Internet, and nobody was yet thinking about taking down things. Now it’s exactly the opposite, and it’s easy to start a site and get good links, but it’s also easy to shut down a service by exploitation.

As a result, the image quality of mimetex has never improved. The GIF files created by default are terribly grainy, and though you could improve them, I think the Internet has moved on.

Joomla and Front-end Rendering

My method of choice and also the hardest to get. For Joomla to be able to do front-end rendering, you need to inject Javascript into the page. That’s of course typically not allowed to content creators (thank goodness). If you are a content editor and the settings allow that, you can get away with adding a script to the article text. But that’s already too late for most relevant Math engines.

If you are certain that the browser supports MathML, you are in semi-good luck. You can simply pass back a <math> element with the required XML for the equation you need, and it will be displayed without need of scripts. But you need to generate the MathML, which is probably not the way you like writing up equations (Hint: the MathML for the equation above is 1476 characters.)

I will argue that the way to go is MathJax. It’s a JavaScript library that, as the name implies, looks for equations on the page and transforms them thanks to AJAX calls to a backend server. You type in the equation, the browser goes and fetches the correct renderer, and then displays what you are supposed to see.

The beautiful thing about MathJax is that it is very modular. You can specify different input languages, different output formats, and interesting rendering options. What is even more interesting is that MathJax is flexible enough to figure out the best supported output format. You don’t have to worry about MathML support, or SVG rendering capabilities: MathJax does that for you.

The downside is that you can’t use it in Joomla natively. That’s because the MathJax script needs to be loaded in the <head> of the page and not in the article, which is in the body. Fortunately, it’s fairly easy to create a plugin that does just that.

MathJax Plugin

Obviously, that’s what I did. To make this work, you install the mathjax plugin into Joomla, turn it on, and merrily start typing away.

You tell the plugin that you want to turn on rendering by inserting the tag { mathjax } (no spaces) into your text. You can give the tag additional parameters that can be set by default in the Admin backend (Plugin parameters).

As mentioned, I particularly like the AsciiMath extension. To use it, you specify the config argument with value AM_HTMLorMML for AsciiMath to HTML or MathML rendering. Something like this (again, ignore the space after the opening brace):

{ mathjax config=AM_HTMLorMML}

AsciiMath likes backticks (top left on your keyboard, in many cases) to specify equations, so use those. The syntax is incredibly easy and you can look it up at the home of AsciiMath.

Good luck, and let me know if you need the plugin!!!

Add a Comment

Your email address will not be published. Required fields are marked *