Extensión Mintlify MDX

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.

• 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

Instala desde la línea de comandos:

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.

La extensión se activa cuando abres un archivo .mdx o un espacio de trabajo que contiene un archivo docs.json.

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:.

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.

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.

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.

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.

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

Abre cualquier archivo .mdx en Modo visual para editar la página en un editor enriquecido como el del panel de Mintlify, con encabezados, listas, tablas, enlaces, avisos, tarjetas, pasos, pestañas, acordeones, bloques de código e imágenes editables 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.

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. Los campos se infieren a partir de los props desestructurados del componente y sus valores predeterminados, de modo que 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:

{/*
  A product tile with a price and a call to action.
  @param {string} name - Product name, shown as the title
  @param {image} [icon] - Path to a square icon under /images
  @param {'Free' | 'Pro' | 'Enterprise'} [tier=Free] - Which plan it belongs to
  @param {number} [seats=1] - Seats included
  @param {boolean} [featured] - Highlight the card
  @param {url} [href] - Where the button goes
  @param {text} [summary] - One or two sentences under the title
*/}
export const ProductCard = ({ name, icon, tier = 'Free', seats = 1, featured = false, href, summary, children }) => ( ... );

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 /.

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.

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. Selecciona 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.

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.

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.

Ejecútalos desde la paleta de comandos:

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.