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, de sorte que chaque objet de la page partage un même contexte et puisse référencer les autres via @id.

Cette page répertorie précisément ce qui entre dans ce graphe, les conditions que votre Markdown doit remplir pour que chaque objet apparaisse, ainsi que l’apparence d’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 sur la documentation client — si vous avez lu à notre sujet une comparaison avec un concurrent affirmant le contraire, c’est là que se trouve réellement ce type.

Les dates proviennent de l’historique Git du fichier, et non du frontmatter : 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 de ces clés, plutôt qu’une date inventée.

Quel format Markdown produit un FAQPage ?#

Une section devient une liste de questions lorsque l’une ou l’autre 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 éléments *, _ en ligne ainsi que les caractères d’accent grave sont supprimés. Les marqueurs de widget de contenu (<!-- widget:accordion --> et son marqueur de fermeture) sont ignorés plutôt qu’absorbés dans 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 le Как russe, dont le caractère suivant ne doit pas être une lettre ou un chiffre, de sorte que Каким образом ne corresponde pas.
2. Une liste numérotée le suit — 1. ou 1) sont tous deux acceptés.
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 et suivie de points de suspension ; son text est l’élément entier, plafonné à 1 000 caractères. Les liens sont aplatis en leur texte d’ancrage et l’emphase en ligne est supprimée. Le contenu des blocs de code délimité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 stepper 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 — ne complétez pas 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." }
      ]
    }
  ]
}

Remarquez 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 rédigé sous forme d'affirmation.

Contenu du fil d’Ariane#

Le fil d’Ariane est composé de l’accueil de l’espace de travail → de l’accueil du projet → d’un élément par segment de chemin. Le name de chaque segment est rendu plus 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 à l’aide du même générateur d’URL canonique que celui utilisé par le <link rel="canonical"> de la page, afin que les deux 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 sur 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 dit speakable#

Avec AEO activé, TechArticle gagne :

"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 étant particulièrement adaptées à la lecture orale » (schema.org). La liste des sélecteurs suit un ordre de préférence : le bloc GEO TL;DR si GEO est activé, puis le premier paragraphe de l’article, puis le H1. La conséquence pratique est que ce qu’un lecteur voit en premier est également ce qu’une machine traite 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#

Docsbook ne valide rien dans le graphe avant sa publication. 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. Ce que les extracteurs ont produit est ce qui est placé sur la page. Quatre modes d’échec méritent d’être connus :

• Le détecteur n’a rien trouvé. Le résultat le plus courant et le moins visible : l’AEO est activée, la page comporte une section qui ressemble à une FAQ, et aucun FAQPage n’apparaît. Presque toujours, 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 trouvé trop d’éléments. 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 relève d’un problème de politique plutôt que 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 et il ne sera plus détecté.
• Du HTML brut dans une réponse casse le bloc. Le texte de la réponse est copié tel quel dans le JSON. Une séquence </script> littérale à l’intérieur d’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é par le reste de la page.
• La page est publiée sur un domaine personnalisé. Un espace de travail sur 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, quel que soit le paramètre AEO. Vérifiez sur l’adresse *.docsbook.io avant de conclure que le détecteur a échoué.

Vérifiez avec le Test des résultats enrichis de Google ou le validateur de balisage Schema. Notez ce que signifie ou ne signifie pas un résultat positif aujourd’hui : BreadcrumbList reste un résultat enrichi pris en charge, tandis que FAQPage et HowTo sont des éléments 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 nommés par Google pour le résultat enrichi 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 tutoriel (tâche), procédures étape par étape, dépannage procédural, spécifications » (schema.org) — et c'est la description exacte d'une page de documentation. La question de savoir si Google considère un sous-type comme éligible au résultat enrichi 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 tutoriels 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 suivi. Tout ce qui se trouve entre un titre de question et le titre suivant est assemblé puis tronqué à 1 000 caractères — les tableaux, les blocs de code et les 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.
• Aucun décompte de ce qui a été généré n'est communiqué nulle part. Il n'existe aucun panneau, journal ou API indiquant combien de questions FAQPage ou d'objets HowTo une page donnée a produits. Affichez le code source ou utilisez un validateur.

Éléments connexes#

• 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 est sélectionné
• GEO — le bloc TL;DR que le sélecteur speakable privilégie
• SEO — balises meta, plan du site et URL canoniques
• Widgets de contenu — les sections d’étapes et d’accordéon que les détecteurs comprennent