Tim Sherratt

Sharing recent updates and work-in-progress

Jun 2024

Running Mirador on GitHub Pages

I’ve just created a GitHub repository template that you can use to get your own Mirador version 3 installation running in minutes. You can also configure it to display local or remote IIIF manifests. I was thinking that it could be useful for researchers who want to create their own customised Mirador workspaces to examine a particular set of documents, but don’t want to install any software or fiddle about on the command-line.

Screenshot of Mirador workspace showing two windows displaying manuscript images.

I’ve been doing a lot with IIIF lately. First a GLAM Workbench notebook to save a collection of images from Trove as an IIIF manifest. Then a tutorial for the Trove Data Guide that walks through the whole process of generating an IIIF manifest from Trove, then loading the manifest into Tropy for analysis and annotation. I’ve also just about finished another tutorial that saves parts of a manuscript collection as IIIF manifests, then loads them into Mirador for side-by-side comparison.

In the new tutorial I was planning to use GitHub to put the manifests online so that they could then be displayed using the Mirador demo site. But then I thought if we’re saving the manifests to GitHub, why not use GitHub Pages to run a customised version of Mirador that can read the manifests from its own repository? There are various examples around of getting Mirador running on services like Netlify, but I couldn’t find a GitHub Pages example. So I decided to make my own.

The Mirador integration examples were useful in getting a basic set-up working. Then it was a matter of creating a GitHub action to generate the Mirador site any time the repository changed. As mentioned, I wanted users to be able to load local manifests into their Mirador workspace, so I wrote a little Python script to check the manifests directory for files, and copy the paths into the Mirador config. So all a researcher has to do is upload a manifest to the repository, then the deploy scripts rewrite the config and create a new version of the Mirador site automatically.

Similarly, if you want to include some remote manifests in your default workspace, it’s just a matter of adding the urls to the manifest_urls.txt file. The deploy scripts read the file and add the urls to the config.

I’ve included the Mirador Image Tools plugin in the default installation, but you can modify the template to add additional plugins if you want. With Mirador version 4 currently being tested, I’ll no doubt create a version 4 template before too long. Let me know if you find this useful!