+<h2 id="album"><code>album</code> directive</h2>
+
+Each page containing an `album` directive is treated as a photo album.
+
+Every image attached to an album or its subpages is considered to be part of
+the album. A "viewer" page, with the wiki's default page extension, will be
+generated in the [[transient underlay|todo/transient_pages]] to display the
+image, if there isn't already a page of the same name as the image: for
+instance, if `debconf` is an album and `debconf/tuesday/p100.jpg` exists,
+then `debconf/tuesday/p100.mdwn` might be created.
+
+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 `album` directive also produces an [[ikiwiki/directive/inline]] which
+automatically includes all the viewers for this album, except those that
+will appear in an <a href="#albumsection">albumsection</a> (if every image
+is in a section, then the `album` directive won't have any visible effect).
+
+The `inline` is in `archive` and `quick` mode, but can include some
+extra information about the images, including file size and a thumbnail made
+using [[ikiwiki/directive/img]]). The default template is `albumitem.tmpl`,
+which takes advantage of these things.
+
+<h2 id="albumsection"><code>albumsection</code> directive</h2>
+
+The `albumsection` directive is used to split an album into sections. It can
+only appear on a page that also has the <a href="#album">album</a> directive.
+
+The `filter` parameter is a [[ikiwiki/PageSpec]] against which viewer pages
+are matched. The `albumsection` directive displays all the images that match
+the filter, and the `album` directive displays any leftover images, like
+this: