Passer au contenu principal
Un frontend personnalisé vous permet de contrôler l’apparence et le comportement de votre documentation tout en utilisant Mintlify pour gérer votre contenu. Au lieu d’utiliser le frontend hébergé de Mintlify, vous pouvez créer le vôtre avec Astro et rendre votre contenu MDX ainsi que la configuration docs.json comme vous le souhaitez. C’est utile lorsque vous avez besoin d’un contrôle total sur le design, la mise en page ou le comportement de votre documentation. Par exemple, pour aligner celle-ci sur un design system existant ou intégrer la documentation dans un site plus vaste. L’intégration @mintlify/astro lit votre configuration docs.json et votre contenu MDX au moment du build, puis transforme le tout dans un format qu’Astro peut rendre. Utilisez vos propres mises en page, composants et styles par-dessus. Avec un frontend personnalisé, vous pouvez toujours utiliser les composants Mintlify sans les importer et vous conservez l’infrastructure de publication, de recherche et d’IA. Ce guide vous accompagne pour configurer un nouveau projet à partir du template de démarrage et l’exécuter en local.

​
Prérequis

​
Configurer votre projet

1

Créer un référentiel à partir du template de démarrage

Accédez au référentiel mintlify-astro-starter sur GitHub et cliquez sur Use this template pour créer un nouveau référentiel sur votre compte.Clonez le référentiel sur votre machine locale.
2

S’inscrire sur Mintlify

Si vous n’avez pas de compte Mintlify, inscrivez-vous sur dashboard.mintlify.com/signup.
3

Installer la GitHub App

Sur la page Git settings de votre tableau de bord Mintlify, installez la Mintlify GitHub app. Si l’application est déjà installée, désinstallez-la puis réinstallez-la afin d’être prêt à connecter votre nouveau référentiel.
4

Connecter votre référentiel

  1. Sur la page Git settings, sélectionnez le référentiel que vous avez créé à partir du template de démarrage.
  2. Activez l’option Set up as monorepo.
  3. Saisissez /docs comme chemin vers le répertoire contenant votre fichier docs.json.
  4. Cliquez sur Enregistrer les modifications.
Paramètres du référentiel sur la page Git settings.
5

Configurer les variables d’environnement

Clonez votre nouveau référentiel en local et créez un fichier .env à la racine du projet avec vos identifiants Mintlify :
.env
PUBLIC_MINTLIFY_SUBDOMAIN=your-subdomain
PUBLIC_MINTLIFY_ASSISTANT_KEY=your-assistant-api-key
Votre sous-domaine correspond au nom de domaine de votre projet. C’est la partie de l’URL de votre tableau de bord après le nom de l’organisation. Par exemple, si l’URL de votre tableau de bord est https://dashboard.mintlify.com/org-name/domain-name, votre sous-domaine est domain-name.Si vous avez une offre Pro ou Enterprise, générez une clé d’API de l’Assistant sur la page API keys de votre tableau de bord. La clé d’API de l’Assistant commence par mint_dsc_.
6

Démarrer le serveur de développement

Installez les dépendances et démarrez le serveur de développement local dans votre référentiel cloné :
cd path/to/your-repository
npm install
npm run dev
Votre site est maintenant disponible en local sur http://localhost:4321.

​
Fonctionnement

L’intégration relie trois éléments : le système de build Astro, votre contenu dans le répertoire docs/ et les packages Mintlify qui traitent et affichent ce contenu.

​
Configuration d’Astro

Configurez l’intégration mintlify() dans astro.config.mjs avec le chemin d’accès à votre répertoire de documentation :
astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import mdx from '@astrojs/mdx';
import { mintlify } from '@mintlify/astro';

export default defineConfig({
  integrations: [mintlify({ docsDir: './docs' }), react(), mdx()],
});
Au moment de la compilation, l’intégration lit votre docs.json et vos fichiers MDX à partir du chemin docsDir et les transforme dans .mintlify/docs/, où les collections de contenu d’Astro les chargent.

​
Structure du contenu

Le contenu de votre documentation se trouve dans le répertoire docs/, organisé de la même manière que dans n’importe quel autre projet Mintlify : 
docs/
├── docs.json          # Navigation et configuration du site
├── index.mdx          # Pages MDX pour le contenu
├── quickstart.mdx
└── guides/            # Répertoires pour organiser les pages
    ├── setup.mdx
    └── troubleshooting.mdx
Les fichiers MDX utilisent le frontmatter standard de Mintlify et peuvent recourir aux composants Mintlify sans avoir à les importer.

​
Routage et navigation

Une route générique (catch-all) affiche chaque page MDX. Le package @mintlify/astro/helpers fournit des fonctions pour déterminer l’état de la navigation à partir de votre docs.json.
  • resolvePageData(): Renvoie les onglets, la navigation de la barre latérale, les liens de pied de page et les ancres pour un chemin de page donné.
  • unwrapNav(): Aplatie l’arborescence de navigation en une liste pour le rendu de la barre latérale.

​
Mises en page et styles

Vous contrôlez entièrement la couche de présentation. Le modèle de base inclut des mises en page, une barre latérale, une table des matières et des styles conçus avec Tailwind CSS, mais vous pouvez remplacer n’importe lequel de ces éléments par les vôtres. Fichiers clés à personnaliser :
FilePurpose
src/layouts/Layout.astroMise en page HTML racine
src/pages/[...slug].astroModèle de page et chargement des données
src/components/Header.astroEn-tête du site
src/components/Sidebar/Navigation de la barre latérale
src/components/TableOfContents.tsxTable des matières de la page
src/styles/Styles globaux, typographie et palette de couleurs

​
Connecter la recherche et l’Assistant

L’Assistant est disponible avec les offres Pro et Enterprise.
Le modèle de démarrage inclut des composants de recherche et d’Assistant qui se connectent aux API de Mintlify à l’aide des variables d’environnement que vous configurez lors de la mise en place.
  • Search : le composant SearchBar dans src/components/SearchBar.tsx interroge l’API de recherche de Mintlify.
  • Assistant : le composant Assistant dans src/components/Assistant/ fournit une interface de chat IA qui répond aux questions en utilisant le contenu de votre documentation.
Les deux nécessitent les variables d’environnement PUBLIC_MINTLIFY_SUBDOMAIN et PUBLIC_MINTLIFY_ASSISTANT_KEY.

​
Prochaines étapes

Après avoir configuré votre projet :
  1. Remplacez le contenu initial dans docs/ par vos propres fichiers MDX et la configuration docs.json.
  2. Personnalisez les mises en page et les styles pour les adapter à votre système de conception.
  3. Déployez votre site Astro sur l’hébergeur de votre choix.