From 2cdec0ccd3ec1fdcafdc4f12fb30c7d58c7632b8 Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Fri, 19 Jun 2026 21:03:03 +0300 Subject: docs: split README into quick-start + reference pages under docs/ Trim README.md to a quick-start guide (install, init, generate, sync, clean) with a main-flags table and feature-toggle summary, and move the detailed reference material into focused pages under docs/: installation, usage, configuration, generation, publishing, templates. Correctness fixes carried over during the split: - The 'Site generated ... with ' source link lives in the page header bar (header.tmpl), not the footer (footer.tmpl only renders the tarball download). Fixed in docs and the SOURCE_URL code comment. - --sync is a config-backed action and accepts --config PATH / reads ./shuriken.conf; the --config action list now includes it. - --refresh-splash also re-copies the site favicon; documented. - State the Bash 5.1 requirement (enforced by the script) in the docs. - docs/stats-exif-audit.md: the EXIF cache moved to metadata-cache.source.sh and the native-field parser extension was implemented; add a status note and fix the stale module path. bin/shuriken regenerated from the config.source.sh comment change. --- docs/configuration.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/configuration.md (limited to 'docs/configuration.md') diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..07bc1e0 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,84 @@ +# 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. | +| `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. | +| `SHUFFLE` | `no` | Randomly shuffle all previews. `yes`/`no`. | +| `SPLASH_PAGE` | `yes` | Generate a splash landing page at `index.html`. `yes`/`no`. | +| `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`. + +## Supported source images + +Only regular files in `INCOMING_DIR` (top level, `maxdepth 1`) 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. +* **`yes`/`no` settings**: `SHUFFLE`, `SPLASH_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`). +* **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`, `IMAGE_JOBS`, +`IMAGEMAGICK_TIMEOUT`, `RANDOM_SEED`, `SHUFFLE`, `SPLASH_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. \ No newline at end of file -- cgit v1.2.3