About the website and technical information

This page provides design choices and technical information about the website and the format in which the resources are written. For information on how to use the website please see our How-to guide.

Structure and navigation

The main content of the website is organised into a simple hierarchy of Tubemap, station, resource, where stations represent mathematical topics. The website tries to keep the idea of being at a particular location in order to make the navigation as easy as possible. To this end, there is a simple main menu that appears at the top of each page, which gives instant access to the map, search and browse screens via dedicated buttons. These screens all appear as modal dialogs and do not take you away from the current page, thus allowing you to stay at the same location whilst you look for a new one.

Technical details: resources

Resources are written online in an admin section of the website, by our team of resource designers (altough they may have ideas on paper first!). The content is stored in a MySQL database and any associated images are uploaded and stored in the file system on the server.

Resources need to be delivered in both HTML (for online viewing) and PDF format (for printing). We decided that the browser print function was not flexible enough to print resources, therefore the we needed a system which could generate HTML and PDF versions from common source code. We chose to use Markdown as a convienent language in which to write resources, which can then be converted to HTML and LaTeX by a program called Pandoc. The LaTeX can then be converted to PDF.

The actual mathematics is written as LaTeX within the Markdown, which is passed straight through to the HTML and LaTeX outputs and the MathJax JavaScript library is used to render the mathematics in the HTML web page.

However, this process is complicated by the fact that we wanted more features than offered by Markdown, such as toggleable sections, highlighting questions and comments, alternative output for the printable version, etc. To do this, we introduced some custom XML (or HTML) tags which are processed before the Markdown, and output different code for the HTML and LaTeX versions.

A subjective note - working with Markdown programmatically is quite difficult due to whitespace being significant, so it may have been better to use a restricted subset of HTML rather than Markdown, even though it is slightly less convienient to write things like lists in HTML.

Since resources can be converted to LaTeX, it's possible to produce a booklet of resources quite easily. Indeed, we even offer that to users as part of 'Your resource collection' (users can generate combined PDFs from subcollections). However, this is not designed to be used for large numbers of resources. Any links in resources take users back to the website, and we don't offer our station pages and other navigational pages as PDFs. This is deliberate as we think the best experience is via the website.

Offline viewing

The website makes use of the ServiceWorker API, currently supported in Chrome and Firefox. This means that pages are cached, and you should be able to visit a page you've been to before even if offline. It will try to fetch the online version first before trying the cache, so very slow internet connections will still cause problems - there needs to be no internet access for the cached version to be fetched.