hugo-snap-gallery

Automagical css image gallery in Hugo using shortcodes.

This is a fork of easy gallery. It is supposed to come without any JavaScript and therefore has limited features, but new JS-less stuff is planned.

Image Gallery Features

• Custom {{< figure >}} shortcode that enables new features but is backwards-compatible with Hugo's built-in {{< figure >}}shortcode
• Use the {{< figure >}} shortcode by itself to enable pretty captions
• Put multiple {{< figure >}} shortcodes inside a {{< gallery >}} to create a pretty image gallery
• Point {{< gallery >}} at a directory to generate a gallery of all images in that directory
• Gallery is responsive, images are scaled/cropped to fill square (or other evenly-sized) tiles
• Pretty captions appear/slide/fade upon hovering over the image
• Only requires 3.8kB of CSS (unminified; you can minify it if you want)
• CSS is automatically loaded the first time you use the {{< figure >}} shortcode on each page

PhotoSwipe Features

• Load PhotoSwipe by calling the {{< load-photoswipe >}} shortcode anywhere in your post
• Loads all of the <figure> elements in your post, regardless of where in your post they appear, into a lightbox/carousel style image gallery
• Works with any existing <figure> elements/shortcodes in your posts
• Does not require you to pre-define the image sizes (the initialisation script pre-loads the image to determine its size; you can optionally pre-define the image size if you want to avoid this pre-loading)

Installation

Use this like an additional Hugo theme.

{{< figure >}} shortcode usage

Specifying your image files:

• {{< figure src="thumb.jpg" link="image.jpg" >}} will use thumb.jpg for thumbnail and image.jpg for lightbox
• {{< figure src="image.jpg" >}} or {{< figure link="image.jpg" >}} will use image.jpg for both thumbnail and lightbox
• {{< figure link="image.jpg" thumb="-small" >}} will use image-small.jpg for thumbnail and image.jpg for lightbox

Optional parameters:

• All the features/parameters of Hugo's built-in figure shortcode work as normal, i.e. src, link, title, caption, class, attr (attribution), attrlink, alt
• size (e.g. size="1024x768") pre-defines the image size for PhotoSwipe. Use this option if you don't want to pre-load the linked image to determine its size.
• class allows you to set any custom classes you want on the <figure> tag.

Optional parameters for standalone {{< figure >}} shortcodes only (i.e. don't use on {{< figure >}} inside {{< gallery >}} - strange things may happen if you do):

• caption-position and caption-effect work the same as for the {{< gallery >}} shortcode (see below).
• width defines the max-width of the image displayed on the page. If using a thumbnail for a standalone figure, set this equal to your thumbnail's native width to make the captions behave properly (or feel free to come up with a better solution and submit a pull request :-)). Also use this option if you don't have a thumbnail and you don't want the hi-res image to take up the entire width of the screen/container.

{{< gallery >}} shortcode usage

To specify a directory of image files:

{{< gallery dir="/img/your-directory-of-images/" />}}`

• The images are automatically captioned with the file name.
• [image].jpg is used for the hi-res image, and [image]-thumb.jpg is used for the thumbnails.
• If [image]-thumb.jpg doesn't exist, then [image].jpg will be used for both hi-res and thumbnail images.
• The default thumbnail suffix is -thumb, but you can specify a different one e.g. thumb="-small" or thumb="_150x150".

To specify individual image files:

{{< gallery >}}
  {{< figure src="image1.jpg" >}}
  {{< figure src="image2.jpg" >}}
  {{< figure src="image3.jpg" >}}
{{< /gallery >}}

Optional parameters:

• 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)
• caption-effect - determines if/how captions appear upon hover. Options:
  • slide (default)
  • fade
  • none (captions always visible)
• hover-transition - determines if/how images change upon hover. Options:
  • not set - smooth transition (default)
  • none - hard transition

CSS Hackers

snap-gallery.css is designed to provide square tiles in a container with max-width: 768px.

Here are some pointers if you want to adapt the CSS:

• Change .gallery {max-width: 768px;} if you want a gallery wider than 768px.
• Change min-width in the @media styles to change the screen widths at which the layout changes
• Change min-width: 9999px in the last @media style to something sensible if you want to use a 4-tile layout
• If you want more than 4 tiles per row, set width = 100% / number of tiles per row
• padding-bottom = width gives square tiles. Change padding-bottom if you want some other aspect ratio, e.g. width: 33.3%; padding-bottom: 25% gives a 4:3 aspect ratio.

License

MIT