Le Prévost-Corvellec Arnault
354c8cd9ef
- Introduced a Makefile for streamlined commands related to building, running, and managing presentations. - Created package.json to define project metadata, dependencies, and scripts for development and testing. - Added .gitignore entries to exclude build artifacts and temporary files from version control. - Included playwright.config.mjs for end-to-end testing setup with Playwright. - Added README.md for project documentation, outlining setup instructions and development guidelines.
133 lines
5.8 KiB
Markdown
133 lines
5.8 KiB
Markdown
# 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`.
|