docs: add GPX manager guide

2026-06-21 12:57:59 +02:00
parent 65597de00d
commit 562de15429
1 changed files with 85 additions and 0 deletions
@@ -0,0 +1,85 @@
+# Managing GPX Files
+
+GPX route files live as media on the active trip page. The map picks them up automatically — any `.gpx` file in `user/pages/01.trips/<active_trip>/` appears on the trip map.
+
+---
+
+## Browser UI — /gpx-manager
+
+The GPX manager at `/gpx-manager` requires admin login (redirects to login form if not authenticated).
+
+### Upload a file
+
+1. Open `/gpx-manager` (login required)
+2. Click **Choose file** → select your `.gpx` file
+3. Click **Upload**
+4. The filename is auto-slugified before upload: spaces and special characters become hyphens, everything becomes lowercase.
+   - Example: `Day 1 — Arrival (Kyoto).gpx` → `day-1-arrival-kyoto.gpx`
+5. The file appears in the list immediately
+
+### Delete a file
+
+1. Find the file in the list at `/gpx-manager`
+2. Click **Delete** next to it
+3. Confirm — the file is removed from the trip media and will no longer appear on the map
+
+---
+
+## Without the browser UI
+
+Drop the file directly into the trip folder and push:
+
+```bash
+cp your-route.gpx /path/to/user/pages/01.trips/japan-korea-2026/
+make content-push
+```
+
+`make content-push` commits and pushes the `user/` repo to Gitea, which triggers a production pull via webhook.
+
+**Filename tip:** slug your filename before dropping it — lowercase, hyphens only:
+```
+day-1-kyoto.gpx         ✅
+Day 1 Kyoto.gpx         ⚠️  works but slugified on upload; skip this if dropping manually
+```
+
+---
+
+## Filename slugification rules
+
+The browser UI slugifies client-side before upload. Manually placed files are used as-is, so name them cleanly.
+
+Rules applied by the UI:
+- Lowercase everything
+- Replace spaces with hyphens
+- Replace non-alphanumeric characters (except `.`) with hyphens
+- Collapse multiple consecutive hyphens to one
+- Strip leading/trailing hyphens
+
+---
+
+## Komoot workflow (no API integration yet)
+
+Komoot doesn't offer GPX export via API without authentication. Current workaround:
+
+1. Open your tour in the Komoot app or website
+2. **More → Export → GPX track** (available on Komoot Premium; free users get a limited version)
+3. Save the `.gpx` file to your phone or laptop
+4. Upload via `/gpx-manager` or drop into the trip folder
+
+Future: a Komoot integration field in the GPX manager (paste tour URL → server fetches GPX) is in the backlog at [`working/backlog.md`](../working/backlog.md).
+
+---
+
+## How files are served
+
+GPX files are registered as a valid media type in `user/config/media.yaml`, so Grav stores and serves them alongside images. The map template picks them up via:
+
+```twig
+{% for file in trip_page.media.all %}
+  {% if file.filename ends with '.gpx' %}
+    {# add to map source list #}
+  {% endif %}
+{% endfor %}
+```
+
+No manual linking is needed — upload and it appears.