Référence docs.json

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

Champs obligatoires

name

Type : string (obligatoire)

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

{ "name": "Acme API Docs" }

theme

Type : "jam" | "nebula" | "pulsar" (obligatoire)

colors

Type : object (obligatoire)

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

Image de marque

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.

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

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

logo

Type : object

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

Typographie

fonts

Type : object (facultatif)

Remplace la police par défaut du thème pour le texte principal et les titres. Chaque thème est livré avec une valeur par défaut ajustée. Ne définissez fonts que si vous avez besoin d'un rendu différent.

Utiliser la même police partout :

{
  "fonts": {
    "family": "Lora"
  }
}

Séparer titres et corps de texte :

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

heading et body acceptent tous deux les mêmes champs. Voir Thème → Typographie pour des conseils sur le choix des polices.

Apparence

appearance

Type : object (facultatif)

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

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

Voir Thème → Mode sombre pour le comportement du bouton de bascule.

Métadonnées de page

metadata

Type : object (facultatif)

Contrôle les métadonnées de page affichées sur chaque page de documentation.

{
  "metadata": {
    "timestamp": true
  }
}

La date s'affiche sur votre site publié et dans jamdesk dev. Elle reflète le commit le plus récent ayant touché le fichier de chaque page, donc les pages que vous n'avez pas modifiées conservent leur date d'origine.

Bannière

banner

Affiche une barre d'annonce à l'échelle du site épinglée en haut de chaque page, au-dessus de l'en-tête, en pleine largeur, dans la couleur d'accent de votre thème. Utilisez-la pour les lancements, les migrations, les fenêtres de maintenance, ou tout message que chaque visiteur doit voir.

{
  "banner": {
    "content": "🎉 Version 2.0 is live! Read the [changelog](/changelog).",
    "dismissible": true
  }
}

La bannière s'affiche sur votre site publié et dans jamdesk dev. Elle est configurée globalement (une seule bannière pour tout le site) ; les bannières par onglet et par langue ne sont pas prises en charge actuellement.

OpenAPI

api.openapi

Type : string | string[]

Listez les fichiers de spécification OpenAPI 3.x que vous voulez que Jamdesk valide et utilise pour les pages d'endpoint. Utilisez des chemins relatifs à votre 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 :

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

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

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

Voir Exemple OpenAPI pour une page d'endpoint en direct et Structure des répertoires pour l'emplacement des fichiers.

Si votre site est multilingue, placez un fichier <spec>.<lang>.<ext> à côté de chaque spécification source (par ex. openapi/api.fr.yaml) et Jamdesk le sert sur les URL de cette langue. Voir Traduire les spécifications OpenAPI.

api.examples.languages

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

Choisissez les langages de programmation qui apparaissent dans les exemples de code API générés automatiquement 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

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

{
  "api": {
    "examples": {
      "languages": ["python", "javascript", "go"]
    }
  }
}

api.examples.defaults

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

Contrôle quels paramètres apparaissent dans les exemples de code générés automatiquement.

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

api.examples.prefill

Type : boolean Défaut : false

Quand true, le Playground API préremplit les champs de paramètres avec les valeurs example de votre spécification OpenAPI.

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

api.playground.display

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

Contrôle le Playground API sur les pages d'endpoint. Un bouton « Try it » apparaît par défaut sur chaque page openapi: et api:.

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

Voir Playground API pour les détails d'utilisation et les surcharges par page.

api.mdx.auth.method

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

Méthode d'authentification utilisée dans les exemples de code générés automatiquement. Une fois définie, les exemples incluent l'en-tête d'authentification approprié.

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

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

Navigation

tabsPosition

Type : "top" | "left"

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

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

{ "tabsPosition": "left" }

anchors

Type : array

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

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

navigation (structure)

Type : object

La structure de navigation de votre documentation. Voir Navigation 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é :

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

{
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  }
}

Barre de navigation et pied de page

navbar

Type : object

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

footer

Type : object

Configure le pied de page avec les liens sociaux et des colonnes de liens personnalisées.

{
  "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" }
        ]
      }
    ]
  }
}

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

Style

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.

{
  "styling": {
    "latex": true
  }
}

Voir Maths et LaTeX 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 de docs et doivent commencer par /.

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

Passez un tableau pour plusieurs fichiers :

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

Sans ce champ, Jamdesk détecte automatiquement les fichiers .js à la racine de votre projet. Voir JavaScript personnalisé pour les détails.

Recherche

search

Type : object (facultatif)

Personnalisez la barre de recherche de la documentation. La recherche fonctionne immédiatement ; vous n'avez besoin de ce champ que pour modifier le texte d'espace réservé ou faire apparaître des pages populaires dans l'état vide.

{
  "search": {
    "prompt": "Ask me anything…",
    "popularPages": [
      { "title": "Quick Start", "slug": "quickstart", "icon": "rocket" },
      { "title": "Authentication", "slug": "guides/authentication", "icon": "key" }
    ]
  }
}

Pages populaires

Chaque entrée de popularPages accepte :

Le champ icon accepte aussi la forme objet complète { "name", "style", "library" }. Voir Forme objet des icônes. Quand popularPages est omis, Jamdesk affiche Quick Start et Introduction par défaut.

Chat

chat

Type : object (facultatif)

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

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

Voir Chat IA pour les détails sur le fonctionnement du chat et ce que voient les visiteurs.

Menu Actions IA

contextual

Type : object (facultatif)

Configure 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 le désactiver.

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

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

Ajouter des options personnalisées en plus des options intégrées :

{
  "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 pour la liste complète des options et le format des options personnalisées.

Vérification orthographique

spellcheck

Type : object (facultatif)

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

{
  "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 à partir du champ name. N'ajoutez que des mots spécifiques à votre projet.

Voir Aperçu de la CLI : Vérification orthographique pour les détails d'utilisation et le mode de correction interactif.

Images

images.convertToWebp

Type : boolean (facultatif, défaut false)

Active la conversion automatique en WebP pour les 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, donc vous n'avez aucun chemin à modifier.

Les favicons, og:image, et twitter:image restent dans leur format d'origine. Tous les robots d'exploration des réseaux sociaux ou clients de messagerie ne rendent pas le WebP de façon fiable, et une carte d'aperçu cassée est pire qu'un JPG légèrement plus lourd.

{
  "images": {
    "convertToWebp": true
  }
}

Voir Conversion d'image automatique 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 (facultatif)

Optez pour la protection par mot de passe partagé de votre site. Configuration déclarative uniquement. Vous définissez toujours la phrase de passe réelle dans le dashboard après l'exécution du 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 du dashboard au prochain build.

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

Voir Protection par mot de passe pour le parcours complet, y compris le flux du dashboard et la façon dont les frontmatters public: true / private: true interagissent avec ces tableaux.

Exemple complet

{
  "$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"]
          }
        ]
      }
    ]
  }
}

Et ensuite ?