Leyline ships a gallery shortcode that renders photos in a masonry column layout. Clicking any thumbnail opens a fullscreen lightbox with keyboard navigation.

The cleanest setup is a leaf bundle: a directory with an index.md and the images alongside it.

content/posts/my-post/
  index.md
  photo-01.jpg
  photo-02.jpg
  photo-03.jpg

Then in index.md:

{{< gallery match="photo-*" >}}

Hugo processes every matched image into optimised WebP — a 600 px-wide thumbnail for the grid and up to 1600 px for the lightbox. Use a consistent prefix (photo-, img-, etc.) so the glob is predictable, and name files numerically to control display order.

From explicit URLs or paths

Pass a comma-separated list with the images parameter. Each entry is tried as a page resource first; if it isn’t found it is used as a URL directly — useful for images hosted elsewhere or served from static/.

{{< gallery images="https://example.com/a.jpg, https://example.com/b.jpg" >}}

Optionally pass captions as a pipe-separated list. Captions map to images by position and appear only in the lightbox:

{{< gallery images="https://example.com/a.jpg, https://example.com/b.jpg" captions="At the coast|On the trail" >}}

The three galleries below are all rendered this way.

Three columns (default)

Two columns

{{< gallery match="photo-*" cols="2" >}}

Parameters

ParameterRequiredDefaultDescription
match——Glob pattern matched against page bundle resources (e.g. "photo-*")
images——Comma-separated list of filenames or URLs
captions——Pipe-separated captions, in image order; shown in the lightbox only
cols—3Number of masonry columns on wide screens

One of match or images must be provided. match requires a leaf bundle.

ActionResult
Click thumbnailOpen lightbox
← / → arrow keysPrevious / next image
EscClose
Click × buttonClose