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

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 :

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 (fond sombre, accent cyan, cartes). Les QR codes sont générés côté client avec la librairie 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)

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

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/.

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

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.