2022-02-28 - Help wanted: Unfortunately I am no longer able to maintain this project myself (I have a busy day job that has nothing to do with web development or computer coding, and any spare time is taken up with family + other committments) so I am looking for collaborators to help maintain this project i.e. review and merge pull requests and help with issues. Thanks to Kishor Bhat and Emiel Hollander who have already generously volunteered. We could use a few more collaborators - please email me if you're interested :-)
Automagical css image gallery in Hugo using shortcodes, with optional lightbox/carousel gadget using PhotoSwipe and jQuery.
New: Create a gallery of all images in a directory with just one line of shortcode, see demo.
Need help?
Fixed an issue or made an improvement?
{{< figure >}} shortcode that enables new features but is backwards-compatible with Hugo's built-in {{< figure >}}shortcode{{< figure >}} shortcode by itself to enable pretty captions{{< figure >}} shortcodes inside a {{< gallery >}} to create a pretty image gallery{{< gallery >}} at a directory to generate a gallery of all images in that directory{{< figure >}} shortcode on each page{{< load-photoswipe >}} shortcode anywhere in your post<figure> elements in your post, regardless of where in your post they appear, into a lightbox/carousel style image gallery<figure> elements/shortcodes in your postscdnjs.cloudflare.comPut files in following places:
NB load-photoswipe.html loads jQuery from cdnjs.cloudflare.com.
load-photoswipe.html.load-photoswipe.js from the footer instead of in load-photoswipe.html.If you want, you could (depending on a front matter param) conditionally load load-photoswipe.html or its contents from the footer of your template. But I've consciously chosen to load PhotoSwipe using a shortcode so that you don't have to modify your template if you don't want to.
Put files in the relevant folders within your theme.
Delete /layouts/shortcodes/load-photoswipe.html.
Rename /layouts/shortcodes/load-photoswipe-theme.html to /layouts/shortcodes/load-photoswipe.html.
Add the following lines to the footer of your template, just before </body>:
(Omit the jQuery line if jQuery is already loaded elsewhere in your template; just make sure that jQuery is loaded before this code.)
<!-- Load PhotoSwipe js if the load-photoswipe shortcode has been used -->
{{ if ($.Scratch.Get "photoswipeloaded") }}
<script src="https://code.jquery.com/jquery-1.12.4.min.js" integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"></script>
<script src="https://github.com/liwenyip/hugo-easy-gallery/raw/master/js/load-photoswipe.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.1/photoswipe.min.js" integrity="sha256-UplRCs9v4KXVJvVY+p+RSo5Q4ilAUXh7kpjyIP5odyc=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/photoswipe/4.1.1/photoswipe-ui-default.min.js" integrity="sha256-PWHOlUzc96pMc8ThwRIXPn8yH4NOLu42RQ0b9SpnpFk=" crossorigin="anonymous"></script>
{{ end }}{{< figure >}} shortcode usageSpecifying your image files:
{{< figure src="https://github.com/liwenyip/hugo-easy-gallery/raw/master/thumb.jpg" link="image.jpg" >}} will use thumb.jpg for thumbnail and image.jpg for lightbox{{< figure src="https://github.com/liwenyip/hugo-easy-gallery/raw/master/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 lightboxOptional parameters:
figure shortcode work as normal, i.e. src, link, title, caption, class, attr (attribution), attrlink, altsize (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. class="no-photoswipe" prevents a <figure> from being loaded into PhotoSwipe. If you click on the figure you'll instead a good ol' fashioned hyperlink to a bigger image (or - if you haven't specified a bigger image - the same one).{{< gallery >}} shortcode usageTo specify a directory of image files:
{{< gallery dir="/img/your-directory-of-images/" />}}[image].jpg is used for the hi-res image, and [image]-thumb.jpg is used for the thumbnails.[image]-thumb.jpg doesn't exist, then [image].jpg will be used for both hi-res and thumbnail images.-thumb, but you can specify a different one e.g. thumb="-small" or thumb="_150x150".To specify individual image files:
{{< gallery >}}
{{< figure src="https://github.com/liwenyip/hugo-easy-gallery/raw/master/image1.jpg" >}}
{{< figure src="https://github.com/liwenyip/hugo-easy-gallery/raw/master/image2.jpg" >}}
{{< figure src="https://github.com/liwenyip/hugo-easy-gallery/raw/master/image3.jpg" >}}
{{< /gallery >}}Optional parameters:
caption-position - determines the captions' position over the image. Options:
bottom (default)centernone hides captions on the page (they will only show in PhotoSwipe)caption-effect - determines if/how captions appear upon hover. Options:
slide (default)fadenone (captions always visible)hover-effect - determines if/how images change upon hover. Options:
zoom (default)growshrinkslideupslidedownnonehover-transition - determines if/how images change upon hover. Options:
none - hard transition{{< load-photoswipe >}} once on each page where you want to use PhotoSwipe.You can optionally have different captions on page vs in PhotoSwipe:
{{< figure src="https://github.com/liwenyip/hugo-easy-gallery/raw/master/image.jpg" alt="This is a caption">}} or {{< figure src="https://github.com/liwenyip/hugo-easy-gallery/raw/master/image.jpg" caption="This is a caption">}} will use the same caption both on the page and in PhotoSwipe.{{< figure src="https://github.com/liwenyip/hugo-easy-gallery/raw/master/image.jpg" caption="A short caption" alt="This is a much longer, verbose, comprehensive caption that will be used in PhotoSwipe">}} will use a different caption in PhotoSwipe.hugo-easy-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:
.gallery {max-width: 768px;} if you want a gallery wider than 768px.min-width in the @media styles to change the screen widths at which the layout changesmin-width: 9999px in the last @media style to something sensible if you want to use a 4-tile layoutwidth = 100% / number of tiles per rowpadding-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.I've tested this with the beautifulhugo theme. If things don't work properly with other themes, raise an issue on GitHub, or even better fix the issue and submit a pull request :-)
These blog posts helped me immensely: