.mdx dans un éditeur visuel et exécute une prévisualisation en direct dans votre éditeur, ce qui vous permet de rédiger et de voir le rendu sans passer par un navigateur.
Prérequis
- VS Code 1.85.0 ou plus récent
- Un répertoire de documentation avec un fichier
docs.jsonvalide - La CLI Mintlify, uniquement pour la prévisualisation dans l’éditeur
Installer l’extension
- Ouvrez la vue Extensions.
- Recherchez
@id:mintlify.mintlify-snippets. - Cliquez sur Install.
.mdx ou un espace de travail contenant un fichier docs.json.
Autocomplétion
< pour afficher tous les composants intégrés. L’autocomplétion suggère les propriétés et les valeurs des composants à l’intérieur des balises, propose les balises fermantes correspondantes après </, ainsi que les valeurs de propriétés énumérées comme <Badge color="…">.
L’extension suggère les composants que vous importez depuis des snippets réutilisables aux côtés des composants intégrés. className, id et style sont proposés sur chaque composant et élément HTML, et la saisie à l’intérieur de className="…" suggère des classes utilitaires Tailwind, y compris les variantes comme md: et hover:.
Diagnostics
- Composants inconnus.
- Propriétés inconnues ou en double.
- Valeurs invalides pour les propriétés énumérées.
- Propriétés requises manquantes.
- Balises non fermées ou mal appariées, y compris les éléments HTML simples comme
<div>. - Imports de snippets non résolus.
mintlify.diagnostics.enabled sur false.
Documentation au survol
Atteindre la définition
- des composants de snippet ;
- des chemins d’import ;
- des attributs
hrefetsrcqui pointent vers des pages locales.
docs.json, de sorte que les imports absolus comme /snippets/example.mdx se résolvent correctement. Le projet détecté apparaît dans la barre d’état. Pour vérifier quelle racine l’extension utilise, exécutez Mintlify: Show detected docs root depuis la palette de commandes.
Repli de code
- Les régions de balises de composants et HTML, comme
<Accordion>…</Accordion>. - Les sections de titres.
- Le frontmatter.
- Les blocs de code.
- Les commentaires JSX.
Validation de la configuration
docs.json par rapport au schéma Mintlify.
Mode visuel
.mdx en mode visuel pour modifier la page dans un éditeur enrichi semblable à celui du tableau de bord Mintlify. Les titres, listes, tableaux, liens, encarts, cartes, étapes, onglets, accordéons, blocs de code et images sont tous modifiables sur place.
Pour basculer entre le mode visuel et l’éditeur de texte :
- Appuyez sur Cmd+Shift+V (macOS) ou Ctrl+Shift+V (Windows).
- Ou utilisez le sélecteur d’éditeur à l’extrémité droite de la ligne des fils d’Ariane.
.mdx s’ouvrent par défaut.
Les raccourcis Markdown fonctionnent à la saisie (# pour un titre, - pour un élément de liste, **gras**, `code`), et la barre d’outils et le menu / insèrent des composants. Les modifications sont réécrites en MDX par le même convertisseur que mint format. Les composants que le mode visuel ne connaît pas sont préservés tels quels.
Formulaires de snippets
true devient une case à cocher, 2 devient un champ numérique, icon ou logo devient un chemin d’image avec une vignette, et href ou url devient un lien.
Pour contrôler les champs, documentez le composant avec un commentaire JSDoc @param juste avant l’export. Dans les fichiers .jsx et .tsx, utilisez un bloc /** … */. Dans les snippets .mdx, utilisez un commentaire MDX ({/* … */}) pour qu’il ne s’affiche pas :
Les crochets (
[name]) indiquent qu’une propriété est optionnelle. Une propriété documentée sans crochets affiche un marqueur « requis ». [name=value] fournit une valeur par défaut lorsque la déstructuration n’en a pas. La première ligne du commentaire est la description affichée dans l’en-tête du formulaire et dans le menu Insert.
children n’est jamais un champ : le corps de la balise est laissé tel quel et résumé sous le formulaire. Basculez vers l’éditeur de texte pour le modifier.
Les snippets importés apparaissent également dans le menu + Insert et dans le menu /.
La vue Mintlify dans la barre d’activité reflète l’arborescence de navigation de votre docs.json. Les produits et onglets de premier niveau restent à la racine, avec leur navigation imbriquée dans des lignes dépliables. La barre latérale utilise les icônes de docs.json et du frontmatter des pages, et les libellés des pages proviennent de sidebarTitle ou de title. Sélectionner une page l’ouvre en mode visuel.
Utilisez l’action + pour ajouter des groupes, onglets, menus déroulants, ancres, langues, produits et versions. Faites glisser les lignes pour les réorganiser, ou déposez une page sur un groupe pour la déplacer en haut de ce groupe. L’arborescence bouge immédiatement, puis Mintlify enregistre le changement dans docs.json.
L’arborescence suit la page active et se recharge lorsque docs.json ou une page change.
Prévisualisation dans votre éditeur
.mdx et sélectionnez l’icône de prévisualisation dans la barre de titre de l’éditeur, ou faites un clic droit sur le fichier et sélectionnez Preview Mintlify. Un panneau de prévisualisation s’ouvre à côté de votre éditeur et affiche le rendu de la page.
La barre d’outils de la prévisualisation comporte des boutons précédent, suivant et recharger, une zone d’adresse et un bouton bascule Follow editor. Saisissez un chemin comme /quickstart dans la zone d’adresse et appuyez sur Entrée pour accéder à cette page. Avec Follow editor activé, la prévisualisation change de page à mesure que vous changez de fichier dans votre éditeur.
Appuyez sur Cmd+F (macOS) ou Ctrl+F (Windows) dans la prévisualisation pour ouvrir une barre de recherche sur la page rendue. Enter et Shift+Enter permettent de parcourir les résultats. Esc ferme la barre de recherche.
La prévisualisation dans l’éditeur s’affiche dans une iframe, donc les outils de développement du navigateur ne peuvent pas y accéder. Cliquez sur le bouton Open in browser dans la barre d’outils de la prévisualisation, ou exécutez Mintlify: Open preview in browser, pour ouvrir la page dans votre navigateur.
Les prévisualisations dans l’éditeur nécessitent la CLI Mintlify. Le serveur de prévisualisation s’exécute par défaut sur le port 3939 afin de ne pas entrer en conflit avec des applications sur le port 3000. Modifiez le port avec le paramètre mintlify.preview.port.
L’URL du serveur en cours d’exécution apparaît dans la barre d’état. Sélectionnez-la pour arrêter le serveur, ou exécutez Mintlify: Stop preview server.
Pour voir la sortie du processus mint dev sous-jacent, ouvrez le canal de sortie Mintlify Preview.
Encadrer du contenu dans des composants
AccordionGroup, CardGroup, CodeGroup, Expandable, Frame, RequestExample, ResponseExample et les blocs de code délimités.
Paramètres
mintlify.preview.command est un paramètre utilisateur, un espace de travail ne peut donc pas le remplacer. Cela empêche un dépôt cloné d’exécuter une commande arbitraire sur votre machine lorsque vous ouvrez une prévisualisation.
Commandes
Extensions en conflit
.mdx, ce qui entre en conflit avec cette extension. Désactivez les autres extensions MDX pour éviter les suggestions en double et une coloration incohérente.
Pour le formatage du code, utilisez Prettier aux côtés de cette extension ou exécutez mint format.
Dépannage
Les composants sont signalés comme inconnus
Les composants sont signalés comme inconnus
L’extension résout les composants par rapport à la racine de votre documentation. Exécutez Mintlify: Show detected docs root pour confirmer qu’elle a trouvé le bon fichier
docs.json. Si la racine est incorrecte ou manquante, ouvrez le dossier contenant votre fichier docs.json comme espace de travail.Si la racine est correcte, exécutez Mintlify: Restart language server.L'autocomplétion et la coloration se comportent de manière incohérente
L'autocomplétion et la coloration se comportent de manière incohérente
Une autre extension MDX est probablement active elle aussi. Ouvrez la vue Extensions, recherchez
mdx et désactivez toute autre extension MDX dans cet espace de travail.La prévisualisation ne démarre pas
La prévisualisation ne démarre pas
Ouvrez le canal de sortie Mintlify Preview pour voir l’erreur de
mint dev.could not run "mint dev --no-open": la CLI n’est pas installée. Installez-la avecnpm i -g mint.Trust the workspace first: faites confiance à l’espace de travail via Manage Workspace Trust.no docs.json found above this file: ouvrez le dossier contenant votre fichierdocs.jsoncomme espace de travail.Invalid docs.json: exécutezmint validatepour trouver l’erreur de configuration.
Les imports de snippets sont signalés comme non résolus
Les imports de snippets sont signalés comme non résolus
Les chemins d’import absolus se résolvent depuis la racine de votre documentation, pas depuis votre fichier. Vérifiez que le chemin correspond à l’emplacement du fichier de snippet par rapport à votre fichier
docs.json, et que la racine détectée est correcte.