Tom MacWright

tom@macwright.com

Math as SVG for fast webpages

Sometimes mathematical notation is a good way to share ideas. You can share formulas as MathML, but suffer the scant browser support, or MathJax1, and require extra JavaScript, CSS, and fonts on your page. Around here, we’re focused on lightweight pages, so let’s talk about a more performant way to include math on the web: SVG.

I’m going to make three assumptions:

  1. You need to share math on the web, and you want to use or already use LaTeX to write formulas
  2. You use a Mac with OS X
  3. You have Homebrew installed on your Mac

If you don’t have Homebrew, I’d recommend installing it - it’s very useful for this and many other bits of software.

There are three levels of software that you’ll need:

  1. A LaTeX distribution
  2. LaTeXiT
  3. Extra dependencies required for LaTeXiT to output SVG

Install ‘a smaller MacTeX’

If you aren’t familiar with LaTeX, it’s a markup language like Markdown or HTML, intended for written documents like books and papers. It’s a powerful language that can produce really complex and beautiful documents.

You usually don’t install ‘LaTeX’ - instead you install a distribution, which is a wrapper around LaTeX, presets, and sometimes editing software. Since you’re on a Mac, the distribution to get is MacTeX. Recently the MacTeX folks have done a real solid and now produce ‘a smaller MacTex’, which I highly recommend: the default is 2.5 gigabytes, the smaller is 100 megabytes, and it works just as well for this case.

Install LaTeXiT

LaTeXiT is an application that turns LaTeX equations into images, PDFs, and SVG. Especially compared to the process of using LaTeX on a command line, LaTeXiT is incredibly simple and easy to use.

Installing those extra dependencies

The ‘full’ version of MacTeX includes these dependencies, but installing the ‘smaller’ version and then getting these from Homebrew is much faster. You’ll need to install ghostscript and pdf2svg:

$ brew install ghostscript pdf2svg

Producing SVG from your math

Okay, you’ve installed all the dependencies: it’s time to do some math! I’ll use this hopelessly mainstream equation:

Beautiful: now you have an SVG file with your equation all typeset. Since we’re really optimizing for speed, you can go a step further and use SVGOMG to reduce the SVG’s size. There’s usually a really good payoff to this, up to a 50% decrease. Since I set all the images on this blog to be 100% width, I usually check the Prefer viewBox to width/height option, which will remove the width and height properties from the image and let it assume the size of its container or have a width controlled by CSS.

Using that SVG on the web

There are three distinct ways to use your fresh new SVG on the web.

<img src='images/emc2.svg' />

The first is the most conventional: as an image, with an img tag, just like you would use a PNG or JPEG image. This means you have the SVG file hosted somewhere, in your images/ directory for instance, and you refer to it from the post.


{% include images/emc2.svg %}

The second is what we do with Mapbox.com, and is specific to websites that use the Jekyll static site generator. You save your image in images/, but instead of referencing it with an img tag, you include it on the page directly by using the include tag. This inserts the content of the SVG image directly into the page but lets you manage the image as a separate file.

<svg ...

The third is what I do on macwright.org (here): I open the SVG file in a text editor and put it directly into these blog posts, which I write in Markdown. This means the illustrations and the text content are in the same file - there’s no reference, in HTML or with Jekyll, just one file.

Why three approaches?

The img tag is the slowest technique if the image will only be on one page and someone’s viewing the page once. It requires another HTTP request, potentially another DNS lookup - it has overhead. But if the image is on lots of pages and the user will see it often, it can be faster than the other two because of caching.

The other two approaches will look the same to a browser and have the same performance characteristics. I prefer to keep SVG in my content because it makes the connection obvious - I don’t have to remember to keep track of which posts use which images when I remove or delete them.

Thanks for reading!

I hope this helps people share their mathematical ideas on the web. Note that there are lots of cases where math symbols may not be the best way of communicating, and there’s a very interesting discussion about alternatives. But sometimes you really need some greek symbols.

If this whetted your appetite for making really efficient webpages, read the last post on optimizing web fonts, CSS, and more.

  1. Readers note: KaTeX is an optimized alternative to MathJax. It’s definitely faster and can do pre-rendering, but still requires extra CSS and fonts. If you’re only using math in some articles, I think the approach in this article is faster and simpler, but if your website is super math-heavy, try out KaTeX.