CMH, 2022-09-04

As the filenames would imply, there are two shortcodes:
- gallery, in layouts/shortcodes/gallery.html
- figure, in layouts/shortcodes/figure.html

'gallery' has a single purpose: to wrap multiple items in a
photo container.  It takes no parameters.

'figure' inserts pictures, which should be done inside 'gallery'
shortcode.  Its parameters are:

- 'resources', a required parameter which will be matched against page
  resources.  This can be a single image name, or it can use globbing,
  e.g. "figure/**.jpg" to match every JPEG.
- 'page', an optional parameter for the name of the page in which to
  find these page resources.  By default this is the current page.
- 'linkto', an optional parameter to have the photo's caption (when
  clicked) also be a link to another Hugo page.  This must be a
  reference Hugo knows how to resolve, e.g. "/about.md".  By default,
  no link is generated.
- 'title', an optional parameter to set the caption's text.  This
  caption will be, in order of preference:
  - The value specified in this parameter
  - Exif title specified in a corresponding JSON to the image (see
    the cavelab URL below for how to generate this)
  - If 'linkto' is specified, that page's title
  - The filename itself

Note that if 'resources' specifies multiple photos (e.g. with
globbing), then 'linkto' and 'title' will apply to all such photos.
Their typical usage is when 'resources' specifies a single file.

An example usage is something like:

{{< gallery >}}
{{< figure resources="image/foo.jpg" title="Foo (a JPEG)" linkto="/about.md">}}
{{< figure page="images" resources="figure/**.jpg" >}}
{{</ gallery >}}

This would make a gallery where the first item is the page resource
'image/foo.jpg' on the current page, and its caption has "Foo (a
JPEG)" as its text, and the text is also a link to the About page.
The gallery's following items are every JPEG in the 'figure' directory
of the page resources for the 'images' page.

This started from a setup documented at:
https://blog.cavelab.dev/2021/04/photo-gallery-posts/
