Saltar al contenido principal
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 abre archivos .mdx en un editor visual y 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, solo para la previsualización en el editor

Instalar la extensión

Instala desde la línea de comandos:
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. 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, sugerencias de etiquetas de cierre después de </ y valores enumerados de propiedades como <Badge color="…">. La extensión sugiere los componentes que importas desde snippets reutilizables junto con los integrados. className, id y style se ofrecen en todos los componentes y elementos HTML, y al escribir dentro de className="…" se sugieren clases de utilidad de Tailwind, incluidas variantes como md: y hover:.

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, incluidos elementos HTML simples como <div>.
  • 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.

Plegado

Usa los chevrones del margen para plegar regiones de una página:
  • Regiones de etiquetas de componentes y HTML, como <Accordion>…</Accordion>.
  • Secciones de encabezados.
  • Frontmatter.
  • Bloques de código.
  • Comentarios JSX.

Validación de configuración

La extensión valida docs.json contra el esquema de Mintlify.

Modo visual

Abre cualquier archivo .mdx en Modo visual para editar la página en un editor enriquecido como el del panel de Mintlify. Los encabezados, listas, tablas, enlaces, avisos, tarjetas, pasos, pestañas, acordeones, bloques de código e imágenes se pueden editar en el sitio. Para alternar entre el Modo visual y el editor de texto:
  • Presiona Cmd+Shift+V (macOS) o Ctrl+Shift+V (Windows).
  • O usa el selector de editor en el extremo derecho de la fila de migas de pan.
Usa el icono de engranaje en la barra de título para elegir con qué editor se abren de forma predeterminada los archivos .mdx. Los atajos de Markdown funcionan mientras escribes (# para un encabezado, - para un elemento de lista, **negrita**, `código`), y la barra de herramientas y el menú / insertan componentes. Las ediciones se escriben de vuelta como MDX a través del mismo conversor que mint format. Los componentes que el Modo visual no conoce se conservan tal como están escritos.

Formularios de snippets

En el Modo visual, un componente importado desde un snippet se muestra como un formulario con una entrada por prop en lugar de una etiqueta opaca. El Modo visual infiere los campos a partir de los props de la firma de la función del componente y sus valores predeterminados. Un valor predeterminado de true se convierte en una casilla, 2 en un cuadro numérico, icon o logo en una ruta de imagen con miniatura, y href o url en un enlace. Para controlar las entradas, documenta el componente con un comentario JSDoc @param justo antes del export. En archivos .jsx y .tsx, usa un bloque /** … */. En snippets .mdx, usa un comentario MDX ({/* … */}) para que no se renderice:
Los siguientes tipos producen las entradas de formulario correspondientes: Los corchetes ([name]) marcan un prop como opcional. Un prop documentado sin corchetes muestra un marcador de requerido. [name=value] proporciona un valor predeterminado cuando la desestructuración no tiene ninguno. La primera línea del comentario es la descripción que se muestra en el encabezado del formulario y en el menú Insert. children nunca es un campo: el cuerpo de la etiqueta se deja tal como está escrito y se resume debajo del formulario. Cambia al editor de texto para editarlo. Los snippets importados también aparecen en los menús + Insert y /.

Barra lateral de documentación

La vista de Mintlify en la barra de actividad refleja el árbol de navegación de tu docs.json. Los productos y las pestañas de nivel superior permanecen en la raíz, con su navegación anidada en filas expandibles. La barra lateral usa iconos de docs.json y del frontmatter de las páginas, y las etiquetas de las páginas provienen de sidebarTitle o title. Al seleccionar una página se abre en el Modo visual. Usa la acción + para agregar grupos, pestañas, menús desplegables, anclas, idiomas, productos y versiones. Arrastra filas para reordenarlas o suelta una página sobre un grupo para moverla al inicio de ese grupo. El árbol se mueve de inmediato y luego Mintlify guarda el cambio en docs.json. El árbol sigue a la página activa y se recarga cuando cambian docs.json o una página.

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. La barra de herramientas de la previsualización tiene botones de atrás, adelante y recargar, un cuadro de dirección y un interruptor Follow editor. Escribe una ruta como /quickstart en el cuadro de dirección y presiona Enter para navegar a esa página. Con Follow editor activado, la previsualización cambia de página a medida que cambias de archivo en tu editor. Presiona Cmd+F (macOS) o Ctrl+F (Windows) dentro de la previsualización para abrir una barra de búsqueda de la página renderizada. Enter y Shift+Enter permiten recorrer las coincidencias. Esc cierra la barra de búsqueda. La previsualización en el editor se renderiza en un iframe, por lo que las herramientas de desarrollo del navegador no pueden acceder a ella. Haz clic en el botón Open in browser en la barra de herramientas de la previsualización, o ejecuta Mintlify: Open preview in browser, para abrir la página en tu navegador. Las previsualizaciones en el editor requieren la CLI de Mintlify. El servidor de previsualización se ejecuta en el puerto 3939 de forma predeterminada para no entrar en conflicto con aplicaciones en el puerto 3000. Cambia el puerto con la configuración mintlify.preview.port. 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 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 selecciona un componente. Hay snippets disponibles para AccordionGroup, CardGroup, CodeGroup, Expandable, Frame, RequestExample, ResponseExample y bloques de código delimitados.

Configuración

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:

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 junto con esta extensión o ejecuta 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 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.