> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Documentation headless avec un frontend personnalisé
> Créez un frontend de documentation headless avec Astro en utilisant Mintlify pour la gestion de contenu, la recherche IA et les fonctionnalités d'assistant.
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](https://astro.build) 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.
| Feature | Availability | Notes |
| ------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mintlify components | Included | Utilisez des composants comme ``, `` et `` dans vos fichiers MDX sans les importer. |
| Content processing | Included | L'intégration `@mintlify/astro` lit votre `docs.json` et vos fichiers MDX et les traite au moment de la compilation. |
| Search | Included | Le composant `SearchBar` se connecte à l'API de recherche de Mintlify en utilisant le sous-domaine de votre projet. |
| AI assistant | Included | Le composant `Assistant` fournit une interface de chat IA alimentée par votre contenu. |
| Layouts and styling | Custom build | En-tête, pied de page, barre latérale, table des matières, modèles de page et tout le CSS. Le template de démarrage inclut des exemples construits avec Tailwind CSS. |
| Routing and navigation | Custom build | Une route générique Astro affiche chaque page. Utilisez `resolvePageData()` et `unwrapNav()` de `@mintlify/astro/helpers` pour résoudre l'état de navigation depuis `docs.json`. |
| Deployment and hosting | Custom build | Déployez votre site Astro sur n'importe quel hébergeur. |
| SEO | You build | Les balises meta, les balises Open Graph, le sitemap et `robots.txt` sont de votre responsabilité. |
| Third-party integrations | Custom build | Ajoutez les intégrations directement à votre mise en page Astro. Les outils configurés dans `docs.json` pour les projets hébergés ne s'appliquent pas en mode headless. |
| `llms.txt`, `llms-full.txt`, and `skill.md` | Custom build | Pour les projets headless, vous devez générer et servir ces fichiers vous-même. |
| Dashboard analytics | Custom build | Si vous utilisez le composant `Assistant`, les statistiques d'utilisation de l'assistant sont disponibles dans votre tableau de bord. Pour le trafic des pages, ajoutez votre propre fournisseur d'analytics à votre mise en page Astro. |
| Web editor | Not available | Nécessite l'environnement de rendu hébergé de Mintlify. |
| Authentication and password protection | Not available | Disponible uniquement pour les sites hébergés sur un sous-domaine Mintlify ou un domaine personnalisé pointant vers Mintlify. |
| API playground | Not available | Disponible uniquement pour les sites hébergés sur la plateforme Mintlify. |
| User feedback | Not available | La fonctionnalité de feedback est intégrée à la couche de rendu hébergée de Mintlify. |
| Preview deployments | Not available | Utilisez l'environnement de prévisualisation de votre hébergeur. |
| PDF export | Not available | Non disponible pour les projets headless. |
## Prérequis
* Un [compte Mintlify](https://dashboard.mintlify.com)
* Un [compte GitHub](https://github.com)
* [Node.js](https://nodejs.org) v20.17.0 ou version ultérieure (versions LTS recommandées)
* Des connaissances de base en [Astro](https://docs.astro.build)
## Configurer votre projet
Accédez au référentiel [mintlify-astro-starter](https://github.com/mintlify/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.
Si vous n’avez pas de compte Mintlify, inscrivez-vous sur [dashboard.mintlify.com/signup](https://dashboard.mintlify.com/signup).
Sur la page [Git settings](https://dashboard.mintlify.com/settings/deployment/git-settings) de votre tableau de bord Mintlify, installez la [Mintlify GitHub app](/fr/deploy/github). 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.
1. Sur la page [Git settings](https://dashboard.mintlify.com/settings/deployment/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**.
Clonez votre nouveau référentiel en local et créez un fichier `.env` à la racine du projet avec vos identifiants Mintlify :
```bash .env theme={null}
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](https://dashboard.mintlify.com/settings/organization/api-keys) de votre tableau de bord. La clé d’API de l’Assistant commence par `mint_dsc_`.
Installez les dépendances et démarrez le serveur de développement local dans votre référentiel cloné :
```bash theme={null}
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 :
```javascript astro.config.mjs theme={null}
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 :
```text theme={null}
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](/fr/organize/pages#page-metadata) 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 :
| File | Purpose |
| ------------------------------------ | -------------------------------------------------- |
| `src/layouts/Layout.astro` | Mise en page HTML racine |
| `src/pages/[...slug].astro` | Modèle de page et chargement des données |
| `src/components/Header.astro` | En-tête du site |
| `src/components/Sidebar/` | Navigation de la barre latérale |
| `src/components/TableOfContents.tsx` | Table des matières de la page |
| `src/styles/` | Styles globaux, typographie et palette de couleurs |
## 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 à 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.