From 2cdec0ccd3ec1fdcafdc4f12fb30c7d58c7632b8 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
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 <URL>' 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/publishing.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 docs/publishing.md

(limited to 'docs/publishing.md')

diff --git a/docs/publishing.md b/docs/publishing.md
new file mode 100644
index 0000000..f31eaaf
--- /dev/null
+++ b/docs/publishing.md
@@ -0,0 +1,45 @@
+# Publishing
+
+To publish generated output, configure destinations and run `shuriken --sync`.
+
+## `SYNC_DESTINATIONS`
+
+`SYNC_DESTINATIONS` must be a Bash array, even for a single destination:
+
+```sh
+SYNC_DESTINATIONS=(
+    admin@fishfinger.buetow.org:/var/www/htdocs/example.org/
+    admin@blowfish.buetow.org:/var/www/htdocs/example.org/
+)
+```
+
+A scalar string is rejected with an error, since word-splitting would break
+destinations that contain spaces (for example
+`SYNC_DESTINATIONS=( '/path/with spaces/' )` is the correct spelling).
+
+`--sync` validates that `SYNC_DESTINATIONS` contains at least one destination and
+that rsync is installed.
+
+## Overriding destinations per run
+
+Pass `--sync-destination DEST` one or more times with `--sync` to override the
+configured destinations for that run only:
+
+```sh
+shuriken --sync --sync-destination user@host:/var/www/htdocs/example.org/
+```
+
+## The rsync command
+
+`--sync` runs, for each destination:
+
+```sh
+rsync -av --delete "$DIST_DIR/" "$destination"
+```
+
+The trailing slash on `DIST_DIR/` means the generated **contents** are copied
+into the target directory. Set `SYNC_DELETE=no` or pass `--no-sync-delete` to
+omit `--delete`.
+
+`--sync` reads `./shuriken.conf` by default; pass `--config PATH` to select a
+different config file.
\ No newline at end of file
-- 
cgit v1.2.3