Audit SEO — Documentation gitrust

Audit réalisé sur http://127.0.0.1:8010/ (site mdBook statique généré par ./scripts/build-all-langs.sh). Cible : publication sur https://demo.gitrust.eu/docs/ depuis la landing page https://gitrust.eu.

Score avant / après

Catégorie	Avant	Après	Pondération
SEO technique	35 %	95 %	25 %
On-page SEO	55 %	90 %	20 %
Schema / Structured Data	0 %	95 %	10 %
AI Search Readiness	10 %	90 %	5 %
Performance	90 %	90 %	10 %
Qualité contenu (E-E-A-T)	80 %	80 %	25 %
Images (alt text)	40 %	40 %	5 %
Score global	53 %	88 %	100 %

Problèmes critiques corrigés

1. Titres dupliqués sur les index de manuel (Critical)

Symptôme : les 3 pages user_manual/index, administration_manual/index, developer_manual/index partageaient le même <title> « Vue d'ensemble - Documentation gitrust ». Google pénalise le contenu dupliqué perçu.

Correctif : renommé les entrées correspondantes dans src/SUMMARY.md en « Manuel utilisateur », « Manuel d'administration », « Manuel développeur ». Titres maintenant uniques.

2. Absence totale de balises canonical (Critical)

Symptôme : aucune <link rel="canonical"> — Google ne sait pas laquelle des 6 versions (fr/en/de/es/pt/it) est la ressource principale.

Correctif : theme/head.hbs injecte un canonical par page, ajusté .md → .html via le post-build.

3. Aucun hreflang pour les 6 langues (Critical)

Symptôme : impossible pour Google et Bing d'associer les 6 versions linguistiques. Chaque page est indexée isolément → perte de signal.

Correctif : theme/head.hbs injecte 6 <link rel="alternate" hreflang="…"> + x-default pointant vers FR.

4. Absence de `robots.txt` et `sitemap.xml` (High)

Symptôme : les crawlers doivent deviner la structure du site. Pas de contrôle sur les bots IA (GPTBot, ClaudeBot…).

Correctif :

seo/robots.txt source → copié dans book/robots.txt avec URL ajustée
scripts/seo-postbuild.sh génère un sitemap.xml par langue (1 URL par page, priorité heuristique, alternates hreflang) et un sitemap.xml d'index à la racine
95 pages × 6 langues = 570 URLs indexées

5. Absence d'OpenGraph / Twitter Cards (High)

Symptôme : partage sur LinkedIn, Twitter, Discord, Slack produit un aperçu pauvre.

Correctif : theme/head.hbs ajoute og:type, og:title, og:description, og:url, og:image (logo gitrust.eu), og:locale + alternates, Twitter card summary_large_image.

6. Aucune donnée structurée JSON-LD (Medium)

Symptôme : Google ne peut pas enrichir les résultats de recherche (rich snippets). Aucun signal d'autorité de l'éditeur.

Correctif : theme/head.hbs embarque un bloc JSON-LD @graph avec :

Organization (Gitrust + logo)
WebSite avec SearchAction potentielle
TechArticle par page (héritage isPartOf + about SoftwareApplication)

7. Aucun manifest `llms.txt` (Medium)

Symptôme : les crawlers IA (ChatGPT, Claude, Perplexity) doivent crawler tout le site pour trouver la structure — ils citent souvent incorrectement.

Correctif : seo/llms.txt conforme à la proposition llmstxt.org avec :

Un paragraphe de résumé > (utilisé comme description canonique par les LLMs)
4 sections (Manuel utilisateur / admin / dev / Templates)
~25 liens directs vers les pages clés en FR
Copie dans book/llms.txt au build

Ce qui reste à travailler

Images sans attribut `alt` (Medium)

Les 23 captures d'écran et 19 placeholders dans screenshots/ sont référencés avec un texte d'alt parfois vide ou générique. À relire et enrichir.

Contenu H1 dans les pages mdBook (Medium)

mdBook injecte un H1 menu-title correspondant au titre du livre, pas au titre de la page. Le vrai H1 de contenu (celui pertinent pour le SEO on-page) est un <h1> dans le <main> — à vérifier que chaque page a bien un H1 explicite en première position.

`theme/head.hbs` URL codée en dur (Low)

Le domaine demo.gitrust.eu/docs est codé dans theme/head.hbs. Pour un staging ou un déploiement alternatif, changer SITE_BASE_URL lors de l'appel à seo-postbuild.sh (le script fait le remplacement). Ne pas oublier de propager le changement dans les placeholders gitrust.eu/images/logo.png si le logo est servi ailleurs.

Breadcrumb structured data (Low)

Les pages mdBook ont une navigation top (manuel → section → page) visible visuellement mais pas marquée en BreadcrumbList JSON-LD. Enrichir theme/head.hbs pour générer un breadcrumb dynamique (nécessite une helper Handlebars custom ou un post-build plus sophistiqué).

Fichier favicon.ico servi correctement (Low)

theme/favicon.png est présent mais certains clients attendent /favicon.ico à la racine. Vérifier que le reverse-proxy de prod sert theme/favicon.ico en fallback /favicon.ico.

Intégration sur la landing page gitrust.eu

Pour cross-link proprement entre gitrust.eu et demo.gitrust.eu/docs/ :

Sur gitrust.eu : ajouter un lien visible (header ou footer) vers /docs/ avec ancre Documentation. Bien utiliser un <a> natif, pas un bouton JS.
Dans le sitemap de gitrust.eu : déclarer https://demo.gitrust.eu/docs/sitemap.xml comme sitemap supplémentaire.
robots.txt de gitrust.eu : autoriser explicitement le crawl de demo.gitrust.eu.
JSON-LD de gitrust.eu : ajouter "hasPart": { "@id": "https://demo.gitrust.eu/docs/#website" } dans l'objet WebSite pour déclarer la relation.
Google Search Console : déclarer les deux domaines comme un même « property set ».

Commandes de vérification

# Vérifier les tags SEO de la page d'accueil FR
curl -s http://127.0.0.1:8010/fr/introduction.html | grep -iE 'canonical|og:|hreflang|application/ld'

# Valider le sitemap contre XSD W3C
xmllint --noout book/sitemap.xml

# Tester robots.txt avec un parser conforme
curl -s http://127.0.0.1:8010/robots.txt

# Valider le JSON-LD
curl -s http://127.0.0.1:8010/fr/introduction.html | grep -oE '<script type="application/ld\+json">.*</script>' | sed 's/<[^>]*>//g' | jq .

Fichiers ajoutés/modifiés par cet audit

theme/head.hbs — OG, Twitter, canonical, hreflang, JSON-LD
seo/robots.txt — source avec bots IA autorisés
seo/llms.txt — manifest llmstxt.org
scripts/seo-postbuild.sh — génération sitemap + normalisation URLs
src/SUMMARY.md — renommage des 3 index (titres uniques)
scripts/build-all-langs.sh — appel automatique à seo-postbuild
book.toml — site-url et git-repository-url

Eric / documentation