Créer des mises en page personnalisées

Les pages Mintlify utilisent une mise en page standard par défaut, avec une barre latérale, une zone de contenu et une table des matières. Personnalisez cette mise en page avec les modes de page pour créer des pages de destination, des vitrines de fonctionnalités ou toute page nécessitant un design unique. Ce guide explique comment utiliser les modes de page, Tailwind CSS et les composants pour créer des mises en page personnalisées.

Choisir un mode de page

Définissez le champ mode dans le frontmatter de votre page pour contrôler quels éléments d’interface apparaissent.

Mode	Barre latérale	Table des matières	Pied de page	Support des thèmes	Idéal pour
`default`	Oui	Oui	Oui	Tous les thèmes	Pages de documentation standard
`wide`	Oui	Non	Oui	Tous les thèmes	Pages sans titres ou nécessitant plus de largeur
`custom`	Non	Non	Non	Tous les thèmes	Pages de destination, pages marketing ou mises en page plein écran
`frame`	Oui	Non	Modifié	Aspen, Almond, Luma, Sequoia	Contenu personnalisé nécessitant une navigation par barre latérale
`center`	Non	Non	Oui	Mint, Linden, Willow, Maple	Journaux de modifications, expériences de lecture concentrée

Pour les pages de destination, le mode custom offre le plus de contrôle. Il supprime tous les éléments d’interface à l’exception de la barre de navigation supérieure, vous offrant une toile vierge pour construire. Les pages en mode personnalisé n’ont pas de typographie par défaut. Les éléments HTML natifs comme <h2> et <p> s’affichent avec les styles par défaut du navigateur ; stylisez-les donc explicitement avec des classes Tailwind CSS.

Example page frontmatter

---
title: "Welcome"
mode: "custom"
---

Créer une page de destination

Une page de destination typique combine une section hero, des cartes de fonctionnalités et des appels à l’action.

Configurer la page

Créez un fichier MDX avec le mode custom :

Example landing page frontmatter

---
title: "Documentation"
description: "Everything you need to build with our platform."
mode: "custom"
---

Créer une section hero

Utilisez du HTML avec des classes Tailwind CSS pour construire une section hero centrée :

Example hero section

<div className="px-4 py-16 lg:py-32 max-w-3xl mx-auto text-center">
  <h1 className="text-4xl font-medium text-gray-900 dark:text-zinc-50 tracking-tight">
    Documentation
  </h1>
  <p className="mt-4 text-lg text-gray-500 dark:text-zinc-500">
    Everything you need to build, deploy, and scale your application.
  </p>
</div>

Incluez des styles pour le mode clair et le mode sombre. Utilisez les classes Tailwind préfixées par dark: pour gérer le mode sombre.

Utilisez les composants Card et Columns pour créer une grille de liens sous la section hero :

Example navigation cards

<div className="max-w-4xl mx-auto px-6">
  <Columns cols={2}>
    <Card title="Quickstart" icon="rocket" href="/quickstart">
      Get up and running in under five minutes.
    </Card>
    <Card title="API reference" icon="code" href="/api-reference">
      Explore endpoints, parameters, and examples.
    </Card>
    <Card title="Guides" icon="book" href="/guides">
      Step-by-step tutorials for common tasks.
    </Card>
    <Card title="Components" icon="puzzle" href="/components">
      Reusable UI components for your docs.
    </Card>
  </Columns>
</div>

Utiliser des images avec support du mode sombre

Affichez différentes images pour le mode clair et sombre en utilisant les classes de visibilité de Tailwind :

Example images with dark mode support

<img
  src="/images/hero-light.png"
  alt="Platform overview showing the main dashboard."
  className="block dark:hidden"
/>
<img
  src="/images/hero-dark.png"
  alt="Platform overview showing the main dashboard."
  className="hidden dark:block"
/>

Utiliser des composants React pour des mises en page interactives

Pour des éléments réutilisables ou interactifs, définissez des composants React directement dans votre fichier MDX :

Example React component

export const FeatureCard = ({ title, description, href }) => (
  <a className="group block p-6 rounded-xl border border-gray-200 dark:border-zinc-800 hover:border-gray-300 dark:hover:border-zinc-700 transition-colors" href={href}>
    <h3 className="font-medium text-gray-900 dark:text-zinc-50 group-hover:underline">
      {title}
    </h3>
    <p className="mt-2 text-sm text-gray-500 dark:text-zinc-500">
      {description}
    </p>
  </a>
);

<div className="max-w-4xl mx-auto px-6 grid sm:grid-cols-2 gap-4">
  <FeatureCard
    title="Authentication"
    description="Set up OAuth, API keys, and session management."
    href="/guides/authentication"
  />
  <FeatureCard
    title="Webhooks"
    description="Receive real-time notifications for events."
    href="/guides/webhooks"
  />
</div>

Évitez d’utiliser la propriété style sur les éléments HTML. Cela peut provoquer un décalage de la mise en page au chargement de la page. Utilisez des classes Tailwind CSS ou un fichier CSS personnalisé à la place.

L’aperçu en direct de l’éditeur web ne génère pas le CSS des classes Tailwind propres à une page ; les mises en page personnalisées peuvent donc sembler sans style pendant que vous les modifiez. Vérifiez vos styles avec mint dev, un déploiement de prévisualisation ou un déploiement en production. Consultez Les classes Tailwind ne s’appliquent pas dans l’aperçu en direct de l’éditeur.

Ajouter du CSS personnalisé

Pour les styles que Tailwind ne couvre pas, ajoutez un fichier CSS à votre dépôt. Mintlify applique les fichiers CSS à l’ensemble du site, rendant leurs noms de classes disponibles dans tous les fichiers MDX. Utilisez un fichier CSS personnalisé lorsque vous avez besoin d’animations par keyframes, de sélecteurs complexes ou de styles qui s’appliquent à de nombreuses pages. Pour des valeurs ponctuelles, utilisez plutôt une valeur arbitraire Tailwind comme w-[350px].

Example custom CSS file

.landing-hero {
  background: linear-gradient(135deg, #f0f9ff 0%, #e0f2fe 100%);
  padding: 4rem 2rem;
}

@media (prefers-color-scheme: dark) {
  .landing-hero {
    background: linear-gradient(135deg, #0c1222 0%, #1a1a2e 100%);
  }
}

Puis référencez la classe dans votre MDX :

Example custom CSS usage

<div className="landing-hero">
  <h1>Welcome to the docs</h1>
</div>

Consultez Scripts personnalisés pour en savoir plus sur le CSS personnalisé et les sélecteurs CSS disponibles.

Exemple complet

Voici une page de destination complète qui combine une section hero avec des cartes de navigation :

Example landing page

---
title: "Documentation"
description: "Everything you need to build with our platform."
mode: "custom"
---

export const HeroCard = ({ title, description, href, icon }) => (
  <a className="group block p-6 rounded-xl border border-gray-200 dark:border-zinc-800 hover:border-gray-300 dark:hover:border-zinc-700 transition-colors" href={href}>
    <h3 className="font-medium text-gray-900 dark:text-zinc-50">
      {title}
    </h3>
    <p className="mt-2 text-sm text-gray-500 dark:text-zinc-500">
      {description}
    </p>
  </a>
);

<div className="px-4 py-16 lg:py-32 max-w-3xl mx-auto text-center">
  <h1 className="text-4xl font-medium text-gray-900 dark:text-zinc-50 tracking-tight">
    Documentation
  </h1>
  <p className="mt-4 text-lg text-gray-500 dark:text-zinc-500 max-w-xl mx-auto">
    Everything you need to build, deploy, and scale your application.
  </p>
</div>

<div className="max-w-4xl mx-auto px-6 pb-16 grid sm:grid-cols-2 gap-4">
  <HeroCard
    title="Quickstart"
    description="Get up and running."
    href="/quickstart"
  />
  <HeroCard
    title="API reference"
    description="Explore endpoints, parameters, and examples."
    href="/api-reference"
  />
  <HeroCard
    title="Guides"
    description="Step-by-step tutorials for common tasks."
    href="/guides"
  />
  <HeroCard
    title="SDKs"
    description="Client libraries for every major language."
    href="/sdks"
  />
</div>

Conseils

Testez en mode clair et sombre. Prévisualisez votre mise en page personnalisée dans les deux modes pour détecter les styles dark: manquants.
Utilisez les classes max-w-* pour limiter la largeur du contenu et garder le texte lisible.
Pensez au responsive. Utilisez les préfixes responsive de Tailwind (sm:, md:, lg:) pour que votre mise en page fonctionne sur tous les écrans.
Combinez les modes. Utilisez le mode custom pour la page d’accueil de votre documentation et le mode default pour le reste. Le mode se définit par page, ce qui permet à différentes pages d’utiliser différentes mises en page.
Vérifiez les décalages de mise en page. Si des éléments sautent au chargement de la page, remplacez les propriétés style en ligne par des classes Tailwind ou du CSS personnalisé.
Stylisez les composants directement. Les composants acceptent une prop className, ce qui vous permet d’ajuster une seule instance sans élément d’encapsulation ni surcharge CSS. Consultez Styliser les composants avec className.

Aperçu

IA

Documentation d'API

Bonnes pratiques

Git

Cas d'usage

Créer des mises en page personnalisées

Choisir un mode de page

Créer une page de destination

Configurer la page

Créer une section hero

Ajouter des cartes de navigation

Utiliser des images avec support du mode sombre

Utiliser des composants React pour des mises en page interactives

Ajouter du CSS personnalisé

Exemple complet

Conseils

​Choisir un mode de page

​Créer une page de destination

​Configurer la page

​Créer une section hero

​Ajouter des cartes de navigation

​Utiliser des images avec support du mode sombre

​Utiliser des composants React pour des mises en page interactives

​Ajouter du CSS personnalisé

​Exemple complet

​Conseils

Choisir un mode de page

Créer une page de destination

Configurer la page

Créer une section hero

Ajouter des cartes de navigation

Utiliser des images avec support du mode sombre

Utiliser des composants React pour des mises en page interactives

Ajouter du CSS personnalisé

Exemple complet

Conseils