ESPACE PUBLICITAIRE DISPONIBLE · PARLONS-EN
Français
English简体中文繁體中文日本語EspañolPortuguês한국어DeutschFrançais
Tous les sites

Comment les équipes de documentation technique configurent leur image de marque, la barre latérale et les groupes d'onglets dans Mintlify

Décryptage
365Finds Editorial
11 430 articles Wiki répertoriés

Utilisez 365 Wiki avec votre IA

Copiez le prompt ci-dessous, collez-le dans l’IA que vous utilisez déjà, puis posez directement votre question.

Télécharger le Skill complet

Commencez par essayer le prompt. Si vous utilisez souvent 365 Wiki, installez le Skill 365Wiki complet pour ne plus avoir à le coller. Sans IA habituelle, les versions web de Gemini ou Microsoft Copilot conviennent aussi.

365Wiki Skill

Télécharger le Skill complet
Lors de la mise en place de portails de documentation destinés aux développeurs modernes, un nombre croissant d'équipes d'ingénierie et de rédaction technique adoptent Mintlify. Plutôt que de maintenir des configurations complexes de routage frontend ou des feuilles de style CSS surchargées, Mintlify s'inscrit dans la démarche « Docs-as-Code ». L'ensemble de l'identité visuelle et de l'architecture de l'information est centralisé dans un fichier de configuration déclaratif unique situé à la racine du dépôt : docs.json (auparavant mint.json). Les équipes peuvent ainsi définir leur charte graphique, structurer des barres latérales multiniveaux et organiser des groupes d'onglets directement dans un fichier JSON versionné aux côtés de leurs contenus MDX.


Ce guide détaille la manière dont les équipes de documentation technique configurent leur identité visuelle, conçoivent des barres latérales hiérarchisées et mettent en place des onglets supérieurs pour structurer des plateformes documentaires d'envergure.




1. Architecture de configuration centrale : La spécification docs.json


Chaque site Mintlify est administré par le fichier docs.json situé à la racine du projet. La spécification actuelle regroupe les thèmes graphiques, l'arborescence de navigation, la console d'exploration d'API et les intégrations analytiques au sein d'une structure de données unifiée.


Validation de schéma et règles de résolution de fichiers


Pour activer l'autocomplétion, la vérification syntaxique en temps réel et l'aide contextuelle dans les éditeurs de code comme VS Code, il est fortement recommandé de déclarer le schéma officiel au sommet de docs.json :


{
  "$schema": "https://mintlify.com/docs.json",
  "name": "Portail Développeur Acme",
  "theme": "maple"
}



Les conventions structurelles majeures de Mintlify sont les suivantes :





2. Configuration de l'image de marque et de l'identité visuelle


Mintlify permet d'aligner le portail sur le design system de l'entreprise sans recourir à des surcharges CSS instables. Les paramètres de marque sont configurés au niveau racine de docs.json.


Thèmes de mise en page (Theme)


Mintlify met à disposition plusieurs moteurs de rendu préconçus via la propriété theme :



Palette de couleurs et adaptation au mode sombre


L'objet colors définit les teintes principales de l'interface en garantissant un contraste adapté tant en mode clair qu'en mode sombre :


"colors": {
  "primary": "#2563EB",
  "light": "#60A5FA",
  "dark": "#1D4ED8"
}




Logos bimodes et Favicon


Pour assurer une netteté irréprochable quel que soit le mode d'affichage, il convient de renseigner des fichiers vectoriels SVG distincts pour les fonds clairs et sombres, ainsi qu'une URL de redirection :


"logo": {
  "light": "/images/logo-light.svg",
  "dark": "/images/logo-dark.svg",
  "href": "https://acme.com"
},
"favicon": "/images/favicon.svg"



Si logo.href n'est pas renseigné, un clic sur le logo redirige par défaut vers la page d'accueil de la documentation.


Typographie, bibliothèques d'icônes et fond de page





3. Conception de la barre latérale : Groupes, imbrication et pages racines


La barre latérale est l'axe directeur qui guide le lecteur à travers les guides et documentations de référence. Dans Mintlify, sa structure est entièrement décrite dans l'objet navigation.


Groupes élémentaires et icônes


Un groupe réunit plusieurs pages sous un intitulé commun. Chaque groupe exige un nom group et une liste pages :


"navigation": {
  "groups": [
    {
      "group": "Prise en main",
      "icon": "rocket",
      "pages": [
        "quickstart",
        "installation",
        "authentication"
      ]
    }
  ]
}



Imbrication hiérarchique et gestion du repli par défaut


À mesure que la documentation s'étoffe, les listes plates deviennent illisibles. Mintlify autorise l'imbrication de sous-groupes directement dans le tableau pages d'un groupe parent.


Pour préserver la clarté de la barre latérale, la propriété booléenne expanded détermine l'état d'ouverture initial :


{
  "group": "Architecture centrale",
  "icon": "cpu",
  "pages": [
    "architecture/overview",
    {
      "group": "Stockage des données",
      "icon": "database",
      "expanded": false,
      "pages": [
        "architecture/storage/relational",
        "architecture/storage/caching"
      ]
    },
    {
      "group": "Sécurité et conformité",
      "icon": "shield-check",
      "tag": "NEW",
      "pages": [
        "architecture/security/rbac",
        "architecture/security/encryption"
      ]
    }
  ]
}



Remarque : Les groupes de premier niveau restent constamment dépliés dans la barre latérale ; l'attribut expanded s'applique spécifiquement aux sous-groupes imbriqués.


Titres de groupes cliquables et pages racines (root)


Par défaut, cliquer sur le titre d'un groupe se contente d'ouvrir ou de fermer ses sous-éléments. Néanmoins, il est souvent souhaitable que le titre du groupe serve lui-même de page d'introduction générale.


La définition de la propriété root associe le titre du groupe à un document MDX précis :


{
  "group": "Référence API",
  "root": "api/overview",
  "pages": [
    "api/users",
    "api/billing",
    "api/webhooks"
  ]
}



Lorsqu'un lecteur clique sur « Référence API », le volet principal affiche immédiatement api/overview.mdx tout en dépliant les points de terminaison associés dans la barre latérale.


Sommaires automatiques de répertoires (directory)


Afin d'éviter la maintenance manuelle de listes de liens, Mintlify met à disposition la fonction directory pour les groupes dotés d'une page root. Le système injecte un index structuré sous le corps de la page racine.


Valeurs acceptées pour directory :



Cette propriété se transmet par héritage aux niveaux inférieurs, permettant d'appliquer "directory": "card" globalement et de le désactiver localement via "directory": "none" sur certaines sous-sections techniques.




4. Découpage de portails multiproduits via les groupes d'onglets (Tabs)


Lorsqu'un portail technique réunit des guides conceptuels, une référence complète d'API, des SDK dans plusieurs langages et des notes de version, regrouper l'ensemble dans une seule barre latérale linéaire sature la navigation. Les groupes d'onglets (Tabs) en en-tête apportent un découpage horizontal qui clarifie les grands axes documentaires.


Onglets de navigation au niveau du site


Les onglets délimitent des sections opérationnelles distinctes. Chaque onglet possède son propre espace de routes et une arborescence de barre latérale dédiée.


Configuration dans navigation.tabs :


"navigation": {
  "tabs": [
    {
      "tab": "Guides",
      "icon": "book-open",
      "groups": [
        {
          "group": "Fondamentaux",
          "pages": ["guides/overview", "guides/quickstart"]
        },
        {
          "group": "Déploiement",
          "pages": ["guides/docker", "guides/kubernetes"]
        }
      ]
    },
    {
      "tab": "Référence API",
      "icon": "square-terminal",
      "groups": [
        {
          "group": "Endpoints",
          "pages": ["api/v1/auth", "api/v1/payments", "api/v1/webhooks"]
        }
      ]
    },
    {
      "tab": "SDKs",
      "icon": "code-2",
      "groups": [
        {
          "group": "Clients officiels",
          "pages": ["sdks/node", "sdks/python", "sdks/go"]
        }
      ]
    },
    {
      "tab": "Journal des modifications",
      "icon": "megaphone",
      "href": "https://changelog.acme.com"
    }
  ]
}



Lorsque l'utilisateur navigue entre les onglets « Guides », « Référence API » et « SDKs » :


    

  1. La barre latérale commute instantanément pour ne présenter que les groupes et pages affiliés à l'onglet sélectionné.
    2. 

  2. L'URL du navigateur intègre le segment de chemin correspondant.
    3. 

  3. Les liens externes (renseignés avec href) s'intègrent visuellement dans l'en-tête tout en ouvrant la ressource ciblée.
    4. 



Menus déroulants au sein des onglets (menu)


Si un onglet principal englobe plusieurs produits indépendants, il est possible d'insérer une propriété menu pour proposer un menu déroulant dans l'en-tête :


{
  "tab": "Produits",
  "icon": "layers",
  "menu": [
    {
      "item": "Moteur de Paiement",
      "icon": "credit-card",
      "description": "Intégration des flux d'encaissement et de règlement.",
      "groups": [
        {
          "group": "Mise en route",
          "pages": ["payments/intro", "payments/checkout"]
        }
      ]
    },
    {
      "item": "Gestion des Identités",
      "icon": "key-round",
      "description": "Normes SSO, SAML et synchronisation d'annuaires.",
      "groups": [
        {
          "group": "Authentification",
          "pages": ["identity/overview", "identity/saml"]
        }
      ]
    }
  ]
}



Ancrages globaux (Anchors) vs. Onglets



Distinction essentielle : Onglets de site vs. composants <Tabs> dans MDX


Il convient de ne pas confondre les onglets globaux avec les composants de contenu :





5. Exemple complet prêt pour la production


Voici un fichier docs.json complet et directement déployable, intégrant l'identité visuelle, les ancrages globaux, plusieurs onglets, des sous-groupes hiérarchisés et un sommaire sous forme de cartes :


{
  "$schema": "https://mintlify.com/docs.json",
  "name": "Documentation CloudScale",
  "theme": "maple",
  "colors": {
    "primary": "#059669",
    "light": "#34D399",
    "dark": "#047857"
  },
  "logo": {
    "light": "/assets/brand/cloudscale-logo-light.svg",
    "dark": "/assets/brand/cloudscale-logo-dark.svg",
    "href": "https://cloudscale.dev"
  },
  "favicon": "/assets/brand/favicon.png",
  "appearance": {
    "default": "system",
    "strict": false
  },
  "fonts": {
    "family": "Inter"
  },
  "icons": {
    "library": "lucide"
  },
  "background": {
    "decoration": "gradient"
  },
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "État des services",
          "icon": "activity",
          "href": "https://status.cloudscale.dev"
        },
        {
          "anchor": "Communauté Slack",
          "icon": "messages-square",
          "href": "https://cloudscale.dev/slack"
        }
      ]
    },
    "tabs": [
      {
        "tab": "Guides Produits",
        "icon": "book-open",
        "groups": [
          {
            "group": "Vue d'ensemble et installation",
            "root": "guides/index",
            "directory": "card",
            "pages": [
              "guides/quickstart",
              "guides/architecture",
              "guides/cli-tooling"
            ]
          },
          {
            "group": "Infrastructure",
            "icon": "server",
            "pages": [
              "guides/compute-clusters",
              {
                "group": "Réseaux et DNS",
                "expanded": false,
                "pages": [
                  "guides/networking/vpc-peering",
                  "guides/networking/tls-certificates"
                ]
              }
            ]
          }
        ]
      },
      {
        "tab": "Référence API",
        "icon": "square-terminal",
        "groups": [
          {
            "group": "Authentification",
            "pages": [
              "api/auth/tokens",
              "api/auth/service-accounts"
            ]
          },
          {
            "group": "API Compute",
            "root": "api/compute/overview",
            "pages": [
              "api/compute/instances",
              "api/compute/snapshots"
            ]
          }
        ]
      }
    ]
  }
}





6. Bonnes pratiques de maintenance et prévention des erreurs


Pour assurer la stabilité et l'évolutivité de la documentation technique au sein d'une équipe en pleine croissance :


    

  1. Validation locale systématique avec la CLI : Avant de pousser vos commits sur le dépôt distant, exécutez npx mintlify dev sur votre machine. Le serveur local détecte instantanément les erreurs de syntaxe JSON, les fautes de frappe dans les chemins de fichiers et les pages manquantes.
    2. 

  2. Exactitude absolue des chemins de fichiers : Chaque entrée déclarée dans "pages" doit correspondre scrupuleusement à un fichier existant. Si un document MDX est renommé (par exemple guides/intro.mdx en guides/overview.mdx), mettez impérativement à jour docs.json dans le même commit Git.
    3. 

  3. Vérification du contraste en mode sombre : Lors de la configuration de colors.primary, ne négligez pas l'ajustement de colors.light. Un contraste insuffisant sur fond sombre nuit à la lisibilité et contrevient aux normes d'accessibilité WCAG AA.
    4. 

  4. Modération de la profondeur d'imbrication : Limitez la barre latérale à deux niveaux d'imbrication au maximum (groupe principal > sous-groupe > page). Une hiérarchie trop profonde génère des défilements horizontaux gênants sur mobile ; segmentez plutôt les sections volumineuses en onglets supérieurs (Tabs) ou en menus déroulants.
    5. 





Références


Produits abordés
Mintlify