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

Complete rewrite #1

Merged
mxmehl merged 27 commits from refactoring into master 2024-02-07 22:17:50 +01:00
Conversation 0 Commits 27 Files Changed 11 +37 -62
1 changed files with 37 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit dc64b7bda1 - Show all commits

99
README.md
View File

@@ -5,20 +5,29 @@
# hugo-snap-gallery # 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 ## Features
- Custom `{{< figure >}}` shortcode that enables new features but is mostly backwards-compatible with Hugo's built-in `{{< figure >}}`shortcode - Custom `{{< snap-gallery >}}` shortcode that allows to display multiple images
- All pictures can be expanded on click in a CSS-only lightbox - Two modes:
- Use the `{{< figure >}}` shortcode by itself to enable pretty captions - **slideshow** displaying only one image at a time with the ability to navigate
- Put multiple `{{< figure >}}` shortcodes inside a `{{< gallery >}}` to create a pretty image gallery - **gallery** displaying all selected pictures next to each other
- Use the `{{< snap-dir >}}` shortcode inside a `{{< gallery >}}` to show all containing files nicely - All pictures can be expanded on click in a lightbox
- Next/prev buttons in galleries - Manually select the images you want to display, or provide the path to a directory to use all images inside
- The gallery is responsive, images are scaled/cropped to fill square tiles - Next/prev buttons in slideshow and lightbox views
- Pretty captions outside and inside lightbox - The gallery is responsive, images are scaled/cropped to fill 16:10 tiles
- Only requires 4kB of CSS (unminified; you can minify it if you want) - CSS and JS is automatically loaded the first time you use the `{{< snap-gallery >}}` shortcode on each page
- CSS is automatically loaded the first time you use the `{{< figure >}}` shortcode on each page - Multiple galleries/slideshows per page supported, no interference
- Automatic rotation of slideshow with a configurable interval. Can also be disabled.
### Roadmap / untested
- Captions / title
- Alternative text
- Disable lightbox
- Automatically detect whether source is an image or directory
- Support a micture of dirs and single images
## Installation ## Installation
@@ -29,64 +38,30 @@ Use this like an additional Hugo theme, so add it to the `theme` config. Example
theme = [ "hugo-sustain", "hugo-snap-gallery" ] 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/page1" >}}`: Display all images in the folder `img/page1` in **gallery** mode
- `{{< figure src="image.jpg" >}}` will just show the image with no caption, and open the full version of it when clicked All parameters:
- `{{< 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
Optional parameters: - `src`: Must contain either a comma-separated list of paths to images, or a directory path containing images.
- `isdir`: Whether `src` contains one or multiple individual images, ow a whole directory. Default: `false`.
- 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 >}}`. - `mode`: Can be either `gallery` or `slideshow`. Default: `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. - For gallery mode:
- `lightbox` allows you to control the lightbox. The value `none` will disable the lightbox completely. - `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`.
Optional parameters work for standalone `{{< figure >}}` shortcodes and inside of `{{< gallery >}}`. However, they cannot be applied to `{{< snap-dir >}}`. - 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`.
## `{{< gallery >}}` shortcode usage - `slideshowrotate_timer`: Interval of automatic slideshow rotation (if enabled), in milliseconds. Default: `5000` (5 seconds).
### 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 >}}
```
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.
### 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.
## Credits ## 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 ## License