[EPIC] Migration des PDFs vers un repo d'assets séparé

[nedseb]

Motivation

Les PDFs pèsent 1,7 Go (68 %) du contenu statique pour seulement 136 fichiers, et constituent l'essentiel du poids de :

• l'historique git (.git = 2,1 Go) ;
• l'artifact déployé sur GitHub Pages (site/build = 2,6 Go) ;
• le temps d'upload du workflow deploy.yml.

Or les PDFs sont du contenu figé : une fois publié, le PDF d'une fiche ne change plus (sauf erratum rare). Les garder dans le repo principal fait payer le coût de l'historique sans aucun bénéfice. Trois PDFs > 50 Mo (Unplugged) sont déjà exclus via .gitignore faute de mieux — preuve que la limite a déjà été atteinte.

Objectif

Externaliser tous les PDFs dans un second repo wikilab-assets déployé sur un sous-domaine GitHub Pages, et faire pointer les liens du site Docusaurus vers ce domaine.

Architecture cible

wikilab/                  ← repo actuel
├── site/
│   ├── docs/             ← inchangé
│   ├── static/img/       ← inchangé (potentiellement migré dans une 2e phase)
│   └── …
└── …                     ← repo principal, ~150 Mo après migration

wikilab-assets/           ← nouveau repo, ~1,7 Go
├── pdf/
│   ├── lets-steam/
│   ├── mimesis/
│   └── …
├── .github/workflows/
│   └── deploy-pages.yml  ← déploie sur Pages depuis `pdf/`
└── README.md

DNS / Pages :
  assets.wikilab.labaixbidouille.com  → wikilab-assets via gh-pages

Les fiches référencent https://assets.wikilab.labaixbidouille.com/pdf/<projet>/<fiche>.pdf au lieu du chemin local /pdf/<projet>/<fiche>.pdf.

Plan de migration

Étape 1 — Préparation (avant migration)

1. Inventaire : générer la liste complète des PDFs présents + leur usage (grep des chemins dans les fiches).
2. Décision sur l'historique : garder dans wikilab-assets un commit initial unique « import depuis wikilab@ », ou conserver l'historique git ? La purge du legacy dans wikilab se fera quoi qu'il en soit via git filter-repo.
3. Choix du DNS :
   • Sous-domaine de wikilab.labaixbidouille.com : assets.wikilab.… (simple, cohérent).
   • Ou racine assets.labaixbidouille.com (plus court).
4. Helper Docusaurus : composant <PdfLink> ou variable ASSETS_BASE_URL qui préfixe automatiquement les liens PDF. Permet de switcher local ↔ prod sans réécriture en masse.

Étape 2 — Création du repo wikilab-assets

1. Créer le repo LabAixBidouille/wikilab-assets.
2. Copier l'arborescence site/static/pdf/ à la racine du nouveau repo, sous pdf/.
3. Workflow Pages minimaliste qui sert le dossier pdf/ à la racine du sous-domaine.
4. Test : curl sur 5-10 URLs après déploiement.

Étape 3 — Réécriture des liens dans wikilab

1. Remplacer les <a href="/pdf/…"> par <PdfLink href="…"> (ou équivalent variable).
2. Tester en local avec un override d'env (ASSETS_BASE_URL=http://localhost:3001 + mini serveur statique sur les PDFs locaux pour la preview).
3. Lychee : ajouter assets.wikilab.… à la config pour vérifier que les liens externes ne cassent pas.

Étape 4 — Purge du legacy

1. Supprimer site/static/pdf/ dans wikilab.
2. git filter-repo pour réécrire l'historique et virer les blobs PDFs (gain attendu sur .git : ~1 Go).
3. Force-push annoncé sur main (opération destructive, demander explicitement avant d'agir).
4. Communiquer aux contributeur·rices pour re-cloner.

Étape 5 — Documentation et CI

1. Mettre à jour CLAUDE.md, CONTRIBUTING.md, CONVENTIONS.md : nouveau workflow d'ajout de PDF (PR sur wikilab-assets).
2. Adapter links.yml (Lychee) pour qu'il check aussi assets.wikilab.….
3. Retirer la mention « 3 PDFs > 50 Mo exclus » qui devient obsolète.

Gains attendus

Métrique	Avant	Après	Gain
site/static/	2,5 Go	847 Mo	-1,7 Go
site/build/	2,6 Go	~950 Mo	-1,7 Go
.git/ (après filter-repo)	2,1 Go	~1 Go	-1 Go
Temps de git clone	plusieurs minutes	< 30 s	substantiel
Temps d'upload deploy.yml	élevé	nettement réduit	substantiel
Réintégration des 3 PDFs Unplugged exclus	non	oui	gain qualitatif

Risques et points d'attention

• DX local : sans fallback, les liens PDF cassent en dev local. À gérer via composant <PdfLink> qui pointe sur les PDFs locaux quand process.env.NODE_ENV === 'development' + miroir local optionnel.
• Cache navigateur / liens externes : les anciens liens wikilab.labaixbidouille.com/pdf/… doivent rediriger vers le nouveau domaine. À configurer côté Pages via redirect rules, ou laisser 404 si on accepte le bris.
• Workflow contributeur : un ajout de fiche avec PDF devient 2 PRs (une dans chaque repo). À automatiser au minimum par un template d'issue cross-repo.
• Sécurité supply-chain : un repo séparé exige les mêmes branch protections que wikilab.

Décisions à prendre avant kickoff

1. Conserver l'historique git des PDFs dans wikilab-assets, ou commit initial unique ?
2. Sous-domaine définitif (assets.wikilab.… ou assets.labaixbidouille.…) ?
3. Purge du legacy dans wikilab immédiate, ou différée (le temps de valider le nouveau workflow) ?
4. Migrer aussi les images dans un second temps (gain supplémentaire ~700 Mo) ou les garder dans wikilab ?

Critères d'acceptation

• Repo wikilab-assets créé, peuplé, déployé sur Pages.
• Tous les liens PDF des fiches pointent vers le nouveau domaine.
• Build wikilab < 1 Go.
• Lychee vert sur wikilab ET wikilab-assets.
• Docs (CLAUDE.md, CONTRIBUTING.md) mises à jour.
• Tickets de suivi pour le post-MEP (purge legacy, migration images éventuelle).

Hors scope (à traiter dans des issues séparées)

• Migration des images (722 Mo) : envisageable en phase 2 si gain démontré.
• Optimisation rétroactive des PNG/JPG existants : issue [OUTILLAGE] Passe d'optimisation rétroactive des images existantes #202.

[nedseb]

Arbitrages tranchés (2026-05-28)

Décision	Choix retenu
1. Historique git des PDFs	Commit initial unique « import depuis wikilab@<sha> ». Le repo wikilab-assets démarre léger ; provenance tracée dans le message + l'historique de wikilab.
2. Sous-domaine	assets.wikilab.labaixbidouille.com (namespacé sous le wiki, propriété claire).
3. Purge du legacy dans wikilab	Différée : migration → repointage des liens → lychee vert → période d'observation, PUIS git filter-repo + force-push. Pas dans la foulée.
4. Migration des images	Non. Les images restent dans wikilab (214 Mo après #204, fort couplage DX/preview locale). À reconsidérer seulement si elles regrossissent.

Conséquences sur le plan

• L'épopée se concentre uniquement sur les PDFs (1,7 Go). Pas de phase 2 images.
• Le renommage des noms de fichiers fragiles côté PDF se fera pendant cette migration (slugification à l'import dans wikilab-assets), pas dans [OUTILLAGE] Nettoyage des noms de fichiers fragiles (espaces, accents) dans static/ #206 qui reste images uniquement.
• La purge destructive est un ticket de suivi distinct, à n'ouvrir qu'après validation du nouveau workflow.

Prochaines étapes (ordre)

1. Créer le repo LabAixBidouille/wikilab-assets + brancher le DNS assets.wikilab.labaixbidouille.com sur Pages.
2. Import des PDFs (slugifiés) en commit unique + workflow Pages.
3. Helper <PdfLink> / ASSETS_BASE_URL côté Docusaurus + repointage des liens.
4. Lychee sur les deux repos.
5. Observation, puis (ticket dédié) purge filter-repo du legacy dans wikilab.