stapix

Yet another static page generator for photo galleries

README.md (4077B)

  1 # stapix
  2 
  3 Yet another static page generator for photo galleries
  4 
  5 ## Philosophy
  6 
  7 stapix aims to provide a minimalist user interface and implement the following
  8 simple feature set:
  9 
 10 * Accessible and optimized HTML output implementing current best practices
 11 * Simple static webpages with no need for JavaScript
 12 * Automatically generate WebP thumbnails in parallel
 13 * Incremental builds
 14 
 15 For a live example please see <https://photos.pablopie.xyz>!
 16 
 17 ### Customizing the HTML Output
 18 
 19 The user is expected to modify the source code to customize the HTML output,
 20 _no templating system is provided_. The idea is that instead of relying in a
 21 complex and inflexible HTML templating systems, users should fork the
 22 application to adapt it for their own needs. Check out
 23 [tikz-gallery-generator](https://git.pablopie.xyz/tikz-gallery-generator/index.html)
 24 for one such example of fork.
 25 
 26 ## Usage
 27 
 28 To use stapix run:
 29 
 30 ```console
 31 $ stapix config.yml [--full-build]
 32 ```
 33 
 34 The configuration file `config.yml` should consist of a list of struct entries
 35 describing the contents of each picture, such as in the following example:
 36 
 37 ```yaml
 38 - path: examples/photos/iss-trails.jpg
 39   alt: "A long exposure shot of star trails, framed by the ISS on the top and
 40   by the surface of Earth on the bottom. Thunderstorms dot the landscape while
 41   the orange glare of cities drifts across Earth and a faint a green-yellow
 42   light hugs the horizon."
 43   license: PD
 44   author: Don Pettit
 45 
 46 - path: examples/photos/solar-eclipse.jpg
 47   alt: "A total solar eclipse. The moon blocks out the sun and creates a
 48   stunning ring of colorful red light against the black background."
 49   license: CC-BY-SA-3
 50   author: Luc Viatour
 51 ```
 52 
 53 Each entry in the list should contain the following fields:
 54 
 55 * **`path`:** The path to the file in question
 56 * **`alt`:** Text altenative for the picture
 57 * **`caption` (optional):** A description of the picture
 58 * **`author`:** The name of the author of the picture
 59 * **`author-url` (optional):** A URL to a webpage by/on the picture's author
 60 * **`license`:** The license type of the picture. Should be one of `PD` (public
 61   domain), `CC0`, `CC-BY-1`, `CC-BY-2`, `CC-BY-2.1`, `CC-BY-2.5`, `CC-BY-3`,
 62   `CC-BY-4`, `CC-BY-SA-1`, `CC-BY-SA-2`, `CC-BY-SA-2.1`, `CC-BY-SA-2.5`,
 63   `CC-BY-SA-3`, `CC-BY-SA-4`, `CC-BY-NC-1`, `CC-BY-NC-2`, `CC-BY-NC-2.1`,
 64   `CC-BY-NC-2.5`, `CC-BY-NC-3`, `CC-BY-NC-4`, `CC-BY-NC-SA-1`, `CC-BY-NC-SA-2`,
 65   `CC-BY-NC-SA-2.1`, `CC-BY-NC-SA-2.5`, `CC-BY-NC-SA-3`, `CC-BY-NC-SA-4`,
 66   `CC-BY-ND-1`, `CC-BY-ND-2`, `CC-BY-ND-2.1`, `CC-BY-ND-2.5`, `CC-BY-ND-3`,
 67   `CC-BY-ND-4`, `CC-BY-NC-ND-1`, `CC-BY-NC-ND-2`, `CC-BY-NC-ND-2.1`,
 68   `CC-BY-NC-ND-2.5`, `CC-BY-NC-ND-3` or `CC-BY-NC-ND-4`
 69 
 70 For best accessibility, the `alt` field should contain a concise visual
 71 description of the picture in question (including subjects, colors and scenery)
 72 to be displayed by screen readers, while the `caption` field should contain
 73 _additional_ information on the picture (such as the location or date when it
 74 was taken) to be displayed for all users. **The `alt` and `caption` attributes
 75 should not be the same!** See
 76 <https://www.htmhell.dev/adventcalendar/2022/22/> for further details.
 77 
 78 ### Options
 79 
 80 * **`--full-build`:** Disables incremental builds. Re-renders all pages and
 81   thumbnails.
 82 
 83 ## Installation
 84 
 85 stapix can be installed via Cargo by cloning this directory, as in:
 86 
 87 ```console
 88 $ git clone git://git.pablopie.xyz/stapix
 89 $ cargo install --path ./stapix
 90 ```
 91 
 92 ## License
 93 
 94 This program is free software: you can redistribute it and/or modify it under
 95 the terms of the GNU General Public License as published by the Free Software
 96 Foundation, either version 3 of the License, or (at your option) any later
 97 version.
 98 
 99 This program is distributed in the hope that it will be useful, but WITHOUT ANY
100 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
101 PARTICULAR PURPOSE. See the GNU General Public License for more details.
102 
103 You should have received a copy of the GNU General Public License along with
104 this program. If not, see <https://www.gnu.org/licenses/>.
105