Roadmap page: visual learning path (roadmap.sh-style) + the tutorial spine

[rufuspollock]

Part of #46. Rufus 2026-07-18: we want a visual walkthrough page, inspired by roadmap.sh — not just lists of pages. An intro-to-markdown-and-what-to-build-with-it journey: learn markdown → build X with markdown (website, KB, Notion-replacement, …), the way 'intro to JavaScript' sites walk you to 'build something with JavaScript'.

Behind it, two structural ideas:

1. One spine: a single major tutorial line the site is organised around (basics → publish → local editing → collaborate → choose your build-X branch). The roadmap page is the map of that spine; learn/onboarding is its text form. Serves job stories JS1 + JS4 (docs/job-stories.md).
2. Visual overview pages generally: more areas deserve a visual intro page rather than a link list.

Tasks

• v1 /roadmap page: HTML/Tailwind in markdown (on-message), vertical staged path + build-X destination grid, linked from landing + learn
• Iterate visuals after Rufus reacts (v1 is deliberately simple: no JS, no checkboxes)
• Consider roadmap-style sub-pages per big track (websites track, KB track)
• Fold in coggle structure when mined (Mine old epic #12 + the coggle mind-map for reusable structure #62)
• Possible later: interactive progress-ticking à la roadmap.sh (needs JS — Flowershow constraints to check)

[rufuspollock]

v1 shipped: /roadmap — two entrances (publish-first 🚀 / notes-first 📝, straight from the coggle's alternative flow), the five-stage spine with time estimates, a 12-card build-your-X grid, and side quests. Linked from the landing page and learn index. Open questions for iteration: does it earn a navbar slot (nav is at 6 items); whether stages want small illustrative screenshots; roadmap-style sub-pages per track.

[rufuspollock]

Visual experiment shipped per Rufus's ask — brief first, then a contained prototype:

• Brief/vision: docs/briefs/visual-roadmap.md — incl. roadmap.sh anatomy, approach trade-offs, and 3 open questions for Rufus
• Prototype: https://wayofmarkdown.com/x-roadmap-experiment (unlisted; hidden from sidebar/search) — 27 clickable nodes, spine + branch clusters, curved edges, status colours = site build-state (green built / amber-dashed partial / grey-dotted planned)
• Architecture: scripts/roadmap-map.json (the map as data) → scripts/roadmap-gen.py → inline SVG. Rendered preview checked visually — it genuinely reads as a roadmap.sh-style map.
• v2 candidates in the brief: progress ticking (needs JS — Flowershow constraints to check), hover panels, full-site coverage.

Awaiting Rufus's eyes on the live page + the brief's 3 open questions (where it lives, coverage, interactivity appetite).

[rufuspollock]

Rufus verdict: experiment is great — promoted. The visual now IS /roadmap (generated in place via markers; experiment page retired), Roadmap added to the navbar (first position). Map data grew to 31 nodes incl. the new pages, all statuses truthful. Remaining on this issue: v2 interactivity (progress ticking) and possible per-track sub-maps.