Restructure documentation following Diátaxis framework

[titouanmathis]

Context

The current documentation mixes different types of content (tutorials, how-to, reference, explanation) without clear separation. Inspired by the Diátaxis framework and data-star.dev documentation structure, this issue proposes a restructure to improve discoverability, learning path, and overall quality.

Current problems

• Guide/Introduction mixes tutorial (learning-oriented) and how-to (task-oriented) content
• "Going further" mixes explanation (why?) with how-to (how?)
• Recipes are buried deep inside the Guide sidebar instead of being a first-class section
• No "Concepts/Explanation" section — nowhere to explain why the framework works the way it does (data-attributes philosophy, component tree architecture, service singleton pattern)
• Getting Started tries to cover too much (install + first component + async registration)
• Homepage lacks an "aha moment" — no interactive demo, minimal pitch

---

Proposed structure

Top navigation

Guide  |  API  |  Utils  |  Examples

(Examples promoted from buried Recipes to top-level nav item)

Guide (learning path — linear, progressive)

Guide
├── Getting Started          ← install + hello world only
├── Components               ← what is a component, data-component, config
├── Refs                     ← data-ref, single/multiple, nested
├── Options                  ← data-option, types, defaults
├── Lifecycle                ← mounted/destroyed/updated hooks
├── Events                   ← onRefEvent, custom events, emitting
├── Services                 ← scroll/resize/raf/pointer/etc.
├── Going Further
│   ├── Child Components     ← managing component trees, lazy imports
│   ├── Decorators           ← what they are, how to compose
│   ├── TypeScript           ← typing components
│   └── Custom Services      ← registering new services
├── Concepts                 ← NEW explanation section
│   ├── Philosophy           ← why data-attributes? positioning vs React/Vue
│   ├── Component Tree       ← how the tree is resolved, mounting order
│   └── Service Architecture ← singleton pattern, perf, lifecycle
└── Migration
    ├── v1 → v2
    └── v2 → v3

API Reference (unchanged)

Already well-structured. Keep as-is.

Utils Reference (unchanged)

Already well-structured. Keep as-is.

Examples (promoted, expanded)

Examples
├── Counter Component        (existing)
├── Accordion                (existing)
├── Lazy Image               (existing)
├── Scroll-linked Animation  (existing)
├── Teleport Refs            (existing)
├── Tabs                     (new)
├── Modal / Dialog           (new)
├── Infinite Scroll          (new)
├── Form Validation          (new)
└── Page Transitions         (new)

Each example follows a consistent template:

1. What we are building (goal)
2. HTML markup
3. JS component
4. App setup
5. Live demo (embedded)

---

Phases

Phase 1 — Restructure navigation

Update config.ts sidebar and nav configuration.

Phase 2 — Rewrite Guide pages

Rewrite introduction pages as a linear progressive tutorial. Create Concepts section.

Phase 3 — Enhance Examples

Move recipes to examples/, add new examples, standardize format.

Phase 4 — Polish

Cross-link consistently, review all pages, improve homepage.

---

Acceptance criteria

Phase 1 — Navigation restructure

• Top nav has 4 entries: Guide, API, Utils, Examples
• Guide sidebar is a flat linear list (no "Introduction" sub-group), progressing from Getting Started → Components → Refs → Options → Lifecycle → Events → Services
• "Going further" remains as a collapsed group in the Guide sidebar with: Child Components, Decorators, TypeScript, Custom Services
• New "Concepts" group appears in the Guide sidebar with stub pages for: Philosophy, Component Tree, Service Architecture
• "Migration" group remains at the bottom of the Guide sidebar
• Examples section exists as a top-level nav item with its own sidebar listing all examples
• Existing recipe pages are moved from guide/recipes/ to a new examples/ directory
• All existing internal links still resolve (no broken links)
• API and Utils sidebars remain unchanged

Phase 2 — Guide rewrite

• "Getting Started" page covers only: installation (npm + CDN) and a minimal hello-world example (< 30 lines of code)
• Each guide page (Components, Refs, Options, Lifecycle, Events, Services) covers exactly one concept
• Each guide page ends with a "Next →" link to the following page in the sequence
• Guide pages use progressive disclosure: each page builds on the previous one
• Concepts/Philosophy page explains the data-attributes approach and positioning vs other frameworks
• Concepts/Component Tree page explains tree resolution, mounting order, and parent-child relationships
• Concepts/Service Architecture page explains the singleton pattern, performance characteristics, and lifecycle

Phase 3 — Examples

• All examples follow the same template: Goal → HTML → JS → App setup → Live demo
• At least 3 new examples are added beyond the existing 5 recipes
• Each example is self-contained (can be understood without reading the full guide)
• Each example links to relevant API/Guide pages for further reading

Phase 4 — Polish

• Every Guide page links to the relevant API reference page(s)
• Every API page links back to the relevant Guide section when applicable
• No broken internal links across the entire docs site (vitepress build succeeds without link warnings)
• Homepage features at least one interactive/visual demo of the framework