From b1efa699f06f51f3735f2f98847b7a3040931b12 Mon Sep 17 00:00:00 2001
From: Mischa <mischa@gorinskat.nl>
Date: Sun, 21 Jun 2026 13:01:50 +0200
Subject: [PATCH] docs: add trip switching guide

---
 docs/guides/trip-switching.md | 89 +++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 docs/guides/trip-switching.md

diff --git a/docs/guides/trip-switching.md b/docs/guides/trip-switching.md
new file mode 100644
index 0000000..a4f957d
--- /dev/null
+++ b/docs/guides/trip-switching.md
@@ -0,0 +1,89 @@
+# Switching to a New Trip
+
+When you start a new trip, **two files must be updated together** — if only one is changed, new entries will be posted to the wrong folder silently (no error, wrong trip).
+
+---
+
+## Checklist
+
+- [ ] Update `user/config/site.yaml` → `active_trip`
+- [ ] Update `user/pages/02.post/post-form.md` → `pageconfig.parent`
+- [ ] Create the new trip page tree (see below)
+- [ ] Run `make content-push` to push the changes to production
+
+---
+
+## Step 1 — Update site.yaml
+
+In `user/config/site.yaml`, set `active_trip` to the new trip slug:
+
+```yaml
+active_trip: japan-korea-2026   # ← change this
+```
+
+The slug must exactly match the folder name under `user/pages/01.trips/`.
+
+---
+
+## Step 2 — Update post-form.md
+
+In `user/pages/02.post/post-form.md`, set `pageconfig.parent` to the new dailies path:
+
+```yaml
+pageconfig:
+  parent: /trips/japan-korea-2026/dailies   # ← change this
+```
+
+**Why both?** Grav's config and page frontmatter are static YAML — no variable substitution is possible, so `post-form.md` can't read from `site.yaml` automatically. They must match manually.
+
+**What breaks if they're out of sync:** `active_trip` controls which trip page is featured on the home page and trip page. `pageconfig.parent` controls where new entries land. If they differ, new posts go to the old trip's dailies folder while the home page shows the new trip — entries appear to vanish.
+
+---
+
+## Step 3 — Create the new trip page tree
+
+Create the standard four subfolders under `user/pages/01.trips/<new-slug>/`:
+
+```
+user/pages/01.trips/japan-korea-2026/
+├─ trip.md                  ← title, date_start, date_end, cover_image, album_url
+├─ 01.dailies/
+│  └─ dailies.md            ← template: dailies (list page)
+├─ 02.map/
+│  └─ map.md                ← template: map
+├─ 03.stats/
+│  └─ stats.md              ← template: stats
+└─ 04.stories/
+   └─ stories.md            ← template: stories
+```
+
+Copy these files from an existing trip and update the frontmatter (especially `title` and `date_start` in `trip.md`).
+
+Fields in `trip.md` to update:
+
+| Field | Example | Notes |
+|---|---|---|
+| `title` | `Japan & Korea 2026` | Displayed in nav and trip header |
+| `date_start` | `2026-07-15` | Used for "X days on the road" stat |
+| `date_end` | *(leave blank while travelling)* | Set when you return |
+| `cover_image` | `cover.jpg` | Shown on the trips listing page |
+| `album_url` | `https://...` | Optional external album link |
+
+---
+
+## Step 4 — Push
+
+```bash
+make content-push
+```
+
+This commits and pushes the `user/` repo to Gitea. The webhook triggers a production pull automatically.
+
+---
+
+## Verify
+
+After pushing, check:
+1. Home page shows the new trip (title and date)
+2. Submit a test entry via `/post` — verify it lands under `user/pages/01.trips/<new-slug>/01.dailies/`
+3. Map at `/trips/<new-slug>/map` shows the correct (empty or GPX-only) state