Passer au contenu principal
Après avoir terminé ce guide, vous disposerez d’un site de documentation en ligne prêt à être personnalisé et enrichi.
Prérequis : Avant de commencer, créez un compte et terminez la configuration initiale.

​
Prise en main

Une fois le processus d’onboarding terminé, votre site de documentation est automatiquement déployé à une URL unique du type suivant : 
https://<nom-de-votre-projet>.mintlify.app
Trouvez votre URL sur la page Overview de votre dashboard.
Domaine Mintlify
L’URL de votre site est disponible immédiatement. Utilisez cette URL pour effectuer des tests et la partager avec votre équipe pendant que vous configurez votre site de documentation.

​
Installer l’application GitHub

Mintlify fournit une application GitHub qui automatise le déploiement lorsque vous envoyez des modifications vers votre dépôt. Installez l’application GitHub en suivant les instructions de la checklist d’onboarding ou de votre tableau de bord.
  1. Dans votre tableau de bord Mintlify, ouvrez Settings.
  2. Sélectionnez GitHub App dans la barre latérale.
  3. Sélectionnez Install GitHub App. Un nouvel onglet s’ouvre avec la page d’installation de l’application GitHub.
  4. Sélectionnez l’organisation ou le compte utilisateur sur lequel vous souhaitez installer l’application.
  5. Sélectionnez les dépôts que vous souhaitez connecter.
Installation de l'application GitHub
Mettez à jour les autorisations de l’application GitHub si vous déplacez votre documentation vers un autre dépôt.

​
Autoriser votre compte GitHub

  1. Accédez à Settings dans votre Tableau de bord Mintlify.
  2. Sélectionnez My Profile dans la barre latérale.
  3. Sélectionnez Authorize GitHub account. Un nouvel onglet s’ouvre vers la page d’autorisation GitHub.
Un administrateur de votre organisation GitHub peut devoir autoriser votre compte en fonction des paramètres de votre organisation.

​
Méthodes d’édition

Mintlify propose deux méthodes pour créer et maintenir votre documentation :

Méthode basée sur le code

Pour les utilisateurs qui préfèrent travailler avec leurs outils habituels en local. Cliquez pour accéder à cette section.

Méthode avec l’éditeur web

Pour les utilisateurs qui préfèrent une interface visuelle dans leur navigateur web. Cliquez pour accéder à cette section.

​
Flux de travail basé sur le code

Le flux de travail basé sur le code s’intègre à votre environnement de développement existant et à vos dépôts Git. Ce flux de travail est idéal pour les équipes techniques qui souhaitent gérer la documentation en parallèle du code.

​
Installer le CLI

Prérequis : le CLI nécessite Node.js v20.17.0 ou une version ultérieure jusqu’à la v24. Les versions LTS sont recommandées.
Pour travailler localement sur votre documentation, installez l’interface en ligne de commande (CLI), appelée mint, en exécutant la commande suivante dans votre terminal : 
npm i -g mint

​
Créer un nouveau projet

Exécutez mint new pour créer un nouveau projet de documentation. Consultez le guide d’installation de l’interface en ligne de commande (CLI) pour plus d’informations sur la commande et ses options.

​
Modifier la documentation

Après avoir configuré votre projet, vous pouvez commencer à éditer vos fichiers de documentation. Par exemple, mettez à jour le titre de la page d’introduction :
  1. Accédez à votre référentiel de documentation.
  2. Ouvrez index.mdx et repérez le début du fichier :
index.mdx
---
title: "Introduction"
description: "Ceci est l'introduction de la documentation"
---
  1. Mettez à jour le champ title avec la valeur "Hello World".
index.mdx
---
title: "Bonjour le monde"
description: "Ceci est l'introduction de la documentation"
---

​
Prévisualiser les modifications

Pour prévisualiser localement les modifications, exécutez la commande suivante : 
mint dev
Votre aperçu est disponible sur localhost:3000.
Mintlify Dev

​
Envoyer les modifications

Lorsque vous êtes prêt à publier vos modifications, poussez-les sur votre dépôt. Mintlify détecte automatiquement les modifications, génère votre documentation et déploie les mises à jour sur votre site. Surveillez l’état du déploiement dans l’historique des commits de votre dépôt GitHub ou sur le tableau de bord. Une fois le déploiement terminé, votre dernière mise à jour sera disponible à l’adresse <your-project-name>.mintlify.app.

Passer à l’ajout d’un domaine personnalisé

Si vous le souhaitez, vous pouvez ignorer le flux de travail de l’éditeur web et passer directement à l’ajout d’un domaine personnalisé.

​
Flux de travail de l’éditeur web

Le flux de travail de l’éditeur web propose une interface WYSIWYG (What You See Is What You Get) pour créer et modifier la documentation. Il convient particulièrement à celles et ceux qui souhaitent travailler dans leur navigateur web sans recourir à des outils de développement locaux supplémentaires.

​
Accéder à l’éditeur web

  1. Connectez-vous à votre tableau de bord.
  2. Sélectionnez Editor dans la barre latérale gauche.
Si vous n’avez pas installé l’application GitHub, vous serez invité à l’installer lors de l’ouverture de l’éditeur web.
L'éditeur web Mintlify en mode éditeur visuel

​
Modifier la documentation

Dans l’éditeur Web, vous pouvez parcourir vos fichiers de documentation dans la barre latérale. Mettons à jour la page d’introduction : Recherchez et sélectionnez index.mdx dans l’explorateur de fichiers. Ensuite, dans l’éditeur, mettez à jour le champ de titre sur « Hello World ».
Modification dans l'éditeur Web
L’éditeur propose un vaste ensemble d’outils de mise en forme et de composants. Tapez / dans l’éditeur pour ouvrir le menu de commandes et accéder à ces outils.

​
Publiez vos modifications

Lorsque vous êtes satisfait de vos changements, cliquez sur le bouton Publish dans l’angle supérieur droit. Vos modifications sont immédiatement déployées sur votre site de documentation.
Utilisez des branches pour prévisualiser et revoir les changements via des pull requests avant de les déployer sur votre site en production.
Pour en savoir plus sur l’utilisation de l’éditeur web — notamment l’usage des branches et des pull requests pour collaborer et prévisualiser les changements — consultez notre documentation de l’éditeur web.

​
Ajouter un domaine personnalisé

Bien que votre sous-domaine <your-project-name>.mintlify.app fonctionne bien pour les tests et le développement, la plupart des équipes préfèrent utiliser un domaine personnalisé pour la documentation en production. Pour ajouter un domaine personnalisé, accédez à la page Domain Setup de votre tableau de bord.
Domaine personnalisé
Saisissez votre domaine (par exemple, docs.yourcompany.com) et suivez les instructions fournies pour configurer les paramètres DNS chez votre fournisseur de domaine.
Les modifications DNS peuvent prendre jusqu’à 48 heures pour se propager, même si elles sont souvent effectives bien plus rapidement.

​
Prochaines étapes

Félicitations ! Vous avez réussi à déployer votre site de documentation avec Mintlify. Voici quelques étapes recommandées pour améliorer votre documentation :

Configurer les paramètres globaux de votre site

Configurez le style, la navigation, les intégrations et plus encore à l’échelle du site avec le fichier docs.json.

Personnaliser votre thème

Apprenez à personnaliser les couleurs, les polices et l’apparence générale de votre site de documentation.

Organiser la navigation

Structurez votre documentation avec une navigation intuitive pour aider les utilisateurs à trouver ce dont ils ont besoin.

Ajouter des composants interactifs

Améliorez votre documentation avec des composants interactifs comme des accordéons, des onglets et des exemples de code.

Configurer les références d’API

Créez des références d’API interactives avec les spécifications OpenAPI et AsyncAPI.

​
Dépannage

Si vous rencontrez des problèmes pendant la configuration, consultez ces solutions de dépannage courantes :
Assurez-vous que Node.js v20.17.0 ou une version supérieure est installé et que vous exécutez la commande mint dev depuis le répertoire contenant votre fichier docs.json.
Le déploiement peut prendre quelques minutes. Vérifiez vos GitHub Actions (pour un workflow basé sur le code) ou les journaux de déploiement dans le Tableau de bord Mintlify afin de vous assurer qu’il n’y a pas d’erreurs de build.
Vérifiez que vos enregistrements DNS sont correctement configurés et laissez suffisamment de temps pour la propagation DNS (jusqu’à 48 heures). Vous pouvez utiliser des outils comme DNSChecker pour vérifier votre enregistrement CNAME.