Passer au contenu principal
Le mode headless de Mintlify 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 votre propre frontend personnalisé avec Astro et afficher votre contenu MDX ainsi que la configuration docs.json comme vous le souhaitez. Cette approche headless est utile lorsque vous avez besoin d’un contrôle total sur le design, la mise en page ou le comportement de votre documentation pour l’aligner sur un système de conception existant ou intégrer la documentation dans un site plus vaste, tout en continuant à utiliser Mintlify pour la publication, la recherche, les composants MDX et les fonctionnalités d’IA. L’intégration @mintlify/astro lit votre configuration docs.json et votre contenu MDX au moment de la compilation, puis transforme le tout dans un format qu’Astro peut afficher. Créez vos propres mises en page, composants et styles par-dessus. Ce guide vous accompagne pour configurer un projet Mintlify headless à partir du template de démarrage et l’exécuter en local.

Prérequis

  • Un compte Mintlify
  • Un compte GitHub
  • Node.js v20.17.0 ou version ultérieure (versions LTS recommandées)
  • Des connaissances de base en Astro
  • Un hébergeur qui exécute du code côté serveur, comme Node.js, pour la recherche et l’Assistant

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 app.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 Save changes.
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
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://app.mintlify.com/org-name/domain-name, votre sous-domaine est domain-name.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_.
N’ajoutez pas le préfixe PUBLIC_ à MINTLIFY_ASSISTANT_KEY. Astro intègre les variables PUBLIC_ dans le code client. Toute personne qui copie la clé depuis votre site peut utiliser vos crédits de l’Assistant et lire les pages protégées de votre projet.
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é :
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
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. Astro pré-rend vos pages en HTML statique. L’adaptateur Node.js les sert et exécute les routes serveur pour la recherche et l’Assistant. Le schéma env déclare MINTLIFY_ASSISTANT_KEY comme secret serveur : le serveur la lit à l’exécution et Astro ne l’écrit jamais dans le résultat de la compilation.

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 :
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(): Aplatit 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 :

Connecter la recherche et l’Assistant

Le modèle de démarrage inclut des composants de recherche et d’Assistant qui se connectent aux API de Mintlify via des routes serveur de votre site. Le navigateur n’appelle jamais directement les API de Mintlify, votre clé d’API de l’Assistant reste donc sur votre serveur.
  • Search : le composant SearchBar dans src/components/SearchBar.tsx envoie les requêtes à la route /api/search.
  • 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. Il envoie les messages à la route /api/assistant, qui renvoie la réponse en streaming.
Les deux routes se trouvent dans src/pages/api/ et nécessitent les variables d’environnement PUBLIC_MINTLIFY_SUBDOMAIN et MINTLIFY_ASSISTANT_KEY. Chaque route ajoute votre clé d’API à la requête et la transmet à Mintlify. Les routes définissent les options de la requête, comme les filtres de recherche, afin que les visiteurs ne puissent pas les modifier. Toute personne pouvant ouvrir votre site peut appeler ces routes, et chaque appel consomme vos crédits de l’Assistant.

Déployer votre site

Le modèle de démarrage utilise l’adaptateur Node.js, vous pouvez donc le déployer sur n’importe quel hébergeur qui exécute un serveur Node.js. Compilez le site et démarrez le serveur :
Définissez PUBLIC_MINTLIFY_SUBDOMAIN avant la compilation. Définissez MINTLIFY_ASSISTANT_KEY dans les variables d’environnement de votre hébergeur. Le serveur de production ne lit pas votre fichier .env. Pour déployer sur une plateforme comme Vercel, Netlify ou Cloudflare, remplacez l’adaptateur Node.js dans astro.config.mjs par l’adaptateur Astro de cette plateforme. La recherche et l’Assistant ne fonctionnent pas sans adaptateur.

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 sur votre hébergeur.