Paramètres globaux

Configurez votre site de documentation Mintlify avec docs.json, le fichier de configuration obligatoire qui contrôle la navigation, l’apparence, les intégrations et plus encore.

Le fichier docs.json est le fichier de configuration central de votre site de documentation Mintlify. Il contrôle les paramètres globaux de votre site, y compris l’identité visuelle, la structure de navigation, les intégrations, les paramètres d’API et plus encore. Considérez-le comme le plan directeur de votre site.

​

Champs obligatoires

Vous devez définir quatre champs pour construire un site fonctionnel.

Champ	Description
name	Le nom de votre projet ou organisation
theme	Le thème de mise en page de votre site
colors.primary	La couleur principale de la marque en code hexadécimal
navigation	La structure de votre contenu

Tous les autres champs sont optionnels. Ajoutez-les au fur et à mesure que vous personnalisez et affinez votre site.

​

Configuration minimale

Pour une meilleure expérience d’édition, incluez la référence $schema en haut de votre docs.json. Cela active l’autocomplétion, la validation et la documentation intégrée dans la plupart des éditeurs.

docs.json

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Your project name",
  "colors": {
    "primary": "#ff0000"
  },
  "navigation": [
    {
      "group": "Home",
      "pages": ["index"]
    }
  ]
}

​

Paramètres

Apparence et identité visuelle

Personnalisez l’apparence visuelle de votre site, y compris le thème, les couleurs, le logo, le favicon, les polices et l’arrière-plan.

Structure du site

Concevez l’architecture de l’information et l’expérience utilisateur de votre site, y compris la barre de navigation, le pied de page, la bannière, la navigation et les redirections.

Paramètres d'API

Contrôlez l’affichage et le comportement de la documentation API, y compris les spécifications OpenAPI et AsyncAPI, le playground d’API et les exemples de code.

Intégrations

Connectez votre site à des services tiers pour l’analytics, le chat et plus encore.

SEO et recherche

Contrôlez comment les moteurs de recherche indexent votre site, y compris les balises meta, la recherche et les horodatages des pages.

Référence du schéma

Référence complète de toutes les propriétés de docs.json.

​

Diviser la configuration avec $ref

Au fur et à mesure que votre configuration grandit, vous pouvez diviser docs.json en fichiers plus petits en utilisant des références $ref. Chaque référence pointe vers un fichier JSON distinct qui est résolu au moment de la compilation.

Ajoutez une propriété $ref avec un chemin de fichier relatif n’importe où dans votre docs.json. Mintlify remplace l’objet $ref par le contenu du fichier référencé.

docs.json

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Acme Docs",
  "colors": {
    "primary": "#1a73e8"
  },
  "navigation": {
    "$ref": "./config/navigation.json"
  }
}

config/navigation.json

[
  {
    "group": "Get started",
    "pages": ["index", "quickstart"]
  },
  {
    "group": "Guides",
    "pages": ["guides/first-steps", "guides/advanced"]
  }
]

• Les fichiers référencés peuvent contenir leurs propres références $ref. Les chemins imbriqués sont résolus relativement au fichier qui les contient, et non relativement à docs.json.
• Les références doivent pointer vers des fichiers JSON valides.
• Les chemins doivent être relatifs et rester dans la racine du projet. La traversée de chemin (par exemple, ../../outside) n’est pas autorisée.
• Les références circulaires provoquent une erreur de compilation.

​

Fusion des clés sœurs

Si un $ref résout en un objet, Mintlify fusionne les clés sœurs du même bloc par-dessus le contenu référencé, permettant à ces clés de prendre le dessus sur les clés correspondantes de la référence. Si un $ref résout en une valeur non-objet telle qu’un tableau, Mintlify ignore les clés sœurs.

docs.json

{
  "appearance": {
    "$ref": "./config/appearance.json",
    "strict": true
  }
}

​

Migration depuis mint.json

Si votre projet utilise le fichier mint.json obsolète, suivez ces étapes pour migrer vers docs.json.

1. Installer ou mettre à jour le CLI

   Si vous n’avez pas installé le CLI, installez-le maintenant :

   npm

   npm i -g mint
   

   Si vous avez déjà le CLI installé, assurez-vous qu’il est à jour :

   mint update
   
2. Créer votre fichier docs.json

   Dans votre dépôt de documentation, exécutez :

   mint upgrade
   

   Cette commande crée un fichier docs.json à partir de votre mint.json existant. Vérifiez le fichier généré pour vous assurer que tous les paramètres sont corrects.

3. Supprimer votre fichier mint.json

   Après avoir vérifié que votre docs.json est correctement configuré, vous pouvez supprimer en toute sécurité votre ancien fichier mint.json.