Documentation headless avec un frontend personnalisé

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.

• 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

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.

S’inscrire sur Mintlify

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

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.

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.

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 :

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.

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

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.

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.

Configurez l’intégration mintlify() dans astro.config.mjs avec le chemin d’accès à votre répertoire de documentation :

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.

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.

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.

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 :

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.

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.