Démarrage rapide

Déployez votre documentation en quelques minutes

Ce guide de démarrage rapide explique comment configurer et déployer votre site de documentation en quelques minutes.

Une fois ce guide terminé, 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 l’onboarding.

​

Bien démarrer

Une fois le processus d’onboarding terminé, votre site de documentation est automatiquement déployé à une URL unique au format suivant :

https://<nom-de-votre-projet>.mintlify.app

Trouvez votre URL sur la page Overview de votre Dashboard.

L’URL de votre site est disponible immédiatement. Utilisez cette URL pour les tests et le partage avec votre équipe pendant la configuration de votre site de documentation.

​

Installer l’application GitHub

Mintlify propose une GitHub App qui automatise le déploiement lorsque vous poussez des modifications vers votre référentiel.

Installez la GitHub App en suivant les instructions de la checklist d’onboarding ou depuis votre Dashboard.

1. Accédez à Settings dans votre Tableau de bord Mintlify.
2. Sélectionnez GitHub App dans la barre latérale.
3. Sélectionnez Install GitHub App. Un nouvel onglet s’ouvre sur la page d’installation de la GitHub App.
4. Sélectionnez l’organisation ou le compte utilisateur où vous souhaitez installer l’app.
5. Sélectionnez les référentiels que vous souhaitez connecter.

Mettez à jour les autorisations de la GitHub App si vous déplacez votre documentation vers un autre référentiel.

​

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 la CLI

Pour travailler localement avec votre documentation, installez l’interface en ligne de commande (CLI), appelée mint, en exécutant la commande suivante dans votre terminal :

npm

npm i -g mint

Vous devez avoir Node.js installé sur votre machine. Si vous rencontrez des problèmes d’installation, consultez le guide de dépannage.

​

Modifier la documentation

Après avoir configuré votre environnement, vous pouvez commencer à modifier vos fichiers de documentation. Par exemple, mettez à jour le titre de la page d’introduction :

1. Ouvrez le référentiel créé lors de l’intégration.
2. Ouvrez index.mdx et repérez le début du fichier :

index.mdx

---
title: "Introduction"
description: "Ceci est l'introduction de la documentation"
---

3. Mettez à jour le champ title sur "Hello World".

index.mdx

---
title: "Bonjour le monde"
description: "Ceci est l'introduction à la documentation"
---

​

Prévisualiser les modifications

Pour afficher un aperçu local des modifications, exécutez la commande suivante :

mint dev

Votre aperçu sera disponible à localhost:3000.

​

Envoyer les modifications

Lorsque vous êtes prêt à publier vos modifications, envoyez-les vers votre référentiel.

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 référentiel GitHub ou sur le Dashboard.

Une fois le déploiement terminé, votre dernière mise à jour sera disponible à <your-project-name>.mintlify.app.

Passer à l’ajout d’un domaine personnalisé

Vous pouvez, si vous le souhaitez, 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 Dashboard.
2. Sélectionnez Editor dans la barre latérale gauche.

Si vous n’avez pas installé la GitHub App, il vous sera demandé d’installer l’app lors de l’ouverture de l’éditeur web.

​

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.

Puis, dans l’éditeur, mettez à jour le champ title avec « Hello World ».

L’éditeur propose un large éventail d’outils de mise en forme et de composants. Tapez / dans l’éditeur pour ouvrir le menu de commandes et accéder à ces outils.

​

Publier vos modifications

Lorsque vous êtes satisfait de vos modifications, cliquez sur le bouton Publish dans l’angle supérieur droit. Vos changements sont immédiatement déployés sur votre site de documentation.

Utilisez des branches pour prévisualiser et relire les modifications 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 modifications, 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 dans votre Dashboard.

Saisissez votre domaine (par exemple, docs.yourcompany.com) et suivez les instructions fournies pour configurer les paramètres DNS auprès de votre fournisseur de domaine.

Les modifications DNS peuvent prendre jusqu’à 48 heures pour se propager, même si elles s’appliquent souvent bien plus rapidement.

​

Prochaines étapes

Félicitations ! Vous avez déployé votre site de documentation avec Mintlify. Voici des étapes recommandées pour améliorer votre documentation :

Configurer vos paramètres globaux

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

Personnaliser votre thème

Découvrez comment 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 Accordions, des onglets et des exemples de code.

Configurer des références d’API

Créez des références d’API interactives à partir de spécifications OpenAPI et AsyncAPI.

​

Dépannage

Si vous rencontrez des problèmes lors de la configuration, consultez ces solutions courantes :

L’aperçu local ne fonctionne pas

Assurez-vous d’avoir installé Node.js v19+ et d’exécuter la commande mint dev depuis le répertoire contenant votre fichier docs.json.

Les modifications ne s’affichent pas sur le site en production

Le déploiement peut prendre plusieurs 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.

Le domaine personnalisé ne se connecte pas

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.