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.

À la fin de 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 l’intégration.

Pour commencer

Après avoir terminé l’onboarding, votre site de documentation est automatiquement déployé à une URL unique au format :

https://<your-project-name>.mintlify.app

Retrouvez votre URL sur la page Aperçu de votre tableau de bord.

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

Installer l’app GitHub

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

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

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 avec la page d’installation de l’app GitHub.
4. Sélectionnez l’organisation ou le compte utilisateur où vous souhaitez installer l’app.
5. Sélectionnez les dépôts que vous souhaitez connecter.

Mettez à jour les autorisations de l’app 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 sur la page d’autorisation GitHub.

Selon les paramètres de votre organisation, un administrateur de votre organisation GitHub peut devoir autoriser votre compte.

Flux d’édition

Mintlify propose deux modes d’édition pour créer et maintenir votre documentation :

Mode basé sur le code

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

Mode É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

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

Installer le 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 résolution des problèmes.

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: "This is the introduction to the documentation"
---

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

index.mdx

---
title: "Hello World"
description: "This is the introduction to the documentation"
---

Prévisualiser les modifications

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

mint dev

L’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 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 dashboard.

Une fois le déploiement terminé, votre dernière mise à jour sera disponible sur <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 offre une interface WYSIWYG (what you see is what you get) pour créer et modifier la documentation. Ce flux de travail convient particulièrement à celles et ceux qui souhaitent travailler dans leur navigateur, sans 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.

Modifier la documentation

Dans l’Éditeur web, vous pouvez parcourir vos fichiers de documentation via 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, modifiez le champ du titre en « Hello World ».

L’éditeur offre un riche ensemble d’outils de mise en forme et de composants. Tapez / dans l’éditeur pour ouvrir le menu des 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 modifications sont immédiatement déployées sur votre site de documentation.

Utilisez des branches pour prévisualiser et faire relire les modifications via des pull requests avant de 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 convienne aux tests et au 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 modifications DNS peuvent prendre jusqu’à 48 heures pour se propager, même si elles sont souvent effectives bien plus tôt.

Prochaines étapes

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

Configurer vos paramètres globaux

Configurez le style global du site, la navigation, les intégrations et bien 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 accordéons, des onglets et des exemples de code.

Configurer les références 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 de dépannage 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 logs 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.