SEO

Mintlify prend automatiquement en charge de nombreuses bonnes pratiques SEO, notamment :

• Génération de balises meta
• Génération des fichiers sitemap et robots.txt
• Structure HTML sémantique
• Optimisation pour mobile

Vous pouvez entièrement personnaliser les balises meta de votre site en ajoutant le champ metatags à votre docs.json ou au frontmatter d’une page.

Mintlify génère les balises meta suivantes pour chaque page. Vous pouvez les remplacer en les définissant dans votre docs.json ou dans le frontmatter d’une page.

Métadonnées de base :

• charset: utf-8 - Encodage des caractères
• og:type: website - Type Open Graph
• og:site_name - Nom de votre site de documentation
• twitter:card: summary_large_image - Type de carte Twitter

Métadonnées spécifiques à la page :

• title - Titre de la page, au format “Titre de la page - Nom du site”
• og:title - Titre Open Graph, par défaut le titre de la page
• twitter:title - Titre Twitter, se rabat sur og:title, puis sur le titre de la page
• description - Description de la page
• og:description - Description Open Graph, se rabat sur la description de la page
• twitter:description - Description Twitter, se rabat sur og:description, puis sur la description de la page

URL et canonique :

• canonical - Généré automatiquement à partir de l’URL de la page
• og:url - Définie sur l’URL canonique

SEO et indexation :

• robots - Généré à partir des métadonnées de la page
• noindex - Généré à partir des métadonnées de la page
• keywords - Généré à partir des métadonnées de la page

Images :

• og:image - Image Open Graph, og:image:width défini à 1200 et og:image:height à 630
• twitter:image - Image Twitter, twitter:image:width défini à 1200 et twitter:image:height à 630

Métadonnées du navigateur et de l’application :

• applicationName - Nom de votre site de documentation
• generator: Mintlify - Identifie Mintlify comme générateur du site
• apple-mobile-web-app-title - Nom de l’application sur l’écran d’accueil iOS
• msapplication-TileColor - Couleur de la tuile Windows
• Favicons et icônes à partir de votre configuration
• Lien vers le sitemap

Toutes les balises meta dans votre configuration docs.json seo.metatags sont également automatiquement injectées dans chaque page, par exemple google-site-verification pour la validation dans Google Search Console.

Mintlify ajoute des données structurées schema.org à chaque page indexable sous la forme d’un script JSON-LD. Ces données structurées aident les moteurs de recherche à afficher des résultats enrichis pour vos pages.

Chaque page émet un @graph connecté d’entités avec des @ids stables :

• Organization : l’éditeur de votre site. Dérivée du nom du site, du logo et de l’URL du site, ou configurée explicitement avec seo.organization.
• WebSite : votre site.
• WebPage : la page actuelle, y compris sa description et ses dates de modification.
• BreadcrumbList : l’emplacement de la page dans votre hiérarchie de navigation, généré à partir de la navigation de docs.json.
• L’entité de contenu principale : TechArticle pour les pages de documentation ou APIReference pour les pages générées à partir de spécifications d’API (pages avec un frontmatter api, openapi ou asyncapi).

Mintlify génère les données structurées à partir du frontmatter de la page et des configurations docs.json, notamment le titre de la page, la description, les mots-clés, l’URL canonique, la date de dernière mise à jour, le nom du site et le logo. Les données structurées n’incluent aucun champ sans valeur correspondante. Les pages avec noindex: true n’incluent pas de données structurées.

Pour modifier les données structurées, mettez à jour les champs correspondants du frontmatter ou les configurations docs.json. Pour contrôler l’entité éditrice, notamment un @id stable, le nom légal, le logo canonique et les liens de profil sameAs, définissez seo.organization dans votre docs.json.

Mintlify génère automatiquement une image Open Graph (OG) pour chaque page. Cette image apparaît comme aperçu social lorsque vous partagez un lien sur les réseaux sociaux et les applications de messagerie.

Propriétés par défaut de l’image OG :

• Largeur : 1200px
• Hauteur : 630px
• Le logo de votre site provenant du champ logo dans docs.json
• Le titre de la page provenant du frontmatter title de la page
• La description de la page provenant du frontmatter description de la page
• La couleur primaire de votre site provenant du champ colors dans docs.json

Il existe trois façons de personnaliser les images OG, selon le niveau de contrôle dont vous avez besoin.

Image d’arrière-plan personnalisée

Pour utiliser une image d’arrière-plan personnalisée tout en conservant la superposition automatique du logo, du titre et de la description, définissez thumbnails.background dans votre docs.json.

"thumbnails": {
  "background": "/images/og-background.png"
}

Consultez thumbnails pour la liste complète des options de personnalisation.

Image OG statique pour toutes les pages

Pour remplacer entièrement l’image générée automatiquement par une seule image statique sur toutes les pages, définissez og:image dans vos balises meta globales.

"seo": {
  "metatags": {
    "og:image": "https://example.com/og-image.png"
  }
}

Image OG statique pour une page spécifique

Pour remplacer l’image OG d’une seule page, définissez og:image dans le frontmatter de cette page.

---
title: "Your page title"
description: "Your page description"
"og:image": "https://example.com/custom-og.png"
---

Pour définir des balises méta par défaut pour toutes les pages, ajoutez le champ metatags dans votre docs.json.

"seo": {
    "metatags": {
        "og:image": "lien vers votre image de balise méta par défaut"
    }
}

Pour vérifier votre site auprès de services comme Google Search Console, Bing Webmaster Tools ou d’autres moteurs de recherche, ajoutez la balise meta de vérification à seo.metatags dans votre docs.json. Mintlify injecte la balise dans chaque page.

"seo": {
    "metatags": {
        "google-site-verification": "your_verification_token"
    }
}

Une URL canonique indique aux moteurs de recherche quelle version de votre documentation fait autorité. Cela améliore le SEO lorsque votre documentation est accessible à partir de plusieurs URL et évite les problèmes de contenu dupliqué.

Canonique globale

Si vous utilisez un domaine personnalisé, définissez la balise meta canonical dans votre docs.json pour vous assurer que les moteurs de recherche indexent votre domaine préféré. Mintlify ajoute le chemin de chaque page à cette URL de base.

"seo": {
    "metatags": {
        "canonical": "https://www.your-custom-domain-here.com"
    }
}

Canonique par page

Pour définir une URL canonique pour une page spécifique, ajoutez canonical au frontmatter de cette page. Cela remplace la canonique globale ainsi que toute canonique générée automatiquement pour cette page. Cela est utile pour la documentation versionnée lorsque vous souhaitez que les pages des versions plus anciennes pointent vers leur équivalent dans la dernière version.

---
title: "My Page"
canonical: "https://docs.example.com/latest/my-page"
---

Pour définir des balises méta spécifiques à une page, ajoutez-les dans le frontmatter de la page.

Les balises méta spécifiques à une page incluent :

• title - Titre de la page
• description - La description de la page apparaît sous le titre sur la page et dans certains résultats des moteurs de recherche
• canonical - URL canonique de cette page ; remplace la canonique générée automatiquement
• keywords - Mots-clés séparés par des virgules
• og:title - Titre Open Graph pour le partage sur les réseaux sociaux
• og:description - Description Open Graph, se rabat sur description
• og:image - URL de l’image Open Graph
• og:url - URL Open Graph
• og:type - Type Open Graph comme “article” ou “website”
• og:image:width - Largeur de l’image Open Graph
• og:image:height - Hauteur de l’image Open Graph
• twitter:title - Titre de la carte Twitter, se rabat sur og:title, puis sur title
• twitter:description - Description de la carte Twitter, se rabat sur og:description, puis sur description
• twitter:image - Image de la carte Twitter
• twitter:card - Type de carte Twitter comme summary ou summary_large_image
• twitter:site - Handle du compte Twitter du site
• twitter:image:width - Largeur de l’image Twitter
• twitter:image:height - Hauteur de l’image Twitter
• noindex - À définir sur true pour empêcher l’indexation par les moteurs de recherche
• robots - Valeur de la balise méta robots

---
title: "Titre de votre page d'exemple"
description: "Description spécifique de la page"
"og:title": "Titre pour les réseaux sociaux"
"og:description": "Description personnalisée pour le partage social"
"og:image": "lien vers votre image de balise meta"
"twitter:title": "Titre spécifique pour Twitter"
keywords: ["mot-clé1", "mot-clé2"]
---

Vous trouverez ci-dessous une liste complète des balises meta que vous pouvez ajouter à votre docs.json. Ces balises meta améliorent le SEO de votre site, le partage sur les réseaux sociaux et la compatibilité avec les navigateurs.

Vous pouvez prévisualiser l’apparence de vos balises meta sur différentes plateformes à l’aide de metatags.io.

"seo": {
    "metatags": {
      "robots": "noindex",
      "charset": "UTF-8",
      "viewport": "width=device-width, initial-scale=1.0",
      "description": "Description de la page",
      "keywords": "mot-clé1, mot-clé2, mot-clé3",
      "author": "Nom de l'auteur",
      "robots": "index, follow",
      "googlebot": "index, follow",
      "google": "notranslate",
      "google-site-verification": "verification_token",
      "generator": "Mintlify",
      "theme-color": "#000000",
      "color-scheme": "light dark",
      "canonical": "https://your-custom-domain-here.com",
      "format-detection": "telephone=no",
      "referrer": "origin",
      "refresh": "30",
      "rating": "general",
      "revisit-after": "7 days",
      "language": "en",
      "copyright": "Copyright 2024",
      "reply-to": "email@example.com",
      "distribution": "global",
      "coverage": "Mondial",
      "category": "Technologie",
      "target": "all",
      "HandheldFriendly": "True",
      "MobileOptimized": "320",
      "apple-mobile-web-app-capable": "yes",
      "apple-mobile-web-app-status-bar-style": "black",
      "apple-mobile-web-app-title": "Titre de l'application",
      "application-name": "Nom de l'application",
      "msapplication-TileColor": "#000000",
      "msapplication-TileImage": "path/to/tile.png",
      "msapplication-config": "path/to/browserconfig.xml",
      "og:title": "Titre Open Graph",
      "og:type": "website",
      "og:url": "https://example.com",
      "og:image": "https://example.com/image.jpg",
      "og:description": "Description Open Graph",
      "og:site_name": "Nom du site",
      "og:locale": "en_US",
      "og:video": "https://example.com/video.mp4",
      "og:audio": "https://example.com/audio.mp3",
      "twitter:card": "summary",
      "twitter:site": "@username",
      "twitter:creator": "@username",
      "twitter:title": "Titre Twitter",
      "twitter:description": "Description Twitter",
      "twitter:image": "https://example.com/image.jpg",
      "twitter:image:alt": "Description de l'image",
      "twitter:player": "https://example.com/player",
      "twitter:player:width": "480",
      "twitter:player:height": "480",
      "twitter:app:name:iphone": "Nom de l'application",
      "twitter:app:id:iphone": "12345",
      "twitter:app:url:iphone": "app://",
      "article:published_time": "2024-01-01T00:00:00+00:00",
      "article:modified_time": "2024-01-02T00:00:00+00:00",
      "article:expiration_time": "2024-12-31T00:00:00+00:00",
      "article:author": "Nom de l'auteur",
      "article:section": "Technologie",
      "article:tag": "tag1, tag2, tag3",
      "book:author": "Nom de l'auteur",
      "book:isbn": "1234567890",
      "book:release_date": "2024-01-01",
      "book:tag": "tag1, tag2, tag3",
      "profile:first_name": "John",
      "profile:last_name": "Doe",
      "profile:username": "johndoe",
      "profile:gender": "male",
      "music:duration": "205",
      "music:album": "Nom de l'album",
      "music:album:disc": "1",
      "music:album:track": "1",
      "music:musician": "Nom de l'artiste",
      "music:song": "Nom de la chanson",
      "music:song:disc": "1",
      "music:song:track": "1",
      "video:actor": "Nom de l'acteur",
      "video:actor:role": "Nom du rôle",
      "video:director": "Nom du réalisateur",
      "video:writer": "Nom du scénariste",
      "video:duration": "120",
      "video:release_date": "2024-01-01",
      "video:tag": "tag1, tag2, tag3",
      "video:series": "Nom de la série"
  }
}

Mintlify génère automatiquement un fichier sitemap.xml et un fichier robots.txt. Vous pouvez consulter votre sitemap en ajoutant /sitemap.xml à l’URL de votre site de documentation.

Par défaut, Mintlify n’indexe que les pages incluses dans la navigation de votre docs.json. Il exclut les pages masquées qui existent dans votre dépôt mais ne figurent pas dans votre navigation de :

• Sitemaps pour les moteurs de recherche
• Recherche interne de la documentation
• Contexte de l’assistant IA
• Résultats de recherche du serveur MCP

Pour inclure les pages masquées dans l’indexation de recherche, ajoutez seo.indexing à votre docs.json :

"seo": {
    "indexing": "all"
}

Pour inclure uniquement les pages situées sous un onglet ou un groupe masqué spécifique, définissez searchable: true sur cet onglet ou ce groupe. Consultez Recherche, SEO et indexation par l’IA pour plus de détails.

Si votre hébergement sert chaque page avec une barre oblique finale (par exemple, /quickstart/ au lieu de /quickstart), activez seo.trailingSlash dans votre docs.json pour que les URL émises par Mintlify pour le SEO correspondent :

"seo": {
    "trailingSlash": true
}

Lorsque cette option est activée, Mintlify ajoute une barre oblique finale à :

• Les balises canoniques et les balises meta og:url
• Les entrées <loc> du sitemap.xml généré automatiquement
• Les liens internes relatifs à la racine entre les pages, en préservant toute chaîne de requête ou tout fragment

Activer trailingSlash n’affecte que la façon dont les URL sont émises. Cela ne modifie pas les routes des pages, ne redirige pas les URL existantes et ne s’applique pas aux valeurs canonical explicites définies par page dans le frontmatter. Laissez trailingSlash non défini ou à false si votre site sert des URL sans barre oblique finale.

Le robots.txt généré automatiquement inclut des directives Content-Signal qui indiquent aux robots d’exploration d’IA comment ils peuvent utiliser votre documentation. Ces signaux suivent la politique Content Signals de Cloudflare et s’appliquent à tous les agents utilisateurs :

User-agent: *
Content-Signal: ai-train=yes, search=yes, ai-input=yes

Les signaux par défaut activent votre documentation pour :

• ai-train=yes—Entraînement de modèles d’IA.
• search=yes—Création d’index de recherche.
• ai-input=yes—Génération de réponses par IA, y compris la génération augmentée par récupération et les assistants IA.

Ces valeurs par défaut aident les outils d’IA comme ChatGPT, Claude et Perplexity à découvrir et à citer votre documentation. Pour modifier les signaux, ajoutez un robots.txt personnalisé à la racine de votre projet. Mintlify sert les fichiers personnalisés tels quels, sans les directives Content-Signal par défaut.

Pour ajouter un sitemap.xml ou un robots.txt personnalisé, créez un fichier sitemap.xml ou robots.txt à la racine de votre projet. L’ajout d’un fichier personnalisé remplacera le fichier généré automatiquement portant le même nom. Si vous supprimez un fichier personnalisé, le fichier par défaut s’appliquera à nouveau automatiquement.

Pour empêcher les moteurs de recherche d’indexer une page, ajoutez noindex: true au frontmatter de cette page.

---
noindex: true
---

Vous pouvez également définir noindex pour toutes les pages de votre documentation en réglant le champ metatags.robots sur "noindex" dans votre docs.json :

"seo": {
    "metatags": {
      "robots": "noindex"
    }
  }

Pour masquer l’intégralité de votre déploiement aux moteurs de recherche tout en le maintenant accessible publiquement, activez Don’t index project dans votre tableau de bord, sous Settings > Deployment > Add-ons > Visibility.

Lorsqu’il est activé, Mintlify :

• Rend chaque page avec les balises meta robots noindex, nofollow.

• Renvoie un sitemap.xml vide.

• Renvoie 404 pour llms.txt et llms-full.txt.

• Vide votre index de recherche, de sorte que les pages n’apparaissent plus dans la recherche interne, l’assistant IA ni le serveur MCP.

• Sert un robots.txt qui interdit l’accès à tout le site :

  User-agent: *
  Content-Signal: ai-train=no, search=no, ai-input=no
  Disallow: /

Utilisez cette option lorsque vous souhaitez conserver un déploiement en ligne pour une relecture interne, une mise en préproduction ou un partage limité, sans qu’il apparaisse dans les résultats de recherche publics ni qu’il soit utilisé comme données d’entraînement ou de récupération pour les outils d’IA.

Ce paramètre fonctionne en complément d’autres contrôles d’indexation :

• noindex par page—Le noindex: true au niveau d’une page dans le frontmatter continue de s’appliquer lorsque le paramètre au niveau du projet est désactivé. Le paramètre au niveau du projet remplace les réglages par page lorsqu’il est activé, et toutes les pages sont alors traitées comme noindex.
• robots.txt personnalisé—Si vous avez un robots.txt personnalisé à la racine de votre projet, Mintlify le sert tel quel. Le paramètre au niveau du projet ne remplace pas un robots.txt personnalisé : mettez-le à jour ou supprimez-le séparément si vous souhaitez que les règles pour les robots d’exploration soient cohérentes.