Paramètres globaux

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.

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.

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

Paramètres

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é.

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

{
  "groups": [
    {
      "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.

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.

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

Migration depuis mint.json

Si votre projet utilise le fichier mint.json obsolète, utilisez la CLI pour migrer vers docs.json.

npm i -g mint

mint update

mint dev