Optimisation SEO

Optimisez votre documentation pour les moteurs de recherche et les aperçus sociaux en définissant des titres, descriptions et métadonnées dans le frontmatter.

Ce que Jamdesk fait automatiquement

Optimiser votre contenu

Rédiger un frontmatter efficace

---
title: User Authentication    # Under 60 characters
description: Set up OAuth, JWT, and session-based authentication  # 120-160 characters
---

Titres de page

• Restez sous 60 caractères, en comptant le nom du site que le format de titre ajoute, pour éviter la troncature dans les résultats de recherche
• Placez votre mot-clé principal près du début
• Assurez-vous que chaque titre est unique dans votre documentation

Par défaut, le titre de l'onglet du navigateur et des résultats de recherche est Titre de la page — Nom du site. Pour le modifier, définissez seo.titleTemplate dans docs.json. Placez %s à l'endroit où le titre de la page doit apparaître :

{
  "seo": {
    "titleTemplate": "%s | Acme"
  }
}

Une page intitulée Getting started affiche alors Getting started | Acme. Utilisez "%s" seul pour omettre le nom du site. Si le modèle ne contient pas %s, le build échoue et jamdesk validate affiche l'erreur. Les aperçus de liens (og:title et twitter:title) affichent toujours le titre de la page seul.

Deux types de pages n'utilisent pas le modèle. Une page sans title affiche votre name suivi de « Documentation », par exemple Acme Documentation, ou simplement votre name s'il se termine déjà par « Docs » ou « Documentation ». Une page dont le titre est identique à votre name affiche ce titre seul.

jamdesk validate et jamdesk dev acceptent seo.titleTemplate à partir de la version 1.1.220 de la CLI. Mettez à jour avec npm i -g jamdesk@latest.

Descriptions

• Visez 120 à 160 caractères
• Résumez ce que le lecteur va apprendre
• Intégrez naturellement des mots-clés pertinents

Contrôler l'indexation

Paramètres à l'échelle du site

Dans votre docs.json, configurez le comportement par défaut des robots :

{
  "seo": {
    "metatags": {
      "robots": "index, follow"
    }
  }
}

Contrôle par page

Remplacez l'indexation pour des pages spécifiques dans le frontmatter :

---
title: Internal Notes
noindex: true
---

Utilisez noindex pour :

• Les pages en brouillon ou en cours de rédaction
• La documentation interne
• Le contenu obsolète que vous conservez pour référence

Indexation de recherche vs. ingestion par l'IA

Les métadonnées robots et noindex contrôlent les moteurs de recherche : si une page apparaît dans Google et dans votre sitemap.xml. Elles n'ont aucun effet sur les fichiers llms.txt et llms-full.txt lus par les outils d'IA. Pour arrêter de publier ces fichiers, définissez seo.ai.llmsTxt sur false (voir Désactiver llms.txt). Les deux contrôles sont indépendants : une page peut être indexée par les moteurs de recherche mais exclue de l'ingestion par l'IA, ou l'inverse.

URLs canoniques

Si votre documentation est accessible via plusieurs URLs, définissez une URL canonique :

---
title: Getting Started
canonical: https://docs.example.com/getting-started
---

Vous pouvez également définir une base canonique à l'échelle du site dans docs.json. Jamdesk ajoute le chemin de chaque page à cette base, afin que chaque page obtienne une URL canonique correcte :

{
  "seo": {
    "metatags": {
      "canonical": "https://docs.acme.com"
    }
  }
}

Aperçus sociaux et Open Graph

Jamdesk génère automatiquement une carte sociale 1200×630 à l'image de votre marque pour chaque page. Remplacez n'importe quelle balise sociale dans le frontmatter. Vous pouvez utiliser des clés plates de premier niveau ou un bloc seo: imbriqué. Les deux fonctionnent, et lorsque la même clé est définie des deux façons, la valeur plate de premier niveau l'emporte.

---
title: API Reference
description: REST API endpoints and authentication
"og:title": API Reference — Acme
"og:description": Everything you need to call the Acme API
"og:image": /images/api-social-card.png
"twitter:card": summary_large_image
"twitter:creator": "@acme"
keywords: ["api", "rest", "authentication"]
canonical: https://docs.acme.com/api-reference
---

Balises prises en charge

Type de carte Twitter / X

La balise twitter:card contrôle la mise en page que X (et d'autres plateformes) utilise lorsque votre lien est partagé :

Pour une carte à l'image de la marque en 1200×630, utilisez summary_large_image afin que l'image s'affiche en pleine largeur.

Image par défaut à l'échelle du site

Définissez une image sociale de repli pour chaque page dans docs.json. Toute page qui définit son propre og:image la remplace :

{
  "seo": {
    "metatags": {
      "og:image": "https://docs.acme.com/images/default-card.png"
    }
  }
}

Personnaliser la carte sociale

Votre carte générée garde son apparence actuelle, sauf si vous ajoutez seo.socialCard à docs.json. Ne définissez que les clés que vous souhaitez modifier :

{
  "seo": {
    "socialCard": {
      "theme": "dark",
      "brandColor": true,
      "accentBar": false,
      "siteName": false,
      "customImage": "replace"
    }
  }
}

La carte ne peut dessiner que des logos SVG, PNG et JPG. Jamdesk convertit en WebP les fichiers de logo PNG et JPG de votre dépôt lors du build de votre site, si bien que la carte affiche généralement votre favicon à la place et conserve le nom du site, même avec siteName: false. Utilisez un logo SVG pour afficher votre logo complet sur la carte, et logo.dark sur une carte sombre.

La carte ne peut pas dessiner le texte d'un logo SVG : le texte reste donc vide. Pour corriger cela, convertissez le texte en contours (tracés) dans votre outil de conception, puis exportez de nouveau le SVG. Dans Figma, sélectionnez le texte et utilisez Flatten. Dans Illustrator, utilisez Type > Create Outlines. Votre build affiche une suggestion quand il trouve du texte dans le logo SVG utilisé par la carte. Les logos indiqués par une URL complète (https://...) ne sont pas vérifiés.

Si votre couleur de marque ne ressort pas assez sur la carte, le texte du badge utilise la couleur de texte normale à la place. La barre conserve votre couleur de marque, sauf si cette couleur est presque identique au fond de la carte. Dans ce cas, la barre est grise.

Par défaut, Jamdesk dessine le titre de la page par-dessus votre og:image. Si votre image contient déjà son propre texte ou son propre design, définissez "customImage": "replace" pour l'afficher telle quelle.

Lorsque votre og:image sert de fond à la carte, choisissez le theme qui lui correspond : dark pour une image sombre, light pour une image claire.

En mode replace, Jamdesk ne dessine aucun titre sur l'image. Si seo.metatags définit og:image, toutes les pages utilisent cette image, et une page qui définit son propre og:image utilise celle-ci à la place. Seules les pages qui n'ont ni l'un ni l'autre obtiennent une carte générée. Utilisez un PNG ou un JPG de 1200×630. Certaines plateformes n'affichent pas les images WebP ou SVG.

Les réseaux sociaux mettent en cache les aperçus de liens : un lien déjà partagé peut donc conserver l'ancienne carte pendant un certain temps après la modification de ces paramètres. Vérifiez la nouvelle carte avec l'outil OpenGraph Preview.

Sitemap et Robots.txt

Chaque site Jamdesk génère automatiquement sitemap.xml et robots.txt à chaque build.

Où les trouver

Les URLs dépendent du fait que votre documentation se trouve à la racine d'un domaine ou sous un sous-chemin /docs :

https://docs.acme.com/sitemap.xml
https://docs.acme.com/robots.txt

Ce qui est inclus dans le sitemap

• Toutes les pages publiées (à l'exclusion de celles avec noindex ou hidden dans le frontmatter)
• Les dates de dernière modification du frontmatter lorsqu'elles sont disponibles
• Une fréquence de changement hebdomadaire

Exclure des pages du sitemap

Ajoutez noindex au frontmatter pour exclure une page à la fois du sitemap et des moteurs de recherche :

---
title: Internal Notes
noindex: true
---

Les pages avec hidden: true sont également exclues automatiquement.

Données structurées JSON-LD

Chaque page inclut automatiquement des données structurées schema.org sous forme de balise <script type="application/ld+json"> avec deux schémas :

• WebSite : le nom, l'URL et la description de votre site (depuis docs.json).
• BreadcrumbList : le chemin de navigation depuis l'accueil jusqu'à la page actuelle, dérivé de votre configuration navigation.

Aucune configuration nécessaire. Les moteurs de recherche utilisent ces données pour des résultats enrichis comme les fils d'Ariane dans les listes de recherche.

IndexNow

Après chaque build, Jamdesk soumet automatiquement les URLs de pages modifiées à IndexNow pour une indexation plus rapide par les moteurs de recherche. Cela informe Bing, Yandex et d'autres moteurs de recherche participants des changements de votre contenu sans attendre leur prochain cycle d'exploration.

• Se déclenche après chaque build réussi
• Ne soumet que les pages qui ont réellement changé
• Non bloquant, donc ne retarde jamais votre build
• Aucune configuration requise

Bonnes pratiques

Passez en revue cette checklist avant de publier :

Articles connexes