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 :

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

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

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