mintlify__docs/fr/organize/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](/fr/customize/themes) 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.

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

## Paramètres

<CardGroup cols={2}>
  <Card title="Apparence et identité visuelle" icon="palette" href="/fr/organize/settings-appearance">
    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.
  </Card>
  <Card title="Structure du site" icon="layout-panel-left" href="/fr/organize/settings-structure">
    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.
  </Card>
  <Card title="Paramètres d'API" icon="square-terminal" href="/fr/organize/settings-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.
  </Card>
  <Card title="Intégrations" icon="plug" href="/fr/organize/settings-integrations">
    Connectez votre site à des services tiers pour l'analytics, le chat et plus encore.
  </Card>
  <Card title="SEO et recherche" icon="search" href="/fr/organize/settings-seo">
    Contrôlez comment les moteurs de recherche indexent votre site, y compris les balises meta, la recherche et les horodatages des pages.
  </Card>
  <Card title="Référence du schéma" icon="code" href="/fr/organize/settings-reference">
    Référence complète de toutes les propriétés de `docs.json`.
  </Card>
</CardGroup>

<div id="split-configuration-with-ref">
## Diviser la configuration avec `$ref`
</div>

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

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

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

<div id="merging-sibling-keys">
### Fusion des clés sœurs
</div>

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.

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

## Migration depuis `mint.json`

Si votre projet utilise le fichier `mint.json` obsolète, utilisez la [CLI](/fr/cli) pour migrer vers `docs.json`.

<Steps>
  <Step title="Installer ou mettre à jour le CLI">
    Si vous n'avez pas installé le [CLI](/fr/cli/install), 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
    ```
  </Step>
  <Step title="Créer votre fichier docs.json">
    Dans votre dépôt de documentation, exécutez :

    ```bash
    mint dev
    ```

    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.
  </Step>
  <Step title="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`.
  </Step>
</Steps>