# 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 :

```json
{ "$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](#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 :

```text
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](/docs/guides/navigation/) pour des exemples complets.
- [Couleur, logo et favicon](/docs/guides/theme-et-logo/).
- [Référence des composants](/docs/reference/composants/).