#web #photos #gallery #cli

bin+lib simple-gallery

Generates a single-page static web application, with no JS, serving a simple photogallery

1 unstable release

0.0.1 Jul 6, 2022

#5 in #gallery


145 lines


A portable webserver for creating extremely simple photo galleries, with no Javascript. It can serve directly, or just generate the raw HTML so you can serve up a static site elsewhere.


Sharing photos is hard. I don't want to create accounts on third-party websites riddled with ads. I'd like to self-host a few photos from an event, but wrangling open source Javascript frameworks is hard. Fortunately, static HTML and CSS is enough to get simple fade-in, fade-out transitions. A simple script to generate static assets is enough for a decent-looking, barebones photo gallery website. You can see an example at https://jawn.best/.

How it works

All you need is a directory of images, preferably in PNG format. Then simple-gallery will:

  1. Scan the directory --directory=img for PNG files (specify e.g. --file-extension jpg to override)
  2. If --generate was given, print the HTML and exit.
  3. Otherwise, spin up a webserver on (specify --bind-address, --port to override)


First, make sure you have Rust installed. Then:

cargo install --force simple-gallery


  1. Some images to serve.
  2. That's it.


simple-gallery 0.1.0
Generates a single-page static web application, with no JS, serving a simple photogallery

    simple-gallery [OPTIONS]

    -b, --bind-address <BIND_ADDRESS>
            Local IP address to bind to [default:]

    -d, --directory <DIRECTORY>
            On-disk path for directory of images to serve [default: img]

    -g, --generate
            Build static HTML and print to stdout, then exit

    -h, --help
            Print help information

    -p, --port <PORT>
            TCP port to listen on [default: 3000]

    -s, --shuffle
            Randomize order of images

    -t, --title <TITLE>
            Title for HTML page, e.g. "example.com" [default: simple-gallery]

    -V, --version
            Print version information

Creating a static site

With a directory structure like:

├── tree.png
├── dog.png
├── horse.png


simple-gallery --generate -d img > index.html

You can now serve that directory, e.g.

python3 -m http.server --port 3000 --directory .

More advanced features (FAQ)

Many features are intentionally left out. There's no navigation functionality: the images will transition indefinitely. If you want to retrieve a specific image, peek at the source, and GET the <img src=""> URL.


The logic for computing the CSS animation duration values were taken from this invaluable blog post. As ever, MDN CSS docs were helpful. Finally, while it's not used, the crate arse may be helpful.




~428K SLoC