---
title: Référence docs.json
description: "Référence complète de chaque champ dans docs.json — thèmes, couleurs, navigation, onglets, intégration OpenAPI, branding, SEO, analytique et chat IA."
---

Le fichier `docs.json` est la configuration centrale de votre site de documentation Jamdesk.

<Tip>
  Les paramètres clés de votre docs.json sont affichés dans le Dashboard sous
  **Paramètres du projet → Points forts de la configuration**. Cette vue est en lecture seule
  et se met à jour automatiquement après chaque build réussi.
</Tip>

## Champs requis

### name

**Type :** `string` (requis)

Le nom de votre site de documentation. Affiché dans l'en-tête et l'onglet du navigateur.

```json
{ "name": "Acme API Docs" }
```

### theme

**Type :** `"jam" | "nebula" | "pulsar"` (requis)

<Tabs>
  <Tab title="jam">
    Design épuré et moderne avec la police Inter. Navigation basée sur l'en-tête.

    **Idéal pour :** La plupart des sites de documentation, les références API
  </Tab>
  <Tab title="nebula">
    Style aéré et détendu avec JetBrains Mono.

    **Idéal pour :** Documentation narrative, guides
  </Tab>
  <Tab title="pulsar">
    Design net et à fort contraste avec navigation en barre latérale.

    **Idéal pour :** Référence technique dense
  </Tab>
</Tabs>

### colors

**Type :** `object` (requis)

| Champ | Type | Requis | Description |
|-------|------|--------|-------------|
| `primary` | string (hex) | Oui | Couleur principale de la marque |
| `light` | string (hex) | Non | Accent pour le thème clair |
| `dark` | string (hex) | Non | Accent pour le thème sombre |

```json
{
  "colors": {
    "primary": "#635BFF",
    "light": "#7C75FF",
    "dark": "#4F46E5"
  }
}
```

## Branding

### favicon

**Type :** `string` ou `object`

Chemin vers votre fichier favicon (SVG recommandé). Fournissez une seule image pour les deux modes, ou des variantes `light` / `dark` séparées.

| Champ | Type | Description |
|-------|------|-------------|
| `light` | string | Favicon pour le mode clair (requis avec la forme objet) |
| `dark` | string | Favicon pour le mode sombre (optionnel — utilise `light` en repli) |

```json
{ "favicon": "/images/favicon.svg" }
```

```json
{
  "favicon": {
    "light": "/images/favicon.svg",
    "dark": "/images/favicon-dark.svg"
  }
}
```

### logo

**Type :** `object`

| Champ | Type | Description |
|-------|------|-------------|
| `light` | string | Logo pour le mode clair |
| `dark` | string | Logo pour le mode sombre |
| `href` | string | URL au clic sur le logo |

```json
{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp",
    "href": "https://yoursite.com"
  }
}
```

## Typographie

### fonts

**Type :** `object` (optionnel)

Remplacez la police par défaut du thème pour le texte courant et les titres. Chaque thème est livré avec une police par défaut optimisée — ne définissez `fonts` que si vous souhaitez un rendu différent.

Utiliser la même police partout :

```json
{
  "fonts": {
    "family": "Lora"
  }
}
```

Séparer les titres et le corps :

```json
{
  "fonts": {
    "heading": { "family": "Space Grotesk" },
    "body": { "family": "Inter" }
  }
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `family` | string | Nom de la famille de polices. Toute Google Font fonctionne — le build la récupère automatiquement |
| `weight` | number | Graisse unique à charger (ex. `400`). Omettez pour charger `400, 500, 600, 700` |
| `source` | string | URL ou chemin relatif `/` vers un fichier de police auto-hébergé. Ignore Google Fonts |
| `format` | `"woff"` \| `"woff2"` | Requis quand `source` est défini |

`heading` et `body` acceptent tous deux les mêmes champs. Voir [Thèmes → Typographie](/fr/customization/theming#typographie) pour les conseils de sélection de polices.

## Apparence

### appearance

**Type :** `object` (optionnel)

Contrôlez le comportement par défaut du mode sombre de votre site.

```json
{
  "appearance": {
    "default": "dark",
    "strict": true
  }
}
```

| Champ | Type | Défaut | Description |
|-------|------|--------|-------------|
| `default` | `"system"` \| `"light"` \| `"dark"` | `"system"` | Mode initial pour les nouveaux visiteurs |
| `strict` | boolean | `false` | Si `true`, masque le bouton de bascule dans la barre de navigation afin que les visiteurs restent sur le mode `default` |

Voir [Thèmes → Mode sombre](/fr/customization/theming#mode-sombre) pour le comportement du bouton de bascule.

## OpenAPI

### api.openapi

**Type :** `string | string[]`

Listez les fichiers de spec OpenAPI 3.x que vous souhaitez que Jamdesk valide et utilise pour les pages d'endpoint. Utilisez des chemins relatifs à votre `docs.json`.

```json docs.json
{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}
```

Une fois configuré, vous pouvez générer des pages d'endpoint en ajoutant un champ `openapi` dans le frontmatter d'une page :

```mdx
---
title: Create Ticket
openapi: /openapi/api.yaml POST /tickets
---
```

Si vous n'avez qu'une seule spec listée, vous pouvez aussi utiliser le format court :

```mdx
---
title: Create Ticket
openapi: POST /tickets
---
```

Voir [Exemple OpenAPI](/fr/api-reference/openapi-example) pour une page d'endpoint en conditions réelles et [Structure des répertoires](/fr/setup/directory-structure) pour le placement des fichiers.

Si votre site est multilingue, déposez un fichier `<spec>.<lang>.<ext>` à côté de chaque spec source (ex. `openapi/api.fr.yaml`) et Jamdesk le sert sur les URL de cette langue. Voir [Traduire les specs OpenAPI](/fr/setup/languages#traduction-des-specs-openapi).

### api.examples.languages

**Type :** `string[]`
**Défaut :** `["curl", "python", "javascript"]`

Choisissez les langages de programmation qui apparaissent dans les exemples de code API auto-générés sur les pages `openapi:`. L'ordre du tableau détermine l'ordre d'affichage des onglets, et le premier langage est sélectionné par défaut.

**Valeurs prises en charge :** `curl`, `bash`, `python`, `javascript`, `go`, `ruby`, `csharp`, `java`, `rust`, `php`

<Note>`bash` est un alias de `curl` ; les deux produisent le même résultat. Utilisez l'étiquette que vous préférez.</Note>

```json All supported languages
{
  "api": {
    "examples": {
      "languages": ["curl", "python", "javascript", "go", "ruby", "csharp", "java", "rust", "php"]
    }
  }
}
```

```json Custom subset
{
  "api": {
    "examples": {
      "languages": ["python", "javascript", "go"]
    }
  }
}
```

### api.examples.defaults

**Type :** `"required" | "all"`
**Défaut :** `"all"`

Contrôlez quels paramètres apparaissent dans les exemples de code auto-générés.

| Valeur | Comportement |
|--------|-------------|
| `"all"` | Les exemples incluent tous les paramètres avec des valeurs de remplacement |
| `"required"` | Les exemples n'incluent que les paramètres marqués comme `required` dans la spec |

```json
{
  "api": {
    "examples": {
      "defaults": "required"
    }
  }
}
```

### api.examples.prefill

**Type :** `boolean`
**Défaut :** `false`

Si `true`, l'[API Playground](/fr/api-reference/playground) pré-remplit les champs de paramètres avec les valeurs `example` de votre spec OpenAPI.

```json
{
  "api": {
    "examples": {
      "prefill": true
    }
  }
}
```

### api.playground.display

**Type :** `"interactive" | "simple" | "none"`
**Défaut :** `"interactive"`

Contrôle l'[API Playground](/fr/api-reference/playground) sur les pages d'endpoint. Un bouton « Essayer » apparaît par défaut sur chaque page `openapi:` et `api:`.

| Valeur | Comportement |
|--------|-------------|
| `"interactive"` | Mode playground complet : remplir les paramètres, générer du code, envoyer des requêtes (défaut) |
| `"simple"` | Remplir les paramètres et copier le code, mais sans bouton Envoyer |
| `"none"` | Playground désactivé |

```json
{
  "api": {
    "playground": {
      "display": "interactive"
    }
  }
}
```

Voir [API Playground](/fr/api-reference/playground) pour les détails d'utilisation et les substitutions par page.

### api.mdx.auth.method

**Type :** `"bearer" | "basic" | "key" | "cobo"`

Méthode d'authentification utilisée dans les exemples de code auto-générés. Quand ce champ est défini, les exemples incluent l'en-tête d'authentification approprié.

| Valeur | Format de l'en-tête |
|--------|---------------------|
| `"bearer"` | `Authorization: Bearer <token>` |
| `"basic"` | `Authorization: Basic <base64>` |
| `"key"` | En-tête personnalisé (voir `api.mdx.auth.name`) |
| `"cobo"` | Authentification spécifique à Cobo |

```json
{
  "api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
  }
}
```

### api.mdx.auth.name

**Type :** `string`

Nom d'en-tête personnalisé pour l'authentification par clé. Utilisé uniquement quand `api.mdx.auth.method` vaut `"key"`.

```json
{
  "api": {
    "mdx": {
      "auth": {
        "method": "key",
        "name": "X-API-Key"
      }
    }
  }
}
```

## Navigation

### tabsPosition

**Type :** `"top" | "left"`

Contrôle l'emplacement d'affichage des onglets de navigation.

| Valeur | Description |
|--------|-------------|
| `"top"` | Les onglets apparaissent dans la barre d'en-tête |
| `"left"` | Les onglets apparaissent en haut de la barre latérale |

La valeur par défaut dépend de votre thème :

| Thème | Défaut |
|-------|--------|
| jam | `"left"` |
| nebula | `"left"` |
| pulsar | `"top"` |

```json
{ "tabsPosition": "left" }
```

### anchors

**Type :** `array`

Liens externes qui apparaissent en haut de la barre latérale sur toutes les pages.

| Champ | Type | Requis | Description |
|-------|------|--------|-------------|
| `name` | string | Oui | Texte affiché |
| `href` | string | Oui | URL (lien externe) |
| `icon` | string | Non | Nom d'icône Font Awesome |

```json
{
  "anchors": [
    { "name": "Blog", "href": "https://blog.example.com", "icon": "newspaper" }
  ]
}
```

### navigation (structure)

**Type :** `object`

La structure de navigation de votre documentation. Voir [Navigation](/fr/navigation/overview) pour la documentation détaillée.

Les pages peuvent être des chaînes (titre auto-généré à partir du nom de fichier) ou des objets avec un titre personnalisé :

```json
"pages": [
  "introduction",
  { "page": "content/mdx-basics", "title": "MDX Basics" }
]
```

<Accordion title="Exemple de navigation de base">
```json
{
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  }
}
```
</Accordion>

## Barre de navigation et pied de page

### navbar

**Type :** `object`

| Champ | Type | Description |
|-------|------|-------------|
| `links` | array | Liens de navigation |
| `links[].label` | string | Texte du bouton par défaut |
| `links[].labels` | object | Substitutions optionnelles par langue, indexées par code de langue (ex. `fr`, `es`). Utilise `label` en repli |
| `links[].icon` | icon | Icône optionnelle à afficher à côté du libellé |
| `links[].href` | string | URL de destination |
| `primary` | object | Bouton CTA principal |
| `primary.label` | string | Texte du bouton par défaut |
| `primary.labels` | object | Substitutions optionnelles par langue, indexées par code de langue. Utilise `label` en repli |

```json
{
  "navbar": {
    "links": [
      {
        "label": "Blog",
        "labels": { "fr": "Blog", "es": "Blog" },
        "href": "/blog"
      },
      {
        "label": "Pricing",
        "labels": { "fr": "Tarifs", "es": "Precios" },
        "href": "/pricing"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "labels": { "fr": "Tableau de bord", "es": "Panel" },
      "href": "https://app.example.com"
    }
  }
}
```

<Note>
  `labels` est optionnel — les docs en langue unique peuvent l'omettre. Quand il est défini, la langue de l'URL courante (ex. `/fr/...`) sélectionne la substitution correspondante.
</Note>

### footer

**Type :** `object`

Configurez le pied de page avec des liens vers les réseaux sociaux et des colonnes de liens personnalisés.

```json
{
  "footer": {
    "socials": {
      "github": "https://github.com/yourorg",
      "x": "https://x.com/yourhandle",
      "discord": "https://discord.gg/yourserver"
    },
    "links": [
      {
        "header": "Resources",
        "items": [
          { "label": "Blog", "href": "https://example.com/blog" },
          { "label": "Changelog", "href": "/changelog" }
        ]
      }
    ]
  }
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `socials` | object | URLs des plateformes de réseaux sociaux |
| `links` | array | Configurations des colonnes de liens |
| `links[].header` | string | En-tête de colonne |
| `links[].items` | array | Tableau d'objets `{ label, href }` |

**Plateformes sociales prises en charge :** `github`, `x`, `twitter`, `linkedin`, `discord`, `slack`, `youtube`, `instagram`, `facebook`, `reddit`, `telegram`, `bluesky`, `threads`, `medium`, `hacker-news`, `website`

## Styles

### styling.latex

**Type :** `boolean`

Active le rendu mathématique LaTeX avec KaTeX. Une fois activé, vous pouvez utiliser `$...$` pour les maths en ligne et `$$...$$` pour les équations en bloc.

```json
{
  "styling": {
    "latex": true
  }
}
```

Voir [Maths et LaTeX](/fr/content/math) pour les détails d'utilisation.

### styling.js

**Type :** `string | string[]`

Fichier(s) JavaScript personnalisé(s) à inclure sur chaque page. Les chemins sont relatifs à votre répertoire docs et doivent commencer par `/`.

```json
{
  "styling": {
    "js": "/script.js"
  }
}
```

Passez un tableau pour plusieurs fichiers :

```json
{
  "styling": {
    "js": ["/chat.js", "/analytics.js"]
  }
}
```

Sans ce champ, Jamdesk détecte automatiquement les fichiers `.js` à la racine de votre projet. Voir [JavaScript personnalisé](/fr/customization/custom-javascript) pour les détails.

## Chat

### chat

**Type :** `object` (optionnel)

Configurez l'assistant de chat IA intégré. Le chat est activé par défaut sur tous les sites ; vous n'avez besoin de ce champ que pour personnaliser les questions de démarrage ou le désactiver.

| Champ | Type | Défaut | Description |
|-------|------|--------|-------------|
| `enabled` | boolean | `true` | Mettez `false` pour supprimer le panneau de chat de votre site |
| `starterQuestions` | string[] | auto-générées | Jusqu'à 4 questions affichées à l'ouverture du chat (5 à 200 caractères chacune). Auto-générées lors des builds si omises. Mettez `[]` pour n'en afficher aucune |

```json
{
  "chat": {
    "starterQuestions": [
      "How do I get started?",
      "What API endpoints are available?"
    ]
  }
}
```

Voir [Chat IA](/fr/ai/chat) pour les détails sur le fonctionnement du chat et ce que voient les visiteurs.

## Menu Actions IA

### contextual

**Type :** `object` (optionnel)

Configurez le menu déroulant Actions IA qui apparaît sur chaque page. Activé par défaut avec toutes les options ; vous n'avez besoin de ce champ que pour personnaliser les options affichées ou désactiver le menu.

| Champ | Type | Défaut | Description |
|-------|------|--------|-------------|
| `enabled` | boolean | `true` | Mettez `false` pour supprimer le menu Actions IA de votre site |
| `options` | array | toutes les intégrées | Liste de clés d'options et/ou d'objets d'options personnalisés |

**Clés d'options intégrées :** `copy`, `view`, `chatgpt`, `claude`, `perplexity`, `gemini`, `mcp`, `cursor`, `vscode`

```json
{
  "contextual": {
    "options": ["copy", "claude", "mcp", "cursor"]
  }
}
```

Ajoutez des options personnalisées aux côtés des options intégrées :

```json
{
  "contextual": {
    "options": [
      "copy",
      "claude",
      {
        "title": "Ask on Discord",
        "description": "Get help from the community",
        "icon": "discord",
        "href": "https://discord.gg/your-server"
      }
    ]
  }
}
```

Voir [Menu Actions IA](/fr/ai/ai-actions) pour la liste complète des options et le format des options personnalisées.

## Vérification orthographique

### spellcheck

**Type :** `object` (optionnel)

Configurez la commande CLI `jamdesk spellcheck`. Vous n'avez besoin de ce champ que pour ajouter des mots spécifiques au projet à la liste d'exclusion.

| Champ | Type | Description |
|-------|------|-------------|
| `ignore` | string[] | Mots à ignorer lors de la vérification orthographique (noms de produits, termes techniques, etc.) |

```json
{
  "spellcheck": {
    "ignore": ["Acme", "kubectl", "Terraform"]
  }
}
```

La CLI inclut plus de 180 termes techniques intégrés (API, GraphQL, Kubernetes, React, etc.) et ignore automatiquement le nom de votre projet défini dans le champ `name`. N'ajoutez que les mots spécifiques à votre projet.

Voir [Aperçu CLI : Vérification orthographique](/fr/cli/overview) pour les détails d'utilisation et le mode de correction interactif.

## Images

### images.convertToWebp

**Type :** `boolean` (optionnel, défaut `false`)

Active la conversion automatique en WebP des ressources PNG et JPG lors des builds. Les fichiers convertis sont généralement 60 à 80 % plus légers que les originaux sans perte de qualité visible. Les références dans votre MDX, CSS personnalisé, JS personnalisé et `docs.json` sont réécrites automatiquement, vous n'avez donc aucun chemin à modifier.

Les favicons, `og:image` et `twitter:image` restent dans leur format d'origine. Tous les robots d'exploration de réseaux sociaux ou clients de messagerie ne gèrent pas le WebP de manière fiable, et une carte de preview brisée est pire qu'un JPG légèrement plus lourd.

```json
{
  "images": {
    "convertToWebp": true
  }
}
```

Voir [Conversion automatique des images](/fr/builds/image-optimization) pour ce qui est converti, le fonctionnement du cache et l'indicateur de progression du build.

## Contrôle d'accès

### auth.password

**Type :** `object` (optionnel)

Activez la protection par mot de passe partagé pour votre site. Configuration déclarative uniquement. Vous devrez toujours définir la phrase de passe dans le [dashboard](/fr/setup/password-protection#rotation-et-r-vocation-des-sessions) après le prochain build.

Définissez `auth.password.enabled: true` pour verrouiller tout le site, ou listez des chemins sous `auth.password.private[]` pour protéger uniquement ces pages. Les deux déclenchent la même invite de mot de passe dans le dashboard lors du prochain build.

```json
{
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask your account manager",
      "public": ["/marketing/**", "/changelog"]
    }
  }
}
```

| Champ | Type | Description |
|-------|------|-------------|
| `enabled` | `boolean` | Mode site entier. Si `true`, chaque page requiert le mot de passe (sauf celles marquées publiques). |
| `hint` | `string` (200 caractères max) | Indication en texte brut affichée sur l'écran de déverrouillage. Pas de HTML. |
| `public` | `string[]` | Globs de chemins qui contournent le mot de passe. Supporte `*` (un segment) et `**` (récursif). Un `/` seul est rejeté. |
| `private` | `string[]` | Chemins exacts qui requièrent le mot de passe. Définir ceci sans `enabled` active le mode pages spécifiques. |

Voir [Protection par mot de passe](/fr/setup/password-protection) pour le guide complet, y compris le flux dans le dashboard et l'interaction entre le frontmatter `public: true` / `private: true` et ces tableaux.

## Exemple complet

<Accordion title="Exemple complet de docs.json" defaultOpen>
```json
{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Documentation",
  "description": "Learn how to use Acme",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "favicon": "/images/favicon.svg",
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "api": {
    "openapi": ["/openapi/api.yaml"],
    "playground": {
      "display": "interactive"
    },
    "examples": {
      "languages": ["curl", "python", "javascript"],
      "prefill": true
    }
  },
  "styling": {
    "latex": true,
    "js": "/script.js"
  },
  "chat": {
    "starterQuestions": ["How do I get started?", "What endpoints are available?"]
  },
  "contextual": {
    "options": ["copy", "claude", "chatgpt", "mcp", "cursor"]
  },
  "spellcheck": {
    "ignore": ["Acme"]
  },
  "anchors": [
    { "name": "Blog", "href": "https://blog.acme.com", "icon": "newspaper" }
  ],
  "navbar": {
    "links": [
      { "label": "Support", "href": "/support" }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "href": "https://app.acme.com"
    }
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Get Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["api/users", "api/posts"]
          }
        ]
      }
    ]
  }
}
```
</Accordion>

## Et ensuite ?

<Columns cols={2}>
  <Card title="Aperçu de la navigation" icon="sitemap" href="/fr/navigation/overview">
    Structurez la navigation de votre documentation
  </Card>
  <Card title="Menu Actions IA" icon="wand-magic-sparkles" href="/fr/ai/ai-actions">
    Personnalisez le menu déroulant IA sur chaque page
  </Card>
</Columns>