1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
# Configuration
The config file is a Bash file sourced by shuriken. `shuriken --init` creates
`./shuriken.conf` from the default config; edit it and override any of the
variables below. Command-line options (see [usage.md](usage.md)) override config
values for the current run.
## Variables
| Variable | Default | Description |
| --- | --- | --- |
| `TITLE` | `A simple Shuriken` | Album title. |
| `HEIGHT` | `1200` | Scaled photo height in pixels. Leave unset to keep original size. Optional positive integer. |
| `THUMBHEIGHT` | `300` | Thumbnail height in pixels. Positive integer. |
| `MAXPREVIEWS` | `40` | Maximum previews per page. Positive integer. |
| `THUMB_SUBDIVIDE_PERCENT` | `30` | Percent chance (0-100) that a preview tile is subdivided into smaller thumbnails (2x2 quad, two stacked wide strips, or two squares plus one wide strip on top/bottom). Each sub-thumbnail is its own clickable photo. `0` disables it. |
| `THUMB_FEATURE_PERCENT` | `10` | Percent chance (0-100) that a preview tile is a large "feature" tile: a single photo spanning a 2x2 block of the overview grid. Rolled before the subdivision chance. `0` disables it. |
| `IMAGE_JOBS` | `3` | Parallel jobs for image processing and HTML template rendering. Positive integer. |
| `IMAGEMAGICK_TIMEOUT` | `60` | Per-ImageMagick-command timeout in seconds. Positive integer. |
| `TAR_TIMEOUT` | `120` | Tarball creation timeout in seconds. Positive integer. |
| `CHRONOLOGICAL_ORDER` | `no` | Order the main album's photos chronologically by EXIF date taken (ascending; years before 2001 are treated as an implausible camera clock-reset default, not a real date), falling back to filename order when a photo has no usable EXIF date. `yes`/`no`. Takes precedence over `SHUFFLE` when both are set. See "Photo ordering" below. |
| `SHUFFLE` | `no` | Randomly shuffle all previews. `yes`/`no`. Ignored when `CHRONOLOGICAL_ORDER=yes`. |
| `SPLASH_PAGE` | `yes` | Generate a splash landing page at `index.html`. `yes`/`no`. |
| `DETAILS_PAGE` | `yes` | Generate each photo's `*-details.html` page (and its "Details" link). `yes`/`no`. See "Details pages" below. |
| `STATS_PAGE` | `no` | Generate the EXIF stats site under `stats/`. `yes`/`no`. |
| `RANDOM_SEED` | _(unset)_ | Any non-empty value makes splash/background picks, animation classes, timestamps, and shuffle order repeatable. |
| `INCOMING_DIR` | `$(pwd)/incoming` | Directory containing source photos (full path). |
| `DIST_DIR` | `$(pwd)/dist` | Output directory (full path). |
| `TEMPLATE_DIR` | `/usr/share/shuriken/templates/default` | Template directory. Falls back to the source tree's `share/templates/default` when running from a checkout. |
| `FAVICON` | _(unset = bundled default)_ | Custom favicon, published as `favicon.ico`. Must be a readable file when set. |
| `SOURCE_URL` | `https://codeberg.org/snonux/shuriken.sh` | Project/source link shown in the page header bar. |
| `TARBALL_INCLUDE` | `yes` (in `--init` config) | Include a `.tar` of the incoming dir in the dist. `yes`/`no`. |
| `TARBALL_SUFFIX` | `.tar` | Suffix for the generated tarball. |
| `TAR_OPTS` | `(-c)` | Tar options as a Bash array (or whitespace-separated scalar). |
| `SYNC_DELETE` | `yes` | Pass `--delete` to rsync on `--sync`. `yes`/`no`. |
| `SYNC_DESTINATIONS` | `()` | Bash array of rsync destinations. See [publishing.md](publishing.md). |
| `ORIGINAL_BASEPATH` | _(unset)_ | Recorded in `shuriken.json` for debugging a published album. |
> Note on `TARBALL_INCLUDE`: the bundled `shuriken.default.conf` sets it to
> `yes`, so a freshly `--init`'d config enables the tarball. The runtime default
> applied when a config file leaves it unset is `no`.
## Details pages
`DETAILS_PAGE` (default `yes`) controls whether each photo gets its own
`*-details.html` page -- a dedicated view showing the full EXIF summary table,
reachable via the "Details" link on that photo's normal view page and, when
`STATS_PAGE=yes`, from the matching filter mini-album's view pages too.
Setting `DETAILS_PAGE=no` (or passing `--no-details`) skips generating these
pages entirely and removes every "Details" link that would point at one, so no
generated page ever links to a missing file. Everything else keeps working
unchanged:
* The normal thumbnail overview pages and per-photo view pages are still
generated.
* The per-photo EXIF tooltip (the `title=""` attribute shown on hover) is
unaffected -- it is controlled independently of the details page.
* `STATS_PAGE` is unaffected: the EXIF stats site and its filter mini-albums
still generate normally with `DETAILS_PAGE=no`; only their "Details" links
(which would otherwise point at the main album's per-photo details page) are
omitted.
A later `--generate` run that switches `DETAILS_PAGE` from `yes` back to `no`
does not leave stale `*-details.html` files behind: generation stages the new
output in a fresh directory and atomically replaces `DIST_DIR`, so files an
older generation wrote but the current run does not produce are naturally gone.
## Photo ordering
By default the main album's photos are listed in plain filename order, or in a
random/seeded shuffle when `SHUFFLE=yes` (see [generation.md](generation.md)
for reproducibility). Set `CHRONOLOGICAL_ORDER=yes` (or pass `--chronological`)
to instead order them chronologically by EXIF date taken (ascending), reusing
the same `DateTimeOriginal` -> `DateTimeDigitized` -> `DateTime` tag fallback
chain, and the same per-photo EXIF cache, as the "Taken:" tooltip field and the
details page. An EXIF date is only trusted from year 2001 onward: many camera
bodies default their clock to a `2000-01-01`-ish date once the battery dies
and stamp every timestamp with that bogus value instead of omitting it, so an
older year is treated the same as a missing tag rather than sorting a whole
clock-reset camera roll to the front of the album. A photo with no usable EXIF
date falls back to plain filename order (not modification time -- copying or
rsyncing an incoming directory commonly rewrites every file's mtime to the
transfer time, unrelated to capture order), so ordering is always fully
deterministic and never crashes on EXIF-less photos (screenshots, downloaded
images, ...); photos with a real, plausible EXIF date always sort before
filename-fallback photos, so an approximate fallback never displaces a
genuine timestamp.
**`CHRONOLOGICAL_ORDER` takes precedence over `SHUFFLE`** when both are set to
`yes`: a chronological album is meant to read as a timeline, so an enabled
shuffle is silently ignored rather than re-scrambling it. This is a config-level
choice, not a validation error, so toggling `SHUFFLE` while experimenting does
not require also touching `CHRONOLOGICAL_ORDER`.
## Supported source images
Only regular files found directly in `INCOMING_DIR` (not in subdirectories) with
supported image extensions are processed as album images. Supported extensions
are `jpg`, `jpeg`, `png`, `webp`, and `gif`, matched case-insensitively. Other
files, such as `.txt` or `.md` notes, are ignored with a warning so generation
can continue.
## Validation
`shuriken` validates the loaded config and command-line overrides before acting.
The checks (details in `src/lib/config.validate.source.sh`):
* **Required values** are set: `TITLE`, `THUMBHEIGHT`, `MAXPREVIEWS`,
`IMAGE_JOBS`, `INCOMING_DIR`, `DIST_DIR`, `TEMPLATE_DIR`.
* **Positive integers**: `THUMBHEIGHT`, `MAXPREVIEWS`, `IMAGE_JOBS`,
`IMAGEMAGICK_TIMEOUT`, `TAR_TIMEOUT`; `HEIGHT` is an optional positive integer.
* **Percentage (0-100 integer)**: `THUMB_SUBDIVIDE_PERCENT`,
`THUMB_FEATURE_PERCENT`.
* **`yes`/`no` settings**: `CHRONOLOGICAL_ORDER`, `SHUFFLE`, `SPLASH_PAGE`,
`DETAILS_PAGE`, `STATS_PAGE`, `TARBALL_INCLUDE`, `SYNC_DELETE` (where
applicable).
* **Readable input**: `INCOMING_DIR` must be a readable directory; `TEMPLATE_DIR`
must be a readable directory containing the required templates (plus `splash`
when `SPLASH_PAGE=yes`, and `details` when `DETAILS_PAGE=yes`).
* **Writable output**: `DIST_DIR` (or its nearest existing parent) must be
writable.
* **ImageMagick** availability (`magick` or `convert`).
* **`FAVICON`**, when set, must be a readable file.
* **`--clean`** additionally refuses to delete dangerous paths (filesystem root,
`HOME`, the current directory, well-known system trees) after resolving
`DIST_DIR` canonically.
* **`--sync`** requires at least one destination and rsync.
Generation stops before writing album output when validation fails.
## `--print-config` output format
`--print-config` writes stable shell-style assignments to stdout in this order:
`CONFIG_SOURCE`, `INCOMING_DIR`, `DIST_DIR`, `TEMPLATE_DIR`, `FAVICON`,
`SOURCE_URL`, `TITLE`, `HEIGHT`, `THUMBHEIGHT`, `MAXPREVIEWS`,
`THUMB_SUBDIVIDE_PERCENT`, `THUMB_FEATURE_PERCENT`, `IMAGE_JOBS`,
`IMAGEMAGICK_TIMEOUT`, `RANDOM_SEED`, `CHRONOLOGICAL_ORDER`, `SHUFFLE`,
`SPLASH_PAGE`, `DETAILS_PAGE`, `STATS_PAGE`, `TARBALL_INCLUDE`,
`TARBALL_SUFFIX`, `TAR_TIMEOUT`, `TAR_OPTS`, `SYNC_DELETE`,
`SYNC_DESTINATIONS`, `ORIGINAL_BASEPATH`.
Scalar values use Bash `%q` quoting; `TAR_OPTS` and `SYNC_DESTINATIONS` are
normalized to Bash array assignments, so the output can be parsed by shell
tooling. `--quiet` does not suppress this output, and `--verbose` does not add
human-readable diagnostics to it.
|
