Créer des mises en page personnalisées

Utilisez les modes de page et les composants pour créer des landing pages, pages marketing et autres mises en page non standard sur Mintlify.

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.

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.

​

Ajouter des cartes de navigation

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.

​

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.

Les valeurs arbitraires de Tailwind CSS (par exemple, w-[350px]) ne sont pas prises en charge. Utilisez un fichier CSS personnalisé pour les valeurs que les classes utilitaires de Tailwind ne couvrent pas.

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é.