Référence docs.json

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

Champs requis

name

Type : string (requis)

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" (requis)

colors

Type : object (requis)

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

{ "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 (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 :

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

Séparer les titres et le corps :

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

heading et body acceptent tous deux les mêmes champs. Voir Thèmes → 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.

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

Voir Thèmes → 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.

{
  "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 aussi utiliser le format court :

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

Voir Exemple OpenAPI pour une page d'endpoint en conditions réelles 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 (ex. openapi/api.fr.yaml) et Jamdesk le sert sur les URL de cette langue. Voir Traduire les 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

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

Si true, l'API Playground 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 l'API Playground sur les pages d'endpoint. Un bouton « Essayer » apparaît par défaut sur chaque page openapi: et api:.

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

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

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

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

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

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.

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

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

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

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

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

Voir Conversion automatique des images 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 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.

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

Voir Protection par mot de passe 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

{
  "$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 ?