Démarrage rapide

Déployez votre documentation en quelques minutes

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

Une fois ce guide terminé, vous aurez 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.

​

Pour commencer

Après avoir terminé l’onboarding, 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 Aperçu de votre tableau de bord.

L’URL de votre site est disponible immédiatement. Utilisez-la pour effectuer des tests et la partager avec votre équipe pendant la configuration de votre site de documentation.

​

Installer l’application GitHub

Mintlify propose une application GitHub qui automatise le déploiement lorsque vous poussez des modifications vers votre dépôt.

Installez l’application GitHub en suivant les instructions de la checklist d’onboarding ou depuis votre tableau de bord.

1. Rendez-vous dans Settings de votre tableau de bord Mintlify.
2. Sélectionnez GitHub App dans la barre latérale.
3. Cliquez sur Install GitHub App. Un nouvel onglet s’ouvre vers la page d’installation de l’application GitHub.
4. Choisissez l’organisation ou le compte utilisateur où vous souhaitez installer l’application.
5. Sélectionnez les dépôts que vous souhaitez connecter.

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.

​

Flux d’édition

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

Workflow basé sur le code

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

Workflow via l’éditeur web

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

​

Flux de travail basé sur le code

Ce flux de travail s’intègre à votre environnement de développement et à vos dépôts Git existants. Il convient particulièrement aux é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

Node.js doit être installé sur votre machine. En cas de problème 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 dépôt créé lors de l’intégration.
2. Ouvrez index.mdx et repérez le début du fichier :

index.mdx

---
title: "Introduction"
description: "Voici l’introduction de la documentation"
---

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

index.mdx

---
title: "Bonjour, monde"
description: "Introduction à la documentation"
---

​

Prévisualiser les modifications

Pour prévisualiser les modifications en local, exécutez la commande suivante :

mint dev

Votre aperçu sera disponible à l’adresse localhost:3000.

​

Pousser les modifications

Lorsque vous êtes prêt à publier vos modifications, poussez-les vers votre dépôt.

Mintlify détecte automatiquement les changements, génère votre documentation et déploie les mises à jour sur votre site. Suivez 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 à <your-project-name>.mintlify.app.

Passer à l’ajout d’un domaine personnalisé

Vous pouvez aussi ignorer 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. Ce flux est idéal pour celles et ceux qui souhaitent travailler dans leur navigateur 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, il vous sera proposé de l’installer à 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 :

Repérez et sélectionnez index.mdx dans l’explorateur de fichiers.

Puis, dans l’éditeur, modifiez le champ du titre en « Hello World ».

L’Éditeur web offre un ensemble complet d’outils de mise en forme et de composants. Tapez / dans l’éditeur pour ouvrir le menu contextuel et accéder à ces outils.

​

Publier vos modifications

Lorsque vous êtes satisfait de vos modifications, cliquez sur le bouton Publier 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 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 sur 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é, rendez-vous sur la page Domain Setup de votre tableau de bord.

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

Les changements DNS peuvent prendre jusqu’à 48 heures pour se propager, même s’ils se finalisent souvent bien plus rapidement.

​

Prochaines étapes

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

Configure your global settings

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

Customize your theme

Découvrez comment personnaliser les couleurs, les polices et l’apparence générale de votre site de documentation.

Organize navigation

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

Add interactive components

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

Set up API references

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 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 n’apparaissent 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 pour vous assurer qu’il n’y a pas d’erreurs de compilation.

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 (jusqu’à 48 heures). Vous pouvez utiliser des outils comme DNSChecker pour vérifier votre enregistrement CNAME.