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

update documentation

Browse Source
This commit is contained in:
Max Mehl
2024-02-05 12:15:56 +01:00
parent 9e85618e77
commit dc64b7bda1
1 changed files with 37 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

99
README.md
View File

@@ -5,20 +5,29 @@
# 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
- 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.
### 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
@@ -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" ]
```
## `{{< 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
- `{{< 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:
- 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.
Optional parameters work for standalone `{{< figure >}}` shortcodes and inside of `{{< gallery >}}`. However, they cannot be applied to `{{< snap-dir >}}`.
## `{{< gallery >}}` shortcode usage
### 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.
- `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`.
- `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).
## 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