Prévisualisez et testez localement les modifications de la documentation avant de publier des mises à jour sur le site de documentation de W&B Weave.
Ce guide s’adresse aux contributeurs à la documentation qui souhaitent prévisualiser localement les modifications apportées à la documentation de W&B Weave avant leur publication. En exécutant le CLI Mintlify sur votre machine, vous pouvez vérifier que vos modifications s’affichent correctement, détecter les liens rompus et itérer rapidement sans attendre un déploiement.
Prérequis : Installez Node.js (version 19 ou ultérieure) avant de continuer.
Migrez vers docs.json avant de continuer et supprimez l’ancien fichier mint.json.
Suivez ces étapes pour installer et exécuter Mintlify sur votre système d’exploitation :
Installez Mintlify :
npm i -g mintlify
Accédez au répertoire docs (où se trouve le fichier docs.json) et démarrez le serveur d’aperçu local :
mintlify dev
Un aperçu local de votre documentation est disponible à l’adresse http://localhost:3000. Vous disposez désormais d’un environnement local qui reproduit le site de documentation Weave publié.
Par défaut, Mintlify utilise le port 3000. Si le port 3000 est déjà utilisé sur votre machine ou si vous préférez exécuter plusieurs aperçus en même temps, utilisez l’indicateur --port pour modifier le port sur lequel Mintlify s’exécute. Par exemple, pour exécuter Mintlify sur le port 3333, utilisez cette commande :
mintlify dev --port 3333
Si vous essayez de lancer Mintlify sur un port déjà utilisé, il utilise le port disponible suivant :
Maintenez votre CLI synchronisée avec la version de Mintlify en Production afin que votre aperçu local corresponde à ce que les lecteurs voient sur le site publié. Chaque version de la CLI est associée à une version spécifique de Mintlify. Si votre site web local ne correspond pas à la version en Production, mettez à jour la CLI :
Les liens rompus dégradent l’expérience de lecture. Vérifiez donc que vos modifications ne contiennent pas de références rompues avant d’ouvrir une pull request. Le CLI peut valider les liens de référence dans votre documentation. Pour identifier les liens rompus, exécutez mintlify broken-links :
Un formatage MDX cohérent facilite la révision de vos modifications et réduit le risque d’erreurs de syntaxe accidentelles. Nous vous recommandons d’utiliser des extensions dans votre IDE pour reconnaître et formater le MDX. Si vous utilisez VSCode, pensez à l’extension MDX pour VSCode pour la coloration syntaxique et à Prettier pour le formatage du code.
Les sections suivantes décrivent les problèmes courants que vous pouvez rencontrer lorsque vous exécutez la CLI Mintlify en local, ainsi que leurs solutions.
Erreur : impossible de charger le module "sharp" avec le runtime darwin-arm64
Cela peut être dû à une version obsolète de Node.js. Essayez la procédure suivante :
Supprimez la version installée de mintlify : npm remove -g mintlify.
Passez à Node.js v19 ou à une version ultérieure.
Réinstallez mintlify : npm install -g mintlify.
Problème : une erreur inconnue se produit
Solution : accédez au répertoire racine de votre machine et supprimez le dossier ~/.mintlify. Exécutez ensuite de nouveau mintlify dev.
