Docsbook
Aperçu

JSON-LD pour la documentation : types de schéma qui comptent

JSON-LD est des données structurées intégrées dans votre HTML qui indiquent aux moteurs de recherche et aux agents IA quel type de contenu se trouve sur la page. Pour la documentation, les bons types de schéma rendent le type de la page, les étapes, les fils d'Ariane et l'identité du produit lisibles par machine au lieu de les laisser implicites par la mise en page.

Ce post énumère les types de schéma à ajouter, nomme celui dont le résultat enrichi a depuis été restreint par Google, et donne des exemples fonctionnels. Il ne promet pas de classement ni de citation : aucune technique examinée n'a d'effet causal stable et interplateforme sur l'un ou l'autre.

TL;DR#

Schéma Utilisé sur Pourquoi c'est important
TechArticle Pages de tutoriels et d'instructions Indique à Google "c'est un contenu technique"
FAQPage Toute page avec Q&A Paires Q&A lisibles par machine — mais pas de résultat enrichi pour la plupart des sites, voir ci-dessous
HowTo Guides étape par étape Résultats enrichis étape par étape dans Google
SoftwareApplication Page de présentation du produit Tarification, évaluations, OS affichés
Article Articles de blog et annonces Résultats enrichis d'articles standard
BreadcrumbList Chaque page de documentation Fil d'Ariane dans les résultats de recherche
WebSite Racine du site SiteSearchAction active la boîte de recherche Google

Si vous ne faites qu'un, faites TechArticle et BreadcrumbList. Docsbook les ajoute automatiquement.

Pourquoi JSON-LD plutôt que Microdata ou RDFa#

JSON-LD l'emporte parce que :

  1. C'est un bloc <script> séparé, découplé de votre balisage HTML
  2. Google le préfère explicitement ("recommandé" dans leur documentation)
  3. Plus facile à maintenir — changez le schéma sans toucher à la mise en page
  4. Les agents IA l'analysent de manière plus fiable que le balisage en ligne

Microdata et RDFa fonctionnent toujours mais sont considérés comme obsolètes en 2026.

TechArticle : le défaut pour les docs#

Pour la plupart des pages de documentation, TechArticle est le bon schéma :

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "How to authenticate with OAuth",
  "description": "Step-by-step guide to authenticating users with OAuth 2.0",
  "author": {
    "@type": "Organization",
    "name": "Acme",
    "url": "https://acme.com"
  },
  "datePublished": "2026-01-15",
  "dateModified": "2026-03-20",
  "publisher": {
    "@type": "Organization",
    "name": "Acme",
    "logo": {
      "@type": "ImageObject",
      "url": "https://acme.com/logo.png"
    }
  },
  "mainEntityOfPage": "https://docs.acme.com/auth/oauth"
}
</script>

Ce que cela vous apporte :

  • Google signale la page comme un contenu technique autoritaire
  • Les agents IA ont tendance à pondérer les pages étiquetées TechArticle plus haut dans les citations
  • dateModified indique aux robots d'exploration que la page est récente

FAQPage : extraits enrichis or#

Si votre page a une structure Q&A, FAQPage le schéma permet à Google d'afficher ces Q&A directement dans les résultats de recherche.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "How do I revoke an API key?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Open the dashboard, navigate to API Keys, find the key, click Revoke. Revocation is immediate."
    }
  }, {
    "@type": "Question",
    "name": "Can I have multiple API keys?",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Yes. Replace this answer with the real limit from your own product."
    }
  }]
}
</script>

Le balisage FAQPage produit-il toujours un résultat enrichi dans Google?#

Pour presque tous les sites de documentation, non. Google a restreint le résultat enrichi FAQ en 2023, et sa propre documentation indique maintenant que la fonctionnalité "n'est affichée que pour les sites gouvernementaux et de santé bien connus et autorisés" (Google Search Central, données structurées FAQPage, lu le 2026-09-03). Tout guide promettant un accroissement des clics grâce aux extraits FAQ sur un site de documentation produit décrit le monde d'avant 2023.

Cela ne constitue pas une raison pour supprimer le balisage. FAQPage fait toujours une chose bien : il indique, sous une forme qu'un analyseur ne peut pas mal interpréter, que ce bloc est une question et que ce bloc est sa réponse. Gardez-le là où la page est réellement une liste de questions et réponses, et n'attendez aucun changement visuel dans Google.

Comment faire : guides étape par étape#

Si vous avez un guide étape par étape numéroté, utilisez HowTo :

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Set up a custom domain for documentation",
  "step": [{
    "@type": "HowToStep",
    "text": "Open the dashboard and go to Settings → Domain"
  }, {
    "@type": "HowToStep",
    "text": "Enter your subdomain (docs.yourcompany.com)"
  }, {
    "@type": "HowToStep",
    "text": "Add a CNAME record in DNS pointing to cname.vercel-dns.com"
  }, {
    "@type": "HowToStep",
    "text": "Wait for SSL to provision (under 5 minutes)"
  }]
}
</script>

Résultat : Google peut afficher des résultats enrichis étape par étape avec chaque étape développée.

ApplicationLogiciel : page produit#

Votre page de présentation du produit doit être étiquetée comme SoftwareApplication :

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Acme",
  "applicationCategory": "DeveloperApplication",
  "operatingSystem": "Web",
  "offers": {
    "@type": "Offer",
    "price": "150",
    "priceCurrency": "USD"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "ratingCount": "247"
  }
}
</script>

Cela fait apparaître les prix et les évaluations dans les résultats enrichis de Google. Soyez honnête sur les évaluations — Google pénalise les aggregateRating gonflés.

BreadcrumbList : chaque page#

Chaque page devrait avoir des fils d'Ariane en JSON-LD. Google les affiche dans les résultats de recherche, les agents IA les utilisent pour comprendre la hiérarchie :

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{
    "@type": "ListItem",
    "position": 1,
    "name": "Docs",
    "item": "https://docs.acme.com"
  }, {
    "@type": "ListItem",
    "position": 2,
    "name": "Authentication",
    "item": "https://docs.acme.com/auth"
  }, {
    "@type": "ListItem",
    "position": 3,
    "name": "OAuth",
    "item": "https://docs.acme.com/auth/oauth"
  }]
}
</script>

Sur votre page d'accueil, déclarez la recherche sur le site :

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "url": "https://docs.acme.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://docs.acme.com/search?q={search_term_string}",
    "query-input": "required name=search_term_string"
  }
}
</script>

Cela déverrouille la boîte de recherche directement sous votre résultat dans Google.

Plusieurs schémas sur une page#

Vous pouvez empiler des schémas. Une page doc peut avoir :

  • TechArticle pour le type de contenu
  • BreadcrumbList pour la navigation
  • FAQPage s'il y a une section Q&A

Les trois dans trois blocs <script type="application/ld+json"> séparés. Google les lit tous.

Ce que les agents IA font avec JSON-LD#

Trois comportements observés :

  1. Filtrage par type — les agents à la recherche de tutoriels préfèrent TechArticle et HowTo par rapport à Article
  2. Raccourcis d'extraction — le schéma FAQPage est extrait presque textuellement
  3. Signaux de confiance — les schémas avec Organization et publisher appropriés sont pondérés plus haut

Comment Docsbook expédie JSON-LD#

Docsbook ajoute automatiquement :

  • TechArticle à chaque page de documentation
  • BreadcrumbList à chaque page
  • FAQPage aux pages où il détecte des modèles de questions-réponses
  • SoftwareApplication à votre page d'accueil si des métadonnées sont fournies
  • WebSite avec SearchAction à la racine du site

Aucune configuration. Le schéma est construit à partir de votre markdown et frontmatter existants.

Validation#

Deux outils :

  • Google Rich Results Test — https://search.google.com/test/rich-results
  • Schema.org validator — https://validator.schema.org/

Exécutez les deux sur vos pages de documentation. Corrigez les avertissements. Les erreurs sont bloquantes ; les avertissements ne le sont pas.

Docsbook ajoute automatiquement JSON-LD sur chaque page. Publiez vos docs →

Updated

Cette page vous a-t-elle été utile ?

Propulsé par Docsbook