sgg

A static photo gallery generator. Point it at a folder of images and it produces a self-contained HTML gallery you can serve with any web server or open directly in a browser.

Features

• Converts jpg, png, webp, tiff, heic/heif, and avif images
• Recursively handles nested folders as sub-albums
• Justified photo grid with a PhotoSwipe lightbox
• Dark theme, no external dependencies in output
• Caches processed images — reruns only process new files
• Optional zip archives for downloading originals or scaled images

Installation

Requires libvips to be installed on your system.

# macOS
brew install vips

# Debian/Ubuntu
sudo apt install libvips-dev

Then build from source:

git clone https://github.com/simhnna/sgg
cd sgg
cargo build --release
# binary is at ./target/release/sgg

Usage

sgg generate --input <photos_dir> --output <output_dir>

Open output/index.html in a browser, or serve the output directory with any static file server.

Commands

Command	Description
generate	Generate a static photo gallery
extract-templates	Extract bundled templates to a directory for customization

Generate options

Flag	Short	Default	Description
--input	-i	required	Directory of images to process
--output	-o	required	Where to write the gallery
--format	-f	webp	Output image format: webp or jpg
--concurrency	-c	2	Number of parallel processing threads
--lines			Print one line per image instead of updating in place
--zip-originals			Add a download link with original images per album
--zip-scaled			Add a download link with processed images per album
--template			Directory of custom templates/assets to override bundled defaults
--rename-to-numbers			Rename output files to sequential numbers (1.webp, 2.webp, …). Disables caching — all images are reprocessed on every run

Examples

Basic gallery:

sgg generate -i ~/Pictures -o ~/gallery

With download archives and jpg output:

sgg generate -i ~/Pictures -o ~/gallery --format jpg --zip-originals --zip-scaled

Customizing templates

Extract the bundled templates to a directory, edit what you want, then pass the directory with --template:

sgg extract-templates ./my-templates
# edit my-templates/album.html.hbs, my-templates/main.css, etc.
sgg generate -i ~/Pictures -o ~/gallery --template ./my-templates

Only files present in the template directory override their bundled counterparts — you don't need to include files you haven't changed. Overridable files: album.html.hbs, album.css, main.css, album.js, ps.css, ps.esm.min.js, ps-light.esm.min.js, placeholder.png.

Input Structure

Subdirectories become sub-albums. Images at the root level appear on the main page.

photos/
  beach.jpg
  mountains.png
  Trip to Rome/
    colosseum.heic
    fountain.jpg
  Family/
    birthday.webp

Output Structure

gallery/
  index.html
  static/            — CSS, JS, and other shared assets
  thumbnails/
  beach.webp
  mountains.webp
  Trip to Rome/
    index.html
    thumbnails/
    colosseum.webp
    fountain.webp
  Family/
    index.html
    thumbnails/
    birthday.webp

Images are scaled to a maximum of 1280px on the long edge (2560px for panoramas with aspect ratio > 2:1). Thumbnails are 200px (panorama thumbnails scale to 400px height instead).