diff --git a/es.json b/es.json index 45df02e5f..1b51be683 100644 --- a/es.json +++ b/es.json @@ -15,6 +15,7 @@ "root": "es/cli/index", "pages": [ "es/cli/install", + "es/cli/mdx-extension", "es/cli/preview", "es/cli/commands" ] diff --git a/es/cli/index.mdx b/es/cli/index.mdx index aa840435f..579bffb0e 100644 --- a/es/cli/index.mdx +++ b/es/cli/index.mdx @@ -86,5 +86,6 @@ https://mcp.mintlify.com - [Instalar la CLI](/es/cli/install): Instala la CLI y prepárala para usarla. +- [Extensión Mintlify MDX](/es/cli/mdx-extension): Agrega autocompletado, verificación de errores en línea y una previsualización en el editor. - [Previsualización local](/es/cli/preview): Ejecuta un servidor de desarrollo local con soporte de búsqueda y asistente. - [Comandos](/es/cli/commands): Referencia completa de todos los comandos y flags. diff --git a/es/cli/install.mdx b/es/cli/install.mdx index 3e8609fc7..73737d430 100644 --- a/es/cli/install.mdx +++ b/es/cli/install.mdx @@ -121,14 +121,16 @@ Si `mint update` no está disponible en tu versión, reinstala la CLI con la úl ``` -
- ## Formato +
+ ## Soporte para editores
-Para resaltado de sintaxis y formato de código en archivos MDX, recomendamos usar las siguientes extensiones: +Para resaltado de sintaxis, autocompletado y verificación de errores en archivos MDX, usa las siguientes extensiones: -- **Cursor, Devin Desktop, VS Code**: [Extensión MDX para VS Code](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) y [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) -- **JetBrains**: [Plugin MDX para IntelliJ IDEA](https://plugins.jetbrains.com/plugin/14944-mdx) y [Prettier](https://prettier.io/docs/webstorm) +- **Cursor, Devin Desktop, VS Code**: [Extensión Mintlify MDX](/es/cli/mdx-extension) y [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) para el formato. +- **JetBrains**: [Plugin MDX para IntelliJ IDEA](https://plugins.jetbrains.com/plugin/14944-mdx) y [Prettier](https://prettier.io/docs/webstorm). + +También puedes formatear archivos MDX con [`mint format`](/es/cli/commands#mint-format).
## Solución de problemas diff --git a/es/cli/mdx-extension.mdx b/es/cli/mdx-extension.mdx new file mode 100644 index 000000000..cd1128c27 --- /dev/null +++ b/es/cli/mdx-extension.mdx @@ -0,0 +1,169 @@ +--- +title: "Extensión Mintlify MDX" +description: "Instala la extensión Mintlify MDX para obtener autocompletado, diagnósticos en línea, documentación al pasar el cursor y una previsualización en el editor mientras escribes MDX localmente." +keywords: ["Cursor", "MDX", "autocompletado", "diagnósticos", "IntelliSense", "previsualización", "editor"] +--- + +La extensión Mintlify MDX agrega compatibilidad de lenguaje para proyectos de Mintlify a VS Code, Cursor, Devin Desktop y otros editores compatibles con la API de extensiones de VS Code. La extensión conoce todos los componentes y propiedades integrados, por lo que obtienes autocompletado mientras escribes, y reporta componentes desconocidos, propiedades inválidas e importaciones de snippets sin resolver. + +La extensión también ejecuta una previsualización en vivo dentro de tu editor, para que puedas escribir y ver el resultado renderizado sin cambiar a un navegador. + +
+ ## Requisitos previos +
+ +- VS Code 1.85.0 o más reciente +- Un directorio de documentación con un archivo `docs.json` válido +- La [CLI de Mintlify](/es/cli/install), solo para la previsualización en el editor + +
+ ## Instalar la extensión +
+ +Instala desde la línea de comandos: + +```bash +code --install-extension mintlify.mintlify-snippets +``` + +O instala desde tu editor: + +1. Abre la vista de Extensiones. +2. Busca `@id:mintlify.mintlify-snippets`. +3. Haz clic en **Install**. + +También puedes instalarla desde el [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). + +La extensión se activa cuando abres un archivo `.mdx` o un espacio de trabajo que contiene un archivo `docs.json`. + +
+ ## Autocompletado +
+ +Escribe `<` para ver todos los componentes integrados. El autocompletado sugiere las propiedades y los valores de los componentes dentro de las etiquetas. + +La extensión sugiere los componentes que importas desde [snippets reutilizables](/es/create/reusable-snippets) junto con los integrados. + +
+ ## Diagnósticos +
+ +La extensión reporta problemas en el panel de Problemas y los subraya en tu archivo mientras escribes: + +- Componentes desconocidos. +- Propiedades desconocidas o duplicadas. +- Valores inválidos para propiedades enumeradas. +- Propiedades requeridas faltantes. +- Etiquetas sin cerrar o mal emparejadas. +- Importaciones de snippets sin resolver. + +Estas clases de errores causan fallos de compilación, así que corrígelos mientras escribes para evitar despliegues fallidos. + +Para desactivar los diagnósticos, establece `mintlify.diagnostics.enabled` en `false`. + +
+ ## Documentación al pasar el cursor +
+ +Pasa el cursor sobre un componente o una propiedad para ver qué hace y un enlace a su página en la documentación de Mintlify. Al pasar el cursor sobre un componente de snippet se previsualiza el contenido del archivo de snippet. + +
+ ## Ir a la definición +
+ +Mantén presionado CMD (macOS) o CTRL (Windows) y haz clic para navegar a la definición de: + +- Componentes de snippet. +- Rutas de importación. +- Atributos `href` y `src` que apuntan a páginas locales. + +La extensión encuentra la raíz de tu documentación subiendo desde el archivo abierto hasta encontrar `docs.json`, por lo que las importaciones absolutas como `/snippets/example.mdx` se resuelven correctamente. El proyecto detectado aparece en la barra de estado. Para comprobar qué raíz está usando la extensión, ejecuta **Mintlify: Show detected docs root** desde la paleta de comandos. + +
+ ## Validación de configuración +
+ +La extensión valida `docs.json` contra el [esquema de Mintlify](https://mintlify.com/docs.json). + +
+ ## Previsualización en tu editor +
+ +Abre un archivo `.mdx` y selecciona el icono de previsualización en la barra de título del editor, o haz clic derecho en el archivo y selecciona **Preview Mintlify**. Un panel de previsualización se abre junto a tu editor y renderiza la página. + +Las previsualizaciones en el editor requieren la [CLI de Mintlify](/es/cli/install). La URL del servidor en ejecución aparece en la barra de estado. Selecciónala para detener el servidor, o ejecuta **Mintlify: Stop preview server**. + +Para ver la salida del proceso `mint dev` subyacente, abre el canal de salida **Mintlify Preview**. + + + Usa la previsualización en el editor mientras escribes páginas individuales, y [`mint dev`](/es/cli/preview) en un navegador cuando quieras probar la navegación, la búsqueda o la autenticación en todo tu sitio. + + +
+ ## Envolver contenido en componentes +
+ +La extensión incluye snippets que envuelven el texto seleccionado en un componente, en lugar de insertar un componente vacío para que lo completes. + +Para usarlos, selecciona el contenido que quieres envolver, luego ejecuta **Snippets: Surround With** desde la paleta de comandos y elige un componente. Hay snippets disponibles para `AccordionGroup`, `CardGroup`, `CodeGroup`, `Expandable`, `Frame`, `RequestExample`, `ResponseExample` y bloques de código delimitados. + +
+ ## Configuración +
+ +| Configuración | Valor predeterminado | Descripción | +| --- | --- | --- | +| `mintlify.diagnostics.enabled` | `true` | Reporta componentes desconocidos, propiedades desconocidas, propiedades requeridas faltantes e importaciones de snippets sin resolver. | +| `mintlify.warnAboutConflictingExtensions` | `true` | Advierte cuando tienes otra extensión MDX instalada junto a la extensión Mintlify MDX. | +| `mintlify.preview.command` | `mint dev --no-open` | Comando usado para iniciar el servidor de previsualización, ejecutado desde la raíz de tu proyecto. | +| `mintlify.preview.followScroll` | `true` | Desplaza la previsualización hasta el encabezado más cercano a la parte superior de tu editor. | + +`mintlify.preview.command` es una configuración de usuario, por lo que un espacio de trabajo no puede sobrescribirla. Esto evita que un repositorio clonado ejecute un comando arbitrario en tu máquina cuando abres una previsualización. + +
+ ## Comandos +
+ +Ejecútalos desde la paleta de comandos: + +| Comando | Descripción | +| --- | --- | +| **Mintlify: Preview Mintlify** | Abre el panel de previsualización para el archivo actual. | +| **Mintlify: Stop preview server** | Detiene el servidor de previsualización en ejecución. | +| **Mintlify: Show detected docs root** | Muestra qué archivo `docs.json` resolvió la extensión. | +| **Mintlify: Open component docs** | Abre la documentación del componente en tu cursor. | +| **Mintlify: Restart language server** | Reinicia el servidor de lenguaje. | + +
+ ## Extensiones en conflicto +
+ +Otras extensiones MDX proporcionan su propio resaltado de sintaxis y funciones de lenguaje para archivos `.mdx`, que entran en conflicto con esta extensión. Desactiva otras extensiones MDX para evitar sugerencias duplicadas y resaltado inconsistente. + +Para el formato de código, usa [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) junto con esta extensión o ejecuta [`mint format`](/es/cli/commands#mint-format). + +
+ ## Solución de problemas +
+ + + + La extensión resuelve los componentes en relación con la raíz de tu documentación. Ejecuta **Mintlify: Show detected docs root** para confirmar que encontró el archivo `docs.json` correcto. Si la raíz es incorrecta o falta, abre la carpeta que contiene tu archivo `docs.json` como tu espacio de trabajo. + + Si la raíz es correcta, ejecuta **Mintlify: Restart language server**. + + + Es probable que otra extensión MDX también esté activa. Abre la vista de Extensiones, busca `mdx` y desactiva cualquier otra extensión MDX en este espacio de trabajo. + + + Abre el canal de salida **Mintlify Preview** para ver el error de `mint dev`. + + - `could not run "mint dev --no-open"`: La CLI no está instalada. Instálala con `npm i -g mint`. + - `Trust the workspace first`: Confía en el espacio de trabajo a través de **Manage Workspace Trust**. + - `no docs.json found above this file`: Abre la carpeta que contiene tu archivo `docs.json` como tu espacio de trabajo. + - `Invalid docs.json`: Ejecuta [`mint validate`](/es/cli/commands#mint-validate) para encontrar el error de configuración. + + + Las rutas de importación absolutas se resuelven desde la raíz de tu documentación, no desde tu archivo. Confirma que la ruta coincide con la ubicación del archivo de snippet en relación con tu archivo `docs.json`, y que la raíz detectada es correcta. + + diff --git a/es/cli/preview.mdx b/es/cli/preview.mdx index d8dd74d91..33f5481e5 100644 --- a/es/cli/preview.mdx +++ b/es/cli/preview.mdx @@ -35,6 +35,10 @@ Para generar una previsualización sin instalar la CLI globalmente, ejecuta: npx mint dev ``` + + Si escribes en VS Code o Cursor, la [extensión Mintlify MDX](/es/cli/mdx-extension) ejecuta esta previsualización en un panel junto a tu editor y la desplaza para coincidir con la página que estás editando. + +
## Iniciar sesión para búsqueda y asistente
diff --git a/fr.json b/fr.json index ad77c4d16..7c90170ea 100644 --- a/fr.json +++ b/fr.json @@ -15,6 +15,7 @@ "root": "fr/cli/index", "pages": [ "fr/cli/install", + "fr/cli/mdx-extension", "fr/cli/preview", "fr/cli/commands" ] diff --git a/fr/cli/index.mdx b/fr/cli/index.mdx index a9103cd73..6c4c4469a 100644 --- a/fr/cli/index.mdx +++ b/fr/cli/index.mdx @@ -86,5 +86,6 @@ https://mcp.mintlify.com
- [Installer la CLI](/fr/cli/install) : Installez la CLI et préparez-la à l'utilisation. +- [Extension Mintlify MDX](/fr/cli/mdx-extension) : Ajoutez l'autocomplétion, la vérification des erreurs en ligne et une prévisualisation dans l'éditeur. - [Prévisualisation locale](/fr/cli/preview) : Lancez un serveur de développement local avec la recherche et l'assistant. - [Commandes](/fr/cli/commands) : Référence complète de toutes les commandes et options. diff --git a/fr/cli/install.mdx b/fr/cli/install.mdx index f23bd28ac..56d298e9c 100644 --- a/fr/cli/install.mdx +++ b/fr/cli/install.mdx @@ -121,14 +121,16 @@ Si `mint update` n'est pas disponible dans votre version, réinstallez la CLI av ``` -
- ## Formatage +
+ ## Prise en charge des éditeurs
-Pour la coloration syntaxique et le formatage du code dans les fichiers MDX, nous recommandons les extensions suivantes : +Pour la coloration syntaxique, l'autocomplétion et la vérification des erreurs dans les fichiers MDX, utilisez les extensions suivantes : -- **Cursor, Devin Desktop, VS Code** : [Extension MDX pour VS Code](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) et [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) -- **JetBrains** : [Plugin MDX pour IntelliJ IDEA](https://plugins.jetbrains.com/plugin/14944-mdx) et [Prettier](https://prettier.io/docs/webstorm) +- **Cursor, Devin Desktop, VS Code** : [Extension Mintlify MDX](/fr/cli/mdx-extension) et [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) pour le formatage. +- **JetBrains** : [Plugin MDX pour IntelliJ IDEA](https://plugins.jetbrains.com/plugin/14944-mdx) et [Prettier](https://prettier.io/docs/webstorm). + +Vous pouvez également formater les fichiers MDX avec [`mint format`](/fr/cli/commands#mint-format).
## Dépannage diff --git a/fr/cli/mdx-extension.mdx b/fr/cli/mdx-extension.mdx new file mode 100644 index 000000000..d82167b10 --- /dev/null +++ b/fr/cli/mdx-extension.mdx @@ -0,0 +1,169 @@ +--- +title: "Extension Mintlify MDX" +description: "Installez l'extension Mintlify MDX pour bénéficier de l'autocomplétion, des diagnostics en ligne, de la documentation au survol et d'une prévisualisation dans l'éditeur pendant que vous rédigez du MDX en local." +keywords: ["Cursor", "MDX", "autocomplétion", "diagnostics", "IntelliSense", "prévisualisation", "éditeur"] +--- + +L'extension Mintlify MDX ajoute la prise en charge du langage pour les projets Mintlify à VS Code, Cursor, Devin Desktop et aux autres éditeurs compatibles avec l'API d'extensions de VS Code. L'extension connaît chaque composant intégré et chaque propriété, vous bénéficiez donc de l'autocomplétion pendant la saisie, et elle signale les composants inconnus, les propriétés invalides et les imports de snippets non résolus. + +L'extension exécute également 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.json` valide +- La [CLI Mintlify](/fr/cli/install), uniquement pour la prévisualisation dans l'éditeur + +
+ ## Installer l'extension +
+ +Installez depuis la ligne de commande : + +```bash +code --install-extension mintlify.mintlify-snippets +``` + +Ou installez depuis votre éditeur : + +1. Ouvrez la vue Extensions. +2. Recherchez `@id:mintlify.mintlify-snippets`. +3. Cliquez sur **Install**. + +Vous pouvez également l'installer depuis le [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets). + +L'extension s'active lorsque vous ouvrez un fichier `.mdx` ou un espace de travail contenant un fichier `docs.json`. + +
+ ## Autocomplétion +
+ +Tapez `<` 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. + +L'extension suggère les composants que vous importez depuis des [snippets réutilisables](/fr/create/reusable-snippets) aux côtés des composants intégrés. + +
+ ## Diagnostics +
+ +L'extension signale les problèmes dans le panneau Problèmes et les souligne dans votre fichier pendant que vous rédigez : + +- 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. +- Imports de snippets non résolus. + +Ces classes d'erreurs provoquent des échecs de build, corrigez-les donc au fil de la rédaction pour éviter des déploiements en échec. + +Pour désactiver les diagnostics, définissez `mintlify.diagnostics.enabled` sur `false`. + +
+ ## Documentation au survol +
+ +Survolez un composant ou une propriété pour voir sa fonction et un lien vers sa page dans la documentation Mintlify. Le survol d'un composant de snippet prévisualise le contenu du fichier de snippet. + +
+ ## Atteindre la définition +
+ +Maintenez CMD (macOS) ou CTRL (Windows) et cliquez pour accéder à la définition : + +- des composants de snippet ; +- des chemins d'import ; +- des attributs `href` et `src` qui pointent vers des pages locales. + +L'extension trouve la racine de votre documentation en remontant depuis le fichier ouvert jusqu'à trouver `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. + +
+ ## Validation de la configuration +
+ +L'extension valide `docs.json` par rapport au [schéma Mintlify](https://mintlify.com/docs.json). + +
+ ## Prévisualisation dans votre éditeur +
+ +Ouvrez un fichier `.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. + +Les prévisualisations dans l'éditeur nécessitent la [CLI Mintlify](/fr/cli/install). 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**. + + + Utilisez la prévisualisation dans l'éditeur pendant que vous rédigez des pages individuelles, et [`mint dev`](/fr/cli/preview) dans un navigateur lorsque vous voulez tester la navigation, la recherche ou l'authentification sur l'ensemble de votre site. + + +
+ ## Encadrer du contenu dans des composants +
+ +L'extension inclut des snippets qui encadrent le texte sélectionné dans un composant, plutôt que d'insérer un composant vide à remplir. + +Pour les utiliser, sélectionnez le contenu à encadrer, puis exécutez **Snippets: Surround With** depuis la palette de commandes et choisissez un composant. Des snippets sont disponibles pour `AccordionGroup`, `CardGroup`, `CodeGroup`, `Expandable`, `Frame`, `RequestExample`, `ResponseExample` et les blocs de code délimités. + +
+ ## Paramètres +
+ +| Paramètre | Valeur par défaut | Description | +| --- | --- | --- | +| `mintlify.diagnostics.enabled` | `true` | Signale les composants inconnus, les propriétés inconnues, les propriétés requises manquantes et les imports de snippets non résolus. | +| `mintlify.warnAboutConflictingExtensions` | `true` | Avertit lorsqu'une autre extension MDX est installée aux côtés de l'extension Mintlify MDX. | +| `mintlify.preview.command` | `mint dev --no-open` | Commande utilisée pour démarrer le serveur de prévisualisation, exécutée depuis la racine de votre projet. | +| `mintlify.preview.followScroll` | `true` | Fait défiler la prévisualisation jusqu'au titre le plus proche du haut de votre éditeur. | + +`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 +
+ +Exécutez-les depuis la palette de commandes : + +| Commande | Description | +| --- | --- | +| **Mintlify: Preview Mintlify** | Ouvre le panneau de prévisualisation pour le fichier actuel. | +| **Mintlify: Stop preview server** | Arrête le serveur de prévisualisation en cours d'exécution. | +| **Mintlify: Show detected docs root** | Affiche le fichier `docs.json` que l'extension a résolu. | +| **Mintlify: Open component docs** | Ouvre la documentation du composant sous votre curseur. | +| **Mintlify: Restart language server** | Redémarre le serveur de langage. | + +
+ ## Extensions en conflit +
+ +D'autres extensions MDX fournissent leur propre coloration syntaxique et leurs propres fonctionnalités de langage pour les fichiers `.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](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) aux côtés de cette extension ou exécutez [`mint format`](/fr/cli/commands#mint-format). + +
+ ## Dépannage +
+ + + + 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**. + + + 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. + + + 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 avec `npm 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 fichier `docs.json` comme espace de travail. + - `Invalid docs.json` : exécutez [`mint validate`](/fr/cli/commands#mint-validate) pour trouver l'erreur de configuration. + + + 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. + + diff --git a/fr/cli/preview.mdx b/fr/cli/preview.mdx index ec63f517f..827cdd65d 100644 --- a/fr/cli/preview.mdx +++ b/fr/cli/preview.mdx @@ -35,6 +35,10 @@ Pour générer une prévisualisation sans installer la CLI globalement, exécute npx mint dev ``` + + Si vous rédigez dans VS Code ou Cursor, l'[extension Mintlify MDX](/fr/cli/mdx-extension) exécute cette prévisualisation dans un panneau à côté de votre éditeur et la fait défiler pour correspondre à la page que vous modifiez. + +
## Se connecter pour la recherche et l'assistant
diff --git a/zh.json b/zh.json index 4452e7efc..d0dba6a96 100644 --- a/zh.json +++ b/zh.json @@ -15,6 +15,7 @@ "root": "zh/cli/index", "pages": [ "zh/cli/install", + "zh/cli/mdx-extension", "zh/cli/preview", "zh/cli/commands" ] diff --git a/zh/cli/index.mdx b/zh/cli/index.mdx index a9cfe01e3..e596f08cd 100644 --- a/zh/cli/index.mdx +++ b/zh/cli/index.mdx @@ -86,5 +86,6 @@ https://mcp.mintlify.com
- [安装 CLI](/zh/cli/install)：安装并准备好 CLI。 +- [Mintlify MDX 扩展](/zh/cli/mdx-extension)：添加自动补全、内联错误检查和编辑器内预览。 - [本地预览](/zh/cli/preview)：运行支持搜索和助手的本地开发服务器。 - [命令参考](/zh/cli/commands)：所有命令和选项的完整参考。 diff --git a/zh/cli/install.mdx b/zh/cli/install.mdx index 22f65116b..deda9bd1e 100644 --- a/zh/cli/install.mdx +++ b/zh/cli/install.mdx @@ -121,14 +121,16 @@ mint update ``` -
- ## 格式化 +
+ ## 编辑器支持
-对于 MDX 文件中的语法高亮和代码格式化，我们推荐使用以下扩展： +对于 MDX 文件中的语法高亮、自动补全和错误检查，请使用以下扩展： -- **Cursor、Devin Desktop、VS Code**：[MDX VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) 和 [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) -- **JetBrains**：[MDX IntelliJ IDEA 插件](https://plugins.jetbrains.com/plugin/14944-mdx) 和 [Prettier](https://prettier.io/docs/webstorm) +- **Cursor、Devin Desktop、VS Code**：[Mintlify MDX 扩展](/zh/cli/mdx-extension) 和用于格式化的 [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)。 +- **JetBrains**：[MDX IntelliJ IDEA 插件](https://plugins.jetbrains.com/plugin/14944-mdx) 和 [Prettier](https://prettier.io/docs/webstorm)。 + +你也可以使用 [`mint format`](/zh/cli/commands#mint-format) 格式化 MDX 文件。
## 故障排除 diff --git a/zh/cli/mdx-extension.mdx b/zh/cli/mdx-extension.mdx new file mode 100644 index 000000000..d0766c44a --- /dev/null +++ b/zh/cli/mdx-extension.mdx @@ -0,0 +1,169 @@ +--- +title: "Mintlify MDX 扩展" +description: "安装 Mintlify MDX 扩展，在本地编写 MDX 时获得自动补全、内联诊断、悬停文档和编辑器内预览。" +keywords: ["Cursor", "MDX", "自动补全", "诊断", "IntelliSense", "预览", "编辑器"] +--- + +Mintlify MDX 扩展为 VS Code、Cursor、Devin Desktop 以及其他支持 VS Code 扩展 API 的编辑器提供 Mintlify 项目的语言支持。该扩展了解每个内置组件和属性，因此你在输入时可以获得自动补全，它还会报告未知组件、无效属性和无法解析的 snippet 导入。 + +该扩展还会在编辑器内运行实时预览，让你无需切换到浏览器即可边写作边查看渲染结果。 + +
+ ## 前提条件 +
+ +- VS Code 1.85.0 或更高版本 +- 包含有效 `docs.json` 文件的文档目录 +- [Mintlify CLI](/zh/cli/install)（仅编辑器内预览需要） + +
+ ## 安装扩展 +
+ +从命令行安装： + +```bash +code --install-extension mintlify.mintlify-snippets +``` + +或在编辑器内安装： + +1. 打开扩展视图。 +2. 搜索 `@id:mintlify.mintlify-snippets`。 +3. 点击 **Install**。 + +你也可以从 [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=mintlify.mintlify-snippets) 安装。 + +当你打开 `.mdx` 文件或包含 `docs.json` 文件的工作区时，扩展会自动激活。 + +
+ ## 自动补全 +
+ +输入 `<` 即可查看所有内置组件。自动补全会在标签内提示组件的属性和值。 + +除内置组件外，扩展还会提示你从[可复用 snippet](/zh/create/reusable-snippets) 导入的组件。 + +
+ ## 诊断 +
+ +扩展会在“问题”面板中报告问题，并在你编写时在文件中以下划线标出： + +- 未知组件。 +- 未知或重复的属性。 +- 枚举属性的无效值。 +- 缺少必需属性。 +- 未闭合或不匹配的标签。 +- 无法解析的 snippet 导入。 + +这些类型的错误会导致构建失败，因此请在编写时及时修复，以避免部署失败。 + +要关闭诊断，请将 `mintlify.diagnostics.enabled` 设置为 `false`。 + +
+ ## 悬停文档 +
+ +将光标悬停在组件或属性上，即可查看其作用以及指向 Mintlify 文档中对应页面的链接。悬停在 snippet 组件上会预览 snippet 文件的内容。 + +
+ ## 跳转到定义 +
+ +按住 CMD（macOS）或 CTRL（Windows）并点击，即可跳转到以下内容的定义： + +- Snippet 组件。 +- 导入路径。 +- 指向本地页面的 `href` 和 `src` 属性。 + +扩展会从打开的文件向上查找，直到找到 `docs.json`，以此确定文档根目录，因此像 `/snippets/example.mdx` 这样的绝对导入可以正确解析。检测到的项目会显示在状态栏中。要查看扩展正在使用哪个根目录，请在命令面板中运行 **Mintlify: Show detected docs root**。 + +
+ ## 配置校验 +
+ +扩展会根据 [Mintlify 架构](https://mintlify.com/docs.json)校验 `docs.json`。 + +
+ ## 在编辑器中预览 +
+ +打开一个 `.mdx` 文件，选择编辑器标题栏中的预览图标，或右键点击文件并选择 **Preview Mintlify**。预览面板会在编辑器旁打开并渲染页面。 + +编辑器内预览需要 [Mintlify CLI](/zh/cli/install)。运行中服务器的 URL 会显示在状态栏中。选择它可以停止服务器，或运行 **Mintlify: Stop preview server**。 + +要查看底层 `mint dev` 进程的输出，请打开 **Mintlify Preview** 输出通道。 + + + 编写单个页面时使用编辑器内预览；当你想在整个站点范围内测试导航、搜索或身份验证时，在浏览器中使用 [`mint dev`](/zh/cli/preview)。 + + +
+ ## 用组件包裹内容 +
+ +扩展包含的 snippet 会将选中的文本包裹在组件中，而不是插入一个空组件让你填写。 + +使用方法：选中要包裹的内容，然后在命令面板中运行 **Snippets: Surround With** 并选择一个组件。可用的 snippet 包括 `AccordionGroup`、`CardGroup`、`CodeGroup`、`Expandable`、`Frame`、`RequestExample`、`ResponseExample` 和围栏代码块。 + +
+ ## 设置 +
+ +| 设置 | 默认值 | 说明 | +| --- | --- | --- | +| `mintlify.diagnostics.enabled` | `true` | 报告未知组件、未知属性、缺少的必需属性和无法解析的 snippet 导入。 | +| `mintlify.warnAboutConflictingExtensions` | `true` | 当你在 Mintlify MDX 扩展之外还安装了其他 MDX 扩展时发出警告。 | +| `mintlify.preview.command` | `mint dev --no-open` | 用于启动预览服务器的命令，从项目根目录运行。 | +| `mintlify.preview.followScroll` | `true` | 将预览滚动到最接近编辑器顶部的标题处。 | + +`mintlify.preview.command` 是用户级设置，工作区无法覆盖它。这可以防止克隆的仓库在你打开预览时在你的机器上运行任意命令。 + +
+ ## 命令 +
+ +在命令面板中运行以下命令： + +| 命令 | 说明 | +| --- | --- | +| **Mintlify: Preview Mintlify** | 为当前文件打开预览面板。 | +| **Mintlify: Stop preview server** | 停止正在运行的预览服务器。 | +| **Mintlify: Show detected docs root** | 显示扩展解析到的 `docs.json` 文件。 | +| **Mintlify: Open component docs** | 打开光标所在组件的文档。 | +| **Mintlify: Restart language server** | 重启语言服务器。 | + +
+ ## 冲突的扩展 +
+ +其他 MDX 扩展为 `.mdx` 文件提供各自的语法高亮和语言功能，会与此扩展冲突。请禁用其他 MDX 扩展，以避免重复的提示和不一致的高亮。 + +对于代码格式化，请将 [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) 与此扩展搭配使用，或运行 [`mint format`](/zh/cli/commands#mint-format)。 + +
+ ## 故障排除 +
+ + + + 扩展相对于文档根目录解析组件。运行 **Mintlify: Show detected docs root**，确认它找到了正确的 `docs.json` 文件。如果根目录错误或缺失，请将包含 `docs.json` 文件的文件夹作为工作区打开。 + + 如果根目录正确，请运行 **Mintlify: Restart language server**。 + + + 很可能有另一个 MDX 扩展也处于激活状态。打开扩展视图，搜索 `mdx`，并在此工作区中禁用其他所有 MDX 扩展。 + + + 打开 **Mintlify Preview** 输出通道，查看 `mint dev` 的错误信息。 + + - `could not run "mint dev --no-open"`：CLI 未安装。使用 `npm i -g mint` 安装。 + - `Trust the workspace first`：通过 **Manage Workspace Trust** 信任该工作区。 + - `no docs.json found above this file`：将包含 `docs.json` 文件的文件夹作为工作区打开。 + - `Invalid docs.json`：运行 [`mint validate`](/zh/cli/commands#mint-validate) 查找配置错误。 + + + 绝对导入路径从文档根目录解析，而不是从当前文件解析。请确认该路径与 snippet 文件相对于 `docs.json` 文件的位置一致，并且检测到的根目录是正确的。 + + diff --git a/zh/cli/preview.mdx b/zh/cli/preview.mdx index 6f4577e77..bd671033a 100644 --- a/zh/cli/preview.mdx +++ b/zh/cli/preview.mdx @@ -35,6 +35,10 @@ mint dev --no-open npx mint dev ``` + + 如果你在 VS Code 或 Cursor 中写作，[Mintlify MDX 扩展](/zh/cli/mdx-extension)会在编辑器旁的面板中运行此预览，并滚动到与你正在编辑的页面相匹配的位置。 + +
## 登录以启用搜索和助手