Navigation

Structurez et personnalisez la hiérarchie de navigation de votre documentation

La propriété navigation dans docs.json contrôle la structure et la hiérarchie d’informations de votre documentation.

Avec une configuration de navigation adéquate, vous pouvez organiser votre contenu pour que les utilisateurs trouvent exactement ce qu’ils recherchent.

​

Pages

Les pages sont le composant de navigation le plus fondamental. Elles correspondent aux fichiers MDX qui composent votre documentation.

Dans l’objet navigation, pages est un tableau dans lequel chaque entrée doit référencer le chemin d’accès vers un fichier de page.

{
  "navigation": {
    "pages": [
      "settings",
      "pages",
      "navigation",
      "themes",
      "custom-domain"
    ]
  }
}

​

Groupes

Utilisez des groupes pour organiser la navigation de votre barre latérale en sections. Les groupes peuvent être imbriqués, accompagnés de tags et stylisés avec des icônes.

Dans l’objet navigation, groups est un tableau où chaque entrée est un objet qui doit contenir un champ group et un champ pages. Les champs icon, tag et expanded sont facultatifs.

{
  "navigation": {
    "groups": [
      {
        "group": "Premiers pas",
        "icon": "play",
        "expanded": false,
        "pages": [
          "quickstart",
          {
            "group": "Édition",
            "icon": "pencil",
            "pages": [
              "installation",
              "editor"
            ]
          }
        ]
      },
      {
        "group": "Rédaction de contenu",
        "icon": "notebook-text",
        "tag": "NOUVEAU",
        "pages": [
          "writing-content/page",
          "writing-content/text"
        ]
      }
    ]
  }
}

​

État développé par défaut

Définissez expanded: true sur un groupe pour qu’il soit développé par défaut dans la barre latérale de navigation. Cela est utile pour mettre en avant des sections importantes ou améliorer la découverte du contenu clé.

{
  "group": "Prise en main",
  "expanded": true,
  "pages": ["quickstart", "installation"]
}

​

Tabs

Les Tabs créent des sections distinctes de votre documentation avec des chemins d’URL séparés. Les Tabs génèrent une barre de navigation horizontale en haut de votre documentation qui permet aux utilisateurs de passer d’une section à l’autre.

Dans l’objet navigation, tabs est un tableau où chaque entrée est un objet qui requiert un champ tab et peut contenir d’autres champs de navigation tels que des groupes, des pages, des icons ou des liens vers des pages externes.

{
  "navigation": {
    "tabs": [
      {
        "tab": "Référence API",
        "icon": "square-terminal",
        "pages": [
          "api-reference/get",
          "api-reference/post",
          "api-reference/delete"
        ]
      },
      {
        "tab": "SDK",
        "icon": "code",
        "pages": [
          "sdk/fetch",
          "sdk/create",
          "sdk/delete"
        ]
      },
      {
        "tab": "Blog",
        "icon": "newspaper",
        "href": "https://external-link.com/blog"
      }
    ]
  }
}

​

Menus

Les menus ajoutent des éléments de navigation déroulants à un onglet. Utilisez-les pour aider les utilisateurs à accéder directement à des pages spécifiques au sein d’un onglet.

Dans l’objet navigation, menu est un tableau où chaque entrée est un objet qui requiert un champ item et peut contenir d’autres champs de navigation tels que des groupes, des pages, des icon, ou des liens vers des pages externes.

{
  "navigation": {
    "tabs": [
      {
        "tab": "Outils de développeur",
        "icon": "square-terminal",
        "menu": [
          {
            "item": "API reference",
            "icon": "rocket",
            "groups": [
              {
                "group": "Points de terminaison principaux",
                "icon": "square-terminal",
                "pages": [
                  "api-reference/get",
                  "api-reference/post",
                  "api-reference/delete"
                ]
              }
            ]
          },
          {
            "item": "SDKs",
            "icon": "code",
            "description": "Les SDK sont utilisés pour interagir avec l'API.",
            "pages": [
              "sdk/fetch",
              "sdk/create",
              "sdk/delete"
            ]
          }
        ]
      }
    ]
  }
}

​

Ancres

Les ancres ajoutent des éléments de navigation persistants en haut de votre barre latérale. Utilisez-les pour structurer votre contenu, offrir un accès rapide à des ressources externes ou créer des appels à l’action bien visibles.

Dans l’objet navigation, anchors est un tableau où chaque entrée est un objet qui exige un champ anchor et peut contenir d’autres champs de navigation tels que des groupes, des pages, des icônes ou des liens vers des pages externes.

{
  "navigation": {
    "anchors": [
      {
        "anchor": "Documentation",
        "icon": "book-open",
        "pages": [
          "quickstart",
          "development",
          "navigation"
        ]
      },
      {
        "anchor": "Référence API",
        "icon": "square-terminal",
        "pages": [
          "api-reference/get",
          "api-reference/post",
          "api-reference/delete"
        ]
      },
      {
        "anchor": "Blog",
        "href": "https://external-link.com/blog"
      }
    ]
  }
}

Pour les ancres qui pointent uniquement vers des liens externes, utilisez le mot‑clé global. Les ancres dans un objet global doivent comporter un champ href et ne peuvent pas pointer vers un chemin relatif.

Les ancres globales sont particulièrement utiles pour créer des liens vers des ressources qui ne font pas partie de votre documentation mais devraient rester facilement accessibles à vos utilisateurs, comme un blog ou un portail d’assistance.

{
  "navigation": {
    "global":  {
      "anchors": [
        {
          "anchor": "Communauté",
          "icon": "house",
          "href": "https://slack.com"
        },
        {
          "anchor": "Blog",
          "icon": "pencil",
          "href": "https://mintlify.com/blog"
        }
      ]
    },
    "tabs": /*...*/
  }
}

​

Menus déroulants

Les menus déroulants se trouvent dans un menu extensible en haut de la navigation de votre barre latérale. Chaque élément d’un menu déroulant mène à une section de votre documentation.

Dans l’objet navigation, dropdowns est un tableau où chaque entrée est un objet qui requiert un champ dropdown et peut contenir d’autres champs de navigation tels que des groups, des pages, des icon ou des liens vers des pages externes.

{
  "navigation": {
    "dropdowns": [
      {
        "dropdown": "Documentation",
        "icon": "book-open",
        "pages": [
          "quickstart",
          "development",
          "navigation"
        ]
      },
      {
        "dropdown": "Référence API",
        "icon": "square-terminal",
        "pages": [
          "api-reference/get",
          "api-reference/post",
          "api-reference/delete"
        ]
      },
      {
        "dropdown": "Blog",
        "href": "https://external-link.com/blog"
      }
    ]
  }
}

​

Produits

Les produits créent une section de navigation dédiée pour organiser la documentation propre à chaque produit. Utilisez les produits pour séparer différentes offres, services ou grands ensembles de fonctionnalités au sein de votre documentation.

Dans l’objet navigation, products est un tableau où chaque entrée est un objet qui exige un champ product et peut contenir d’autres champs de navigation tels que des groupes, des pages, des icons ou des liens vers des pages externes.

{
  "navigation": {
    "products": [
      {
        "product": "Core API",
        "description": "Description de l'API Core",    
        "icon": "api",
        "groups": [
          {
            "group": "Prise en main",
            "pages": [
              "core-api/quickstart",
              "core-api/authentication"
            ]
          },
          {
            "group": "Points de terminaison",
            "pages": [
              "core-api/users",
              "core-api/orders"
            ]
          }
        ]
      },
      {
        "product": "Analytics Platform",
        "description": "Description de la plateforme Analytics",
        "icon": "chart-bar",
        "pages": [
          "analytics/overview",
          "analytics/dashboard",
          "analytics/reports"
        ]
      },
      {
        "product": "Mobile SDK",
        "description": "Description du SDK Mobile",
        "icon": "smartphone",
        "href": "https://mobile-sdk-docs.example.com"
      }
    ]
  }
}

​

OpenAPI

Intégrez des spécifications OpenAPI directement dans votre structure de navigation pour générer automatiquement la documentation de votre API. Créez des sections API dédiées ou placez des pages d’endpoints au sein d’autres éléments de navigation.

Définissez une spécification OpenAPI par défaut à n’importe quel niveau de votre hiérarchie de navigation. Les éléments enfants hériteront de cette spécification, sauf s’ils définissent la leur.

{
  "navigation": {
    "groups": [
      {
        "group": "Référence API",
        "openapi": "/path/to/openapi-v1.json",
        "pages": [
          "overview",
          "authentication",
          "GET /users",
          "POST /users",
          {
            "group": "Produits",
            "openapi": "/path/to/openapi-v2.json",
            "pages": [
              "GET /products",
              "POST /products"
            ]
          }
        ]
      }
    ]
  }
}

Pour en savoir plus sur la façon de référencer des endpoints OpenAPI dans votre documentation, consultez la page OpenAPI setup.

​

Versions

Divisez votre navigation en différentes versions. Les versions peuvent être sélectionnées à partir d’un menu déroulant.

Dans l’objet navigation, versions est un tableau dans lequel chaque entrée est un objet qui requiert un champ version et peut contenir n’importe quels autres champs de navigation.

{
  "navigation": {
    "versions": [
      {
        "version": "1.0.0",
        "groups": [
          {
            "group": "Premiers pas",
            "pages": ["v1/overview", "v1/quickstart", "v1/development"]
          }
        ]
      },
      {
        "version": "2.0.0",
        "groups": [
          {
            "group": "Premiers pas",
            "pages": ["v2/overview", "v2/quickstart", "v2/development"]
          }
        ]
      }
    ]
  }
}

​

Langues

Segmentez votre navigation par langue. Les langues sont sélectionnables depuis un menu déroulant.

Dans l’objet navigation, languages est un tableau dont chaque entrée est un objet qui requiert un champ language et peut contenir tout autre champ de navigation.

Nous prenons actuellement en charge les langues suivantes pour la localisation :

Arabic (ar)

Chinese (cn)

Chinese (zh-Hant)

Dutch (nl)

English (en)

French (fr)

German (de)

Indonesian (id)

Italian (it)

Japanese (jp)

Korean (ko)

Latvian (lv)

Norwegian (no)

Portuguese (pt-BR)

Russian (ru)

Spanish (es)

Swedish (sv)

Turkish (tr)

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [
          {
            "group": "Premiers pas",
            "pages": ["en/overview", "en/quickstart", "en/development"]
          }
        ]
      },
      {
        "language": "es",
        "groups": [
          {
            "group": "Premiers pas",
            "pages": ["es/overview", "es/quickstart", "es/development"]
          }
        ]
      }
    ]
  }
}

Pour des traductions automatiques, contactez notre équipe commerciale pour discuter de solutions.

​

Imbrication

Vous pouvez utiliser n’importe quelle combinaison d’ancres, d’onglets, de menus déroulants et de produits. Les composants peuvent être imbriqués les uns dans les autres de manière interchangeable pour créer la structure de navigation de votre choix.

Ancres

{
  "navigation": {
    "anchors": [
      {
        "anchor": "Anchor 1",
        "groups": [
          {
            "group": "Group 1",
            "pages": [
              "some-folder/file-1",
              "another-folder/file-2",
              "just-a-file"
            ]
          }
        ]
      },
      {
        "anchor": "Anchor 2",
        "groups": [
          {
            "group": "Group 2",
            "pages": [
              "some-other-folder/file-1",
              "various-different-folders/file-2",
              "another-file"
            ]
          }
        ]
      }
    ]
  }
}

​

Fil d’Ariane

Le fil d’Ariane affiche le chemin de navigation complet en haut des pages. Certains thèmes activent le fil d’Ariane par défaut, d’autres non. Vous pouvez contrôler son activation pour votre site à l’aide de la propriété styling dans votre docs.json.

Display full breadcrumbs

"styling": {
  "eyebrows": "breadcrumbs"
}

​

Configuration des interactions

Contrôlez la manière dont les utilisateurs interagissent avec les éléments de navigation à l’aide de la propriété interaction dans votre docs.json.

​

Activer la navigation automatique pour les groupes

Lorsqu’un utilisateur ouvre un groupe de navigation, certains thèmes redirigent automatiquement vers la première page du groupe. Vous pouvez modifier le comportement par défaut d’un thème avec l’option drilldown.

• Définissez true pour forcer la navigation automatique vers la première page lorsqu’un groupe de navigation est sélectionné.
• Définissez false pour empêcher la navigation et uniquement développer ou réduire le groupe lorsqu’il est sélectionné.
• Laissez la valeur non définie pour utiliser le comportement par défaut du thème.

Forcer la navigation

"interaction": {
  "drilldown": true  // Forcer la navigation vers la première page lorsqu’un utilisateur ouvre un menu déroulant
}