mxmehl/hugo-snap-gallery
1
0
Fork 0
Code Issues 2 Pull Requests Releases 2 Wiki Activity

Complete rewrite (#1)

Browse Source 
A complete rewrite of the gallery plugin:

* Using flexbox
* Using lightweight JS for lightbox to avoid anchor links, and allow full rotation
* Add slideshow as an additional field
* Make many more things configurable
* Better support for dirs, allow mixed paths
* Translatable captions for many files using metadata files
* SCSS instead of CSS

Reviewed-on: #1
Co-authored-by: Max Mehl <mail@mehl.mx>
Co-committed-by: Max Mehl <mail@mehl.mx>
This commit was merged in pull request #1.
This commit is contained in:
Max Mehl
2024-02-07 22:17:49 +01:00
committed by mxmehl
parent 0e16b03230
commit 437b0202ba
11 changed files with 588 additions and 211 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
README.md
View File

@@ -5,20 +5,22 @@
# hugo-snap-gallery
Automagical css image gallery in [Hugo](https://gohugo.io/) using shortcodes. No JavaScript is used, just plain CSS.
Automagical css image gallery in [Hugo](https://gohugo.io/) using shortcodes. Lightweight, slim and fully local JavaScript.
## Features
- Custom `{{< figure >}}` shortcode that enables new features but is mostly backwards-compatible with Hugo's built-in `{{< figure >}}`shortcode
- All pictures can be expanded on click in a CSS-only lightbox
- Use the `{{< figure >}}` shortcode by itself to enable pretty captions
- Put multiple `{{< figure >}}` shortcodes inside a `{{< gallery >}}` to create a pretty image gallery
- Use the `{{< snap-dir >}}` shortcode inside a `{{< gallery >}}` to show all containing files nicely
- Next/prev buttons in galleries
- The gallery is responsive, images are scaled/cropped to fill square tiles
- Pretty captions outside and inside lightbox
- Only requires 4kB 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
- 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` and `title` attributes as well as captions
## Installation
@@ -29,64 +31,56 @@ 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
## `{{< figure >}}` shortcode usage
Quickstart:
Specifying your image files:
- `{{< 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 directory `img/folder1` and the single image `image2.png` in **gallery** mode
- `{{< figure src="image.jpg" >}}` will just show the image with no caption, and open the full version of it when clicked
- `{{< figure src="image.jpg" caption="My description" >}}` will show the image and open the full version of it when clicked, and shows the caption text in both views. Markdown is possible
- `{{< figure src="image.jpg" link="http://example.com" >}}` will use `image.jpg` for thumbnail and link to `http://example.com` when clicked
All parameters:
Optional 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 either `gallery` or `slideshow`. 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` or `30%`. May conflict with the desired amount of columns. Default: `200px`.
- For slideshow mode:
- `slideshowwidth`: Width of slideshow, e.g. `300px` or `80%`. 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).
- All the [features/parameters](https://gohugo.io/content-management/shortcodes/#figure) of Hugo's built-in `figure` shortcode work as normal, i.e. src, link, rel, title, caption, class, attr (attribution), attrlink, alt. width and height might lead to strange results when used inside `{{< gallery >}}`.
- `class` allows you to set any custom classes you want on the `<figure>` tag. The values `no-border`, `sm`, `md`, `lg`, `pull-left` and `pull-right` are made available by this project.
- `lightbox` allows you to control the lightbox. The value `none` will disable the lightbox completely.
**Note: Boolean values (`true`/`false`) must be provided without surrounding `"` characters!** `lightbox=false` disables the lightbox, while `lightbox="false"` does not.
Optional parameters work for standalone `{{< figure >}}` shortcodes and inside of `{{< gallery >}}`. However, they cannot be applied to `{{< snap-dir >}}`.
### 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" >}}`.
## `{{< gallery >}}` shortcode usage
This would assume you have a file named `/data/images.en.yaml`. It may contain the following data:
### Using defined images
To specify individual image files, call it like in the following example. All parameters for the figure should work as described above.
```
{{< gallery >}}
{{< figure src="image1.jpg" >}}
{{< figure src="image2.jpg" >}}
{{< figure src="image3.jpg" >}}
{{< /gallery >}}
```yaml
- 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
```
Inside of the lightbox (so when clicked on one image), you will see forward and backward arrows on the right and left side. The backward arrow will not work when you are on the first image of a gallery. The forward arrow however will still show when on the last image but just close the frame.
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.
### Using a whole directory
To specify a directory full of image files, use the example below. This will use all files (make sure it's only images!) and display them in a gallery. You cannot define captions or other parameters for the individual images:
```
{{< gallery >}}
{{< snap-dir srcdir="/img/blog/orr" >}}
{{< /gallery >}}
```
The navigation inside the lightbox will work as with the individually defined gallery image, and even recognise when the gallery is at its last image.
## CSS Hackers
`snap-gallery.css` is designed to provide square tiles. The gallery contains three tiles per row on larger screens, and will limit to 2 or 1 tile per row if the screen is smaller. To change that, you should look at the three definition of `.snap-gallery figure`. Please feel free to contact me if you found a more flexible way to change that.
Other than that, the CSS should be simple enough to allow modifications.
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 comes from [Li-Wen Yip's easy-gallery](https://github.com/liwenyip/hugo-easy-gallery). However, snap-gallery is a 98% rewrite.
The original inspiration for this shortcode came from [Li-Wen Yip's easy-gallery](https://github.com/liwenyip/hugo-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](https://www.w3schools.com/howto/howto_js_lightbox.asp), thanks!
## License