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

complete rewrite of this project

Browse Source
This commit is contained in:
max.mehl
2020-03-09 13:20:20 +01:00
parent 51e757b527
commit 81ece5842c
6 changed files with 429 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
README.md
View File

@@ -1,72 +1,57 @@
<!--
SPDX-FileCopyrightText: 2019 Li-Wen Yip <liwen.yip@gmail.com>
SPDX-FileCopyrightText: 2019 Max Mehl <mail@mehl.mx>
SPDX-FileCopyrightText: 2020 Max Mehl <mail@mehl.mx>
SPDX-License-Identifier: MIT
-->
# hugo-snap-gallery
Automagical css image gallery in [Hugo](https://gohugo.io/) using shortcodes.
Automagical css image gallery in [Hugo](https://gohugo.io/) using shortcodes. No JavaScript is used, just plain CSS.
This is a fork of [easy gallery](https://github.com/liwenyip/hugo-easy-gallery). It is supposed to come without any JavaScript and therefore has limited features, but new JS-less stuff is planned.
## Features
## Image Gallery Features
- Custom `{{< figure >}}` shortcode that enables new features but is backwards-compatible with Hugo's built-in `{{< figure >}}`shortcode
- 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
- **Point `{{< gallery >}}` at a directory to generate a gallery of all images in that directory**
- Gallery is responsive, images are scaled/cropped to fill square (or other evenly-sized) tiles
- Pretty captions appear/slide/fade upon hovering over the image
- Only requires 3.8kB of CSS (unminified; you can minify it if you want)
- 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
## PhotoSwipe Features
- Load PhotoSwipe by calling the `{{< load-photoswipe >}}` shortcode anywhere in your post
- Loads all of the `<figure>` elements in your post, regardless of where in your post they appear, into a lightbox/carousel style image gallery
- Works with any existing `<figure>` elements/shortcodes in your posts
- Does not require you to [pre-define the image sizes](http://photoswipe.com/documentation/faq.html#image-size) (the initialisation script pre-loads the image to determine its size; you can optionally pre-define the image size if you want to avoid this pre-loading)
## Installation
Use this like an additional Hugo theme.
Use this like an additional Hugo theme, so add it to the `theme` config. Example:
```
theme = [ "hugo-sustain", "hugo-snap-gallery" ]
```
## `{{< figure >}}` shortcode usage
Specifying your image files:
- `{{< figure src="thumb.jpg" link="image.jpg" >}}` will use `thumb.jpg` for thumbnail and `image.jpg` for lightbox
- `{{< figure src="image.jpg" >}}` or `{{< figure link="image.jpg" >}}` will use `image.jpg` for both thumbnail and lightbox
- `{{< figure link="image.jpg" thumb="-small" >}}` will use `image-small.jpg` for thumbnail and `image.jpg` for lightbox
- `{{< 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" capation="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:
- All the [features/parameters](https://gohugo.io/extras/shortcodes) of Hugo's built-in `figure` shortcode work as normal, i.e. src, link, title, caption, class, attr (attribution), attrlink, alt
- `size` (e.g. `size="1024x768"`) pre-defines the image size for PhotoSwipe. Use this option if you don't want to pre-load the linked image to determine its size.
- 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.
Optional parameters for standalone `{{< figure >}}` shortcodes only (i.e. don't use on `{{< figure >}}` inside `{{< gallery >}}` - strange things may happen if you do):
- `caption-position` and `caption-effect` work the same as for the `{{< gallery >}}` shortcode (see below).
- `width` defines the [`max-width`](https://www.w3schools.com/cssref/pr_dim_max-width.asp) of the image displayed on the page. If using a thumbnail for a standalone figure, set this equal to your thumbnail's native width to make the captions behave properly (or feel free to come up with a better solution and submit a pull request :-)). Also use this option if you don't have a thumbnail and you don't want the hi-res image to take up the entire width of the screen/container.
Optional parameters work for standalone `{{< figure >}}` shortcodes and inside of `{{< gallery >}}`. However, they cannot be applied to `{{< snap-dir >}}`.
## `{{< gallery >}}` shortcode usage
To specify a directory of image files:
### Using defined images
```
{{< gallery dir="/img/your-directory-of-images/" />}}`
```
To specify individual image files, call it like in the following example. All parameters for the figure should work as described above.
- The images are automatically captioned with the file name.
- `[image].jpg` is used for the hi-res image, and `[image]-thumb.jpg` is used for the thumbnails.
- If `[image]-thumb.jpg` doesn't exist, then `[image].jpg` will be used for both hi-res and thumbnail images.
- The default thumbnail suffix is `-thumb`, but you can specify a different one e.g. `thumb="-small"` or `thumb="_150x150"`.
To specify individual image files:
```
{{< gallery >}}
@@ -76,33 +61,34 @@ To specify individual image files:
{{< /gallery >}}
```
Optional parameters:
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.
- `caption-position` - determines the captions' position over the image. Options:
- `bottom` (default)
- `center`
- `none` hides captions on the page (they will only show in PhotoSwipe)
- `caption-effect` - determines if/how captions appear upon hover. Options:
- `slide` (default)
- `fade`
- `none` (captions always visible)
- `hover-transition` - determines if/how images change upon hover. Options:
- not set - smooth transition (default)
- `none` - hard transition
### 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 in a container with `max-width: 768px`.
`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.
Here are some pointers if you want to adapt the CSS:
Other than that, the CSS should be simple enough to allow modifications.
- Change `.gallery {max-width: 768px;}` if you want a gallery wider than 768px.
- Change `min-width` in the `@media` styles to change the screen widths at which the layout changes
- Change `min-width: 9999px` in the last `@media` style to something sensible if you want to use a 4-tile layout
- If you want more than 4 tiles per row, set `width` = 100% / number of tiles per row
- `padding-bottom` = `width` gives square tiles. Change padding-bottom if you want some other aspect ratio, e.g. `width: 33.3%; padding-bottom: 25%` gives a 4:3 aspect ratio.
## 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.
## License
MIT
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](https://reuse.software) for more information.
The main license of this repo is MIT.