Publier un site statique
Objectif
Publier ou préparer le déploiement d'un site web statique terminé.
Cette compétence est destinée aux sorties HTML/CSS/JS déployables comme site/, dist/, out/, public/ ou docs/. Elle peut également publier des projets framework après qu'ils aient produit un dossier de sortie statique, mais ne doit pas transformer un site statique simple en projet framework uniquement pour le déployer.
Position par défaut :
- Préférer un hébergement statique simple plutôt qu'un déploiement spécifique à un framework.
- Préférer un déploiement basé sur Git pour les sites que l'utilisateur continuera à modifier.
- Préférer un téléversement direct uniquement pour une publication rapide unique.
- Ne pas créer de dépôts distants, pousser du code, modifier le DNS, ajouter des domaines ou déployer vers un compte payant sauf si l'utilisateur le demande explicitement.
Contrat
Entrées :
- Racine de déploiement statique telle que
site/,dist/,out/,public/,docs/ou racine du dépôt. - Plateforme ou cible préférée : GitHub Pages, Cloudflare Pages, Netlify, Vercel, domaine personnalisé, simple conseil ou déploiement en direct.
- État Git/dépôt actuel, accès au compte de la plateforme, connexion CLI/navigateur et contraintes de déploiement.
Sorties :
- Paramètres de déploiement concrets : plateforme, branche, commande de build, répertoire de base, répertoire de publication/sortie et fichiers de configuration si nécessaire.
- Configuration facultative spécifique à la plateforme : workflow GitHub Pages,
netlify.toml,vercel.json,.nojekyllouCNAME. - URL en direct et vérification post-déploiement lorsque le déploiement est effectué.
- Étapes manuelles du tableau de bord lorsque les identifiants ou l'accès au compte ne sont pas disponibles.
Limites :
- Ne pas construire ou reconcevoir le site ; rediriger les défauts vers la compétence enfant appropriée.
- Ne pas pousser, créer de dépôts/projets, téléverser, lier des domaines, modifier le DNS ou utiliser des ressources payantes sauf autorisation explicite.
- Ne pas utiliser le déploiement comme solution de contournement pour des problèmes de compatibilité de chemins locaux/statiques sauf si l'utilisateur accepte explicitement un comportement limité à la racine du serveur.
Condition de succès :
review-static-sitea réussi ou les risques non résolus sont explicites.- La racine de déploiement contient
index.htmlet la plateforme publiera le dossier correct. - L'URL en ligne charge la page d'accueil, les ressources, la navigation et les sous-pages représentatives après le déploiement.
Si la condition échoue :
- Corriger les problèmes de chemin, de ressource, d'encodage ou de type de page avant le déploiement.
- Rediriger les problèmes de contenu/conception/importation vers
personalize-site,edit-site-part,add-blog-posts,make-personal-siteoucopy-website-style. - Réexécuter
review-static-sitepuis réessayer ou mettre à jour les paramètres de déploiement.
Références
Charger uniquement la référence nécessaire pour la plateforme ou le problème choisi :
- Stratégie de chemin et compatibilité d'ouverture directe :
references/path-strategy.md. - Intégration Git Cloudflare Pages et téléversement direct :
references/cloudflare-pages.md. - Source de branche GitHub Pages et workflows Actions :
references/github-pages.md. - Tableau de bord Netlify et
netlify.toml:references/netlify.md. - Tableau de bord Vercel et
vercel.json:references/vercel.md.
Documentation officielle :
- Source de publication GitHub Pages : https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
- Workflows personnalisés GitHub Pages : https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
- HTML statique Cloudflare Pages : https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
- Intégration Git Cloudflare Pages : https://developers.cloudflare.com/pages/get-started/git-integration/
- Téléversement direct Cloudflare Pages : https://developers.cloudflare.com/pages/get-started/direct-upload/
- Création de déploiements Netlify : https://docs.netlify.com/deploy/create-deploys/
- Configuration de build Netlify : https://docs.netlify.com/build/configure-builds/overview/
- Déploiements Vercel : https://vercel.com/docs/deployments
- Configuration de projet Vercel : https://vercel.com/docs/project-configuration
Modes de déploiement
Déterminer d'abord ce que l'utilisateur souhaite réellement :
- Simple conseil : expliquer le choix de la plateforme et les paramètres exacts. Ne pas modifier les fichiers sauf si utile.
- Préparer le dépôt : ajouter les fichiers de configuration nécessaires et indiquer à l'utilisateur sur quoi cliquer dans le tableau de bord d'hébergement.
- Déployer maintenant : effectuer des actions distantes uniquement si l'utilisateur l'a explicitement demandé et que le CLI/auth/session requis existe.
- Vérifier l'URL en direct : ouvrir l'URL déployée dans un navigateur et la comparer au site local.
Si les identifiants, l'accès au compte, la connexion au navigateur ou l'authentification CLI sont manquants, fournir les étapes exactes du tableau de bord au lieu d'inventer une solution de contournement.
Flux de travail
- Identifier le dossier de sortie statique et la plateforme préférée de l'utilisateur, le cas échéant.
- Appeler ou suggérer d'utiliser
review-static-siteavant la publication. - Confirmer que la racine de déploiement contient
index.html. - Inspecter les chemins des ressources et convertir les chemins locaux accidentellement absolus à la racine avant la publication. Charger
references/path-strategy.mdlorsque le comportement des chemins n'est pas clair. - Choisir la plateforme et le mode de déploiement les plus simples correspondants.
- Charger la référence de la plateforme choisie et ajouter uniquement les fichiers de configuration requis par cette plateforme.
- Si le déploiement se fait via Git, vérifier l'état Git et éviter d'inclure des fichiers non liés ou privés.
- Si l'utilisateur a autorisé les actions distantes, pousser ou déployer exactement ce qui a été convenu.
- Après la publication, ouvrir l'URL en direct et vérifier le site déployé dans un navigateur.
Liste de vérification pré-vol
Effectuer ces vérifications avant d'écrire des configurations de déploiement ou de communiquer des paramètres à l'utilisateur :
- Racine de déploiement : choisir le dossier qui contient directement
index.html. - Page d'entrée :
index.htmldoit exister au niveau supérieur de la racine de déploiement. - Aperçu en ouverture directe : l'
index.htmlracine doit conserver CSS, JS, images et navigation lorsqu'il est ouvert directement depuis le système de fichiers, sauf si l'utilisateur a explicitement accepté un comportement serveur uniquement. - HTTP local : servir la racine de déploiement avec
python -m http.serveret confirmer qu'elle fonctionne viahttp://127.0.0.1:<port>/. - Audit statique : exécuter ou recommander
review-static-sitepour les liens, la lisibilité UTF-8, les résidus de placeholders, le rendu navigateur, les résidus de confidentialité et la disposition mobile. - Chemins des ressources : inspecter
href,src,srcset, CSSurl(...), polices, favicons, images de couverture, RSS, sitemap et liens de manifeste. - Données privées : s'assurer que les tokens, les chemins du système de fichiers local, les notes de brouillon, les identités du site source et les secrets personnels ne sont pas publiés.
- Complétude de la sortie : confirmer que les sous-pages, articles, images, polices fournisseurs, ressources KaTeX/mathématiques et médias copiés se trouvent dans la racine de déploiement.
Traiter ces éléments comme des bloqueurs :
- Absence d'
index.htmldans la racine de déploiement. - Chemins de ressources CSS, JS, image, police, RSS, sitemap ou fournisseur locaux cassés.
- Les fichiers source contiennent du mojibake ou un encodage illisible.
- Le site personnel généré contient encore l'identité de la source copiée qui aurait dû être remplacée.
- Des chemins locaux accidentellement absolus à la racine tels que
/assets/...,/posts/...,/data/...ou/images/...subsistent dans un site statique simple généré. - Le site fonctionne uniquement via HTTP local parce que les chemins absolus à la racine sont servis depuis
127.0.0.1, mais l'ouverture directe du fichier ou le déploiement sur un sous-chemin perdrait CSS/JS/images. - Des fichiers sensibles à la vie privée ou des secrets seraient déployés.
- La plateforme déploierait le mauvais dossier.
Choix de la plateforme
Utiliser ce classement par défaut pour les sites personnels statiques simples :
- Intégration Git Cloudflare Pages : meilleure valeur par défaut pour un dossier
site/généré et les mises à jour futures. - GitHub Pages avec GitHub Actions : meilleur lorsque l'utilisateur souhaite tout garder dans GitHub.
- Netlify : hébergement statique simple avec des aperçus conviviaux et des paramètres de tableau de bord.
- Vercel : bon lorsque l'utilisateur utilise déjà Vercel ou pourrait plus tard passer à Next.js, mais pas la valeur par défaut pour du HTML simple.
Règles de décision :
- Si l'utilisateur souhaite le moins de friction et a un dépôt GitHub : intégration Git Cloudflare Pages. Charger
references/cloudflare-pages.md. - Si l'utilisateur souhaite un hébergement uniquement GitHub : GitHub Pages. Charger
references/github-pages.md. - Si les fichiers de déploiement se trouvent dans la racine du dépôt ou dans
/docs: la source de branche GitHub Pages est acceptable. - Si les fichiers de déploiement se trouvent dans
site/,dist/,out/ou un autre dossier personnalisé : préférer GitHub Actions pour GitHub Pages. - Si l'utilisateur souhaite un téléversement manuel aujourd'hui : téléversement direct Cloudflare ou déploiement manuel Netlify.
- Si l'utilisateur a déjà un compte/projet Vercel : utiliser Vercel avec des paramètres explicites de répertoire de sortie.
Sortie statique du framework
Si le site n'est pas en HTML/CSS/JS simple :
- Inspecter
package.json, la configuration du framework et les scripts existants. - Utiliser la commande de build existante du projet ; ne pas inventer de workflows npm.
- Publier le dossier de sortie statique final, pas le dossier source.
- Les sorties courantes incluent
dist,out,build,.output/publicetpublic, selon le framework. - Pour l'export statique Next.js, vérifier que le projet est effectivement configuré pour l'export statique avant de traiter
out/comme sortie finale. - Pour les projets Vue/Vite/Astro, publier le répertoire de sortie configuré après un build réussi.
Si l'utilisateur a demandé une publication statique simple et qu'aucun fichier framework n'existe, ne pas introduire npm.
Politique des fichiers de configuration
Ajouter uniquement les fichiers de configuration correspondant à la plateforme choisie :
- Actions GitHub Pages :
.github/workflows/pages.yml. - Domaine personnalisé GitHub Pages :
CNAMEdans la racine déployée, uniquement lorsque l'utilisateur a fourni le domaine. - Contournement Jekyll GitHub Pages :
.nojekylldans la racine déployée si utile. - Netlify :
netlify.tomluniquement lorsque les paramètres du tableau de bord ne suffisent pas ou que l'utilisateur souhaite une configuration dans Git. - Vercel :
vercel.jsonuniquement lorsque Vercel a besoin de paramètres de sortie explicites. - Cloudflare Pages : généralement, les paramètres du tableau de bord suffisent pour les sites statiques simples.
Ne pas ajouter de configurations de déploiement pour chaque plateforme à la fois.
Sécurité Git et distante
Avant toute action distante, indiquer ce qui va se passer et confirmer que l'utilisateur l'a demandé :
- Création d'un dépôt GitHub.
- Ajout d'un remote.
- Indexation ou validation de fichiers.
- Poussée de commits vers une branche distante.
- Activation de GitHub Pages.
- Création de projets Cloudflare, Netlify ou Vercel.
- Téléversement de fichiers vers un fournisseur d'hébergement.
- Ajout de variables d'environnement.
- Ajout de domaines personnalisés ou modification des enregistrements DNS.
Avant d'indexer ou de pousser :
- Exécuter
git status --short. - Identifier les fichiers de site générés par rapport aux modifications utilisateur non liées.
- Ne pas indexer les modifications non liées.
- Ne pas publier de notes privées, identifiants, chemins locaux, captures d'écran avec secrets ou fichiers temporaires.
Ne jamais placer de secrets, tokens, notes privées ou chemins du système de fichiers locaux dans le site statique ou la configuration de déploiement.
Vérification post-déploiement
Après que la plateforme a signalé une URL en direct :
- Ouvrir l'URL déployée avec un outil navigateur interactif réellement disponible. « Disponible » signifie qu'il est exposé dans la liste des outils appelables du tour actuel. Dans Codex, cela peut être le plugin Navigateur/navigateur intégré à l'application lorsqu'il est acheminé dans le tour.
- Vérifier que la page d'accueil n'est pas une erreur 404, une page blanche ou un listing de répertoire.
- Vérifier que CSS, JavaScript, images, polices, favicon, RSS, sitemap et ressources fournisseurs se chargent depuis le domaine déployé.
- Cliquer sur la navigation principale et au moins une sous-page représentative par type de page.
- Tester les largeurs bureau et mobile.
- Vérifier la console du navigateur pour les ressources manquantes ou les erreurs JavaScript.
- Confirmer les métadonnées, le titre, la description, l'image Open Graph, l'URL canonique, RSS, sitemap et les fichiers robots lorsqu'ils sont présents.
- Si vous utilisez GitHub Project Pages, vérifier spécifiquement les sous-pages et les URL des ressources sous le sous-chemin du dépôt.
- Si vous utilisez un domaine personnalisé, vérifier HTTPS et les redirections entre le domaine nu et
wwwsi configuré.
Si aucun outil navigateur interactif n'est appelable, ne pas prétendre qu'une vérification navigateur en direct a eu lieu. Demander à l'utilisateur d'activer ou d'invoquer l'outil navigateur si la vérification visuelle en direct est importante ; pour Codex, cela peut signifier envoyer une requête qui mentionne explicitement @browser. Si l'utilisateur ne redirige pas ou si le client ne dispose pas d'un tel outil, revenir à Playwright, aux captures d'écran, aux vérifications HTTP ou aux vérifications statiques et préciser la limitation.
Ne pas utiliser par défaut Playwright ou des vérifications en direct par captures d'écran uniquement lorsqu'un outil navigateur interactif est réellement appelable. Utiliser Playwright uniquement comme solution de repli, ou lorsque l'utilisateur demande explicitement des vérifications de déploiement scriptées.
Si le site déployé diffère de l'aperçu local, inspecter le journal de déploiement, le répertoire de sortie et la stratégie de chemin des ressources avant de modifier le code de conception.
Sortie
Garder le rapport final destiné à l'utilisateur concis :
- Plateforme choisie et pourquoi.
- Dossier statique publié ou préparé.
- Mode de déploiement : conseil, configuration préparée, intégration Git, téléversement direct ou déploiement en direct.
- Paramètres utilisés : branche, commande de build, répertoire de base, répertoire de publication/sortie.
- Fichiers de configuration modifiés, le cas échéant.
- URL du guide officiel pour la plateforme choisie.
- URL en direct, si le déploiement a eu lieu.
- Vérification effectuée et toute étape manuelle restante.
Si seul un conseil a été demandé, ne pas prétendre que le site a été déployé. Donner des paramètres de plateforme concrets et des liens vers les guides officiels.