Home / Blog / Hugo Photoswipe5 Gallery Theme

Hugo Photoswipe5 Gallery Theme

5 minutes
December 30, 2022 - Last modified: March 6, 2024

Over the last days I create a gallery displaying images in a lightbox/carousel gadget. It’s a css image gallery in Hugo using shortcodes, for the optional lightbox/carousel gadget I’m using PhotoSwipe 5.3.x and Dynamic caption plugin.

This theme can create a gallery of all images in a page bundle. It uses Hugo Page Resources, which allows to create thumbnails on the fly, with a configurable thumbnail size.

It’s based and inspired by the easy-gallery theme from Li-Wen Yip. But due to the usage of Hugo Resources and PhotoSwipe 5.x, it is not compatible anymore.

Create a gallery from a page bundle

{{< gallery />}} {{< load-photoswipe >}}

  • All images in the page bundle are listed.
  • The images are automatically captioned with the file name.
  • Thumbnails are automatically generated using Hugos Image Resources. The default thumbnail size is 300x300 pixels.
  • The layout is repsonsive, change the browser window size or use Chrome device mode to see the effects.
  • {{< load-photoswipe >}} enables PhotoSwipe carousel/lightbox gadget. This shortcode needs to be called once per page. Without this shortcode, the same image gallery is shown, but the images are referenced directly.
  • The directory structure for this blog post is:
content/
└── post/
    ├── _index.md
    └── hugo-photoswipe5-gallery/             <-- page bundle
        ├── index.md
        ├── 20221002093800-00-wm.jpg          <-- page resource
        └── img/
            ├── 20220927152237-00-wm.jpg      <-- page resource in subdir
            ├── 20220928121359-00-wm.jpg
            ├── 20220928121359-00-wm.jpg.meta <-- sidecar file
            └── 20220928161751-00-wm.jpg
{{< gallery >}} {{< load-photoswipe >}}
{{< picture src="20221002093800-00-wm.jpg" caption="Leaving Amrum" >}}
{{< picture src="20220927152237-00-wm.jpg" caption="After heavy rain" >}}
{{< picture src="20220928161751-00-wm.jpg" caption="Amrum Lighthouse" >}}
{{< /gallery >}}
{{< gallery match="*202210*" />}} {{< load-photoswipe >}}

Optional parameters

  • caption-effect - determines if/how captions appear upon hover. Options:
    • slide (default)
    • fade
    • none (captions always visible)
  • caption-position - determines the captions’ position over the image. Options:
    • bottom (default)
    • center
    • none hides captions on the page (they will only show in PhotoSwipe)
  • hover-effect - determines if/how images change upon hover. Options:
    • zoom (default)
    • grow
    • shrink
    • slideup
    • slidedown
    • none
  • hover-transition - determines if/how images change upon hover. Options:
    • not set - smooth transition (default)
    • none - hard transition
  • thumbnail-size sets the size of the thumbnails for the gallery. Default is “300x300”. First number is width, second number is height. This option affects the quality and size of the preview image, but not the display size, which depends on the style.
  • match - limits the search path and pattern for images
  • sort - decides how the images get’s sorted. Options:
    • asc (ascending, default)
    • desc (descending)

Global Configuration Variables

[params.gallery]
  useExif = true
  sort = asc

  • useExif defines if Exif informations should be shown in the photoswipe lightbox. This can be overwritten per page in the Front Matter.

  • sort decides whether the images are sorted ascending (“asc”) or descending (“desc”) and can be overwritten per gallery option.

Sidecar files

The metadata embedded in an image can be extended or overwritten by a metadata sidecar file. The file must have the same name as the image plus “.meta” (e.g. “image.jpg.meta”). The content has to be a JSON like:

{
"Tags": ["amrum","natur"],
"Title": "Lighthouse",
"Caption": "The Lighthouse of Amrum",
"Rating": 2
}

Caption effects

{{< gallery hover-effect="none" caption-effect="slide" />}}
{{< gallery hover-effect="none" caption-effect="fade" />}}
{{< gallery hover-effect="none" caption-effect="appear" />}}
{{< gallery hover-effect="none" caption-effect="none" />}}

Caption position

{{< gallery caption-position="bottom" caption-effect="slide" />}}
{{< gallery caption-position="center" caption-effect="fade" />}}
{{< gallery caption-position="none" />}}

Hover effects

{{< gallery hover-effect="zoom" />}}
{{< gallery hover-effect="grow" />}}
{{< gallery hover-effect="shrink" />}}
{{< gallery hover-effect="slideup" />}}
{{< gallery hover-effect="slidedown" />}}
{{< gallery hover-effect="none" />}}
{{< gallery hover-effect="grow" hover-transition="none" />}}

Thumbnail Size

{{< gallery thumbnail-size="100x100" />}}

Picture

{{< picture src="20220928161751-00-wm.jpg"
    thumbnail-size="480x480"
    alt="Lighthouse Amrum" >}}

Picure options

The picture shortcode can use the following named parameters:

  • src - URL of the image to be displayed.
  • alt - Alternate text for the image if the image cannot be displayed.
  • title - Image title.
  • caption - Image caption.
  • class - class attribute of the HTML figure tag.
  • height - height attribute of the image.
  • width - width attribute of the image.
  • attr - Image attribution text. Markdown within the value of attr will be rendered.
  • attrlink - If the attribution text needs to be hyperlinked, URL of the destination.

The options caption-position and caption-effect don’t work yet:

{{< gallery caption-position="bottom" caption-effect="slide" />}}
{{< gallery caption-position="center" caption-effect="fade" />}}
{{< gallery caption-position="none" />}}