Make the favicon configurable via FAVICON config / --favicon flag

The generated pages link a favicon.ico that was always the bundled shuriken
favicon (copy_site_favicon hard-copied share/shuriken/assets/favicon.ico). Add a
FAVICON config variable and a --favicon PATH CLI flag: when set, that file is
published as favicon.ico instead of the bundled default; when empty, the bundled
favicon is used as before.

Plumbed through apply_config_defaults, CLI_OPTION_SPEC + override allowlist,
usage, print_config, the action config list and effective-setting log, and
validated (a non-empty FAVICON must be a readable file) before generation.
shuriken.default.conf and the README document it; a test covers a custom favicon,
its appearance in --print-config, and rejection of a missing file.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

8 files changed, 34 insertions, 2 deletions

diff --git a/src/lib/action.source.sh b/src/lib/action.source.sh
index e2649d7..12be053 100644
--- a/src/lib/action.source.sh
+++ b/src/lib/action.source.sh
@@ -42,6 +42,7 @@ run_action_body_context() {
         INCOMING_DIR
         DIST_DIR
         TEMPLATE_DIR
+        FAVICON
         TITLE
         HEIGHT
         THUMBHEIGHT
@@ -155,6 +156,7 @@ log_configured_action() {
     log_verbose "Effective incoming directory: ${INCOMING_DIR:-}"
     log_verbose "Effective output directory: ${DIST_DIR:-}"
     log_verbose "Effective template directory: ${TEMPLATE_DIR:-}"
+    log_verbose "Effective favicon: ${FAVICON:-(bundled default)}"
     log_verbose "Effective image jobs: $IMAGE_JOBS"
     log_verbose "Effective ImageMagick timeout: ${IMAGEMAGICK_TIMEOUT}s"
     log_verbose "Effective tar timeout: ${TAR_TIMEOUT}s"
diff --git a/src/lib/album.source.sh b/src/lib/album.source.sh
index 532c218..08509fb 100644
--- a/src/lib/album.source.sh
+++ b/src/lib/album.source.sh
@@ -1047,8 +1047,14 @@ copy_site_favicon() {
     local asset_dir
     local favicon_src
 
-    asset_dir=$(resolve_default_asset_dir)
-    favicon_src="$asset_dir/favicon.ico"
+    # Use the configured favicon when set, otherwise the bundled default. Either
+    # way it is published as favicon.ico (the name the templates link to).
+    if [ -n "${FAVICON:-}" ]; then
+        favicon_src="$FAVICON"
+    else
+        asset_dir=$(resolve_default_asset_dir)
+        favicon_src="$asset_dir/favicon.ico"
+    fi
 
     if [ ! -r "$favicon_src" ]; then
         config_error "favicon file $favicon_src must be readable"
diff --git a/src/lib/bootstrap.source.sh b/src/lib/bootstrap.source.sh
index a047f5d..2b19e58 100644
--- a/src/lib/bootstrap.source.sh
+++ b/src/lib/bootstrap.source.sh
@@ -15,6 +15,7 @@ usage() {
     --incoming PATH
     --dist PATH
     --template PATH
+    --favicon PATH
     --title TEXT
     --height VALUE
     --thumbheight VALUE
diff --git a/src/lib/config.print.source.sh b/src/lib/config.print.source.sh
index 7b91b60..c5fe2b4 100644
--- a/src/lib/config.print.source.sh
+++ b/src/lib/config.print.source.sh
@@ -27,6 +27,7 @@ print_config() {
     print_shell_assignment INCOMING_DIR "$INCOMING_DIR"
     print_shell_assignment DIST_DIR "$DIST_DIR"
     print_shell_assignment TEMPLATE_DIR "$TEMPLATE_DIR"
+    print_shell_assignment FAVICON "$FAVICON"
     print_shell_assignment TITLE "$TITLE"
     print_shell_assignment HEIGHT "$HEIGHT"
     print_shell_assignment THUMBHEIGHT "$THUMBHEIGHT"
diff --git a/src/lib/config.source.sh b/src/lib/config.source.sh
index 50c331a..c13e807 100644
--- a/src/lib/config.source.sh
+++ b/src/lib/config.source.sh
@@ -30,6 +30,9 @@ missing_config() {
 }
 
 apply_config_defaults() {
+    # Empty FAVICON means use the bundled default favicon; otherwise it is a path
+    # to a custom favicon file copied into the album as favicon.ico.
+    FAVICON="${FAVICON:-}"
     HEIGHT="${HEIGHT:-}"
     IMAGE_JOBS="${IMAGE_JOBS:-3}"
     IMAGEMAGICK_TIMEOUT="${IMAGEMAGICK_TIMEOUT:-60}"
diff --git a/src/lib/config.validate.source.sh b/src/lib/config.validate.source.sh
index bd2fccf..fda20f0 100644
--- a/src/lib/config.validate.source.sh
+++ b/src/lib/config.validate.source.sh
@@ -195,6 +195,19 @@ validate_common_config() {
     validate_yes_no_config_var SPLASH_PAGE || return
     validate_yes_no_config_var STATS_PAGE || return
     validate_yes_no_config_var TARBALL_INCLUDE || return
+    validate_favicon_config || return
+}
+
+# A custom FAVICON (when set) must be a readable file; empty means the bundled
+# default favicon is used.
+validate_favicon_config() {
+    if [ -z "${FAVICON:-}" ]; then
+        return
+    fi
+    if [ ! -f "$FAVICON" ] || [ ! -r "$FAVICON" ]; then
+        config_error "FAVICON file $FAVICON must be a readable file"
+        return 1
+    fi
 }
 
 validate_generation_config() {
diff --git a/src/shuriken.default.conf b/src/shuriken.default.conf
index c0fe41a..9d0b1a8 100644
--- a/src/shuriken.default.conf
+++ b/src/shuriken.default.conf
@@ -28,6 +28,10 @@ DIST_DIR=$(pwd)/dist
 TEMPLATE_DIR=/usr/share/shuriken/templates/default
 #TEMPLATE_DIR=/usr/share/shuriken/templates/minimal
 
+# Custom favicon, published as favicon.ico. Leave unset/empty to use the bundled
+# shuriken favicon. Can also be set with --favicon PATH.
+#FAVICON=$(pwd)/my-favicon.ico
+
 # Includes a .tar of the incoming dir in the dist, can be yes or no
 TARBALL_INCLUDE=yes
 TARBALL_SUFFIX=.tar
diff --git a/src/shuriken.sh b/src/shuriken.sh
index b6a6cc5..36f3b57 100755
--- a/src/shuriken.sh
+++ b/src/shuriken.sh
@@ -32,6 +32,7 @@ declare -ra CLI_CONFIG_OVERRIDE_TARGETS=(
     INCOMING_DIR
     DIST_DIR
     TEMPLATE_DIR
+    FAVICON
     TITLE
     HEIGHT
     THUMBHEIGHT
@@ -46,6 +47,7 @@ declare -ra CLI_CONFIG_OVERRIDE_TARGETS=(
 )
 declare -Ar CLI_OPTION_SPEC=(
     [--config]='kind=value target=SHURIKEN_CLI_CONFIG_FILE argument=path'
+    [--favicon]='kind=value config=FAVICON argument=path'
     [--incoming]='kind=value config=INCOMING_DIR'
     [--dist]='kind=value config=DIST_DIR'
     [--template]='kind=value config=TEMPLATE_DIR'