Révision SEO HTML
Vue d'ensemble
Produisez une liste exploitable de résultats classés par sévérité pour un ou plusieurs fichiers HTML statiques. Cette compétence intègre un analyseur HTML basé uniquement sur la bibliothèque standard Python qui extrait chaque signal pertinent pour le SEO dans un document JSON unique, une grille d'évaluation complète et un modèle de rapport de résultats — ensemble, ils permettent à un audit de produire une sortie prévisible à chaque fois.
Quand l'utiliser
À utiliser lorsque l'entrée est un ou plusieurs fichiers .html statiques (ou un répertoire les contenant) et que l'utilisateur souhaite des constats SEO on-page exploitables. Les déclencheurs incluent « révision SEO », « audit SEO », « vérifier le SEO de ce HTML », « examiner les balises meta de cette page », « auditer le SEO on-page ».
Ne pas utiliser lorsque :
- L'artefact est le source d'un générateur de site statique (Jekyll/Hugo/Astro/Eleventy/Next.js). Ceux-ci nécessitent une révision tenant compte de leur source ; à reporter vers une future compétence
ssg-seo-review. - L'utilisateur souhaite des métriques de performance live (LCP, CLS, INP). Le HTML seul ne peut pas les produire ; recommandez Lighthouse ou PageSpeed Insights.
- L'utilisateur souhaite une analyse des backlinks, de l'autorité de domaine ou d'autres facteurs off-page. Cela nécessite des outils tiers (Ahrefs, SEMrush, etc.).
Flux de travail
1. Extraire les signaux
Exécutez l'analyseur sur la cible. Il accepte un fichier unique ou un répertoire (récursif *.html) :
python3 scripts/extract_seo_signals.py <chemin> --pretty
La sortie est un document JSON avec les clés de premier niveau suivantes : lang, title, meta, links, scripts, headings, images, links_audit, body_word_count. Chaque élément porte un numéro de line pour citation dans les constats.
Pour un répertoire, la sortie est {"files": [<objet par fichier>]}.
Le script utilise uniquement la bibliothèque standard de Python — pas de pip install requis. Si l'analyse échoue sur un fichier spécifique, le résultat pour ce fichier contient un champ error et l'audit continue pour les autres.
2. Mapper les signaux à la grille d'évaluation
Chargez references/seo-checklist.md. Parcourez chaque section dans l'ordre et vérifiez le chemin JSON correspondant. La grille d'évaluation liste explicitement le chemin à inspecter pour chaque vérification (par exemple, images.missing_alt, meta.description.length, scripts.render_blocking_candidates).
Pour chaque vérification échouée, enregistrez :
- La sévérité (P0/P1/P2/P3) de la grille.
- Le numéro de ligne de la sortie JSON.
- La valeur de balise ou d'attribut citée exacte du fichier (relisez le fichier avec le numéro de ligne pour citer textuellement — ne paraphrasez jamais).
- La correction, rédigée sous forme de diff concret avant/après lorsque la modification est mécanique.
3. Vérifier chaque constat avant de le rapporter
Avant de rédiger un constat, confirmez le problème mécaniquement :
- Une affirmation selon laquelle un attribut est « manquant » doit provenir de la sortie structurée de l'analyseur, pas d'une lecture superficielle du HTML.
- Une affirmation selon laquelle une valeur est « trop courte/longue » doit citer le nombre réel de caractères du JSON.
- Le balisage cité doit être exact ; si une citation ne peut pas être reproduite caractère par caractère à partir du fichier, abandonnez-la.
Cela protège contre l'échec le plus courant des révisions : inventer un problème qui n'existe pas vraiment.
4. Produire le rapport de constats
Utilisez assets/findings-template.md comme structure. Remplissez :
- Paragraphe de résumé avec le verdict global et les décomptes par sévérité.
- Un bloc par constat, trié par sévérité (P0 → P3) puis par ordre de fichier.
- Une section facultative « Gains rapides » lorsque le nombre de constats dépasse ~10 — sélectionnez les 3 à 5 corrections à plus fort impact.
- Une section « Éléments hors périmètre notés » listant tout ce pour quoi l'utilisateur devrait utiliser des outils externes (Lighthouse pour les CWV réels, curl pour la résolution canonique, etc.).
Si l'audit couvre plusieurs fichiers, produisez un rapport unique les couvrant tous, avec les constats groupés par fichier sous chaque niveau de sévérité — pas un rapport par fichier.
5. Passer élégamment
Si une vérification nécessite des informations que l'analyseur ne peut pas produire (par exemple, « cette URL canonique renvoie-t-elle un 200 ? »), ne devinez pas. Notez-la dans la section « Éléments hors périmètre » du rapport et passez à la suite.
Référence
scripts/extract_seo_signals.py— Analyseur HTML. Bibliothèque standard uniquement. Produit du JSON structuré avec numéros de ligne.references/seo-checklist.md— Grille d'évaluation complète, organisée par catégorie, avec niveaux de sévérité et chemins JSON pour chaque vérification.assets/findings-template.md— Format de sortie pour le rapport d'audit.