hugo-shortcode-gallery

This is a theme component for hugo.

This component contains a shortcode to include a gallery in your .md files.

The gallery is rendered using autogenerated thumbnails arranged in a grid. With a click on the images a lightbox is opened an all images can be viewed fullscreen.

Demo

You can see this shortcode-gallery in action on my website.

Installation

Clone this git repository into your themes folder.

git clone https://github.com/mfg92/hugo-shortcode-gallery.git

Next edit your projects config.toml and add this theme component to your themes:

theme = ["your-main-theme", "hugo-shortcode-gallery"]

To read about hugo's theme components and how to use them have a look at https://gohugo.io/hugo-modules/theme-components/.

Usage Example

Here is an usage example:

{{< gallery match="images/*" sortOrder="desc" rowHeight="150" margins="5" resizeOptions="600x300 q90 Lanczos" showExif="true" previewType="blur" embedPreview="true" >}}

This shortcode will generate a gallery containing all images of the folder images. The folder must be next to the .md file where this gallery is used in. This uses page bundles so the directory layout should look like this:

new-post-name/
    index.md
    images/
        DSC_0001.jpg
        DSC_0002.jpg

The parameter sortOrder decides whether the images are sorted ascending ("asc") or descending ("desc").

The rowHeight parameter determines the height of the rows that are displayed while the margin parameter defines the gap between the images.

A thumbnail is generated using the resizeOptions parameter, they are handed over to Hugo's image processing function using the fit method. In the example above, the generated thumbnails have a width of max 300 pixel and a height of max 600, the actual width and height depend on the original aspect ratio. The JPEG image quality is 90% and the scaling uses the high quality Lanczos filter.

If previewType is set to "blur" (or "color"), a very low resolution image (or a single pixel image) will be loaded for every image in the gallery first. The hight resolution thumbnail images (see resizeOptions) will only be loaded if they are on the currently visible part of the page (or close to it). This leads to a faster loading page. You can set previewType to "none" to disable this feature and all thumbnails will be directly loaded.

Enable embedPreview to let hugo embed the tiny preview image directly in the page HTML as a base64 strings. This reduces the amount of required network round trip times.

The setting thumbnailHoverEffect configures what should happen when the mouse hovers above a thumbnail in the gallery. It defaults to "none", but it can be set to "enlarge", in that case the image is scaled up (x1.1) in a short smooth animation.

The setting lastRow configures the justification of the last row of the grid. When set to "justify", the entire grid including the last row will be fully-justified, right and left. This parameter respects all of the lastRow options of Justified Gallery, including "nojustify" and "hide".

When the users clicks on an image, a lightbox shows up displaying the clicked image in large using the whole available space. If the image contains a title or description there will be a top bar displaying that. If the showExif option is set to "true", some parts of the image's EXIF data will be shown on the bottom bar e.g.: "Canon EOS 80D + EF100-400mm f/4.5-5.6L IS II USM 400mm f/8 1/400sec ISO 2500". The EXIF display will only work if you add following lines to your config.toml:

[imaging.exif]
    includeFields = ".*"

An advanced setting is filterOptions: It allows the user to filter the displayed images by using buttons. The text of the buttons and the regex used to filter has to be specified in a JSON array of objects. Currently it is only supported to filter by EXIF tags. In the future it will be possible to filter by image name or other EXIF fields (pull requests are welcome).

In addition to the tags of the EXIF embedded in the image, a meta sidecar file can be used to add tags to an image. 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":["macro","insect"}.

Additionally to the filter buttons, a button to activate full screen mode of the gallery is added

An example of the filterOptions JSON:

filterOptions="[{label: 'All', tags: '.*'}, {label: 'Birds', tags: 'bird'}, {label: 'Macro', tags: 'macro'}, {label: 'Insects', tags: 'insect'}]"

As many websites/themes already include jQuery, this theme component will use the available jQuery lib. If the page does not already use jQuery the parameter loadJQuery=true must be used to instruct the theme component to load the provided jQuery lib.

All settings can be done globally in the site's config.toml, for that the prefix gallery has to be used. E.g. galleryLoadJQuery instead of loadJQuery.

Requirements

This component requires a hugo version >= 0.59.

Dependencies

The component uses (and includes) Justified Gallery to render the images between the text and Swipebox to show them full screen.

Troubleshooting

When bigger galleries are processed it can be required to set hugo's timeout property in the config.toml to a higher value:

timeout = 60000 # This is required for larger galleries to be build (60 sec)

JaccyLi / hugo-shortcode-gallery