From f4dc8fed78e14ffed8db3d6d14da8a99b20e07b0 Mon Sep 17 00:00:00 2001
From: andy5995 <arch_stanton5995@proton.me>
Date: Fri, 22 May 2026 23:42:23 -0500
Subject: [PATCH] Document testing the site generation script in the README

Adds context to the Testing section explaining that the catalog pages
are auto-generated by ivan-hc/AM:tools/am2pla-site and overwritten
every 30 minutes by the sync workflow, with the list of which files
in this repo are durable vs regenerated.

Adds Option 3 with a worktree-based recipe for testing changes to
am2pla-site itself: detached worktree, patched script (sed neutralises
the cd-to-Desktop), run inside the worktree, preview via the Option 1
Docker command. Includes the gotcha about root-owned files left by
the Docker container and how to clean them up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 49 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 24d8b4a5..4b9625cd 100644
--- a/README.md
+++ b/README.md
@@ -18,10 +18,19 @@
 
 ### Testing
 
-To test changes to the website before pushing or while working on a pull
-request, pick one of the two options below. Docker is recommended because
-the container matches the GitHub Pages build environment and works on any
-host Ruby version.
+Most pages on this site are auto-generated by `tools/am2pla-site` in
+the [`ivan-hc/AM`](https://github.com/ivan-hc/AM) repository — a
+GitHub Actions workflow runs that script every 30 minutes and pushes
+the output back to `main`. Hand-edits to generated files (`index.md`,
+`apps.md`, `appimages.md`, the 24 category pages, `apps.json`, the
+`am2pla-site` copy in this repo) are overwritten on the next sync.
+Durable changes live in `_layouts/`, `assets/css/`, `assets/js/`,
+`_config.yml`, `Gemfile`, this README, and `.github/workflows/`.
+
+To test changes to the website before pushing or while working on a
+pull request, pick one of the three options below. Docker is
+recommended because the container matches the GitHub Pages build
+environment and works on any host Ruby version.
 
 </div>
 
@@ -60,6 +69,42 @@ version manager such as [`rbenv`](https://github.com/rbenv/rbenv) or
 `:development` group so `jekyll serve` works on Ruby 3.0+ (GitHub Pages
 production does not use `webrick`).
 
+#### Option 3: Testing changes to the site generation script
+
+If you are changing `tools/am2pla-site` in the `ivan-hc/AM` repository
+(the script that produces the catalog pages on every sync), run it
+against a detached worktree of this site so the output doesn't pollute
+your main checkout. The `sed` mirrors what the sync workflow does — it
+neutralises the script's `cd "$(xdg-user-dir DESKTOP)"` so output lands
+in the worktree instead of your Desktop directory.
+
+```sh
+# Adjust to wherever you have ivan-hc/AM cloned
+AM_REPO=~/src/AM
+
+# Detached worktree of this repo's main branch
+git worktree add -d ../pla-site-test main
+
+# Run the patched script inside the worktree
+sed 's|^cd "$(xdg-user-dir|#&|' "$AM_REPO/tools/am2pla-site" > /tmp/am2pla-site-test
+cd ../pla-site-test && bash /tmp/am2pla-site-test
+
+# Preview with the Docker command from Option 1 (or use Option 2)
+docker run --rm -it -p 4000:4000 \
+  -v "$PWD:/srv/jekyll" -w /srv/jekyll \
+  -v jekyll-bundle:/usr/local/bundle \
+  ruby:3.3 \
+  bash -c "bundle install && bundle exec jekyll serve --host 0.0.0.0"
+
+# Clean up when done
+cd - && git worktree remove --force ../pla-site-test
+```
+
+When the Docker container runs as root it leaves a root-owned
+`_site/` and `Gemfile.lock` inside the worktree; `git worktree remove
+--force` will fail to delete those, so finish with
+`sudo rm -rf ../pla-site-test` if the remove complains.
+
 #### Viewing the site
 
 You will see messages that confirm that site has generated and the server is