docs.json

docs.json vit à la racine du dossier de la doc. Il reprend le format de Mintlify : les champs que Docs ne gère pas sont acceptés et ignorés, jamais refusés.

Pour l’autocomplétion dans ton éditeur, ajoute la ligne :

{ "$schema": "https://docs.hgdc.ch/docs.schema.json" }

Champs

Champ	Type	Obligatoire	Règle et rôle
$schema	texte	non	Adresse du schéma, pour l’autocomplétion.
name	texte	oui	Nom de la doc, en tête du site et dans llms.txt. 1 à 80 caractères.
description	texte	non	Présentation d’une phrase. 300 caractères au plus.
project	identifiant	non	Identifiant du projet dans la console. Il active l’assistant et permet l’indexation. 8 à 64 caractères, lettres minuscules et chiffres.
language	fr, en, de ou it	non	Langue du site. Défaut : fr.
base	chemin	non	Sous-chemin où la doc est servie, par exemple /docs. Un ou plusieurs segments, sans / final. Le site est alors écrit dans dist/docs/.
colors.primary	couleur	oui, si colors est présent	Couleur des liens et des éléments actifs, au format #rrggbb ou #rgb.
colors.dark	couleur	non	La même couleur, en mode sombre.
logo	chemin, ou objet	non	Un chemin, ou { "light": "…", "dark": "…" }. light est obligatoire dans l’objet.
favicon	chemin	non	Icône de l’onglet. Défaut : /favicon.svg.
navigation	objet	oui	Voir Navigation.
footer.socials	objet	non	Liens vers tes réseaux. Clés acceptées : github, gitlab, linkedin, x.com, mastodon, discord, youtube, instagram, bluesky. Les autres clés sont ignorées.
assistant.enabled	booléen	non	false retire le bouton de l’assistant du site. Défaut : true.
assistant.endpoint	adresse https://	non	Adresse de l’API de l’assistant. Par défaut, celle de Docs : ne la change que sur indication de HGDC.

Accepté mais sans effet pour l’instant : colors.light, logo.href, navbar.

Les chemins de logo et favicon partent de la racine de la doc, comme les liens. Le fichier déclaré ici est publié, même hors d’un dossier d’images.

Navigation

navigation accepte une seule des quatre formes suivantes. En écrire deux fait échouer le build.

Forme	Contenu
pages	Une liste de pages, sans groupe.
groups	Une liste de groupes.
tabs	Une liste d’onglets, chacun avec groups ou pages.
versions	Une liste de versions, chacune avec tabs, groups ou pages.

Détail des éléments :

Élément	Champs	Règle
Groupe	group, pages, expanded	group non vide. pages contient au moins une entrée : une page ou un groupe imbriqué. expanded vaut true par défaut ; false replie le groupe.
Onglet	tab, groups ou pages	tab non vide.
Version	version, default, tabs, groups ou pages	version de 1 à 32 caractères. Une seule version porte default: true. Sans drapeau, la première est la version par défaut. Deux versions ne peuvent pas avoir le même nom.
Page	chemin	Sans extension, sans / au début, sans ... Lettres, chiffres, tirets, tirets bas et /. Exemple : guides/publier.

Erreurs

Un docs.json invalide fait échouer le build, avec la liste des problèmes et leur chemin :

docs.json n'est pas un JSON valide : …
colors.primary : couleur attendue au format #rrggbb
navigation : utiliser une seule forme parmi versions, tabs, groups ou pages
navigation.versions : une seule version par défaut
navigation.versions : deux versions ont le même nom
docs.json cite des pages absentes du dossier :
- guides/facturer.mdx

Un identifiant project qui ne correspond pas au projet de la console produit un message du type : project : docs.json porte …. Recopie l’identifiant du projet visé depuis la console.

Voir aussi

• Organiser la navigation pour des exemples complets.
• Couleur, logo et favicon.
• Référence des composants.