# Organiser la navigation

Le résultat : une barre latérale qui reflète le plan de ta doc.

**Avant de commencer** : un `docs.json` avec des pages à ranger.

La navigation se décrit dans `docs.json`, sous `navigation`. Tu choisis **une seule** forme parmi `pages`, `groups`, `tabs` et `versions`. En écrire deux à la fois fait échouer le build.

## Pages et groupes

Pour une petite doc, une liste de groupes suffit. Un groupe peut contenir d’autres groupes :

```json
{
  "navigation": {
    "groups": [
      { "group": "Démarrer", "pages": ["index", "installation"] },
      {
        "group": "Guides",
        "pages": [
          "guides/facturer",
          { "group": "Avancé", "expanded": false, "pages": ["guides/webhooks"] }
        ]
      }
    ]
  }
}
```

- Un chemin de page s’écrit sans extension et sans `/` au début : `guides/facturer` désigne `guides/facturer.mdx`.
- `expanded: false` replie un groupe au chargement. Par défaut, il est ouvert.
- Un groupe contient au moins une page.

## Onglets

Au-delà d’une vingtaine de pages, sépare les grandes parties en onglets. Chaque onglet a ses propres groupes et s’affiche en haut de la barre latérale :

```json
{
  "navigation": {
    "tabs": [
      { "tab": "Guides", "groups": [{ "group": "Démarrer", "pages": ["index"] }] },
      { "tab": "Référence", "groups": [{ "group": "API", "pages": ["reference/api"] }] }
    ]
  }
}
```

## Versions

Quand ton produit garde plusieurs versions en service, chacune peut avoir sa doc. Le visiteur passe de l’une à l’autre avec un menu en haut de la barre latérale :

```json
{
  "navigation": {
    "versions": [
      { "version": "v2", "default": true, "groups": [{ "group": "Démarrer", "pages": ["index"] }] },
      { "version": "v1", "groups": [{ "group": "Démarrer", "pages": ["v1/index"] }] }
    ]
  }
}
```

- Le nom de version compte 32 caractères au plus, et deux versions ne peuvent pas porter le même nom.
- Une seule version porte `default: true`. Sans ce drapeau, la première est la version par défaut.
- L’assistant lit la version par défaut en priorité. `llms.txt` range les autres versions dans une section `Optional`.

## Précédent et suivant

En bas de chaque page, les liens **Précédent** et **Suivant** suivent l’ordre de la navigation, dans l’onglet ouvert.

## Si ça ne marche pas

- **`utiliser une seule forme parmi versions, tabs, groups ou pages`** : tu as mis deux formes dans `navigation`. Garde-en une.
- **`une seule version par défaut`** : deux versions portent `default: true`.
- **`deux versions ont le même nom`** : renomme l’une d’elles.
- **`docs.json cite des pages absentes du dossier`** : la liste donne les chemins introuvables. Corrige le chemin ou crée la page.