Réponses structurées

Docsbook écrit un élément <script type="application/ld+json"> par page de documentation. Il contient un @graph schema.org — un tableau unique d’objets liés — plutôt que plusieurs balises script distinctes, afin que chaque objet de la page partage un même contexte et puisse référencer les autres par @id.

Cette page décrit exactement ce qui est inclus dans ce graphe, ce qui doit être vrai dans votre Markdown pour que chaque objet apparaisse, et à quoi ressemble un échec.

Que contient le graphe et qu’est-ce qui l’active#

SoftwareApplication ne fait pas partie de ce graphe. Docsbook le génère sur ses propres pages marketing, et non dans la documentation client — si vous avez lu une comparaison avec un concurrent affirmant le contraire à notre sujet, c’est là que ce type se trouve réellement.

Les dates proviennent de l’historique Git du fichier, et non du front matter : datePublished et dateModified sont lus dans le dernier commit ayant modifié ce fichier. Une page ne possédant encore aucun historique de commits ne contient aucune des deux clés, plutôt qu’une date inventée.

Quelle structure Markdown produit un FAQPage ?#

Une section devient une liste de questions lorsqu’une des conditions suivantes est remplie :

1. Un H2 dont le texte correspond à FAQ, Frequently asked questions, ou au russe Частые вопросы / Вопросы и ответы / Часто задаваемые — sans tenir compte de la casse. Chaque H3 qui le suit devient une question, qu’il se termine ou non par un point d’interrogation.
2. Tout H3 se terminant par ?, où qu’il se trouve dans le document, quelle que soit la section dans laquelle il se situe.

La réponse correspond à chaque ligne non vide située entre ce H3 et le titre suivant. Les *, _ inline et les caractères backtick sont supprimés. Les marqueurs de widget de contenu (<!-- widget:accordion --> et son marqueur de fermeture) sont ignorés plutôt qu’intégrés à la réponse, car un accordéon est généralement utilisé pour rédiger une FAQ.

Les limites s’appliquent ensuite, dans cet ordre : un ? final est ajouté à chaque question qui n’en possède pas ; chaque réponse est limitée à 1 000 caractères ; une paire est supprimée si la question comporte 3 caractères ou moins ou si la réponse en comporte 10 ou moins ; et la page conserve au maximum 20 questions.

## FAQ
 
### Does a custom domain change my page URLs
 
Yes. Every canonical URL, sitemap entry and breadcrumb item moves to the new host on the next render.
 
### How long does the certificate take
 
Usually under a minute after the CNAME resolves.

Un H3 qui n’est pas une question et qui ne se trouve pas dans une section FAQ ne produit rien. ### Install the CLI sous ## Setup est correctement ignoré.

Quelle structure Markdown produit un HowTo ?#

Trois conditions doivent être réunies :

1. Un H1, H2 ou H3 commençant par How to — ou par le russe Как, dont le caractère suivant ne doit pas être une lettre ou un chiffre, donc Каким образом ne correspond pas.
2. Une liste numérotée le suit — 1. ou 1) conviennent tous deux.
3. La liste comporte au moins 3 étapes.

Chaque élément numéroté devient un HowToStep. Son name est la première phrase, tronquée à 80 caractères à la limite d’un mot avec des points de suspension ; son text est l’élément entier, limité à 1 000 caractères. Les liens sont aplatis pour ne conserver que leur texte d’ancrage et la mise en évidence inline est supprimée. Le contenu des blocs de code clôturés est entièrement ignoré : une liste numérotée dans un exemple ne devient donc pas une procédure.

Une procédure est limitée à 20 étapes et une page à 5 objets HowTo.

Un widget d’étapes compte comme une liste numérotée. Dans une région <!-- widget:stepper -->, chaque titre ouvre l’étape suivante, quel que soit son niveau — mais la région ne devient un HowTo que si un titre How to / Как l’a introduite. Un stepper sous # Quick start ne produit rien.

## How to move your docs to a custom domain
 
1. Open the admin panel and select **Custom Domain**.
2. Enter `docs.example.com` and save.
3. Add the CNAME record the panel shows to your DNS provider.

Deux étapes ne produisent rien. Si la procédure comporte réellement deux étapes, c’est le résultat attendu — n’ajoutez pas d’éléments à la liste pour atteindre le seuil.

À quoi ressemble réellement le JSON-LD généré#

Voici la sortie des propres extracteurs de Docsbook, exécutés sur les deux blocs Markdown ci-dessus :

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "FAQPage",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "Does a custom domain change my page URLs?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Yes. Every canonical URL, sitemap entry and breadcrumb item moves to the new host on the next render."
          }
        },
        {
          "@type": "Question",
          "name": "How long does the certificate take?",
          "acceptedAnswer": { "@type": "Answer", "text": "Usually under a minute after the CNAME resolves." }
        }
      ]
    },
    {
      "@type": "HowTo",
      "name": "How to move your docs to a custom domain",
      "step": [
        { "@type": "HowToStep", "position": 1, "name": "Open the admin panel and select Custom Domain.", "text": "Open the admin panel and select Custom Domain." },
        { "@type": "HowToStep", "position": 2, "name": "Enter docs.example.com and save.", "text": "Enter docs.example.com and save." },
        { "@type": "HowToStep", "position": 3, "name": "Add the CNAME record the panel shows to your DNS provider.", "text": "Add the CNAME record the panel shows to your DNS provider." }
      ]
    }
  ]
}

Notez ce que l'extracteur a fait aux titres des questions : il a ajouté le ? que le Markdown avait omis. C'est pourquoi un H3 formulé comme une question se lit correctement dans le balisage, même lorsque vous l'avez écrit comme une affirmation.

Ce que contient le fil d’Ariane#

Le fil d’Ariane est l’accueil de l’espace de travail → l’accueil du projet → un élément par segment de chemin. Le name de chaque segment est rendu lisible — l’extension .md est supprimée, les tirets et les traits de soulignement sont remplacés par des espaces, et chaque mot commence par une majuscule — tandis que son URL item est générée par le même générateur d’URL canonique que celui utilisé par le <link rel="canonical"> de la page, de sorte qu’ils ne puissent jamais désigner des hôtes différents. Dans une langue traduite, les URL du fil sont exprimées dans cette langue.

{
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "acme", "item": "https://acme.docsbook.io" },
    { "@type": "ListItem", "position": 2, "name": "Acme Handbook", "item": "https://acme.docsbook.io/handbook" },
    { "@type": "ListItem", "position": 3, "name": "Guides", "item": "https://acme.docsbook.io/handbook/guides" },
    { "@type": "ListItem", "position": 4, "name": "Custom Domains", "item": "https://acme.docsbook.io/handbook/guides/custom-domains" }
  ]
}

Google exige position, name et item dans chaque ListItem, ainsi qu’au moins deux éléments dans la liste (Google, fil d’Ariane) ; une page située à la racine du projet produit exactement les deux éléments d’accueil, ce qui correspond au minimum documenté.

Ce que speakable dit#

Lorsque l’AEO est activé, le TechArticle bénéficie de :

"speakable": {
  "@type": "SpeakableSpecification",
  "cssSelector": [".tldr", "article > p:first-of-type", "h1"]
}

schema.org définit SpeakableSpecification comme indiquant « des sections d’un document mises en évidence comme particulièrement adaptées à la lecture à voix haute » (schema.org). La liste de sélecteurs constitue un ordre de préférence : le bloc TL;DR de GEO si GEO est activé, puis le premier paragraphe de l’article, puis le H1. En pratique, cela signifie que ce qu’un lecteur voit en premier est également ce qu’une machine considère comme le résumé — une page qui commence par le contexte plutôt que par une réponse désigne le contexte comme son résumé.

Que se passe-t-il lorsque le balisage est incorrect#

Rien dans Docsbook ne valide le graphe avant sa mise en ligne. Il n’y a pas de linter de schéma dans le chemin de rendu, et audit_geo — l’outil qui vérifie l’accès des robots d’exploration, le rendu côté serveur et llms.txt — n’inspecte pas du tout le JSON-LD. Les données produites par les extracteurs sont directement publiées sur la page. Quatre modes de défaillance méritent d’être connus :

• Le détecteur n’a rien trouvé. C’est le résultat le plus courant et le moins visible : l’AEO est activée, la page comporte une section ressemblant à une FAQ, et aucun FAQPage n’apparaît. Dans presque tous les cas, le problème vient du niveau de titre — le détecteur lit les sections H2 et les questions H3, donc une FAQ rédigée avec des sections H3 et des questions H4 ne produit rien.
• Le détecteur a trop trouvé. Tout H3 se terminant par ? devient une question de FAQ n’importe où dans le document, y compris un titre rhétorique dans un texte. Le résultat est un balisage valide décrivant une page qui n’est pas une FAQ, ce qui constitue un problème de conformité plutôt qu’un problème de syntaxe — les consignes de Google exigent que « Vos données structurées doivent être une représentation fidèle du contenu de la page » (Google). Reformulez le titre sous forme d’affirmation pour qu’il ne corresponde plus.
• Du HTML brut dans une réponse interrompt le bloc. Le texte de la réponse est copié tel quel dans le JSON. Une séquence </script> littérale dans une réponse de FAQ termine prématurément l’élément JSON-LD, et tous les objets qui suivent sont perdus. N’utilisez pas de HTML brut dans les réponses de FAQ ; utilisez le Markdown employé dans le reste de la page.
• La page est servie sur un domaine personnalisé. Un espace de travail utilisant son propre domaine est rendu via un chemin différent qui émet un simple TechArticle et rien d’autre — ni fil d’Ariane, ni FAQPage, ni HowTo, ni speakable. Vérifiez l’adresse *.docsbook.io avant de conclure que le détecteur a échoué.

Vérifiez le résultat avec le Test des résultats enrichis de Google ou le Validateur de balisage Schema. Notez ce que signifie ou ne signifie pas aujourd’hui un résultat positif : BreadcrumbList reste un résultat enrichi pris en charge, tandis que FAQPage et HowTo sont des schémas schema.org valides que Google n’affiche plus — consultez les limites de l’AEO.

Limites et questions ouvertes#

• TechArticle ne fait pas partie des trois types que Google nomme pour le résultat enrichi d'article. La documentation de Google indique que « les objets Article doivent être basés sur l'un des types schema.org suivants : Article, NewsArticle, BlogPosting » (Google, article). TechArticle est un sous-type schema.org de Article — « Un article technique - Exemple : sujets de type guide pratique (tâche), procédures étape par étape, dépannage procédural, spécifications » (schema.org) — et c'est la description fidèle d'une page de documentation. La question de savoir si Google considère un sous-type comme éligible au résultat enrichi d'article n'est pas tranchée dans cette documentation. Nous avons privilégié l'exactitude plutôt que les suppositions.
• Les détecteurs de FAQ et de procédures How-to reconnaissent uniquement l'anglais et le russe. Les titres de section et le verbe de procédure sont comparés dans ces deux langues. Une page de FAQ en allemand ou en japonais ne produit aucun FAQPage, sauf si ses titres H3 se terminent par ?.
• Les réponses sont uniquement du texte. Tout le contenu compris entre un titre de question et le titre suivant est assemblé et tronqué à 1 000 caractères — les tableaux, blocs de code et images se retrouvent sous forme de source brute dans le texte de la réponse, ou sont tronqués en cours de route. Limitez les réponses de FAQ à quelques phrases.
• Le nombre d'éléments générés n'est indiqué nulle part. Il n'existe aucun panneau, journal ni API vous indiquant combien de questions FAQPage ou d'objets HowTo une page donnée a produits. Affichez la source ou utilisez un validateur.

Articles associés#

• AEO — ce dont un moteur de réponses a besoin et ce que le balisage peut encore apporter
• Règles de contenu pour les moteurs de réponses — les règles rédactionnelles qui déterminent si le passage sera sélectionné
• GEO — le bloc TL;DR que le sélecteur speakable privilégie
• SEO — les balises meta, le sitemap et les URL canoniques
• Widgets de contenu — les zones d’étapes et d’accordéon comprises par les détecteurs