Architecture Overview

How the intotheeast site hangs together.

Stack

Layer	Technology	Notes
CMS	Grav 2.0.0-rc.10	Flat-file PHP CMS; no database
Admin	Admin2 v2.0.0-rc.15	Plugin slug: `admin2` (not `admin`)
Container	Docker (`getgrav/grav` base + custom `Dockerfile`)	Grav 2.0 baked in at build time
PHP session	`session.save_path = /tmp`	Set in `php/php-local.ini`
Dev URL	http://localhost:8081	Mapped from container port 80
Maps	MapLibre GL JS	Replaced Leaflet; all 3 map templates use it
GPX rendering	maplibre-gl-leaflet-gpx (CDN)	Renders GPX files as route layers

Plugin roles

The posting pipeline is a chain of three plugins:

Browser POST /post
│
├─ Grav Form plugin (built-in)
│  └─ validates required fields; handles file uploads
│
├─ add-page-by-form (third-party, patched)
│  └─ reads post-form.md config:
│     ├─ pageconfig.parent → target folder (e.g. /trips/japan-korea-2026/dailies)
│     ├─ pageconfig.slug_field → slug from date + title
│     └─ pagefrontmatter → template: entry, published: true
│  └─ writes entry.md to user/pages/01.trips/<trip>/01.dailies/<slug>.entry/
│  └─ moves uploaded photos into the page folder
│
└─ cache-on-save (custom, user/plugins/cache-on-save/)
   └─ calls $grav['cache']->deleteAll() on every new-entry form submission
   └─ ensures entries appear in feed immediately in both dev and prod mode

Other notable plugins:

Plugin	Role
`login`	Auth for /post and /gpx-manager
`api` (Grav API v1)	Used by /gpx-manager to list/upload/delete GPX files
`admin2`	Admin panel at /admin

Template hierarchy

All page templates extend base.html.twig:

templates/
├─ base.html.twig          ← site shell: nav, fonts, CSS tokens
├─ default.html.twig       ← extends base; generic page
├─ home.html.twig          ← extends base; context-aware two-column layout
├─ trip.html.twig          ← extends base; trip page with filter bar (All/Journal/Stories)
├─ entry.html.twig         ← extends base; single journal entry (gallery, badges, map)
├─ dailies.html.twig       ← extends base; journal feed list
├─ map.html.twig           ← extends base; full-height MapLibre trip map
├─ stats.html.twig         ← extends base; trip stats (days, distance, elevation)
├─ stories.html.twig       ← extends base; stories grid
├─ story.html.twig         ← extends base; single story (Ken Burns hero, shortcodes)
└─ gpx-manager.html.twig   ← extends base; admin UI for GPX file management

Partials live in templates/partials/. Key partials: entry-card.html.twig (feed card), map-init.html.twig (shared MapLibre bootstrap).

Trip entity structure

The site is organized around Trip entities. The active trip is set in user/config/site.yaml → active_trip.

user/pages/01.trips/
└─ japan-korea-2026/
   ├─ trip.md              ← template: trip; title, date_start, cover_image, album_url
   ├─ *.gpx               ← GPX route files (served as page media; auto-detected by map.html.twig)
   ├─ 01.dailies/         ← journal entries (template: dailies list + entry children)
   ├─ 02.map/map.md       ← template: map
   ├─ 03.stats/stats.md   ← template: stats
   └─ 04.stories/         ← story pages (template: stories list + story children)

GPX data flow

GPX file uploaded to trip page media
         │
         ▼
user/pages/01.trips/<slug>/*.gpx
         │
         ▼
map.html.twig: trip_page.media.all → filter .gpx files → pass as JS array
         │
         ▼
MapLibre source: each GPX file added as a GeoJSON source via maplibre-gl-leaflet-gpx
         │
         ▼
Connector suppression: same-file 10km proximity check prevents spurious inter-track segments
         │  (override with force_connect: true in trip frontmatter)
         ▼
Rendered as route polyline on map

Data flow for a post submission

1. User fills /post form and taps Submit
2. Grav Form plugin validates: title and content required
3. add-page-by-form reads post-form.md:
     pageconfig.parent:  /trips/japan-korea-2026/dailies
     pageconfig.slug:    {date}-{title|slugify}
     pagefrontmatter:    template: entry, published: true
4. New page written to:
     user/pages/01.trips/japan-korea-2026/01.dailies/
     └─ 2026-07-20-0930-first-day-in-kyoto.entry/
        └─ entry.md
5. Photos moved into the same folder
6. cache-on-save calls $grav['cache']->deleteAll()
7. Browser: form shows success message
8. Feed at /trips/japan-korea-2026 immediately shows new entry

Key config files

File	Purpose
`user/config/site.yaml`	`active_trip` slug; site title/description
`user/config/system.yaml`	Twig cache, flex accounts/pages, language prefix
`user/config/media.yaml`	Registers `.gpx` as a valid media type
`user/plugins/api/api.yaml`	`session_enabled: true` for GPX manager auth
`user/themes/intotheeast/css/tokens.css`	Design tokens (colors, fonts, spacing)
`CLAUDE.md`	Project rules and always-loaded context for Claude

5.2 KiB Raw Blame History