stapix
Yet another static page generator for photo galleries
001 002 003 004 005 006 007 008 009 010 011 012 013 014 015 016 017 018 019 020 021 022 023 024 025 026 027 028 029 030 031 032 033 034 035 036 037 038 039 040 041 042 043 044 045 046 047 048 049 050 051 052 053 054 055 056 057 058 059 060 061 062 063 064 065 066 067 068 069 070 071 072 073 074 075 076 077 078 079 080 081 082 083 084 085 086 087 088 089 090 091 092 093 094 095 096 097 098 099 100 101 102 103 104 105
# 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](https://git.pablopie.xyz/tikz-gallery-generator/index.html) for one such example of fork. ## Usage To use stapix run: ```console $ 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: ```yaml - 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: ```console $ 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/>.