settings.mdx

title	Paramètres globaux
description	Configurez votre site de documentation Mintlify avec docs.json, le fichier qui contrôle la navigation, l'apparence et les intégrations.
keywords	docs.json configuration setup mint.json

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.

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

Paramètres

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. 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. 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. Connectez votre site à des services tiers pour l'analytics, le chat et plus encore. 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 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é.

{
  "$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.

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

{
  "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.

Si vous n'avez pas installé le [CLI](/fr/installation), installez-le maintenant :

<CodeGroup>

```bash npm
npm i -g mint
```

```bash yarn
yarn global add mint
```

```bash pnpm
pnpm add -g mint
```

</CodeGroup>

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

```bash
mint update
```

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

```bash
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.

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