# Talks techniques

Portail statique (**VitePress**) + decks (**Slidev**). Le portail sort dans **`dist/portal/`** ; les decks Slidev sont buildés dans **`artifacts/slides/`** (hors `dist/`, pour ne pas être effacés par Vite), puis **`assemble-dist`** les copie dans **`dist/portal/slides/`** pour le déploiement (`npx serve dist/portal`).

---

## Démarrage rapide

```bash
npm install
npm run dev
```

Ouvre le portail en local : les decks buildés sont servis sous `/slides/` par le **plugin Vite** (`portal/.vitepress/vite-plugin-slides-fs.mjs`) depuis `dist/slides/` — pas de second serveur HTTP. Pour le portail seul (sans decks) : `npm run dev:portal`.

Pour prévisualiser le **résultat de production** après un build :

```bash
npm run build
npm run preview
```

---

## Développement

| Commande | Description |
|----------|-------------|
| `npm run dev` | Sync + build slides → `dist/slides/` + VitePress (plugin sert `/slides/` depuis ce dossier) |
| `npm run dev:portal` | Sync + VitePress seul — pas de decks sous `/slides/` en local |
| `npm run dev:slides:kubernetes-operators` | Deck Slidev avec rechargement à chaud |
| `npm run dev:slides:spring-ai` | Idem pour l’autre exemple |
| `npm run sync` | Régénère uniquement le portail (liste, fiches, « À la une ») à partir de `slides/*/meta.json` |

En **`npm run dev`**, un seul processus VitePress ; les builds Slidev vont sur le disque (`dist/slides/`) et le plugin les expose. Pour éditer un deck avec le mode Slidev interactif, utilisez `npm run dev:slides:…`.

### Thème et QR codes

L’apparence reprend la charte de [talk.specificat.io](https://talk.specificat.io/) (fond sombre, accent cyan, cartes). Les QR codes sont générés côté client avec la librairie [`qrcode`](https://www.npmjs.com/package/qrcode) (canvas).

- URL du dépôt Git affichée sur l’accueil : `talkRepoUrl` (et textes associés) dans `portal/.vitepress/config.mjs` → `themeConfig`.
- Chaque fiche présentation inclut un QR vers le deck `/slides/<slug>/`.

### Tests (base solide avant corrections ciblées)

```bash
npx playwright install chromium   # une fois (navigateur pour les E2E)
npm test                          # tout : Node + Playwright (make test)
```

| Script | Contenu |
|--------|---------|
| `npm run test:node` | Tous les tests **Node** (`node:test`) : chemins `SITE_BASE`, **contrats** de génération (`scripts/presentation-contracts.mjs`), cohérence dépôt après sync, sync sur dépôt temporaire (`TALKS_ROOT`), layout `dist/` si présent |
| `npm run test:e2e` | **Playwright** : build + `serve dist/portal` — parcours UI, **HTTP 200**, matrice par slug |
| `npm run test:e2e:ui` | Mode UI Playwright |
| `npm run test:unit` | Alias de `test:node` |

**Fichiers** : `tests/site-base.test.mjs`, `tests/presentation-contracts.test.mjs`, `tests/repo-consistency.test.mjs`, `tests/sync-tmp-repo.test.mjs`, `tests/dist-layout.test.mjs`, `e2e/flows.spec.js`, `e2e/http-routes.spec.js`, `e2e/presentations-matrix.spec.js`.

La logique du portail généré est dans **`scripts/presentation-contracts.mjs`** (une seule source pour `sync-portal.mjs` et les tests).

**CI** : `.github/workflows/ci.yml` (Node + E2E), `.github/workflows/build.yml` (build + test `dist/`).

**Aller plus vite en local** : `npx serve dist/portal -p 4174 -L` puis `PW_SKIP_WEBSERVER=1 npm run test:e2e`.

---

## Build production

```bash
npm run build
```

Enchaîne : sync → **VitePress** → `dist/portal/` → **Slidev** → `artifacts/slides/<slug>/` (hors `dist/`, donc pas effacé par le build VitePress) → **`assemble-dist`** copie vers `dist/portal/slides/`.

| Commande | Quand l’utiliser |
|----------|------------------|
| `npm run build` | Complet : sync (`prebuild`) + portail + decks + assemble |
| `npm run build:portal` | Idem `build` (via Makefile, sync explicite) |
| `npm run build:vitepress-only` | **Uniquement** VitePress → `dist/portal/` |
| `npm run build:slides` | Decks seuls → `dist/slides/` |

Après build : **`dist/portal/`** contient le site prêt à servir. La sortie brute Slidev est dans **`artifacts/slides/`** (gitignoré) jusqu’à fusion ; surcharger avec **`SLIDES_BUILD_OUT`** si besoin.

Servir **`dist/portal`** (ex. `npx serve dist/portal`).

---

## Déploiement sous un sous-chemin

Exemple : site hébergé en `https://pages.example.org/mon-repo/`.

```bash
export SITE_BASE=/mon-repo/
npm run sync
npm run build
```

Même variable pour VitePress, les liens générés et les assets Slidev. À la racine du domaine, ne rien exporter (comportement par défaut).

---

## Ajouter une présentation

1. Créer `slides/<slug>/meta.json` et `slides/<slug>/slides.md`.  
2. Optionnel : ajouter un script `dev:slides:<slug>` dans `package.json`.  
3. `npm run sync` puis `npm run build` (le `prebuild` lance déjà le sync).

Champs utiles dans `meta.json` : `title`, `description`, `tags`, `order`, `featured` (sinon la home prend les premières entrées par `order`).

---

## Structure du dépôt

```text
scripts/          # sync-portal, build-slides, assemble-dist, préfixe SITE_BASE
portal/           # sources VitePress + vite-plugin-slides-fs (dev)
slides/<slug>/    # slides.md + meta.json par deck
dist/portal/      # portail buildé (+ slides copiés après assemble)
artifacts/slides/ # sortie Slidev avant fusion (hors dist/, non versionné)
```

Les fichiers sous `portal/presentations/` et `portal/.vitepress/data/presentations.json` sont **régénérés** par `sync`. La zone « À la une » dans `portal/index.md` est entre `<!-- FEATURED_START -->` et `<!-- FEATURED_END -->`.

---

## Notes techniques

- **VitePress** : ne pas définir `outDir` dans `vite.build` — utiliser `outDir` au **premier niveau** de la config (sinon le build SSR casse).  
- **Slidev** : le paquet `@slidev/theme-default` est requis pour un build non interactif.

Stack : Node.js **18+** (LTS 20 ou 22 recommandées), `npm`.