Photo Gallery

What it does

A build-and-embed pipeline for event photography. Full-resolution originals go into a folder; a Python script generates thumbnails, web-optimized lightbox images, and a manifest, all served from GitHub Pages. The host page needs two lines of HTML.

The numbers are the point: one gallery went from 926 MB of originals down to 5.6 MB of thumbnails plus 41 MB of images loaded only when someone opens the lightbox. Originals stay in the repo for archival purposes and are never served to a visitor.

What it can do

• Masonry grid with lazy-loaded thumbnails and a full-screen lightbox
• Idempotent build — only processes what has not been built yet
• Multiple galleries on one page from a single script include
• Namespaced CSS that will not collide with the host site
• Configurable thumbnail width, maximum image side, and JPEG quality
• No server, no database, no image CDN bill

Make it your own

Start by forking the repository into your own organization. Everything below assumes you are working in your fork, not this one.

1. Fork the repo and delete the sample galleries from galleries/ and docs/galleries/.
2. Add your own folder of full-resolution photos at galleries/<your-name>/.
3. Run pip install Pillow then python3 build.py. Tune THUMB_WIDTH, WEB_MAX_SIDE, and quality at the top of build.py first if you need different sizes.
4. In Settings → Pages, choose Deploy from a branch, main, folder /docs.
5. Replace docs/CNAME with your domain, add the DNS record, and enable Enforce HTTPS.
6. Embed with <div data-gallery="your-name"></div> and one script tag pointing at your own embed.js.

Stuck on a step? Open an issue on the repository. Questions from people adapting these for their own institution are the most useful feedback we get.