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
|
# Generation
This page describes how `shuriken --generate` works and the features that
affect its output.
## Artifact reuse and incremental generation
Normal generation preserves reusable generated artifacts from the previous
`DIST_DIR` while still rerendering HTML, random splash/background choices,
animation classes, timestamps, and shuffled preview order. Existing scaled
photos, thumbnails, and blurs are reused from the previous output when the
source image is unchanged.
## The EXIF cache
The per-photo EXIF `identify` output is cached in a separate `cache/exif/`
directory created next to `DIST_DIR` (i.e. parallel to `dist/` in the working
directory — the path is `$(dirname "$DIST_DIR")/cache/exif`). Each cache entry
records a `<photo>:<size>:<mtime>` signature so it is reused only while the
source file is unchanged.
This cache is volatile and safe to delete, is **not** part of the published
output (it is never written into `DIST_DIR`, so `--sync` does not deploy it),
and persists across runs even if `DIST_DIR` is removed or rebuilt. Because
reading EXIF from full-size originals is the slowest part of generation, keeping
this cache makes regenerating an album dramatically faster: an unchanged photo
skips `identify` entirely.
* `--clean` removes `DIST_DIR` (and any leftover staging directories) but leaves
`cache/` in place; delete `cache/` by hand to force a full EXIF rebuild on the
next run.
* `--force` (with `--generate`) clears `cache/` once up front, then repopulates
it during the run, so there is still exactly one `identify` per photo even
under force.
## Splash page
By default the generated root `index.html` is a no-JavaScript splash page using
a randomly selected album photo. Set `SPLASH_PAGE=no` or pass `--no-splash` to
restore the top-level redirect to `page-1.html`.
To quickly pick a new random splash photo for an already generated album, run
`shuriken --refresh-splash`. This rewrites `DIST_DIR/index.html` (and re-copies
the site favicon) using the existing `photos` and `blurs` output, so it avoids
reprocessing images and rerendering album pages. It requires `SPLASH_PAGE=yes`;
pass `--random-seed VALUE` when you need a repeatable pick.
## Details pages
Every photo gets a `*-details.html` page by default: a dedicated view with the
full EXIF summary table, reachable via the "Details" link on that photo's
normal view page. Set `DETAILS_PAGE=no` or pass `--no-details` to skip
generating these pages; the "Details" link (on the normal view pages and, when
`STATS_PAGE=yes`, on the filter mini-album view pages) is removed along with
it, so no generated page links to a missing file.
`DETAILS_PAGE=no` only affects the details pages and their links. It does not
disable the per-photo EXIF tooltip (the `title=""` attribute shown on hover
over a photo) or `STATS_PAGE`: both stay independently controlled and keep
working exactly as configured.
## Stats site
`shuriken` can also generate a no-JavaScript stats site with EXIF-derived
insights (camera leaderboard, shooting dates, exposure, dimension, format, and
decoded-enum breakdowns), reachable from the `Stats` link in the page header
bar. This is off by default; set `STATS_PAGE=yes` or pass `--stats` to enable it.
Every row on the stats overview is clickable: each bucket (each camera, ISO,
year, aperture, orientation, …) is its own filter "mini-album" — a gallery of
just the matching photos with view pages whose previous/next cycle within that
filter.
To keep the album root uncluttered, all of this lives under a `stats/`
subdirectory: the overview is `stats/index.html` and each mini-album is its own
directory `stats/<filter>/` (gallery `index.html` plus numbered view pages). Only
the main album sits in `DIST_DIR` itself. The mini-album pages reuse the album's
shared `photos/`, `thumbs/`, and `blurs/` assets (only the HTML is per-filter)
and are rendered in parallel honouring `IMAGE_JOBS`. Set `STATS_PAGE=no` or pass
`--no-stats` (the default) to skip the whole `stats/` tree and hide the link.
See [stats-exif-audit.md](stats-exif-audit.md) for the EXIF field coverage
analysis behind these categories.
## Reproducibility
By default, splash and background photos, animation classes, generated
timestamps, and `--shuffle` preview order remain non-deterministic. Set
`RANDOM_SEED` in the config, or pass `--random-seed VALUE`, to make those
choices repeatable for stable tests or reproducible album builds. Use the same
seed and inputs to produce the same HTML.
`CHRONOLOGICAL_ORDER=yes` (see "Photo ordering" in
[configuration.md](configuration.md)) is always deterministic regardless of
`RANDOM_SEED`: it orders by each photo's EXIF date taken (with a source-mtime
fallback), so it needs no seed to repeat, and it takes precedence over
`SHUFFLE` when both are enabled.
## Parallelism and timeouts
ImageMagick photo processing and per-photo HTML template rendering run in
parallel. The default is `IMAGE_JOBS=3`. Set `IMAGE_JOBS` in the config, or pass
`--image-jobs N`, to tune the number of concurrent image and template jobs.
Each ImageMagick command is bounded by `IMAGEMAGICK_TIMEOUT=60` seconds, and
tarball creation is bounded by `TAR_TIMEOUT=120` seconds. Set either config
value to a positive integer to adjust the limit for large images or archives.
## Generation metadata (`shuriken.json`)
Successful generation writes `shuriken.json` into the output directory. This
metadata records:
* the generator name and version, and a generation timestamp;
* the config source and template name/directory;
* the source `INCOMING_DIR` and source image count;
* generated photo, thumbnail, and HTML file counts;
* tarball status (included + file);
* effective settings (title, height, thumbheight, maxpreviews, subdivide
percent, feature percent, image jobs, random seed, chronological order,
shuffle, splash page, details page, stats page, original basepath) useful for
debugging a published album.
## Favicon
Generation writes `favicon.ico` into the output directory and the default
templates link to it. By default this is the bundled shuriken favicon; set
`FAVICON` in the config or pass `--favicon PATH` to publish your own favicon
file instead (it is copied in as `favicon.ico`).
## Source URL
The page header bar links to the project source ("Site generated … with
`<URL>`"). This defaults to the shuriken.sh repository; set `SOURCE_URL` in
the config or pass `--source-url URL` to point it at your own album's repository
instead. The displayed link text is the URL with its scheme removed.
|
