SEO Astro

Que fait SEO Astro ?

Audite et améliore la configuration SEO d'un site Astro en s'appuyant sur la pile complète décrite dans Astro SEO : le guide complet. Cette compétence couvre neuf domaines — fondations techniques, données structurées, contenu, structure du site, performances, sitemaps et indexation, découverte par les agents, redirections et analyses — et génère du code prêt à l'emploi pour tout ce qui est manquant ou faible.

L'épine dorsale de cette compétence est @jdevalk/astro-seo-graph. La plupart des correctifs passent par elle. Si le projet ne l'utilise pas encore, son installation est la première recommandation.

Les recettes de code se trouvent dans AGENTS.md — lisez-le lorsque vous devez implémenter un correctif spécifique. Ce fichier contient le flux de travail et la liste de contrôle d'audit.

Flux de travail

1. Détecter le projet — confirmer qu'il s'agit d'un site Astro et comprendre sa structure.
2. Auditer — noter neuf catégories et produire des conclusions exploitables.
3. Améliorer — générer ou modifier des fichiers pour combler les lacunes. Les recettes se trouvent dans AGENTS.md.
4. Passage des métadonnées — invoquer metadata-check sur chaque chaîne courte générée par la compétence (titres, descriptions, champs description de schéma, réponses FAQ, extraits de frontmatter).
5. Vérifier — exécuter la build, vérifier que les validations réussissent, rappeler à l'utilisateur les tâches non liées aux fichiers (Search Console, Bing Webmaster Tools, vérification de la clé IndexNow).

---

Phase 0 : Détecter le projet

Confirmer les bases avant d'auditer :

• astro.config.mjs / astro.config.ts existe.
• package.json a astro comme dépendance.
• site: est défini dans astro.config — les URLs canoniques, les sitemaps et les URLs d'images OG en dérivent tous. S'il est manquant, vide ou http://localhost, le signaler comme un problème bloquant avant toute autre chose. C'est la configuration erronée la plus courante.
• Collections de contenu dans src/content/ (ou src/pages/ markdown hérité).
• Cible de déploiement — lire package.json, vercel.json, netlify.toml, wrangler.toml ou public/_headers pour déterminer l'hôte. Cela détermine la syntaxe des redirections et des en-têtes dans la phase 2.
• @jdevalk/astro-seo-graph est-il déjà installé ? Si oui, enregistrer la version et les fonctionnalités connectées (rechercher <Seo, seoGraph(, createSchemaEndpoint, createSchemaMap, FuzzyRedirect, createIndexNowKeyRoute, createMarkdownEndpoint, createApiCatalog, gitLastmod). Vérifier la version installée par rapport à la dernière version sur npm avec npm view @jdevalk/astro-seo-graph version. Si le projet est en retard, recommander une mise à niveau dans la phase 2 avant d'auditer les lacunes fonctionnelles — le package publie régulièrement de nouvelles valeurs par défaut et des correctifs, et une version obsolète est une cause plausible de tout résultat d'audit. La phase 2 bifurque en fonction de cela.
• Le site est-il multilingue ? Vérifier la présence de i18n dans astro.config ou de plusieurs répertoires de locale sous src/content/. Si oui, hreflang est important ; sinon, l'ignorer.

Ne demander que ce que vous ne pouvez pas détecter. Ne pas demander à l'utilisateur de quoi parle le site — lire astro.config.mjs et le contenu de la page d'accueil.

---

Phase 1 : Audit

Noter chaque catégorie sur 10. Pour chacune, donner 2 à 4 conclusions spécifiques qui citent le code ou la configuration réelle. Au sein de chaque catégorie, les vérifications sont hiérarchisées :

• Obligatoire — bloqueurs de publication. Un écheco ici cause une régression SEO visible.
• Recommandé — pratique standard. Sauter coûte de la portée.
• Accessoire — orienté vers l'avenir ou situationnel. Utile mais pas fondamental pour tous les sites.

Ignorer les vérifications Accessoire pour les petits blogs personnels, sauf si l'utilisateur demande le traitement complet.

1. Composant <Seo> et métadonnées d'en-tête (/10)

• Obligatoire — un seul composant pour toutes les métadonnées d'en-tête (pas dispersées entre plusieurs layouts).
• Obligatoire — site: dans astro.config est défini sur l'origine de production.
• Obligatoire — URLs canoniques dérivées de la configuration site avec les paramètres de suivi supprimés.
• Obligatoire — canonical omis lorsque noindex est vrai (selon la recommandation de Google).
• Obligatoire — chaîne de secours pour les champs SEO manquants : seo.title → title → siteName ; seo.description → excerpt → premier paragraphe. Les pages avec des titres ou descriptions vides sont le symptôme le plus courant d'une chaîne de secours défaillante.
• Recommandé — la méta robots inclut max-snippet:-1, max-image-preview:large, max-video-preview:-1.
• Recommandé — balises Twitter supprimées lorsqu'elles dupliquent Open Graph (Twitter utilise automatiquement le fallback).
• Recommandé — alternatives hreflang présentes sur les sites multilingues. Ignorer si monolingue.
• Accessoire — utilise le composant <Seo> de @jdevalk/astro-seo-graph plutôt qu'un composant fait maison. (Un composant fait maison qui couvre tout ce qui précède est acceptable ; cette compétence encourage le package car il gère la chaîne de secours et les règles robots par défaut.)

2. Données structurées / graphe JSON-LD (/10)

• Un objet Article plat unique, ou un @graph lié avec plusieurs entités ?
• Entités connectées avec des références @id ?
• WebSite, Blog/WebPage, Person/Organization, BlogPosting/Article, BreadcrumbList, ImageObject tous présents là où c'est pertinent ?
• Signaux de confiance : publishingPrinciples, copyrightHolder, copyrightYear, knowsAbout, SearchAction ?
• Valide dans le Test des résultats enrichis et ClassySchema ?

3. Collections de contenu et schéma SEO (/10)

• Collections de contenu définies avec des schémas Zod ?
• seoSchema de @jdevalk/astro-seo-graph appliquant les longueurs de titre (5–120) et de description (15–160) ?
• Champs obligatoires (publishDate, title, excerpt) appliqués au moment de la build ?
• articleBody (avec Markdown supprimé) exposé dans les terminaisons de schéma (jusqu'à 10K caractères) ?

4. Images Open Graph (/10)

• Chaque page a une image OG, ou beaucoup sont manquantes ?
• 1 200 × 675 (Google Discover minimum 1 200 px de large, ratio 16:9) ?
• Générée au moment de la build via satori + sharp, ou manuelle ?
• JPEG (les plateformes sociales ne prennent pas en charge WebP/AVIF de manière fiable) ?
• La route dérive l'URL OG du slug automatiquement ?
• Chaque <img> dans le HTML rendu a un attribut alt (ou alt="" / role="presentation" pour les images décoratives) ? validateImageAlt sur seoGraph() détecte cela au moment de la build en ≥ 1.1.0.

5. Sitemaps et indexation (/10)

• Obligatoire — @astrojs/sitemap installé, index du sitemap accessible.
• Obligatoire — robots.txt référence l'index du sitemap.
• Obligatoire — Flux RSS existant (@astrojs/rss), annoncé via <link rel="alternate" type="application/rss+xml">, contient le contenu complet des articles (pas des extraits tronqués).
• Recommandé — divisé par collection via l'option chunks (sitemap-posts-0.xml, etc.) — beaucoup plus facile à déboguer l'indexation dans GSC.
• Recommandé — lastmod renseigné à partir des horodatages des commits git, pas des dates de frontmatter ou des horodatages de fichiers CI. @jdevalk/astro-seo-graph ≥ 1.4.0 exporte gitLastmod(filePath, { excludeCommits, depth }) pour cela — il retourne la date du commiteur du commit non exclu le plus récent qui a touché le fichier, ou null si git est indisponible. Le connecter dans le callback serialize du sitemap. Si la base de code a un helper execSync('git log ...') fait maison, le remplacer par l'export du package — l'export gère l'exclusion des commits en masse (imports, reformatages) qu'une recherche naïve -1 ne peut pas.
• Recommandé — IndexNow intégré et soumettant à chaque build, avec une route de vérification de clé à /[key].txt. ≥ 1.0.1 exclut /404 des soumissions par défaut. Limiter la soumission à l'hôte de production (par ex. process.env.CF_PAGES === '1' && CF_PAGES_BRANCH === 'main', VERCEL_ENV === 'production', CONTEXT === 'production'). Une soumission inconditionnelle envoie une requête à la terminaison à chaque npm run build local et déploiement de prévisualisation avec des URLs que l'hôte de production n'a pas encore servies, ce qui rend la clé invalide (403) et force une rotation.

6. Découverte par les agents (/10)

• Recommandé — terminaisons de schéma (/schema/*.json) exposant du JSON-LD à l'échelle du corpus.
• Recommandé — carte de schéma (/schemamap.xml) listant toutes les terminaisons, avec la directive Schemamap: dans robots.txt.
• Recommandé — llms.txt à la racine du site listant les pages (titre + description) pour les consommateurs LLM. @jdevalk/astro-seo-graph ≥ 0.9.0 génère cela via l'option d'intégration llmsTxt.
• Recommandé — URLs alternatives en Markdown (/blog/post.md à côté de /blog/post/) servant du Markdown propre avec un frontmatter YAML pour que les agents IA puissent le consommer sans analyse HTML. @jdevalk/astro-seo-graph ≥ 1.2.0 fournit createMarkdownEndpoint pour la route et une option d'intégration markdownAlternate: true qui émet <link rel="alternate" type="text/markdown"> sur chaque page. ≥ 1.3.0 ajoute une vérification post-build : l'intégration parcourt la sortie de la build et supprime tout lien dont la cible .md n'est pas sur le disque (avec un warn par occurrence) — ainsi une terminaison mal configurée apparaît comme un avertissement de build au lieu d'une 404 en production. À associer avec une règle de transformation Cloudflare (réécriture d'URL via wildcard_replace, pas d'en-tête Vary: Accept — CF supprime les valeurs Vary personnalisées) pour la négociation de contenu sur Accept: text/markdown sans avoir besoin de SSR.
• Recommandé — catalogue d'API à /.well-known/api-catalog selon RFC 9727. @jdevalk/astro-seo-graph ≥ 1.4.0 fournit createApiCatalog, qui type automatiquement les terminaisons de schéma vers leurs URLs https://schema.org/<Type> et absolutise les chemins par rapport à siteUrl. Lister les terminaisons de schéma, la carte de schéma et toute API spécifique au site (/ask, /feed.xml, etc.). La RFC est finalisée donc le format est stable ; l'adoption est précoce mais le coût est un fichier de route.
• Recommandé — directive Content Signals dans robots.txt (par ex. Content-Signal: ai-train=yes, search=yes, ai-input=yes). Déclare les préférences pour l'entraînement IA, l'ancrage de la recherche et l'utilisation en entrée IA indépendamment de l'accès par crawling. La spécification est un brouillon IETF et l'adoption est précoce, mais c'est une ligne dans un fichier que chaque site possède déjà.
• Recommandé — en-tête Link sur /* pointant vers les fichiers de découverte (sitemap, llms.txt, api-catalog, schemamap, et toutes les cartes MCP / A2A que le site publie). Les agents lisant les en-têtes de réponse les trouvent sans analyser le HTML. Sur Cloudflare Pages / Netlify, c'est public/_headers ; sur Vercel, c'est vercel.json.
• Accessoire — carte de serveur MCP à /.well-known/mcp/server-card.json (SEP-1649) et/ou carte d'agent A2A à /.well-known/agent-card.json (protocole A2A). Pertinent uniquement lorsque le site expose réellement un serveur MCP ou un agent A2A. Les deux sont des fichiers JSON statiques déclarant la terminaison, les capacités et les compétences. Ignorer sinon.
• Accessoire — <link rel="nlweb"> pointant vers une terminaison conversationnelle. NLWeb est précoce ; la balise est une ligne et vaut la peine d'être présente, mais ce n'est pas un facteur de notation en 2026.
• Accessoire — Catalogue ARD (Agentic Resource Discovery) à /.well-known/ai-catalog.json, listant ce que le domaine offre (serveur MCP, agent A2A, bundle OKF, API spécifiques au site). Brouillon v0.9, donc facultatif — mais c'est la couche de découverte par laquelle les cartes MCP / A2A et le bundle OKF sont rentabilisés. Deux pièges : la spécification de base (Agent-Card/ai-catalog) nomme le champ du type de média mediaType tandis que la couche ARD (ards-project/ard-spec) le nomme type — émettre les deux clés avec la même valeur pour que l'entrée soit valide sous l'une ou l'autre lecture (les deux spécifications exigent que les consommateurs ignorent les clés inconnues). ARD ajoute également un tableau facultatif representativeQueries d'exemples de requêtes par entrée.
• Accessoire — Bundle OKF (Open Knowledge Format) : une arborescence de fichiers Markdown typés (un par page, chemins reflétant les URL canoniques) empaquetée sous forme d'un seul .tar.gz, avec des fichiers d'index entre les deux. Le service et la découverte sont explicitement des non-objectifs d'OKF — c'est à cela que sert l'entrée du catalogue ARD. Brouillon v0.9, facultatif. Il n'y a pas encore de type de média enregistré, donc la chaîne provisoire est application/okf-bundle+gzip (suivi dans knowledge-catalog#111 et ard-spec#27) ; la marquer comme provisoire, elle peut changer. Il est préférable de la générer comme une sortie supplémentaire d'un pipeline de contenu existant plutôt que comme une copie maintenue à la main.

7. Performances (/10)

• Sortie statique par défaut (pas de SSR sur les pages qui n'en ont pas besoin) ?
• Zéro JavaScript côté client sauf si une île l'exige ?
• Composant <Image> d'Astro utilisé pour toutes les images de contenu (srcset responsive, WebP, chargement différé, asynchrone) ?
• Police web principale préchargée en woff2 ?
• <ClientRouter /> avec defaultStrategy: 'viewport' pour la prélecture ?
• Actifs hachés sous /_astro/ servent-ils Cache-Control: public, max-age=31536000, immutable ?
• En-tête de réponse No-Vary-Search supprimant les paramètres UTM de la clé de cache ?

8. Redirections et gestion des erreurs (/10)

• public/_redirects (ou équivalent) maintenu pour chaque URL qui a jamais existé et a été déplacée ?
• 301 et non 302 pour les déplacements permanents ?
• Composant FuzzyRedirect de @jdevalk/astro-seo-graph connecté à la page 404 ?
• La page 404 elle-même renvoie un statut 404, pas 200 ?

9. Validation au moment de la build et qualité du contenu (/10)

• Obligatoire — Intégration seoGraph() exécutée à chaque build avec validateH1 et validateUniqueMetadata activés. Pour la validation JSON-LD, passer warnOnDanglingReferences: true à assembleGraph() dans seo-graph-core — c'est la vérification au moment de l'assemblage, pas une option d'intégration.
• Recommandé — validateImageAlt, validateMetadataLength et validateInternalLinks activés sur seoGraph() (tous true par défaut en ≥ 1.1.0). Ils détectent le texte alternatif manquant, les titres ou descriptions en dehors des limites SERP (valeurs par défaut : titre 30–65, description 70–200) et les liens internes qui génèrent une 404 ou rencontrent une incohérence de barre oblique finale. Mettre à niveau vers ≥ 1.1.1 si le projet est sur 1.1.0 — cette version corrective corrige deux bogues de validation : validateInternalLinks reconnaît désormais les actifs public/ comme des cibles valides (plus de faux positifs sur /images/* ou /fonts/*), et validateMetadataLength ne tronque plus les descriptions contenant des points de code multi-octets.
• Accessoire — validateTitleCase (si disponible) pour la cohérence de la casse du titre du site.
• Accessoire — Vérificateur de liens externes dans le pipeline de build (par ex., avec linkinator ou broken-link-checker). Utile pour les sites qui citent beaucoup de sources externes ; coûteux sur les grands sites.

Notation de l'audit

• 9–10 : Excellent à parfait. Pas d'action requise sauf pour les accessoires manquants si l'utilisateur les souhaite.
• 6–8 : Correct à bien. Quelques lacunes à combler.
• 3–5 : Faible. Plusieurs domaines doivent être améliorés.
• 0–2 : Critique. Des problèmes fondamentaux doivent être résolus immédiatement.

Pour toute note inférieure à 6 dans une catégorie, générer le code de correction dans l'étape suivante.

---

Phase 2 : Améliorer

Pour chaque catégorie notée en dessous de 9, implémenter les correctifs. Les recettes de code détaillées pour chaque correctif se trouvent dans AGENTS.md – lire ce fichier pour la syntaxe exacte de la configuration, des composants et des routes.

La stratégie a trois branches selon l'utilisation du package :

1. Projet n'utilisant pas le package : Installer @jdevalk/astro-seo-graph. C'est une dépendance npm. Ensuite, mettre en place les fonctionnalités une par une en utilisant les recettes de AGENTS.md.
2. Projet utilisant une version ancienne : Mettre à niveau. Vérifier la version par rapport à npm. Ensuite, procéder comme en 1 pour les fonctionnalités manquantes.
3. Projet avec le package et certaines fonctionnalités : Ajouter les fonctionnalités manquantes.

Ordre des opérations à haut niveau

1. Installer / mettre à niveau @jdevalk/astro-seo-graph (si ce n'est pas encore fait).
2. Configurer l'intégration.
3. Mettre en place le composant <Seo> avec la chaîne de secours et les règles robots.
4. Connecter les terminaisons de schéma.
5. Générer les images OG.
6. Mettre en place la carte de schéma, llms.txt, et les routes de découverte.
7. Connecter IndexNow.
8. Connecter les redirections floues.
9. Ajouter les validateurs de build.
10. Implémenter les fonctionnalités accessoires si l'utilisateur les souhaite.

---

Phase 3 : Passage des métadonnées

Invoquer metadata-check sur chaque chaîne courte que la compétence a générée (titres, descriptions, champs description de schéma, réponses FAQ, extraits de frontmatter). Cela valide la longueur, la lisibilité, la duplication et la détection de vidage.

---

Phase 4 : Vérifier

• Exécuter npm run build (ou la commande de build du projet).
• Résoudre toute erreur de validation de build.
• Confirmer que le sitemap, les terminaisons de schéma et le flux RSS sont accessibles (les endpoints de prévisualisation suffisent).
• Rappeler à l'utilisateur les tâches qui ne peuvent pas être automatisées :
  • Ajouter la propriété du site à Google Search Console, Bing Webmaster Tools (et vérifier la clé IndexNow), Yandex Webmaster si pertinent.
  • Vérifier manuellement les données structurées avec le Test des résultats enrichis après le déploiement.
  • Vérifier le certificat HTTPS et les en-têtes de sécurité.
  • Configurer les analyses (par ex., Plausible, Fathom, Google Analytics) si ce n'est pas déjà fait.
  • Configurer le suivi des classements (par ex., Wincher, Ahrefs).

---

Glossaire des termes liés au package (que vous pourriez rencontrer lors de l'utilisation du package)

• <Seo> — composant qui rend les métadonnées d'en-tête, les balises OG, les balises Twitter et les balises de schéma. Centralise tout le rendu head. Appelé avec un objet seo qui a title, description, canonical, noindex, nofollow, ogImage, etc.
• seoGraph — la fonction d'intégration Astro. L'épine dorsale de la configuration. Ajoutée à astro.config.mjs sous integrations: [seoGraph({...})]. Accepte des options pour le schéma, l'image OG, la carte de schéma, llms.txt, les validateurs, etc.
• seoSchema — un schéma Zod pour les collections de contenu. Applique les contraintes de longueur et les champs obligatoires pour les métadonnées SEO dans les collections.
• createSchemaEndpoint — crée une route d'API qui sert les données structurées JSON-LD pour une collection spécifique. Généralement une route [...slug].json.ts.
• createSchemaMap — crée la carte de schéma (/schemamap.xml) listant toutes les terminaisons de schéma disponibles.
• createIndexNowKeyRoute — crée la route /[key].txt pour la vérification de la propriété IndexNow.
• createMarkdownEndpoint — crée une route qui sert le contenu en Markdown brut avec le frontmatter YAML. Avec markdownAlternate: true dans l'intégration, les pages HTML incluent automatiquement <link rel="alternate" type="text/markdown">.
• FuzzyRedirect — un composant pour la page 404 qui essaie de faire correspondre l'URL demandée avec des articles ou pages existants, et redirige vers la correspondance la plus proche.
• createApiCatalog — crée /.well-known/api-catalog listant les terminaisons d'API et leurs types selon RFC 9727.
• gitLastmod — une fonction utilitaire qui extrait la date du dernier commit pour un fichier donné à partir de l'historique git. Utilisée pour renseigner lastmod dans le sitemap.
• llmsTxt — option d'intégration qui génère llms.txt à la racine du site, listant le contenu pour les consommateurs LLM.
• Content-Signal — une directive robots.txt déclarant les préférences pour l'utilisation du contenu par l'IA (entraînement, ancrage de la recherche, entrée IA), indépendante de l'accès par crawling.
• No-Vary-Search — un en-tête de réponse qui supprime les paramètres de requête spécifiés de la clé de cache d'un agent utilisateur, empêchant les caches de créer des entrées distinctes pour les URLs avec et sans paramètres UTM.
• knowledgeGraph — un objet (potentiellement avec des champs @context, @graph, siteUrl, etc.) utilisé pour construire des références @id pour le graphe de connaissances. Généralement construit avec assembleGraph() et passé aux composants.
• assembleGraph — une fonction utilitaire qui assemble un graphe JSON-LD à partir de parties, avec une vérification optionnelle des références pendantes.

---

Règles critiques

1. Ne jamais modifier le contenu éditorial (les articles de blog, les descriptions de page, etc.). Se concentrer sur la configuration, la structure du site et les métadonnées.
2. Utiliser le fichier AGENTS.md pour les recettes de code. Ce fichier contient la syntaxe exacte pour chaque mise en place. Si AGENTS.md est manquant ou incomplet, demander au package source.
3. Vérifier que site: est présent et correct avant toute chose. C'est la cause numéro un des problèmes SEO sur Astro.
4. Pour tout ce qui concerne les métadonnées, invoquer metadata-check sur les chaînes générées.
5. Ne pas deviner ou réinventer. Utiliser les outils et fonctions du package. Si le package ne peut pas faire quelque chose, ne pas le faire — ou le signaler comme une limitation.
6. Rester dans les limites du projet. Ne pas ajouter de fichiers inutiles. Ne pas modifier les composants existants sauf si l'audit le demande et que la modification est claire.
7. Toujours vérifier le résultat. Exécuter la build et confirmer le succès.
8. Ne pas configurer les analyses. Ce n'est pas du SEO. Signaler qu'elles doivent être configurées.
9. Ne pas configurer les certificats HTTPS ou les en-têtes de sécurité. Signaler qu'ils doivent être configurés.
10. Ne pas configurer les redirections pour des pages qui n'existent pas. Se concentrer sur la structure existante.
11. Préférer les chemins relatifs dans la configuration et les routes lorsque cela est possible.
12. Si le site a un favicon, un manifeste ou un fichier browserconfig.xml, s'assurer qu'ils sont correctement liés dans l'en-tête du site. Sinon, le signaler.
13. Si le site a des pages de connexion, de profil ou de tableau de bord, ne pas les indexer. Utiliser noindex dans les métadonnées SEO de ces pages. (S'applique uniquement si l'audit est effectué sur un site qui a de telles pages. En règle générale : ne pas indexer une page qu'un utilisateur ne partagerait pas en public.
14. L'utilisateur est un développeur. Utiliser un langage précis et technique. Donner les extraits de code, les noms de fichiers, et les options de configuration explicitement.