Installer la CLI

Utilisez la CLI pour prévisualiser la documentation en local, tester les modifications en temps réel et détecter les problèmes avant de déployer votre site de documentation.

Utilisez la CLI pour prévisualiser votre documentation en local pendant la rédaction et l’édition. Visualisez les changements en temps réel avant le déploiement, testez l’apparence et les fonctionnalités de votre site de documentation, et repérez les problèmes tels que les liens brisés ou les défauts d’accessibilité.

La CLI propose également des utilitaires pour maintenir votre documentation, notamment des commandes pour renommer des fichiers, valider des spécifications OpenAPI et migrer du contenu entre différents formats.

​

Prérequis

• Node.js v20.17.0+ installé (versions LTS recommandées)
• Git installé
• Votre référentiel de documentation cloné localement

​

Cloner votre référentiel

1. Repérer votre référentiel

   1. Accédez à la page Git settings de votre Dashboard.
   2. Notez l’emplacement de votre référentiel. Il s’agit de l’un des formats suivants :

   • mintlify-community/docs-{org-name}-{id} (référentiel hébergé par Mintlify)
   • your-org/your-repo (votre propre référentiel GitHub)
2. Cloner votre référentiel

   Votre propre référentiel

   Remplacez your-org/your-repo par les informations de votre référentiel indiquées dans Git settings.

   git clone https://github.com/your-org/your-repo
   cd your-repo
   

   GitHub App requise. Pour activer les déploiements automatiques lorsque vous envoyez des modifications (push), vous devez installer la GitHub App. Consultez GitHub pour plus d’informations.

   Référentiel hébergé par Mintlify

   Vous pouvez cloner votre référentiel sous forme de référentiel privé ou public. Les référentiels publics sont visibles par toute personne qui accède à l’URL du référentiel. Les référentiels privés sont visibles uniquement par les personnes de votre organisation.

   Sur la page Git settings de votre Dashboard, sélectionnez Clone as private ou Clone as public.

​

Installer le CLI

Exécutez la commande suivante pour installer le CLI :

npm

npm i -g mint

​

Prévisualiser localement

Accédez à votre répertoire de documentation contenant votre fichier docs.json, puis exécutez :

mint dev

Une prévisualisation locale de votre documentation est disponible à l’adresse http://localhost:3000.

Par défaut, le navigateur s’ouvre automatiquement. Pour empêcher l’ouverture du navigateur, utilisez l’option --no-open :

mint dev --no-open

Sinon, si vous ne souhaitez pas installer l’Interface en ligne de commande (CLI) globalement, vous pouvez exécuter un script ponctuel :

npx mint dev

​

Ports personnalisés

Par défaut, l’interface en ligne de commande (CLI) utilise le port 3000. Vous pouvez définir le port avec l’option --port. Pour exécuter la CLI sur le port 3333, par exemple, utilisez la commande suivante :

mint dev --port 3333

Si vous tentez d’exécuter sur un port déjà utilisé, la CLI utilisera le prochain port disponible :

Le port 3000 est déjà utilisé. Utilisation du port 3001 à la place.

​

Ignorer le traitement OpenAPI

Si vous avez beaucoup de fichiers OpenAPI, vous pouvez ignorer leur traitement lors du développement local pour améliorer les performances en utilisant l’option --disable-openapi :

mint dev --disable-openapi

​

Prévisualiser en tant que groupe spécifique

Si vous utilisez un contrôle d’accès basé sur les groupes pour restreindre l’accès à votre documentation, vous pouvez prévisualiser en tant que groupe d’authentification spécifique en utilisant l’option --groups [groupname].

Par exemple, si vous avez un groupe nommé admin, vous pouvez prévisualiser en tant que membre de ce groupe avec la commande :

mint dev --groups admin

​

Créer un nouveau projet

Pour créer un nouveau projet de documentation, exécutez la commande suivante :

mint new [directory]

Cette commande clone le kit de démarrage dans un répertoire donné. Si aucun répertoire n’est précisé, l’interface en ligne de commande (CLI) vous propose de créer un nouveau sous-dossier ou d’écraser le répertoire actuel.

L’écrasement du répertoire actuel supprime tous les fichiers existants.

L’outil CLI vous demande un nom de projet et un thème pour finaliser la configuration de votre projet.

​

Options

Option	Description	Requis
--name	Définit le nom du nouveau projet.	Oui
--theme	Définit le thème du nouveau projet.	Oui
--force	Écrase le répertoire actuel sans confirmation, même s’il contient déjà des fichiers.	Non

Lors de l’exécution de mint new dans des environnements non interactifs comme les pipelines CI/CD ou avec des agents IA de codage, vous devez fournir toutes les options requises (--name et --theme).

L’Interface en ligne de commande (CLI) détecte automatiquement les environnements non interactifs. Si des options requises sont manquantes, elle affiche les instructions d’utilisation au lieu de rester bloquée en attente de réponses aux invites.

​

Mettre à jour l’interface en ligne de commande (CLI)

Si votre aperçu local n’est pas en phase avec ce que vous voyez sur le Web dans la version de production, mettez à jour votre CLI locale :

mint update

Si la commande « mint update » n’est pas disponible dans votre version locale, réinstallez l’interface en ligne de commande (CLI) avec la dernière version :

npm

npm i -g mint@latest

​

Commandes supplémentaires

​

Détecter les liens brisés

Identifiez les liens brisés dans votre documentation :

mint broken-links

La commande ignore les fichiers correspondant aux motifs de .mintignore. La commande signale comme brisés les liens qui pointent vers des fichiers ignorés.

Par défaut, la commande vérifie uniquement les liens internes. Utilisez des options pour étendre la portée :

option	Description
--check-anchors	Valide également les liens d’ancrage (par exemple, /page#section) par rapport aux slugs des titres.
--check-external	Vérifie également les liens externes pour détecter les URL brisées.
--check-snippets	Vérifie également les liens à l’intérieur des composants <Snippet>.

​

Détecter les problèmes d’accessibilité

Testez les rapports de contraste des couleurs et recherchez les textes alternatifs manquants pour les images et les vidéos de votre documentation avec la commande suivante :

mint a11y

Utilisez des options pour détecter des problèmes d’accessibilité spécifiques.

# Check only for missing alt text
mint a11y --skip-contrast

# Vérifier uniquement les problèmes de contraste des couleurs
mint a11y --skip-alt-text

​

Valider la génération de la documentation

Validez la génération de votre documentation en mode strict, qui se termine par une erreur en cas d’avertissement ou d’erreur. Utilisez cette commande dans les pipelines CI/CD pour éviter les déploiements de documentation défectueux.

mint validate

Utilisez des options pour configurer la commande de validation.

• --groups [groupname] : Simuler des groupes d’utilisateurs pour la validation (utile lors de tests de contrôle d’accès basé sur les groupes)
• --disable-openapi : Désactiver la génération du fichier OpenAPI pendant la validation

​

Vérifier la spécification OpenAPI

Vérifiez votre fichier OpenAPI à la recherche d’erreurs avec la commande suivante :

mint openapi-check <nom de fichier OpenAPI ou URL>

Indiquez un nom de fichier (par exemple, ./openapi.yaml) ou une URL (par exemple, https://petstore3.swagger.io/api/v3/openapi.json).

Pour vérifier un fichier OpenAPI hébergé localement et servi via HTTP, utilisez l’option --local-schema :

mint openapi-check http://localhost:8080/openapi.json --local-schema

Seules les URL HTTPS sont prises en charge dans les déploiements en production. L’option --local-schema est réservée au développement local.

​

Créer un workflow

Créez de manière interactive un fichier de workflow avec la commande suivante :

mint workflow

L’Interface en ligne de commande (CLI) vous invite à saisir un nom, un type de déclencheur et d’autres paramètres, puis crée un fichier .md dans .mintlify/workflows/.

​

Renommer des fichiers

Renommez les fichiers et mettez à jour toutes leurs références avec la commande suivante :

mint rename <chemin/vers/ancien-nom-de-fichier> <chemin/vers/nouveau-nom-de-fichier>

​

Migrer les pages d’endpoints MDX

Migrez les pages d’endpoints MDX vers des pages générées automatiquement à partir de votre spécification OpenAPI avec la commande suivante :

mint migrate-mdx

Cette commande convertit les pages MDX d’endpoint individuelles en pages générées automatiquement, telles que définies dans votre docs.json, déplace le contenu MDX vers l’extension x-mint de votre spécification OpenAPI, et met à jour votre navigation. Consultez Migration depuis MDX pour plus de détails.

​

Importer du contenu

Récupérez le contenu d’un site de documentation externe ou d’une spécification OpenAPI à l’aide des commandes mint scrape. C’est utile lorsque vous migrez votre documentation d’une autre plateforme vers Mintlify.

Importer un site entier :

mint scrape site <url>

Utilisez l’option --filter (ou -f) pour limiter le scraping aux URL dont le chemin commence par un préfixe spécifique :

mint scrape site <url> --filter=<path>

Importer une seule page :

mint scrape page <url>

Générez des pages à partir d’une spécification OpenAPI :

mint scrape openapi <openApiFilename or URL>

Option	Description
--outDir	Répertoire où écrire les fichiers générés. Par défaut : ./docs.
--overwrite	Remplace les fichiers existants.
--no-writeFiles	Affiche un aperçu du résultat sans écrire de fichiers.

​

Mise à niveau de la configuration

Convertissez un fichier de configuration mint.json au format docs.json actuel :

mint upgrade

Consultez Paramètres globaux pour en savoir plus sur docs.json.

​

Vérifier la version

Affichez la version actuelle de l’interface en ligne de commande (CLI) et du client :

mint version

​

Mise en forme

Lors du développement en local, nous recommandons d’utiliser des extensions pour votre IDE afin de reconnaître et de formater les fichiers MDX.

Si vous utilisez Cursor, Windsurf ou VS Code, nous recommandons l’extension MDX pour VS Code pour la coloration syntaxique, et Prettier pour le formatage du code.

Si vous utilisez JetBrains, nous recommandons le plugin MDX pour IntelliJ IDEA pour la coloration syntaxique, ainsi que la configuration de Prettier pour le formatage du code.

​

Dépannage

Erreur : impossible de charger le module "sharp" avec l’environnement d’exécution darwin-arm64

Cela peut être dû à une version obsolète de Node.js. Essayez ce qui suit :

1. Désinstallez la version actuellement installée de l’interface en ligne de commande (CLI) Mint : npm uninstall -g mint
2. Mettez à jour vers Node.js v20.17.0+.
3. Réinstallez la CLI Mint : npm install -g mint

Problème : erreur inconnue

Solution : Accédez à la racine de votre appareil et supprimez le dossier ~/.mintlify. Ensuite, exécutez de nouveau mint dev.

Erreur : permission refusée

Cela est dû au fait que vous n’avez pas les autorisations nécessaires pour installer globalement des paquets Node.

Solution : Essayez d’exécuter sudo npm i -g mint. Lorsque vous y êtes invité, entrez le mot de passe que vous utilisez pour déverrouiller votre ordinateur.

L’aperçu local n’a pas le même rendu que ma documentation en ligne

Cela est probablement dû à une version obsolète de la CLI.

Solution : Exécutez mint update pour récupérer les dernières modifications.

mintlify versus paquet mint

Si vous rencontrez des problèmes avec le paquet CLI, commencez par exécuter npm ls -g. Cette commande affiche les paquets installés globalement sur votre machine.

Si vous n’utilisez pas npm ou ne le voyez pas dans la liste -g, essayez which mint pour localiser l’installation.

Si vous avez un paquet nommé mint et un paquet nommé mintlify installés, vous devez désinstaller mintlify.

1. Désinstallez l’ancien paquet :

  npm uninstall -g mintlify

2. Videz le cache npm :

  npm cache clean --force

3. Réinstallez le nouveau paquet :

npm i -g mint

La version du client affiche « none » après l’installation

Si vous exécutez mint version et que la version du client s’affiche sur none, il est probable que la CLI ne parvienne pas à télécharger l’application cliente en raison d’un pare-feu d’entreprise ou d’un VPN qui bloque le téléchargement.

Solution : Demandez à votre administrateur informatique d’ajouter releases.mintlify.com à la liste d’autorisation de votre réseau afin d’activer le développement local avec la CLI.