stapix

Yet another static page generator for photo galleries

stapix

Yet another static page generator for photo galleries

Philosophy

stapix aims to provide a minimalist user interface and implement the following simple feature set:

Accessible and optimized HTML output implementing current best practices
Simple static webpages with no need for JavaScript
Automatically generate WebP thumbnails in parallel
Incremental builds

For a live example please see https://photos.pablopie.xyz!

Customizing the HTML Output

The user is expected to modify the source code to customize the HTML output, no templating system is provided. The idea is that instead of relying in a complex and inflexible HTML templating systems, users should fork the application to adapt it for their own needs. Check out tikz-gallery-generator for one such example of fork.

Usage

To use stapix run:

$ stapix config.yml [--full-build]

The configuration file config.yml should consist of a list of struct entries describing the contents of each picture, such as in the following example:

- path: examples/photos/iss-trails.jpg
  alt: "A long exposure shot of star trails, framed by the ISS on the top and
  by the surface of Earth on the bottom. Thunderstorms dot the landscape while
  the orange glare of cities drifts across Earth and a faint a green-yellow
  light hugs the horizon."
  license: PD
  author: Don Pettit

- path: examples/photos/solar-eclipse.jpg
  alt: "A total solar eclipse. The moon blocks out the sun and creates a
  stunning ring of colorful red light against the black background."
  license: CC-BY-SA-3
  author: Luc Viatour

Each entry in the list should contain the following fields:

path: The path to the file in question
alt: Text altenative for the picture
caption (optional): A description of the picture
author: The name of the author of the picture
author-url (optional): A URL to a webpage by/on the picture's author
license: The license type of the picture. Should be one of PD (public domain), CC0, CC-BY-1, CC-BY-2, CC-BY-2.1, CC-BY-2.5, CC-BY-3, CC-BY-4, CC-BY-SA-1, CC-BY-SA-2, CC-BY-SA-2.1, CC-BY-SA-2.5, CC-BY-SA-3, CC-BY-SA-4, CC-BY-NC-1, CC-BY-NC-2, CC-BY-NC-2.1, CC-BY-NC-2.5, CC-BY-NC-3, CC-BY-NC-4, CC-BY-NC-SA-1, CC-BY-NC-SA-2, CC-BY-NC-SA-2.1, CC-BY-NC-SA-2.5, CC-BY-NC-SA-3, CC-BY-NC-SA-4, CC-BY-ND-1, CC-BY-ND-2, CC-BY-ND-2.1, CC-BY-ND-2.5, CC-BY-ND-3, CC-BY-ND-4, CC-BY-NC-ND-1, CC-BY-NC-ND-2, CC-BY-NC-ND-2.1, CC-BY-NC-ND-2.5, CC-BY-NC-ND-3 or CC-BY-NC-ND-4

For best accessibility, the alt field should contain a concise visual description of the picture in question (including subjects, colors and scenery) to be displayed by screen readers, while the caption field should contain additional information on the picture (such as the location or date when it was taken) to be displayed for all users. The alt and caption attributes should not be the same! See https://www.htmhell.dev/adventcalendar/2022/22/ for further details.

Options

--full-build: Disables incremental builds. Re-renders all pages and thumbnails.

Installation

stapix can be installed via Cargo by cloning this directory, as in:

$ git clone git://git.pablopie.xyz/stapix
$ cargo install --path ./stapix

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.