intotheeast-com/docs/guides/gpx-manager.md

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:

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.

---

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:

{% 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.