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.
- 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
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
- Sur la page Git settings, sélectionnez le référentiel que vous avez créé à partir du template de démarrage.
- Activez l’option Set up as monorepo.
- Saisissez
/docscomme chemin vers le répertoire contenant votre fichierdocs.json. - Cliquez sur Save changes.
5
Configurer les variables d’environnement
Clonez votre nouveau référentiel en local et créez un fichier 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
.env à la racine du projet avec vos identifiants Mintlify :.env
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_.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.docs/ et les packages Mintlify qui traitent et affichent ce contenu.
Configurez l’intégration mintlify() dans astro.config.mjs avec le chemin d’accès à votre répertoire de documentation :
astro.config.mjs
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.
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 :
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.
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
SearchBardanssrc/components/SearchBar.tsxenvoie les requêtes à la route/api/search. - Assistant : le composant
Assistantdanssrc/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.
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.
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 :
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.
Après avoir configuré votre projet :
- Remplacez le contenu initial dans
docs/par vos propres fichiers MDX et la configurationdocs.json. - Personnalisez les mises en page et les styles pour les adapter à votre système de conception.
- Déployez votre site sur votre hébergeur.