Navigation

Votre barre latérale et votre barre supérieure sont entièrement définies dans docs.json. La hiérarchie de navigation comporte trois niveaux — des onglets pour les sections de premier niveau, des groupes pour les dossiers repliables, et des pages pour les entrées individuelles — ainsi que des anchors pour les liens externes qui apparaissent sur toutes les pages.

Les captures d'écran montrent l'interface en anglais.

Aperçu de la structure

{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  }
}

Concepts

Onglets

Sections de navigation de premier niveau. Contrôlez leur position avec le paramètre tabsPosition :

La position par défaut dépend de votre thème :

{
  "tabsPosition": "left",
  "navigation": {
    "tabs": [
      { "tab": "Guides", "icon": "book", "groups": [...] },
      { "tab": "API", "icon": "code", "groups": [...] }
    ]
  }
}

Liens externes (Anchors)

Ajoutez des 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" },
    { "name": "Status", "href": "https://status.example.com", "icon": "signal" }
  ]
}

Groupes

Un groupe est un ensemble d'entrées de barre latérale étiquetées à l'intérieur d'un onglet. Les groupes donnent à votre barre latérale un rythme à deux niveaux et vous permettent de masquer les sections plus profondes derrière des dossiers de style accordéon.

{
  "group": "Authentication",
  "pages": ["auth/overview", "auth/tokens"]
}

Deux niveaux de rendu

La barre latérale affiche différemment les groupes de premier niveau et les groupes imbriqués :

Le niveau d'un groupe est positionnel : les groupes les plus externes sous un onglet s'affichent comme des groupes de premier niveau, et tout groupe placé dans le tableau pages d'un autre groupe s'affiche comme un dossier imbriqué. Il n'existe pas de propriété topLevel.

Utilisez les groupes de premier niveau pour les sections principales de votre barre latérale (Pour commencer, Référence, Guides) et les groupes imbriqués lorsqu'une section de premier niveau comporte suffisamment de pages pour qu'un second niveau de hiérarchie aide le lecteur à parcourir le contenu. Voir Groupes imbriqués pour la structure JSON.

Comportement des groupes imbriqués

• Développement automatique vers la page courante. Le groupe contenant la page que vous consultez s'ouvre automatiquement, de sorte que le lien actif est toujours visible.
• Cliquer pour basculer. Cliquer sur l'en-tête d'un groupe imbriqué le développe (et navigue vers sa première page) ou le réduit s'il est déjà ouvert.
• L'état persiste lors de la navigation dans l'application. Les groupes que vous ouvrez manuellement restent ouverts lorsque vous changez de page. Un rechargement complet de la page réinitialise l'état ouvert/fermé.

Champs d'un groupe

Pages

Pages de documentation individuelles, référencées par leur chemin de fichier (sans .mdx) :

"pages": ["introduction", "guides/quickstart", "api/endpoints"]

Par défaut, le titre de la barre latérale est généré à partir du nom de fichier — les tirets deviennent des espaces et chaque mot est mis en majuscule. Par exemple, "api/getting-started" s'affiche comme « Getting Started ».

Pour définir un titre de barre latérale personnalisé, utilisez un objet à la place d'une chaîne de caractères :

"pages": [
  "guides/quickstart",
  { "page": "deploy/aws", "title": "AWS Route 53 & CloudFront" },
  { "page": "content/seo", "title": "SEO" },
  { "page": "api/users", "title": "List Users", "method": "GET" }
]

C'est utile pour les acronymes, les noms propres et les badges d'endpoints API.

Plusieurs onglets

Créez des sections séparées pour différents publics :

{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "icon": "book",
        "groups": [
          { "group": "Getting Started", "pages": ["intro", "quickstart"] }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [{ "group": "Endpoints", "pages": ["api/auth", "api/users"] }]
      }
    ]
  }
}

Liens d'onglets externes

Liez vers une documentation externe ou des ressources directement depuis les onglets :

{
  "navigation": {
    "tabs": [
      { "tab": "Docs", "icon": "book", "groups": [...] },
      { "tab": "GitHub", "icon": "github", "href": "https://github.com/example/repo" }
    ]
  }
}

Les onglets externes s'ouvrent dans un nouvel onglet du navigateur.

Groupes imbriqués

Organisez une documentation complexe avec des structures imbriquées :

{
  "group": "SDKs",
  "pages": [
    "sdks/overview",
    {
      "group": "JavaScript",
      "pages": ["sdks/js/install", "sdks/js/usage"]
    },
    {
      "group": "Python",
      "pages": ["sdks/python/install", "sdks/python/usage"]
    }
  ]
}

Et ensuite ?