diff --git a/CLAUDE.md b/CLAUDE.md index 72fb226..7824842 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,6 +10,8 @@ - **scripts/**: Server install and maintenance scripts - **user/**: Site content, config, pages, and theme (standalone git repo — do not modify from here) - **docs/**: All plans, specs, and project documentation (moved here from `user/docs/` on 2026-06-19) +- **docs/solutions/**: documented solutions to past problems (bugs, patterns, workflow gotchas), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Relevant when implementing or debugging in a documented area +- **CONCEPTS.md** (repo root): shared domain vocabulary (Trip, Entry, Story, Active Trip). Relevant when orienting to the codebase or discussing domain concepts ### Current stack diff --git a/CONCEPTS.md b/CONCEPTS.md new file mode 100644 index 0000000..59a422b --- /dev/null +++ b/CONCEPTS.md @@ -0,0 +1,28 @@ +# Concepts + +Shared domain vocabulary for this project — entities, named processes, and status concepts with project-specific meaning. Seeded with core domain vocabulary, then accretes as ce-compound and ce-compound-refresh process learnings; direct edits are fine. Glossary only, not a spec or catch-all. + +## Relationships + +A **Trip** owns its **Entries** and **Stories**. Exactly one Trip is the **Active Trip** at a time; it is the one surfaced on the home page and the target for new posts. Entries and Stories are always scoped to a Trip — they do not exist independently. + +## Trip + +### Trip +A single journey the blog is organised around — the top-level content entity. A Trip aggregates its Entries and Stories and carries its own metadata (title, start/end dates, cover image, route GPX files). Each Trip renders as one consolidated **Trip page** showing an inline map, a filtered feed, and inline stats; the journal, map, stats, and story views are not separate pages. + +### Active Trip +The one Trip currently featured — set in site config and read by the home page and the post form. Switching the Active Trip is a deliberate, multi-file change; if the post form's target and the featured Trip fall out of sync, new posts land under the wrong Trip. + +### Entry +A single dated journal post within a Trip — the atomic unit of the day-to-day travel log. +*Avoid:* daily, journal post + +The Trip's journal section is labelled "Journal" and lives in the Trip's `dailies` container, so an Entry is colloquially "a daily"; in templates and page metadata the same thing is called an `entry`. Entries carry a date, optional location and coordinates, weather, and photos, and are ordered by date within a Trip. + +### Story +A long-form, designed narrative piece within a Trip — hero image plus scrollytelling/gallery sections — distinct from the short, dated Entry. Stories are curated set pieces; Entries are the running log. + +## Flagged ambiguities + +- "daily" / "entry" / "journal post" all refer to the same concept (a dated journal post). Canonical term: **Entry**. The section/folder is named "dailies" and the nav label is "Journal" — these name the *collection*, not a different entity. diff --git a/docs/solutions/architecture-patterns/retiring-a-consolidated-grav-sub-page.md b/docs/solutions/architecture-patterns/retiring-a-consolidated-grav-sub-page.md new file mode 100644 index 0000000..913f2aa --- /dev/null +++ b/docs/solutions/architecture-patterns/retiring-a-consolidated-grav-sub-page.md @@ -0,0 +1,104 @@ +--- +title: Retiring a standalone Grav sub-page that was consolidated onto another page +date: 2026-07-04 +category: architecture-patterns +module: Grav theme — trip pages / templates +problem_type: architecture_pattern +component: rails_view +severity: medium +applies_when: + - Deleting a standalone Grav view whose content now renders inside another page + - A page folder holds child pages that other templates fetch via grav.pages.find(route).children + - Detail pages have a Back link that falls back to the deleted page + - The affected trip is demo content regenerated by make demo-load +tags: [grav, twig, page-tree, routable, back-link, demo-content, page-retirement] +--- + +# Retiring a standalone Grav sub-page that was consolidated onto another page + +## Context + +The site consolidated four standalone trip views — `/map`, `/stats`, `/dailies`, `/stories` — onto a single trip page (inline map + filter bar + inline stats). Removing the now-redundant view pages looks like a simple `git rm`, but a Grav "page" is a **folder + a `.md` that names a template**, and several things quietly depend on both halves. Missing any of them ships a broken site or a broken `make demo-load`. This captures the safe procedure and the three traps that are not obvious from the file listing. + +## Guidance + +Treat a page as two separable roles: a **routable view** (the `.md`'s template renders a URL) and a **data container** (the folder holds child pages other code reads). Retiring the view must preserve the container. + +**1. Keep the folder; neutralise the view — do not delete the container.** +`01.dailies/` and `04.stories/` hold the journal/story children, and `trip.html.twig` / `home.html.twig` reach them via `grav.pages.find(route ~ '/dailies').children`. Deleting the folder (or its `.md`) breaks that lookup and the entries vanish from the feed. Instead, keep the folder and repoint its `.md` to an inert container: + +```yaml +# 01.dailies/dailies.md +--- +title: Journal +template: default # was: dailies (dailies.html.twig is deleted) +routable: false # the container's own URL 404s +visible: false # not enumerated in nav +--- +``` + +`routable: false` makes the container URL inert **without** unrouting its children — individual entries stay reachable at `/trips//dailies/`, and `find(...).children` still resolves because the page remains in the tree. (Folders that were pure views with no children — `02.map/`, `03.stats/` — can be deleted outright.) + +**2. Repoint Back-link fallbacks to the surviving surface (grandparent), not the retired parent.** +Detail templates used `href="{{ page.parent().url }}"` with an `onclick` that runs `history.back()` when history exists. `history.back()` covers in-app navigation, but the `href` is the fallback for **direct-landing visitors** (shared link, new browser tab, search result) — and it pointed at the now-inert container: + +```twig +{# entry.html.twig / story.html.twig — BEFORE (breaks on direct landing) #} +← Back + +{# AFTER — fall back to the trip page (grandparent), the surface that survived #} +← Back +``` + +This is a **silent** regression: the detail page renders fine (200, no Twig error), so curl/CI-of-the-page all pass. It only breaks when a cold visitor clicks Back — the exact path a shared link takes. + +**3. Sync the gitignored demo source AND the Makefile, or the next reload undoes the cleanup.** +The `italy-2026-demo` trip pages are **gitignored**; they are regenerated by `make demo-load` from `user/docs/demo/trips/italy-2026-demo/` (which **is** tracked in the user repo). Deleting pages from the live tree is not enough — you must also: +- delete/repoint the demo **source** files (`map.md`, `stats.md`, and the `dailies/`/`stories` container `.md`s), and +- update the `demo-load` Makefile target so it no longer `mkdir`s `02.map`/`03.stats` or copies the deleted `.md`s. + +Otherwise the next `make demo-load` recreates the deleted pages pointing at deleted templates. This matters doubly because Playwright's `global-setup` runs `make demo-load` before the suite — stale demo source breaks tests, not just a manual reload. + +**4. Sweep the test suite for the deleted routes.** Delete tests that target the gone pages; re-point tests whose behaviour moved to the consolidation surface (e.g. the feed sort toggle is now `#trip-sort-toggle` on the trip page). Note the consolidation surface may sort differently (the trip page is oldest-first; the old `/dailies` view was newest-first) — re-pointed ordering assertions may need to invert. + +## Why This Matters + +The two halves of a Grav page (routable view vs. data container) are invisible in a file listing but load-bearing. The failure modes are asymmetric and sneaky: deleting a container **loudly** empties a feed (easy to catch), but the back-link fallback fails **silently** for only a subset of visitors, and the demo-source drift fails **later** — on the next reload or CI run, not during the change. A curl/HTTP smoke test passes all three while two are broken. Getting the procedure right the first time avoids a shipped regression and a red suite that looks unrelated to the change. + +## When to Apply + +- Deleting any Grav view page whose feed/map/list now renders inside another page. +- Any time a page folder is a parent of child pages that templates fetch via `find(route).children` — keep it as a `routable:false` container. +- Whenever a detail page's Back link (or any `page.parent()` reference) could resolve to the page being retired. +- Whenever the affected trip is `italy-2026-demo` (or any gitignored, `demo-load`-regenerated content). + +## Examples + +**Verification that proves the container split worked** (children of a `routable:false` parent stay reachable): + +``` +# keepers +/ → 200 +/trips/italy-2026-demo → 200 (feed still populated) +/trips/italy-2026-demo/dailies/ → 200 (child of routable:false container) +/trips/italy-2026-demo/stories/ → 200 +# retired views +/trips/italy-2026-demo/map → 404 +/trips/italy-2026-demo/stats → 404 +/trips/italy-2026-demo/dailies → 404 (container inert; children still route) +``` + +**Grep gate before declaring done** — no `include`/`import`/link references to the deleted templates remain (a lone `macros/stats.html.twig` hit is the shared macro, a keeper — not the deleted `stats.html.twig` page): + +``` +grep -rnE "include .*(feed-map|dailies|stories|map|stats)\.html|~ '/map'|~ '/stats'" templates/ +``` + +## Related + +- `docs/working/plans/2026-07-04-standalone-page-cleanup.md` — the plan this learning came from +- `docs/reference/architecture.md` — page-tree structure and the single `MapUtils.initEntryMap` map path +- `docs/guides/trip-switching.md` — new trips now scaffold only `01.dailies/` + `04.stories/` (inert containers) +- `CLAUDE.md` → "Trip entity architecture" and "One map path" — the current-state contract