# 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.