initial commit

2019-10-20 22:27:27 +02:00
commit 51e757b527
6 changed files with 388 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,108 @@
+<!--
+  SPDX-FileCopyrightText: 2019 Li-Wen Yip <liwen.yip@gmail.com>
+  SPDX-FileCopyrightText: 2019 Max Mehl <mail@mehl.mx>
+  SPDX-License-Identifier: MIT
+-->
+
+# hugo-snap-gallery
+
+Automagical css image gallery in [Hugo](https://gohugo.io/) using shortcodes.
+
+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.
+
+## Image Gallery Features
+
+- Custom `{{< figure >}}` shortcode that enables new features but is backwards-compatible with Hugo's built-in `{{< figure >}}`shortcode
+- 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)
+- 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.
+
+
+## `{{< 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
+
+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.
+- `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. 
+
+
+## `{{< gallery >}}` shortcode usage
+
+To specify a directory of image files:
+
+```
+{{< gallery dir="/img/your-directory-of-images/" />}}`
+```
+
+- 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 >}}
+  {{< figure src="image1.jpg" >}}
+  {{< figure src="image2.jpg" >}}
+  {{< figure src="image3.jpg" >}}
+{{< /gallery >}}
+```
+
+Optional parameters:
+
+- `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
+
+
+## CSS Hackers
+
+`snap-gallery.css` is designed to provide square tiles in a container with `max-width: 768px`.
+
+Here are some pointers if you want to adapt the CSS:
+
+ - 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.
+
+## License
+
+MIT