Max Mehl d0fe8315cb | ||
---|---|---|
LICENSES | ||
assets/scss | ||
layouts | ||
static/js | ||
README.md | ||
theme.yaml |
README.md
hugo-snap-gallery
Automagical css image gallery in Hugo using shortcodes. Lightweight, slim and fully local JavaScript.
Features
- Custom
{{< snap-gallery >}}
shortcode that allows to display multiple images - Two modes:
- slideshow displaying only one image at a time with the ability to navigate
- gallery displaying all selected pictures next to each other
- All pictures can be expanded on click in a lightbox
- Manually select the images you want to display, or provide the path to a directory to use all images inside. This can be combined!
- Next/prev buttons in slideshow and lightbox views
- The gallery is responsive, images are scaled/cropped to fill 16:10 tiles
- CSS and JS is automatically loaded the first time you use the
{{< snap-gallery >}}
shortcode on each page - Multiple galleries/slideshows per page supported, no interference
- Automatic rotation of slideshow with a configurable interval. Can also be disabled.
- Supports providing metadata such as
alt
andtitle
attributes as well as captions
Installation
Use this like an additional Hugo theme, so add it to the theme
config. Example:
theme = [ "hugo-sustain", "hugo-snap-gallery" ]
{{< snap-gallery >}}
shortcode usage
Quickstart:
{{< snap-gallery src="image1.jpg, image2.png" >}}
: Display these two images in gallery mode{{< snap-gallery src="image1.jpg, image2.png" mode="slideshow" >}}
: Display these two images in slideshow mode{{< snap-gallery src="img/folder1/, image2.png" >}}
: Display all images in the directoryimg/folder1
and the single imageimage2.png
in gallery mode
All parameters:
src
: Must contain either a comma-separated list of paths to images, or a directory path containing images. Note that the paths are absolute, so imagine a/
in front of them. Also note that the shortcode assumes that they are all stored in/static/
.lightbox
: Whether a click on an image shall open a lightbox modal. Default:true
.aspectratio
: Define the aspect ratio of the images in the slideshow/gallery. Default:16/10
.metadata
: See below for how to add metadata to your files. Default:map[]
.mode
: Can be eithergallery
orslideshow
. Default:gallery
.- For gallery mode:
columns
: Amount of columns the images are displayed in. Default:4
.minwidth
: Minimum width that each image shall have, e.g.150px
or30%
. May conflict with the desired amount of columns. Default:200px
.
- For slideshow mode:
slideshowwidth
: Width of slideshow, e.g.300px
or80%
. Default:100%
.slideshowrotate
: Whether the slideshow shall automatically rotate through the images. Default:true
.slideshowrotate_timer
: Interval of automatic slideshow rotation (if enabled), in milliseconds. Default:5000
(5 seconds).
Note: Boolean values (true
/false
) must be provided without surrounding "
characters! lightbox=false
disables the lightbox, while lightbox="false"
does not.
Metadata
Using separate data files, you can provide metadata to the image files. Imagine using the following shortcode: {{< snap-gallery src="image1.jpg, img/folder1/" metadata="images.en" >}}
.
This would assume you have a file named /data/images.en.yaml
. It may contain the following data:
- src: image1.jpg
html:
alt: Alternative text
title: Title, text displayed when hovering
- src: img/folder1/foo.png
html:
alt: Alternative text for the first picture in the image folder
This way, you can add any HTML attributes to the <img>
element for the images you describe in the metadata file. In this example, you add this for two images, one of them is in a folder whose path you provided. You don't have to add information for all files.
This flexible way allows you to also translate metadata. Just use different metadata
values to the shortcodes depending on the language.
Note that a title
is also taken as a caption to the picture in order to reduce duplicated work.
Credits
The original inspiration for this shortcode came from Li-Wen Yip's easy-gallery. The first major version of this was already a 90% rewrite, and the current one has even less to do with it. However, the rewrite took some inspirations from W3Schools, thanks!
License
This repository follows the REUSE best practices for clear copyright and licensing information. The license texts for all used licenses can be found in the LICENSES/ directory under the root of this repository. Visit reuse.software for more information.
The main license of this repo is MIT.