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 : les onglets pour les sections de premier niveau, les groupes pour les dossiers repliables, et les pages pour les entrées individuelles. Les ancres ajoutent des liens externes qui apparaissent sur chaque page.

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

Aperçu de la structure

docs.json

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

Valeur	Position
`"top"`	Dans la barre d'onglets de l'en-tête
`"left"`	En haut de la barre latérale

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

Thème	Par défaut
jam	`"left"`
nebula	`"left"`
pulsar	`"top"`

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

Les icônes de la barre latérale s'affichent par défaut dans la variante Solid de Font Awesome. Modifiez le poids de n'importe quelle icône avec un préfixe de style (light/book) ou la forme objet de l'icône.

Liens externes (ancres)

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" }
  ]
}

Champ	Type	Obligatoire	Description
`name`	string	Oui	Texte affiché pour le lien
`href`	string	Oui	URL (s'ouvre dans un nouvel onglet)
`icon`	string	Non	Nom de l'icône Font Awesome

Groupes

Un groupe est un ensemble étiqueté d'entrées de la barre latérale à l'intérieur d'un onglet. Les groupes ajoutent un second niveau de hiérarchie à votre barre latérale et vous permettent de masquer les sections plus profondes derrière des dossiers de type accordéon.

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

Comportement des sections et accordéons

Les groupes de premier niveau sont des sections permanentes : le titre et ses pages sont toujours visibles, et cliquer sur le titre accède à la première page du groupe. Les groupes imbriqués nommés sont des accordéons repliables. Un groupe imbriqué démarre fermé, sauf s'il contient la page actuelle ou définit expanded: true. Au chargement initial et lors des changements de route, toute la chaîne d'ancêtres de la page actuelle s'ouvre automatiquement pour révéler le lien actif ; les visiteurs peuvent tout de même replier manuellement le groupe imbriqué actif.

Type de groupe	Comportement par défaut
Groupe de premier niveau	Toujours ouvert, sans chevron. Cliquer sur le titre navigue vers la première page du groupe.
Groupe imbriqué nommé	Replié jusqu'à ce qu'il soit actif, ouvert manuellement, ou configuré avec `expanded: true`. Cliquer sur un groupe fermé l'ouvre et cliquer sur un groupe ouvert le referme ; la navigation ne se produit que lorsque vous cliquez sur une page.
Conteneur sans nom	Affiche toujours ses pages car il n'a ni étiquette ni contrôle de bascule.

Utilisez les groupes de premier niveau pour les sections principales de votre barre latérale et les groupes imbriqués pour garder les sections plus longues faciles à parcourir. L'état d'expansion persiste pendant la navigation dans l'application et se réinitialise lors d'un rechargement complet de la page.

Barre latérale avec le groupe « Confidentialité et accès » replié : le chevron pointe vers la droite, les pages enfants sont masquées — Un groupe imbriqué à l'état replié. Le chevron pointe vers la droite et les pages enfants sont masquées.

Barre latérale avec le groupe « Confidentialité et accès » développé : le chevron est orienté vers le bas, trois pages enfants visibles en dessous — Le même groupe après avoir accédé à l'une de ses pages enfants. Le chevron pivote et les pages enfants apparaissent en dessous.

Champs du groupe

Champ	Type	Obligatoire	Description
`group`	string	Oui	Étiquette affichée dans la barre latérale.
`pages`	array	Oui	Liste de chemins de pages et/ou d'objets de groupe imbriqués (voir Groupes imbriqués pour la forme imbriquée).
`icon`	string	Non	Nom de l'icône Font Awesome affichée à côté de l'étiquette du groupe.
`tag`	string	Non	Petit badge à côté de l'étiquette (par exemple, `"New"`, `"Beta"`).
`root`	string	Non	Chemin de page vers lequel le groupe pointe lorsqu'on clique sur l'étiquette (au lieu d'accéder à la première page enfant).
`hidden`	boolean	Non	Masque le groupe de la barre latérale par défaut. Les pages restent accessibles par lien direct.
`public`	boolean	Non	Marque le groupe comme accessible publiquement. Par défaut, reprend le paramètre de l'onglet parent.
`expanded`	boolean	Non	Ouvre un groupe imbriqué nommé par défaut au premier chargement de la page. Les groupes de premier niveau sont toujours ouverts, donc l'indicateur n'a aucun effet visible sur eux. Les groupes ancêtres de la page actuelle s'ouvrent automatiquement au chargement initial et lors des changements de route.

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 affiché dans 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 sous la forme « Getting Started ».

Pour définir un titre personnalisé pour la barre latérale, utilisez un objet plutôt qu'une chaîne :

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

Cela est utile pour les acronymes, les noms propres et les badges d'endpoint d'API.

Champ	Type	Obligatoire	Description
`page`	string	Oui	Chemin de fichier sans `.mdx`
`title`	string	Non	Titre personnalisé pour la barre latérale
`icon`	string	Non	Nom de l'icône Font Awesome
`tag`	string	Non	Petit badge à côté du titre (par exemple, "New", "Beta")
`method`	string	Non	Badge de méthode HTTP : GET, POST, PUT, PATCH ou DELETE

Onglets multiples

Créez des sections distinctes 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

Créez un lien vers une documentation ou des ressources externes 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"]
    }
  ]
}

Étapes suivantes

Connecter GitHub

Connectez votre dépôt pour des builds automatiques

Structure des répertoires

Organisez votre documentation pour qu'elle passe à l'échelle