diff --git a/docs/superpowers/specs/2026-06-20-demo-data-redesign.md b/docs/superpowers/specs/2026-06-20-demo-data-redesign.md new file mode 100644 index 0000000..93640d8 --- /dev/null +++ b/docs/superpowers/specs/2026-06-20-demo-data-redesign.md @@ -0,0 +1,300 @@ +# Demo Data Redesign — italy-2026-demo + +**Date:** 2026-06-20 +**Status:** Approved + +## Goal + +Replace the existing patchwork of demo content across three trips with a single, high-quality demo trip (`italy-2026-demo`) that: +- Follows the real Tuscany cycling route (Campiglia Marittima loop, 8 days) +- Has 12 journal entries with actual photos for realistic gallery/lightbox QA +- Has 4 stories that collectively exercise every story shortcode type +- Is cleanly managed by a single `make demo-load` / `make demo-reset` pair + +--- + +## 1. Cleanup + +### Remove + +| Path | Action | +|---|---| +| `user/docs/demo/trips/japan-korea-2026/` | Delete entirely | +| `user/docs/demo/trips/italy-2025/dailies/` | Delete all entries | +| `user/docs/demo/trips/italy-2025/04.stories/` | Delete all stories | +| `user/docs/demo/trips/italy-2026-demo/dailies/` | Replace with 12 new entries | +| `user/docs/demo/trips/italy-2026-demo/04.stories/` | Replace with 4 new stories | + +Italy 2025 keeps its GPX files and page-structure files (trip.md, map.md, stats.md) — only demo-generated entries and stories are removed. + +### Update CLAUDE.md + +Remove the Japan/Korea reference from the `demo-load` description. New description: +> `make demo-load` — load demo content into `italy-2026-demo` trip (journal entries + stories + GPX) + +--- + +## 2. GPX Files + +Rename the 4 newly added files to match the existing naming convention. Keep existing day-5/6/8 names unchanged. + +| New filename | Original | +|---|---| +| `day-1-campiglia-to-sugherella.gpx` | `2025-10-11_2627663255_TGE Tuscany...Day 1...gpx` | +| `day-2-sugherella-to-orbetello.gpx` | `2025-10-12_2630489431_TGE Tuscany...Day 2.gpx` | +| `day-3-orbetello-to-sorano.gpx` | `2025-10-13_2632495944_TGE Tuscany...Day 3.gpx` | +| `day-4-sorano-to-val-dorcia.gpx` | `2025-10-14_2634086364_TGE Tuscany...Day 4.gpx` | + +All 7 GPX files live at `user/docs/demo/trips/italy-2026-demo/`. + +--- + +## 3. Journal Entries (12) + +Each entry is a directory at `user/docs/demo/trips/italy-2026-demo/dailies/.entry/` containing: +- `entry.md` — frontmatter + one prose paragraph +- `01.jpg` … `N.jpg` — placeholder images (numbered for sort order) + +Images are downloaded from `https://picsum.photos/seed//1200/800` during `make demo-load`. Seeds are fixed so the same images load every time. + +### Entry list + +| # | Slug | Date/Time | Location | Weather | Photos | Seed prefix | +|---|---|---|---|---|---|---| +| 1 | `2026-09-01-0700-setting-off-from-campiglia` | 2026-09-01 07:00 | Campiglia Marittima, Italy | Sunny 27°C | 2 | `demo-d1` | +| 2 | `2026-09-02-1130-maremma-in-full-sun` | 2026-09-02 11:30 | Maremma, Italy | Sunny 29°C | 3 | `demo-d2a` | +| 3 | `2026-09-02-1900-the-lagoon-at-dusk` | 2026-09-02 19:00 | Orbetello, Italy | Partly cloudy 24°C | 3 | `demo-d2b` | +| 4 | `2026-09-03-0800-orbetello-morning` | 2026-09-03 08:00 | Orbetello, Italy | Sunny 22°C | 2 | `demo-d3a` | +| 5 | `2026-09-03-1700-tufa-and-towers` | 2026-09-03 17:00 | Sorano, Italy | Sunny 26°C | 2 | `demo-d3b` | +| 6 | `2026-09-04-1500-the-long-climb-north` | 2026-09-04 15:00 | Val d'Orcia, Italy | Partly cloudy 23°C | 4 | `demo-d4` | +| 7 | `2026-09-05-0830-before-the-heat-arrives` | 2026-09-05 08:30 | Pienza, Italy | Sunny 21°C | 2 | `demo-d5a` | +| 8 | `2026-09-05-1800-into-siena` | 2026-09-05 18:00 | Siena, Italy | Sunny 25°C | 3 | `demo-d5b` | +| 9 | `2026-09-06-2000-florence-by-nightfall` | 2026-09-06 20:00 | Florence, Italy | Cloudy 21°C | 3 | `demo-d6` | +| 10 | `2026-09-07-1400-one-rest-day` | 2026-09-07 14:00 | Florence, Italy | Partly cloudy 22°C | 2 | `demo-d7` | +| 11 | `2026-09-08-0730-dawn-on-the-cecina-coast` | 2026-09-08 07:30 | Cecina, Italy | Sunny 20°C | 1 | `demo-d8a` | +| 12 | `2026-09-08-1630-home` | 2026-09-08 16:30 | Campiglia Marittima, Italy | Sunny 26°C | 2 | `demo-d8b` | + +### Entry coordinates + +| # | lat | lng | Notes | +|---|---|---|---| +| 1 | 43.024 | 10.603 | GPX Day 1 start | +| 2 | 42.612 | 11.171 | GPX Day 2 midpoint | +| 3 | 42.442 | 11.218 | GPX Day 2 end (Orbetello) | +| 4 | 42.442 | 11.217 | GPX Day 3 start | +| 5 | 42.683 | 11.715 | GPX Day 3 end (Sorano) | +| 6 | 43.077 | 11.678 | GPX Day 4 end (Pienza/Val d'Orcia) | +| 7 | 43.078 | 11.676 | GPX Day 5 start | +| 8 | 43.318 | 11.335 | GPX Day 5 end (Siena) | +| 9 | 43.767 | 11.253 | GPX Day 6 end (Florence) | +| 10 | 43.769 | 11.255 | Florence (rest day, slight offset) | +| 11 | 43.553 | 10.313 | GPX Day 8 start (Cecina coast) | +| 12 | 43.017 | 10.587 | GPX Day 8 end (Campiglia) | + +### Entry frontmatter pattern + +```yaml +--- +title: '' +date: '2026-09-NN HH:MM' +template: entry +published: true +hero_image: '' +lat: '<lat>' +lng: '<lng>' +location_city: '<City>' +location_country: 'Italy' +weather_temp_c: <N> +weather_desc: '<Desc>' +--- +``` + +`hero_image` is left empty — the template auto-picks `media.images|first` as hero, which will be `01.jpg`. + +--- + +## 4. Stories (4) + +Each story is a directory at `user/docs/demo/trips/italy-2026-demo/04.stories/<slug>/` containing `story.md` + image files. + +Stories are ordered chronologically and geographically along the route. Each story's **primary shortcode** is different, ensuring all 4 types get QA coverage. + +### Story list + +| # | Slug | Day | Location | Primary shortcode | Also uses | +|---|---|---|---|---|---| +| 1 | `01.sorano-rock-and-time` | 3 | Sorano | `scrolly-section` | `chapter-break`, `snap-gallery` | +| 2 | `02.val-dorcia-at-dawn` | 5 | Pienza / Val d'Orcia | `snap-gallery` | `chapter-break`, `pull-quote` | +| 3 | `03.one-evening-siena` | 5 | Siena | `pull-quote` (with image) | `chapter-break`, `scrolly-section` | +| 4 | `04.florence-without-a-map` | 7 | Florence | `chapter-break` (structural) | `pull-quote`, `scrolly-section` | + +### Story: 01.sorano-rock-and-time + +**Structure:** +1. Intro prose (1 paragraph) +2. `[scrolly-section image="hero.jpg"]` — 3 scroll steps separated by `---`: approach to Sorano, the tufa cliffs close up, entering the gate +3. Prose bridge (1 paragraph) +4. `[chapter-break image="photo-1.jpg" title="After Dark" number="II"]` +5. `[snap-gallery images="photo-1.jpg,photo-2.jpg"]` — alley + view from the walls +6. Closing prose (1 paragraph) + +**Images:** `hero.jpg` (town on tufa cliff), `photo-1.jpg` (narrow medieval alley), `photo-2.jpg` (view south over valley) + +**Frontmatter:** +```yaml +title: Sorano: Rock and Time +date: '2026-09-03' +location_name: Sorano +location_country: Italy +lat: 42.683 +lng: 11.715 +hero_image: hero.jpg +hero_alt: Medieval town of Sorano perched on tufa cliffs +published: true +``` + +--- + +### Story: 02.val-dorcia-at-dawn + +**Structure:** +1. Intro prose (1 paragraph — leaving camp before sunrise) +2. `[snap-gallery images="hero.jpg,photo-1.jpg,photo-2.jpg"]` — 3 landscape shots: valley at first light, cypress road, distant farmhouse +3. Prose bridge (1 paragraph — route through the valley floor) +4. `[chapter-break image="photo-1.jpg" title="The Hour Before Heat"]` +5. `[pull-quote]` (text-only, no image) — a short reflection on cycling rhythms +6. Closing prose (1 paragraph — reaching Pienza by noon) + +**Images:** `hero.jpg` (wide valley, golden hour), `photo-1.jpg` (cypress-lined road), `photo-2.jpg` (farmhouse on hillside) + +**Frontmatter:** +```yaml +title: Val d'Orcia at Dawn +date: '2026-09-05' +location_name: Val d'Orcia +location_country: Italy +lat: 43.078 +lng: 11.676 +hero_image: hero.jpg +hero_alt: Wide Tuscan valley at dawn, long cypress shadows +published: true +``` + +--- + +### Story: 03.one-evening-siena + +**Structure:** +1. `[pull-quote image="hero.jpg" alt="..."]` — image-backed opener quote about arriving by bike +2. Intro prose (1–2 paragraphs — the Campo appearing at the end of a street) +3. `[chapter-break image="photo-1.jpg" title="The Campo" number="I"]` +4. `[scrolly-section image="hero.jpg"]` — 3 scroll steps: the square filling up at dusk, a busker, sitting down after 8 hours riding +5. Closing prose (1 paragraph — finding dinner, the specific relief of sitting still) + +**Images:** `hero.jpg` (Campo at golden hour from upper rim), `photo-1.jpg` (stone doorway / Siena street detail) + +**Frontmatter:** +```yaml +title: One Evening in Siena +date: '2026-09-05' +location_name: Siena +location_country: Italy +lat: 43.318 +lng: 11.330 +hero_image: hero.jpg +hero_alt: Piazza del Campo at dusk, terracotta rooftops fading to blue +published: true +``` + +--- + +### Story: 04.florence-without-a-map + +**Structure:** +1. Intro prose (1 paragraph — rest day, no route, no GPS) +2. `[chapter-break image="hero.jpg" title="Day Seven" number="VII"]` +3. `[snap-gallery images="hero.jpg,photo-1.jpg"]` — Arno view + street scene +4. `[pull-quote]` (text-only) — reflection: cycling makes you earn the places; today we got Florence for free +5. `[scrolly-section image="photo-1.jpg"]` — 3 steps: Uffizi queue they didn't join, a leather market, crossing a bridge at midday light +6. Closing prose (1 paragraph — tired feet, early bed, tomorrow the coast road home) + +**Images:** `hero.jpg` (Arno river with Ponte Vecchio), `photo-1.jpg` (narrow Florence street with washing lines) + +**Frontmatter:** +```yaml +title: Florence Without a Map +date: '2026-09-07' +location_name: Florence +location_country: Italy +lat: 43.769 +lng: 11.255 +hero_image: hero.jpg +hero_alt: Arno river at midday with Ponte Vecchio +published: true +``` + +--- + +## 5. Makefile Changes + +### demo-load (full replacement) + +New behaviour: +1. Create trip folder structure under `user/pages/01.trips/italy-2026-demo/` +2. Copy page-level markdown files (trip.md, map.md, stats.md, stories.md) +3. Copy all 4 stories (with their image files) to `04.stories/` +4. Copy all 12 journal entries to `01.dailies/` +5. Copy 7 GPX files to trip root +6. Download placeholder images via `curl` into each entry and story folder (skip if file exists) +7. `php bin/grav clearcache` + +Image download pattern for entries (per entry `SLUG`, images `01.jpg`…`NN.jpg`): +```bash +[ -f ".../01.dailies/SLUG/01.jpg" ] || curl -sL "https://picsum.photos/seed/demo-dN-1/1200/800" -o ".../01.jpg" +``` + +Seed naming convention: `{seed-prefix}-{image-number}` e.g. entry 1 (`demo-d1`) gets seeds `demo-d1-1` and `demo-d1-2`. Story images use prefix `demo-s{N}` e.g. `demo-s1-hero`, `demo-s1-1`, `demo-s1-2`. + +Image sizes: entries `1200x800`, story images `1600x1000`. + +### demo-reset (updated) + +Remove `user/pages/01.trips/italy-2026-demo/` entirely and clear cache. Behaviour unchanged from current, just scoped correctly. + +--- + +## 6. trip.md Updates + +`user/docs/demo/trips/italy-2026-demo/trip.md`: + +```yaml +--- +title: 'Tuscany 2026' +template: trip +date: '2026-09-01' +date_start: '2026-09-01' +date_end: '2026-09-08' +cover_image: '' +--- +``` + +Title changed from "Italy 2026 (Demo)" to "Tuscany 2026" — cleaner for a realistic demo. + +--- + +## 7. What Is Not Changing + +- `user/pages/01.trips/italy-2025/` — real trip page stays; only the demo entries in `docs/demo/trips/italy-2025/dailies/` and `docs/demo/trips/italy-2025/04.stories/` are removed +- `user/pages/01.trips/japan-korea-2026/` — active trip, untouched +- GPX files already loaded on the italy-2025 page — untouched +- `user/config/site.yaml` `active_trip` — untouched + +--- + +## Implementation Notes + +- Write stories first (they define the image filenames), then entries +- Image seeds are fixed strings so `make demo-load` is idempotent +- The `|| true` pattern on `cp` commands is already established in the Makefile — follow it +- `stories.md` (the listing page) frontmatter is unchanged +- No `hero_image` in entry frontmatter — let the template auto-select `01.jpg`