Important: how the shutdown of cdn.mathjax.org affects Numbas

The MathJax team has announced that their free cdn.mathjax.org service, which serves copies of MathJax, will shut down on April 30, 2017 – the end of this month. Numbas uses MathJax to render mathematical notation using LaTeX, and until now the default theme has used cdn.mathjax.org.

This is much less notice than we would’ve liked, but it’s out of our hands. So we need to change how Numbas uses MathJax from now on, and the shutdown has ramifications for existing exam packages.

How Numbas will use MathJax from now on

In short: there’s a new default URL, and you shouldn’t notice any difference. You can configure Numbas to use your own copy of MathJax if you’d prefer.

  • By default, MathJax is now loaded from cdnjs.org, another free CDN (content delivery network) service. Again, this is a free service, so could shut down or change at some point in the future. I couldn’t find a terms of use policy, so there’s no guarantee of advance warning if that does happen. If this becomes unusable in the future, we’ll try to find another solution. However, cdnjs is backed by several well-established sponsors and used on over a million websites.
  • You can now set a preferred URL to load MathJax from in your profile on the Numbas editor. If your institution has a local copy of MathJax, you can use that: any exam or question you compile will use your preferred MathJax URL.
  • If you run your own instance of the Numbas editor, you must add a MATHJAX_URL setting to numbas/settings.py. This should be the URL of the directory containing MathJax.js, for example for cdnjs.org it’s https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0.

If you’d like to set up your own copy of MathJax, the MathJax documentation has instructions on installation.

Existing exams

In short: existing Numbas packages downloaded before April 5th will stop working in 3-6 months’ time. They must be replaced, either by re-downloading from the editor, or modifying the index.html file in each package.

If you downloaded a Numbas exam before the April 5th, it loads MathJax from cdn.mathjax.org. In the long term, these exams will have to be recompiled and replaced. However, the MathJax team have set cdn.mathjax.org to redirect to cdnjs.org, and expect that to continue for 3-6 months, so any exams uploaded to VLEs should continue working unmodified until the end of the (northern hemisphere) academic year. We can expect a similar amount of warning before this redirection ends.

You should make sure to replace any exams which will be permanently available. You don’t need to make any changes in the editor: just download the SCORM package or standalone .zip, as before, and the package you get will load MathJax from the new URL.

In case you’re not able to recompile exams, for whatever reason, or you’re the kind of person who finds command-line file modification easier, you can update your existing exams by making the following change in each exam’s index.html file:

Replace

<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML.js"></script>

with

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

If your exams are on a server running Linux, we’ve had some success with the following command, which finds all files containing references to cdn.mathjax.org and replaces them with the cdnjs.org URL. Note that this script modifies files in-place without backups and should be used entirely at your own risk.

grep cdn.mathjax.org -rl . | xargs sed -i 's#\(https\?:\)\?//cdn.mathjax.org/mathjax/\(.*-\)\?latest/#https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/#g'

Other things we’re doing to help

An absolutely fail-safe solution would be to include a copy of MathJax with each exam. Unfortunately, MathJax is 33MB, while a typical Numbas exam is only around 1MB. So, I’m looking into whether it would be possible to create a drastically stripped-down version of MathJax, which could be included with every Numbas exam and used in case the full version can’t be loaded. I’m about to go on annual leave for a week, so I expect to know whether this is possible in about a fortnight.

Another option we’re considering is to make a browser extension which automatically replaces any cdn.mathjax.org reference in pages you visit with the corresponding cdnjs.org address. This would work for Chrome and Firefox only, and might be useful if you have exams in use which you can’t replace or modify. This will be quite a bit of work, so I’ll only investigate this if there’s sufficient interest – please let us know if you’d find this useful.

In conclusion

  • We’ve made the necessary changes to make sure things keep working.
  • Try to replace any exams you’re currently using with students. If you can’t do that, don’t worry: they’ll keep working at least until the end of July.
  • If you have any queries or encounter problems, email us – we’ll be happy to help.