HowTo: Automatically generating image galleries based on

As you might have noticed all image galleries of this blog are meanwhile based on the framework. is great because it is Free/Libre Software (MIT-licensed), simply does what it is supposed to do, and requires not yet another plugin for WordPress nor a database backend. It also supports mobile devices and its typical touch gestures. Furthermore it enables self-hosted galleries and does not require to rely on any cloud services where you might loose control on your data.

The only thing that I was missing was a straight forward way to automatically generate a gallery. Creating it by hand – as for example described in’s “Beginners Guide” – is time-consuming, cumbersome, and error-prone. So the overall idea was to create a ready-to-run gallery based on a given folder that contains just the image files by using a shell script.

In detail I wanted to have the following functionality:

  • A gallery based on should be generated out of a given source folder that contains the image files as JPEGs. The folder corresponds to one gallery (collection of image files).
  • Multiple folders should be supported so to be able to generate multiple galleries at once.
  • Required thumbnails with naturally much lower resolution should be automatically generated based on the original image files.
  • Title and description of gallery should be customisable. The intended text should be provided during gallery creation.
  • In case an image has a title and caption given within the JPEG file it should be extracted. As I use Adobe Lightroom the title and caption are provided within the XMP tags “Xmp.dc.title” and “Xmp.dc.description”.
  • Images, thumbnails and provided metadata should be automatically integrated within the gallery definition file.
  • Actual files (images, thumbnails and gallery definition file) should be added to the resulting destination folder that could then be easily uploaded to the hosting web server.

As solution I have created a shell (Bash) script that could be run on any GNU/Linux-like environment. For thumbnail creation ImageMagick was used, for extraction of EXIF/XMP metadata Exiv2 was used. The script works also on a Macintosh as it actually was developed and tested on it. Required tools are available via MacPorts.

You are welcome to download, use, and modify it from here:


./ [destination directory]

Prerequisites (as stated): Bash, ImageMagick, Exiv2 and ideally some knowledge in scripting, HTML and to adjust it to your needs.

Please note: You need to place the core files somewhere on your server and set the (relative) links to these files correctly within the provided script. In other words the script just works fine with my settings and needs to be adjusted to your setup. Error handling is currently very basic and addresses only some common mistakes.

Improvement opportunities:

  • Move any customisations like imports and the links to the core files into a separate config file or alternatively to a configuration part within the script.
  • Offer a persistent storage of already processed galleries in order to remember at least the already provided title and description per gallery. Use case: It might happen that you need to recreate a gallery as you forgot to include or remove certain images.
  • Improved error handling and overall guidance to also support non-expert users.