Plugin: album
Author: Simon McVittie
Included in ikiwiki: no
Enabled by default: no
Included in goodstuff: no
Currently enabled: no

This plugin provides the album directive, which turns a page into a photo album or image gallery, containing all images attached to the album or its subpages. It also provides the albumsection and albumimage directives.

This plugin automatically enables the filecheck, img, inline, trail and transient plugins. The meta plugin is also recommended.


Altered Demo

Available in a git repository branch.
Branch: cbaines/album

This uses the album plugin, with some altered css, and with the css applied to all of the themes.


Available in a git repository branch.
Branch: smcv/album5
Author: Simon McVittie

Available from smcv's git repository, in the album5 branch. I've called it album to distinguish it from contrib/gallery, although gallery might well be a better name for this functionality.

(The Summer of Code gallery plugin does the next/previous UI in Javascript using Lightbox, which means that individual photos can't be bookmarked in a meaningful way, and the best it can do as a fallback for non-Javascript browsers is to provide a direct link to the image.)

Updated, June 2014: integrated changes from KathrynAndersen, Lukas Lipavsky and kjs

An album6 branch is also available, but is less suitable for manual installation since it needs core IkiWiki changes (until trails depend on everything is fixed).

Manual installation

First, you need a version of ikiwiki with the trail plugin merged in (version 3.20120203 or later).

Manual installation requires these files (use the "raw" link in gitweb to download):

Changing the templates

When a viewer page is generated or inlined into an album, the template can contain these extra variables:

  • <TMPL_VAR ALBUM> - page name of the album
  • <TMPL_VAR ALBUMURL> - relative URL to the album
  • <TMPL_VAR ALBUMTITLE> - title of the album, usually taken from a meta directive
  • <TMPL_VAR CAPTION> - caption for the image
  • <TMPL_VAR THUMBNAIL> - a small img for the image
  • <TMPL_VAR IMAGEWIDTH> - width of the full-size image in pixels
  • <TMPL_VAR IMAGEHEIGHT> - height of the full-size image in pixels
  • <TMPL_VAR IMAGEFILESIZE> - size of the image, e.g. 1.2 MiB
  • <TMPL_VAR IMAGEFORMAT> - format of the image, typically JPEG

The template for the viewer page can also contain:

  • <TMPL_VAR IMG> - a large img to display the image
  • <TMPL_VAR PREV> - a link to the previous viewer, typically with a thumbnail
  • <TMPL_VAR NEXT> - a link to the next viewer, typically with a thumbnail

Including album entries elsewhere

To display images from elsewhere in the wiki with the same appearance as an album or albumsection, you can use an inline with the albumitem template:

[[!inline  pages="..." sort="-age" template="albumitem"]]


  • There's currently a hard-coded list of extensions that are treated as images: png, gif, jpg, jpeg or mov files. More image and video types could be added in future.

  • Videos aren't currently handled very well; ideally, something like totem-video-thumbnailer would be used.

  • The plugin doesn't do anything special to handle albums that are subpages of each other. If, say, debconf and debconf/monday are both albums, then debconf/monday/p100.jpg will currently be assigned to one or the other, arbitrarily. It should probably pick the closest (longest) album name. (I'm not sure that it can do this reliably, though, since the scan stage runs in an undefined order.)

  • The plugin doesn't do anything special to handle photos with similar names. If you have p100.jpg and p100.png, one will get a viewer page called p100 and the other will be ignored. (I'm not sure what we could do better, though.)

  • If there's no albumimage in a viewer page, one should probably be appended automatically.


  • The generated viewer page should extract as much metadata as possible from the photo's EXIF tags (creation/modification dates, author, title, caption, copyright). smcv once had a half-written implementation which runs scanimage hooks, and an exiftool plugin using Image::ExifTool as a reference implementation of that hook, but has lost that code somewhere :-(

  • There should be an option to reduce the size of photos and write them into an underlay (perhaps just the transient underlay), for this workflow:

    • your laptop's local ikiwiki has two underlays, photos and webphotos
    • photos contains full resolution photos with EXIF tags
    • for each photo that exists in photos but not in webphotos, the album plugin automatically resamples it down to a web-compatible resolution (smcv uses up to 640x640), optimizes it with jpegoptim, strips out all EXIF tags, and and writes it into the corresponding location in webphotos
    • webphotos is what you rsync to the web server
    • the web server's ikiwiki only has webphotos as an underlay
  • Eventually, there could be a specialized CGI user interface to batch-edit all the photos of an album (so for each photo, you get an edit box each for title, author, copyright etc.) - this would work by making programmatic edits to all the albumimage directives.