Site statique → GitHub Pages
Workflow complet : données → page HTML/CSS/JS autonome → vérification navigateur → publication GitHub Pages.
Cible : pages de 1 à quelques centaines d'éléments, un seul auteur, zéro dépendance à l'exécution.
Quand l'utiliser
| Oui | Non |
|---|---|
| « fais-moi une page avec cette liste / ce tableau », galerie, dashboard de données | app avec backend, auth, base de données → demander avant |
| « publie-le sur GitHub / GitHub Pages » | site généré par un framework (Next, Astro, Hugo) → suivre le flux du framework |
| reproduction d'une page existante en données (titres, dates, prix…) | copie du design/CSS/HTML d'un site tiers → refuser, refaire un design propre |
Règles non négociables
- Design maison. Ne jamais copier le CSS, le HTML ni les assets d'un site tiers. S'inspirer de la structure d'information est OK ; reprendre la charte ne l'est pas.
- Faits oui, œuvres non. Titres, dates, prix, notes, liens = données factuelles, réutilisables. Textes rédactionnels, descriptions, visuels = protégés : ne pas les recopier. Pour les images, hotlinker le CDN d'origine plutôt que de les committer (voir
reference/data-and-ethics.md). - Respecter les protections d'accès.
robots.txtqui interdit les crawlers, challenge Cloudflare/bot → on ne contourne pas. Chercher une API officielle, une clé, ou dégrader en simple lien sortant. - Toujours vérifier dans un vrai navigateur avant de dire « c'est fait » (screenshot + test de clic).
- Ne pas publier sans confirmation du nom de dépôt / du compte si ambigu.
- Ne pas créer de domaine personnalisé sans confirmation. Si l'utilisateur ne l'a pas précisé, lui demander s'il veut une redirection Cloudflare et sur quel domaine (étape 6). Ne jamais inventer un sous-domaine ni en créer un de sa propre initiative : le DNS est un effet de bord visible à l'extérieur.
Workflow
1. Cadrer (30 s)
-
Quelle donnée, combien d'items, mise à jour unique ou récurrente ?
-
Sortie attendue : une page ? tri/recherche ? quelles règles d'affichage métier ?
-
Où publier : compte GitHub, nom de dépôt, public/privé (Pages exige un dépôt public sur les comptes gratuits).
-
Domaine personnalisé — à demander explicitement si non précisé. Poser la question en une fois, avec la proposition par défaut :
Veux-tu une redirection Cloudflare vers
<owner>.github.io(CNAME, proxy désactivé) ? Si oui, quel sous-domaine/rubrique ?Le nom est libre côté skill, mais le domaine est public dès sa création : ne rien créer sans réponse explicite. Si l'utilisateur répond non, s'arrêter à l'URL
https://<owner>.github.io/<repo>/et ne pas créer d'entrée DNS.
2. Récupérer les données
Une seule passe de script → un data.json = source de vérité, séparée du rendu.
python3 fetch_data.py # → data.json
Politesse : 0,3–0,7 s entre requêtes, User-Agent explicite, retry sur 429/5xx.
Détails et cas piégeux (PoW Anubis, Cloudflare, matching flou, API sans clé) : reference/data-and-ethics.md.
3. Générer la page
Partir des templates, pas de feuille blanche :
cp .dsh/skills/static-site-publish/templates/{index.html,styles.css,script.js} ./site/
cp .dsh/skills/static-site-publish/templates/build.py ./site/ # data.json → index.html
python3 ./site/build.py
build.py: petit générateur Python (f-string +html.escape) qui injecte les données dans une grille de cartes. Aucun runtime JS pour les données.styles.css: thème sombre par défaut, grilleauto-fill minmax(), variables CSS.script.js: recherche instantanée + tri + règles d'affichage calculées à l'ouverture (pour que la page reste juste sans rebuild).- Tout ce qui est calculable à l'affichage (statuts, dates relatives) doit l'être en JS : ça évite de reconstruire le site tous les jours.
- Le HTML doit rester lisible sans JS, et le JS doit être progressif.
4. Vérifier
.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html
Ouvre la page dans Chrome headless, écrit /tmp/site-shot.png, et lance le test de superposition des clics. Regarder le screenshot (outil read_image) avant de conclure.
Checklist : rendu desktop + mobile, données complètes (compter les items), liens corrects, aucun chevauchement.
5. Publier
.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site mon-nom-de-repo
Le script : gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → polling de l'URL jusqu'au 200 → affiche l'URL finale.
Le délai Pages est de 20 à 90 s : ne pas conclure « ça ne marche pas » avant d'avoir bouclé sur un 200. Vérifier aussi gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = built.
6. Domaine personnalisé + Cloudflare
Uniquement si l'utilisateur l'a demandé (cf. étape 1). Le DNS est public : ne pas réinterpréter un « oui » vague en nom de domaine choisi par l'IA.
Ordre imposé : DNS d'abord, certificat ensuite, Enforce HTTPS en dernier. Le site doit déjà répondre en 200 sur *.github.io avant de commencer.
a. Redirection DNS chez Cloudflare (MCP Cloudflare)
Pré-requis jeton : scopes zone.read + dns.write (Zone Read / DNS Edit). S'il manque, s'arrêter et demander l'élargissement — ne pas contourner.
GET /zones?name=<domaine racine>→zone.id. Si zéro zone : le domaine n'est pas dans ce compte, demander.GET /zones/{zone_id}/dns_records?name=<fqdn>→ si un CNAME identique existe déjà, ne rien recréer (idempotence).POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<sous-domaine>", "content": "<owner>.github.io",
"proxied": false, "ttl": 1 }
proxied: false= DNS only, non négociable : le proxy Cloudflare empêche GitHub d'émettre le certificat.- La cible est
<owner>.github.io, sans slash final et sans nom de dépôt (jamesdadams.github.io, pas.../mon-repo). ttl: 1= Auto.
- Vérifier en résolution publique, pas seulement via l'API :
dig +short <fqdn> CNAME @1.1.1.1 # → <owner>.github.io.
dig +short <fqdn> A @1.1.1.1 # → 185.199.108-111 .153
b. Domaine + Enforce HTTPS côté GitHub Pages
.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <domaine> ./site
Le script : écrit le fichier CNAME dans le site (il survit aux redéploiements et évite de perdre le domaine) → PUT /repos/{owner}/{repo}/pages avec cname → attend https_certificate.state = approved → active https_enforced: true.
⚠️ https_enforced: true renvoie 400 tant que le certificat n'existe pas. Délai réel : 5 à 20 min après création du CNAME. C'est pourquoi le script boucle au lieu d'échouer. Ne pas cocher « Enforce HTTPS » à la main avant l'émission, et ne pas conclure à un échec pendant cette fenêtre.
c. Vérification finale
curl -sI https://<domaine>/ | head -5 # 200 + header server: GitHub.com
Puis rouvrir la page dans le navigateur (étape 4) sur l'URL personnalisée : un 200 ne prouve pas que les chemins relatifs (styles.css, script.js) résolvent — c'est le piège classique des project pages servies à la racine d'un domaine.
7. Rendre la mise à jour possible
- Mettre le dossier git dans le dossier de projet de l'utilisateur (pas dans
/tmp, effacé au reboot). - Documenter dans le
README.md: d'où viennent les données, comment relancer l'extraction, ce qui est figé (données) vs vivant (règles calculées en JS). - Signaler explicitement à l'utilisateur ce qui ne se mettra pas à jour tout seul.
Pièges déjà rencontrés
| Symptôme | Cause | Correctif |
|---|---|---|
| 403 « Just a moment… » | challenge Cloudflare | documenter la limite, API officielle ou lien sortant ; ne pas tenter de contourner |
| Page tronquée « Making sure you're not a bot » | PoW Anubis | résoudre le challenge (cf. reference) ou demander un export à l'utilisateur |
| Sélecteur qui renvoie 0 résultat sur tous les items | mauvais motif (ex. /games/lib/genre: vs /games/lib/popular/genre:) | imprimer un échantillon du HTML et tester le regex sur 1 page avant de boucler |
| Clic sur une carte qui n'ouvre pas le bon lien | couche <a> recouverte par un enfant positionné | pointer-events: none sur les éléments décoratifs ; tester avec elementFromPoint |
| GitHub Pages 404 les premières minutes | build en cours | polling jusqu'à 90 s |
| Données d'une colonne vides | libellé variable côté source (« Released » vs « Early Access ») | motif tolérant + log par item, jamais de except: pass silencieux |
https_enforced en 400 « certificate does not exist » | certificat pas encore émis | attendre https_certificate.state = approved (5-20 min), le script boucle |
| Domaine perso en 404 après 30 min | CNAME absent / mauvais propriétaire / fichier CNAME manquant dans le repo | dig pour confirmer le CNAME, relancer set-pages-domain.sh |
| HTTPS cassé après activation du proxy | enregistrement passé en Proxied | repasser en DNS only (proxied: false), le certificat GitHub ne peut pas être validé à travers le proxy |
| « Domain is already in use » | domaine déjà déclaré sur un autre dépôt du compte | un domaine personnalisé par dépôt ; libérer l'ancien avant de réassigner |
CSS/JS en 404 sur le domaine perso mais OK en *.github.io/repo/ | chemins absolus (/styles.css) sur une project page servie à la racine | chemins relatifs (styles.css) |
Références
reference/data-and-ethics.md— extraction, PoW Anubis, Cloudflare, licences, hotlink d'imagesreference/design-and-verify.md— design system minimal, tests navigateur, a11yreference/publish-gh-pages.md— commandesgh, nommage, domaines, dépannagescripts/publish-gh-pages.sh— publication + activation Pagesscripts/set-pages-domain.sh— domaine personnalisé + Enforce HTTPS (après le CNAME Cloudflare)scripts/verify-site.shtemplates/{index.html,styles.css,script.js,build.py}