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

Branding

favicon

Type : string

Chemin vers votre fichier favicon (SVG recommandé).

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

logo

Type : object

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

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.

{
  "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 spec listée, vous pouvez également 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 le placement des fichiers.

Si votre site est multilingue, déposez un fichier <spec>.<lang>.<ext> à côté de chaque spec source (par exemple, openapi/api.fr.yaml) et Jamdesk le sert sur les URL de cette langue. Voir 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 supportées : 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ôlez quels paramètres apparaissent dans les exemples de code auto-générés.

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

api.examples.prefill

Type : boolean Défaut : false

Lorsque true, le playground API pré-remplit les champs de paramètres avec les valeurs example de votre spec 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 "Essayer" apparaît sur chaque page openapi: et api: par défaut.

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

Voir Playground API pour les détails d'utilisation et les remplacements 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. Lorsque défini, 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 lorsque api.mdx.auth.method est "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 de caractères (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 & 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

Configurez le pied de page avec des 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 supportées : github, x, twitter, linkedin, discord, slack, youtube, instagram, facebook, reddit, telegram, bluesky, threads, medium, hacker-news, website

Style

styling.latex

Type : boolean

Activez le rendu mathématique LaTeX avec KaTeX. Lorsqu'activé, vous pouvez utiliser $... pour les mathématiques en ligne et $...$ pour les équations en bloc.

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

Voir Math & 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 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 dans la racine de votre projet. Voir JavaScript personnalisé pour plus de 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.

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

Voir Chat IA pour plus de 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 le désactiver.

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

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

Ajoutez des options personnalisées aux côtés 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 (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.

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

Le 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 les mots spécifiques à votre projet.

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

Images

images.convertToWebp

Type : boolean (optionnel, défaut false)

Activez la conversion automatique en WebP pour les ressources PNG et JPG lors des builds. Les fichiers convertis sont généralement 60-80 % plus petits 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 pas à modifier les chemins.

Les favicons, og:image et twitter:image conservent leur format d'origine. Tous les robots d'indexation sociaux ou clients de messagerie ne rendent pas le WebP de manière fiable, et une carte de preview cassée est pire qu'un JPG légèrement plus grand.

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

Voir Conversion automatique d'images pour savoir ce qui est converti, comment fonctionne la mise en 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 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 les 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 lors du prochain build.

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

Voir Protection par mot de passe pour la procédure complète, y compris le flux du dashboard et comment le frontmatter public: true / private: true interagit 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 ?