Comment Docsbook construit l’en-tête d’une page

Cette page décrit le mécanisme : ce que Docsbook place dans <head> et dans sitemap.xml pour chaque page qu’il héberge, dans l’ordre où le code le résout, afin que vous puissiez prévoir le résultat au lieu de l’extraire avec curl. Pour savoir ce qui vous est utile et ce que vous devez activer, commencez par l’index SEO.

Quel est le titre de la page et d’où vient-il#

Le <title> d’une page Docsbook est déterminé en trois étapes, la première correspondance étant retenue :

Ordre	Source	Pourquoi elle est prioritaire
1	Frontmatter `title:`	Le seul des trois que vous pouvez modifier sans changer ce qu’un lecteur voit sur la page.
2	Le `# H1` du corps	Un véritable titre, déjà rédigé pour un lecteur.
3	Un titre dérivé du nom du fichier	Jamais vide ; une page possède toujours une ligne SERP.

Le nom de l’espace de travail est ensuite ajouté exactement une fois, sous la forme Page title — Workspace, et omis lorsque le titre le contient déjà comme mot autonome. « Docs » dans « Docsbook » ne compte pas — les deux caractères voisins de la correspondance doivent être des caractères qui ne constituent pas un mot, la vérification s’effectuant par rapport aux lettres et chiffres Unicode plutôt qu’ASCII, de sorte qu’un nom d’espace de travail en cyrillique ou en CJK correspond de la même manière qu’un nom latin. Une page dont le titre se limite au nom de l’espace de travail (la racine du site) devient Workspace — Documentation. La chaîne finale est émise comme un titre absolu, ce qui empêche le modèle %s | Docsbook appliqué à l’ensemble du site d’ajouter une seconde copie de la marque.

Sur une page traduite, le titre provient des métadonnées traduites mises en cache, et sinon du premier <h1> du code HTML traduit stocké — ainsi, une page chinoise affiche un titre chinois. La description est volontairement conservée dans la langue source : Docsbook n’invente pas de traduction pour celle-ci.

Qu’est-ce que la méta-description et qu’est-ce qui en est supprimé ?#

Ordre : le description: du frontmatter en premier, puis les propres paragraphes d’ouverture de la page.

Avant que le texte du corps puisse devenir une description, il est nettoyé : les commentaires HTML (qui correspondent aux marqueurs de widgets), les marqueurs {icon-name}, les titres, les images, le code délimité et le code inline, les caractères de mise en emphase, les balises HTML brutes, les puces de liste et les marqueurs de citation sont supprimés, et un lien Markdown est réduit à son texte de lien plutôt que d’entraîner son URL dans la phrase. Les paragraphes de 20 caractères ou moins sont supprimés comme fragments.

Deux longueurs sont générées à partir de la même source en un seul passage : 160 caractères pour <meta name="description"> et 400 pour og:description et le description JSON-LD. Une description rédigée dans le frontmatter remplit les deux. La troncature s’arrête à la limite d’un mot et privilégie la fin d’une phrase lorsqu’il y en a une dans la seconde moitié de la limite ; sinon, le texte se termine par des points de suspension.

Quelle URL la page considère-t-elle comme canonique ?#

Une page, une URL canonique, résolue dans cet ordre :

Votre domaine personnalisé, lorsque l’espace de travail en possède un. Le miroir *.docsbook.io sert alors Disallow: / au lieu de constituer une seconde copie.
Un chemin apex appartenant au produit, pour la documentation propre à Docsbook.
Le chemin apex court pour les espaces de travail de présentation, car c’est l’URL qui répond à 200 — la forme en sous-domaine y redirige.
https://<owner>.docsbook.io/<repo>/<path> pour tout le reste.

Les pages traduites suivent les mêmes quatre branches, avec la locale insérée à l’endroit où le routeur la sert effectivement. en fait l’objet d’un traitement particulier et renvoie à l’URL sans préfixe, puisque /en/page et /page servent un contenu identique octet par octet, et qu’une URL localisée pour une page qui n’est pas réellement traduite affiche le texte source : son URL canonique est donc l’URL source au lieu de se prétendre comme faisant autorité.

Quelles langues sont annoncées comme alternatives ?#

L’ensemble hreflang contient x-default et en à l’URL source, ainsi qu’une entrée pour chaque langue activée dans laquelle cette page a effectivement été traduite. Activer une langue ne l’ajoute pas : l’URL d’une langue pour laquelle aucune traduction n’existe est redirigée canoniquement vers elle-même, et un seul membre de ce type suffit à invalider l’ensemble du cluster. Une page portant noindex n’obtient aucun ensemble, plutôt qu’un ensemble orphelin.

Le sitemap n’émet aucune alternative au niveau de la page, volontairement : il ne peut pas se permettre la vérification de traduction page par page, et tout ensemble qu’il construirait listerait chaque langue activée et réintroduirait exactement la contradiction que l’ensemble au niveau de la page cherche à éviter.

Chaque page génère des métadonnées OpenGraph (og:title, og:description limité à 400 caractères, og:url = l’URL canonique, og:site_name, og:type: article, og:locale) ainsi qu’une carte X de type summary_large_image contenant la description de 160 caractères. L’image est générée pour chaque page au format 1200×630, mise en cache pendant 24 heures et affiche l’identité visuelle de l’espace de travail, la section sous forme de surtitre, le titre de la page (tronqué à 64 caractères et affiché dans une taille réduite au-delà de 30 caractères) ainsi que la description tronquée à 130 caractères, dans les couleurs de l’espace de travail. Sur un domaine personnalisé, la carte utilise la même image, demandée via une URL absolue depuis le domaine racine — mais og:description contient alors la chaîne de 160 caractères, et non celle de 400 caractères.

Quelles directives robots une page contient-elle ?#

Quatre règles, par ordre de priorité stricte :

Condition	Émis
Aperçu administrateur (`?preview=true`)	`noindex, follow`
Option SEO désactivée pour tout le site	`noindex, nofollow`
Frontmatter de la page `noindex`	`noindex, follow`
Sinon	`index, follow`

noindex: true, noindex: yes, noindex: 1 et l’orthographe robots: noindex sont tous pris en compte. Tout le reste — absence, false, index — signifie une indexation.

robots.txt varie selon l’hôte. Le domaine racine fournit une règle générique permissive avec Crawl-delay: 10, interdit les chemins ne contenant pas de contenu propres à l’application, nomme explicitement dix-huit robots d’IA et de recherche à Crawl-delay: 5, bloque complètement treize robots à fort volume et à faible valeur de citation, et répertorie une ligne Sitemap: par site découvrable. Un sous-domaine d’espace de travail fournit la même politique pour les robots, ainsi que sa propre ligne Sitemap:. Un domaine personnalisé fournit la politique pour les robots sans ligne Sitemap: — il ne possède pas encore de sitemap qui lui soit propre, et rediriger les robots vers le sitemap du miroir annoncerait un deuxième hôte pour chaque page. Crawl-delay est une simple courtoisie, et non une norme : RFC 9309 définit uniquement user-agent, allow et disallow, et Google ajoute sitemap et rien d’autre — « les autres champs tels que crawl-delay ne sont pas pris en charge ».

Que contient sitemap.xml ?#

Un plan du site par propriétaire, reconstruit au maximum toutes les heures. Pour chaque dépôt indexé, il répertorie chaque fichier Markdown, en faisant correspondre un README à la racine du site et chaque autre fichier à son propre chemin. Chaque entrée contient :

lastmod — la date du dernier commit ayant modifié ce fichier, issue du dépôt source. L'heure de génération est utilisée uniquement lorsque l'historique des commits ne peut pas être lu.
changefreq — weekly.
priority — 0.9 pour une page d'accueil, 0.7 pour une page interne et 0.8 / 0.6 pour leurs traductions.

Les URL traduites sont répertoriées uniquement lorsqu'une traduction existe réellement, et les URL en double sont regroupées avant l'émission du fichier. Un dépôt dont l'arborescence ne peut pas être lue est ignoré silencieusement, et le reste du plan du site continue d'être fourni : un plan du site qui renvoie une erreur 500 coûte plus cher qu'un plan auquel il manque une page du site.

Les pages portant noindex sont tout de même répertoriées. Reconnaître cet indicateur implique de lire le contenu de chaque page, ce que la génération du plan du site ne fait délibérément pas ; la directive propre à la page est respectée lors de son accès, de sorte que le coût se limite à une visite d'exploration.

Quelles données structurées sont générées ?#

Sur un site hébergé par Docsbook, chaque page génère un @graph JSON-LD avec trois nœuds :

Organization — l’espace de travail, son URL, son profil GitHub et son logo s’il est défini.
TechArticle — le titre, la description, l’URL canonique, inLanguage, datePublished et dateModified issus de l’historique des commits du dépôt source, l’auteur, l’éditeur, mainEntityOfPage.
BreadcrumbList — propriétaire → site → chaque segment de chemin, généré à partir du même constructeur canonique que celui utilisé par <link rel="canonical">, afin qu’aucun fil d’Ariane ne puisse nommer un hôte avec lequel la balise canonique est en désaccord.

Lorsque l’AEO est activé, speakable est ajouté, et les nœuds FAQPage / HowTo n’apparaissent que lorsque la page contient réellement cette structure. Lorsque la GEO est activée, un auteur Person est ajouté à partir du frontmatter ou de l’auteur du dernier commit.

Ancres, mode de rendu et hôtes#

Ancres. Les identifiants des titres proviennent du générateur de slugs du moteur de rendu, et chaque lien profond fourni par Docsbook — résultats de recherche, citations d’IA — est calculé en appelant cette même bibliothèque plutôt qu’en recréant la chaîne. Les titres en double renvoient à la première occurrence.

Mode de rendu. Une requête anonyme pour une page publique est servie depuis une route mise en cache et rendue côté serveur (fenêtre de 24 heures) ; les requêtes d’utilisateurs connectés et d’aperçu passent à un rendu dynamique et ne sont jamais mises en cache par le CDN. Dans tous les cas, le robot reçoit un HTML complet — aucune étape de rendu côté client ne s’interpose entre un robot et votre texte.

Domaine personnalisé ou domaine partagé. Sur un domaine personnalisé, l’URL canonique, le titre, la description, les cartes et un nœud TechArticle sont tous présents, et la politique destinée aux robots est appliquée. Cinq éléments ne le sont pas : le paramètre SEO global et le noindex par page (les pages sont servies index, follow sans condition), l’ensemble hreflang, les nœuds BreadcrumbList et Organization, les redirections des pages déplacées, ainsi que les signaux GEO — aucun bloc TL;DR, aucune ligne « Mis à jour » visible, et un auteur TechArticle qui est toujours un Person nommé d’après le propriétaire du dépôt. Voir Limites.

Pourquoi ces règles (preuves)#

Règle	Pourquoi cela fonctionne pour le consommateur	Source
Un `<title>` sur chaque page, la marque ajoutée une seule fois	Google place `<title>` en premier parmi les sources des liens de titre et déconseille les « textes répétés ou standardisés dans les éléments `<title>` »	Liens de titre
Des descriptions propres à chaque page, jamais une seule chaîne pour tout le site	« Des descriptions identiques ou similaires sur chaque page d'un site ne sont pas utiles »	Extraits
Le lien canonique pointe vers une URL qui renvoie un code 200, jamais vers une redirection	`rel="canonical"` est « un signal fort », et Google recommande un lien canonique autoréférent sur la page canonique	Regrouper les URL en double
Uniquement les versions réellement traduites dans `hreflang`	« Si la page X contient un lien vers la page Y, la page Y doit renvoyer vers la page X… ces annotations peuvent être ignorées »	Versions localisées
De vraies dates de commit comme `lastmod`	Google utilise `<lastmod>` « si cette valeur est systématiquement et vérifiablement… exacte »	Créer un sitemap
Des données structurées uniquement pour le contenu présent sur la page	« n'ajoutez pas de données structurées concernant des informations qui ne sont pas visibles pour l'utilisateur »	Présentation des données structurées
HTML généré côté serveur plutôt que côté client	Google exécute le code JavaScript dans une file d'attente où une page « peut rester… quelques secondes, mais cela peut prendre plus longtemps », et « tous les robots ne peuvent pas exécuter JavaScript »	Principes de base du référencement JavaScript
Image de carte de 1200×630	« Utilisez des images d'au moins 1200 x 630 pixels », soit un rapport proche de 1,91:1	Images de partage

Limites et questions ouvertes#

priority et changefreq sont décoratifs. Docsbook les génère, et Google l'affirme clairement : « Google ignore les valeurs <priority> et <changefreq>. » Le protocole sitemaps.org ajoute que la priorité « n'est probablement pas susceptible d'influencer la position de vos URL ». Ils ne coûtent rien et ne rapportent rien de Google ; les autres moteurs varient.
TechArticle ne figure pas dans la liste des résultats enrichis Article de Google. Il s'agit d'un véritable type schema.org (Thing > CreativeWork > Article > TechArticle) qui décrit le contenu fidèlement, mais la documentation Article de Google indique que les objets « doivent être basés sur l'un des types schema.org suivants : Article, NewsArticle, BlogPosting ». Considérez ce nœud comme une description exacte, et non comme une garantie d'éligibilité aux résultats enrichis. Les données structurées ne sont pas non plus documentées comme un facteur de classement : l'introduction de Google les décrit comme permettant à une page d'être éligible à un affichage enrichi et ne dit rien du classement.
Question en suspens : ce que rapporte le og:description de 400 caractères. Docsbook le génère parce que la balise dispose d'un espace que <meta description> n'a pas. Aucune source que nous avons consultée ne documente la manière dont un consommateur donné tronque og:description, et le protocole OpenGraph ne spécifie aucune longueur. Considérez 400 comme un choix interne, et non comme un optimum mesuré.
Les pages utilisant un domaine personnalisé ignorent vos paramètres d'indexation. Le paramètre SEO applicable à l'ensemble du site et le noindex propre à chaque page ne sont respectés que sur les hôtes hébergés par Docsbook ; sur un domaine personnalisé, la page est diffusée index, follow dans tous les cas. /sitemap.xml n'y est pas résolu non plus, son robots.txt ne contient donc aucune ligne Sitemap:, et une page renommée via Docsbook ne conserve sa redirection que sur le domaine partagé. Pour empêcher aujourd'hui une page d'être indexée sur un domaine personnalisé, ne la publiez pas dans le dépôt.
Un sitemap unique est limité à 50 000 URL / 50 Mo conformément au protocole sitemaps.org et à la propre limite de Google. Docsbook génère un sitemap par propriétaire et ne les répartit pas ; un propriétaire dépassant ce plafond n'est pas pris en charge à ce jour.