publication-site-statique

Compétence de codage. Génère un petit site statique en HTML/CSS/JS pur (sans build ni framework) à partir de données — liste, galerie, tableau de bord, portfolio — le vérifie dans un navigateur headless, puis le publie sur GitHub avec GitHub Pages. Configure aussi le domaine personnalisé : redirection CNAME Cloudflare (proxy désactivé) et Enforce HTTPS sur GitHub Pages.

Qu'est-ce que publication-site-statique ?

Cette compétence permet de transformer des données (listes, galeries, tableaux de bord, portfolios) en un site statique complet, autonome en HTML/CSS/JS, sans dépendance à un framework ou à un outil de build. Le flux complet inclut la récupération des données (via un script Python), la génération de la page à partir de templates prédéfinis, la vérification dans un navigateur headless (Chrome) pour valider le rendu et l'absence de chevauchements, puis la publication sur GitHub Pages. Elle gère également la configuration d’un domaine personnalisé via Cloudflare (CNAME proxy désactivé) et l’activation de HTTPS forcé côté GitHub Pages, avec une vérification finale de la résolution des chemins relatifs. La compétence est conçue pour des sites de 1 à quelques centaines d’éléments, pour un seul auteur, et s’intègre avec Claude Code, Cursor, Codex ou tout autre agent capable d’exécuter des scripts shell et Python. Elle impose des règles éthiques strictes : pas de copie de design tiers, respect des protections d’accès (robots.txt, Cloudflare), et demande systématique de confirmation avant la création d’un dépôt ou d’un domaine personnalisé.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JamesDAdams/my-skills/tree/HEAD/.apm/skills/static-site-publish

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

OuiNon
« fais-moi une page avec cette liste / ce tableau », galerie, dashboard de donnéesapp 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

  1. 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.
  2. 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).
  3. Respecter les protections d'accès. robots.txt qui interdit les crawlers, challenge Cloudflare/bot → on ne contourne pas. Chercher une API officielle, une clé, ou dégrader en simple lien sortant.
  4. Toujours vérifier dans un vrai navigateur avant de dire « c'est fait » (screenshot + test de clic).
  5. Ne pas publier sans confirmation du nom de dépôt / du compte si ambigu.
  6. 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, grille auto-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.

  1. GET /zones?name=<domaine racine> → zone.id. Si zéro zone : le domaine n'est pas dans ce compte, demander.
  2. GET /zones/{zone_id}/dns_records?name=<fqdn> → si un CNAME identique existe déjà, ne rien recréer (idempotence).
  3. 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.
  1. 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ômeCauseCorrectif
403 « Just a moment… »challenge Cloudflaredocumenter la limite, API officielle ou lien sortant ; ne pas tenter de contourner
Page tronquée « Making sure you're not a bot »PoW Anubisrésoudre le challenge (cf. reference) ou demander un export à l'utilisateur
Sélecteur qui renvoie 0 résultat sur tous les itemsmauvais 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 liencouche <a> recouverte par un enfant positionnépointer-events: none sur les éléments décoratifs ; tester avec elementFromPoint
GitHub Pages 404 les premières minutesbuild en courspolling jusqu'à 90 s
Données d'une colonne videslibellé 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 émisattendre https_certificate.state = approved (5-20 min), le script boucle
Domaine perso en 404 après 30 minCNAME absent / mauvais propriétaire / fichier CNAME manquant dans le repodig pour confirmer le CNAME, relancer set-pages-domain.sh
HTTPS cassé après activation du proxyenregistrement passé en Proxiedrepasser 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 compteun 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 racinechemins relatifs (styles.css)

Références

  • reference/data-and-ethics.md — extraction, PoW Anubis, Cloudflare, licences, hotlink d'images
  • reference/design-and-verify.md — design system minimal, tests navigateur, a11y
  • reference/publish-gh-pages.md — commandes gh, nommage, domaines, dépannage
  • scripts/publish-gh-pages.sh — publication + activation Pages
  • scripts/set-pages-domain.sh — domaine personnalisé + Enforce HTTPS (après le CNAME Cloudflare)
  • scripts/verify-site.sh
  • templates/{index.html,styles.css,script.js,build.py}

Skills associés