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. Il s'affiche dans l'en-tête et dans l'onglet du navigateur. Pour changer le format du titre de l'onglet, consultez seo.titleTemplate.

{ "name": "Acme API Docs" }

theme

Type : "jam" | "nebula" | "pulsar" | "halo" | "dusk" (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 distinctes.

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

Remplacez la police par défaut du thème pour le corps de texte et les titres. Chaque thème est livré avec une police par défaut soigneusement choisie. Ne définissez fonts que si vous voulez un autre rendu.

Utiliser la même police partout :

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

Séparer les titres et le corps de texte :

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

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

Apparence

appearance

Type : object (facultatif)

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

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

Consultez Thèmes → Mode sombre pour le fonctionnement du bouton de bascule.

Métadonnées de page

metadata

Type : object (facultatif)

Contrôlez les métadonnées affichées sur chaque page de la 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 : les pages que vous n'avez pas modifiées conservent donc leur date d'origine.

SEO

seo.titleTemplate

Type : string (facultatif) Valeur par défaut : %s — <nom>, où <nom> est votre name

Définissez le format du titre de page dans l'onglet du navigateur et dans les résultats de recherche. Placez %s à l'endroit où le titre de la page doit apparaître. Chaque %s est remplacé. Le modèle peut contenir jusqu'à 200 caractères. S'il ne contient pas %s, le build échoue et jamdesk validate affiche l'erreur.

{
  "seo": {
    "titleTemplate": "%s | Acme"
  }
}

Une page intitulée Getting started affiche alors Getting started | Acme. Utilisez "%s" seul pour omettre le nom du site. Cela ne modifie pas og:title ni twitter:title. Consultez Titres de page pour les pages sans titre.

seo.socialCard

Type : object (facultatif)

Modifiez la carte sociale que Jamdesk génère pour chaque page. Sans cette clé, les cartes conservent leur apparence par défaut.

{
  "seo": {
    "socialCard": {
      "theme": "dark",
      "brandColor": true
    }
  }
}

La carte ne peut dessiner que des logos SVG, PNG et JPG, et Jamdesk convertit les fichiers de logo PNG et JPG en WebP lors du build de votre site. Utilisez un logo SVG pour afficher votre logo complet sur la carte. La carte ne peut pas dessiner le texte d'un logo SVG : convertissez tout texte en contours (tracés) dans votre outil de conception, puis exportez de nouveau le SVG.

Consultez Personnaliser la carte sociale pour le détail de chaque option et l'image utilisée par une page.

Localisation

localization

Type : object (facultatif)

Contrôlez la manière dont les visiteurs accèdent à la version traduite de votre documentation.

{
  "localization": {
    "autoRedirect": true
  }
}

Seules les racines sont redirigées. Un lien profond tel que /guides/authentication renvoie toujours la page qu'il désigne : un lien que vous collez dans un ticket ouvre donc la même page pour tout le monde. Les robots des moteurs de recherche ne sont jamais redirigés, de sorte que vos balises hreflang continuent de déterminer ce qui est indexé.

La langue du visiteur est mémorisée pendant un an. Choisir une langue dans le sélecteur de langue remplace ensuite la correspondance automatique.

Consultez Support multilingue → Routage automatique de la langue pour le comportement complet.

Bannière

banner

Affichez une barre d'annonce sur tout le site, épinglée en haut de chaque page, au-dessus de l'en-tête, sur toute la largeur et 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 pour le moment.

OpenAPI

api.openapi

Type : string | string[]

Listez les fichiers de spécification OpenAPI 3.x que Jamdesk doit valider et utiliser pour les pages d'endpoint. Utilisez des chemins relatifs à votre docs.json.

{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}

Une fois cette option configurée, 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 ne listez qu'une seule spécification, vous pouvez aussi utiliser le format court :

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

Consultez Exemple OpenAPI pour une page d'endpoint réelle 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 exemple openapi/api.fr.yaml) et Jamdesk le sert sur les URL de cette langue. Consultez Traduire les spécifications OpenAPI.

navigation openapi (pages générées)

Type : object

Ajoutez un objet openapi à un onglet de navigation et définissez generate: true : Jamdesk crée au moment du build une page d'endpoint par opération de cette spécification, ainsi que les groupes de la barre latérale pour les accueillir. Rien à rédiger, rien à committer.

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Les pages générées se placent sous le nom de l'onglet, converti en slug, avec un slug construit à partir de la méthode et du chemin : l'onglet ci-dessus place POST /tickets à l'adresse /api-reference/post-tickets. Les opérations sont regroupées selon leur premier tag ; les spécifications sans tags se rabattent sur le premier segment de chemin significatif, de sorte que /api/v1/auctions/{auctionId} se retrouve sous Auctions. Les titres proviennent du summary de l'opération lorsque la spécification en fournit un, sinon de la méthode et du chemin. Une opération qui cible une seule ressource reçoit un titre au singulier (GET /users/{id} → « Get User »).

Un fichier .mdx committé l'emporte toujours en cas de collision de slug : vous pouvez donc adopter la génération progressivement, en l'activant puis en supprimant vos pages d'endpoint écrites à la main une par une, à votre rythme.

Si vous renommez plus tard un chemin dans votre spécification, le slug généré suit le changement. Jamdesk conserve un historique des slugs par opération et émet à chaque build une redirection de chaque ancienne URL vers l'URL actuelle, afin que les liens entrants et les favoris survivent au renommage. Vos propres redirections et toute page existante restent prioritaires.

Limites actuelles. La génération ne fonctionne que sur les navigation.tabs de premier niveau, pas sur les groupes, les ancres ni les onglets imbriqués sous languages ou versions, et elle ne produit des pages que pour votre langue par défaut. Une clé directory est acceptée par le schéma mais n'a aucun effet sur l'emplacement des pages.

api.mdx.server

Type : string

URL de base utilisée dans les exemples de code des pages à frontmatter api: (celles rédigées en MDX, et non les pages openapi:, qui tirent leurs serveurs de la spécification).

{
  "api": {
    "mdx": {
      "server": "https://api.example.com"
    }
  }
}

api.examples.languages

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

Choisissez les langages de programmation qui apparaissent dans les exemples de code d'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" Par défaut : "all"

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

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

api.examples.prefill

Type : boolean Par défaut : false

Lorsque la valeur est true, le playground d'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" Par défaut : "interactive"

Contrôle le playground d'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"
    }
  }
}

Consultez playground d'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 générés automatiquement. Lorsqu'elle est définie, les exemples incluent l'en-tête d'authentification correspondant.

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

tabsAlignment

Type : "start" | "center" | "end"

Définit l'alignement horizontal de la rangée d'onglets lorsque les onglets sont dans l'en-tête (tabsPosition: "top"). Sans effet avec tabsPosition: "left", ni dans le thème Pulsar, qui place les onglets du haut sur le côté droit de l'en-tête.

{ "tabsPosition": "top", "tabsAlignment": "center" }

anchors

Type : array

Liens externes affichés 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. Consultez Navigation pour la documentation détaillée.

Les pages peuvent être des chaînes (titre généré automatiquement à 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

Configurez le pied de page avec des liens vers les réseaux 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 des formules mathématiques LaTeX avec KaTeX. Une fois activé, vous pouvez utiliser $...$ pour les formules en ligne et $$...$$ pour les équations en bloc.

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

Consultez Mathématiques 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 documentation 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. Consultez JavaScript personnalisé pour plus de 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 indicatif ou mettre en avant 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 l'objet complet { "name", "style", "library" }. Consultez Forme objet de l'icône. Lorsque popularPages est omis, Jamdesk affiche Quick Start et Introduction par défaut.

Chat

chat

Type : object (facultatif)

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épart, le nom et l'icône du bouton, ou pour le désactiver.

{
  "chat": {
    "label": "Acme Assistant",
    "icon": "/images/assistant.svg",
    "starterQuestions": [
      "How do I get started?",
      "What API endpoints are available?"
    ]
  }
}

Consultez Chat IA pour savoir comment le chat fonctionne et ce que voient les visiteurs.

Menu des actions IA

contextual

Type : object (facultatif)

Configurez le menu déroulant des actions IA qui apparaît sur chaque page. Il est activé par défaut avec toutes les options ; vous n'avez besoin de ce champ que pour choisir 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"]
  }
}

Ajoutez des options personnalisées en plus de celles qui sont 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"
      }
    ]
  }
}

Consultez Menu des actions IA pour la liste complète des options et le format des options personnalisées.

Vérification orthographique

spellcheck

Type : object (facultatif)

Configurez la commande CLI jamdesk spellcheck. Vous n'avez besoin de ce champ que pour ajouter à la liste d'exclusion des mots propres à votre projet.

{
  "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 indiqué dans le champ name. N'ajoutez que les mots propres à votre projet.

Consultez Présentation de la CLI : vérification orthographique pour les détails d'utilisation et le mode de correction interactif.

Images

images.convertToWebp

Type : boolean (facultatif, false par défaut)

Active la conversion automatique en WebP des ressources PNG et JPG pendant les 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, votre CSS personnalisé, votre JS personnalisé et docs.json sont réécrites automatiquement : vous n'avez à modifier aucun chemin.

Les favicons, og:image et twitter:image conservent leur format d'origine. Certains robots des réseaux sociaux et clients de messagerie n'affichent pas 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
  }
}

Consultez Conversion automatique des images pour savoir ce qui est converti, comment fonctionne le cache et à quoi sert l'indicateur de progression du build.

Contrôle d'accès

auth.password

Type : object (facultatif)

Activez la protection par mot de passe partagé pour votre site. Il s'agit d'une configuration déclarative uniquement : vous définissez le mot de passe lui-même dans le dashboard une fois le build suivant exécuté.

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

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

Consultez Protection par mot de passe pour le guide complet, y compris le parcours dans le dashboard et la manière dont public: true / private: true dans le frontmatter interagissent avec ces tableaux.

auth.jwt

Type : object (facultatif)

Protégez tout le site derrière votre propre système de connexion. Votre backend signe un jeton de courte durée pour chaque utilisateur connecté, et Jamdesk l'échange contre un cookie de session. La clé de signature est générée dans le dashboard, pas dans ce fichier. auth.jwt et auth.password ne peuvent pas être activés tous les deux ; un build où les deux sont activés échoue avec une erreur config_error.

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/**", "/status"]
    }
  }
}

L'accès par page se règle en plus grâce à groups dans le frontmatter des pages. Consultez Authentification JWT pour le format du jeton, le flux de redirection et le fonctionnement des groupes.

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 ?