# 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/<slug>.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/<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: '<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`