m038/intotheeast-com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add demo data redesign spec

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vgmzx8VTTTmCskSpQtsLTr
This commit is contained in:
Mischa
2026-06-20 20:44:05 +02:00
parent c973bf0ab3
commit d9f99af1cb
1 changed files with 300 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-06-20-demo-data-redesign.md
+300
View File
@@ -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/<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`