.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.jsonválido - La CLI de Mintlify, solo para la previsualización en el editor
Instalar la extensión
- Abre la vista de Extensiones.
- Busca
@id:mintlify.mintlify-snippets. - Haz clic en Install.
.mdx o un espacio de trabajo que contiene un archivo docs.json.
Autocompletado
< 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
- 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.
mintlify.diagnostics.enabled en false.
Documentación al pasar el cursor
Ir a la definición
- Componentes de snippet.
- Rutas de importación.
- Atributos
hrefysrcque apuntan a páginas locales.
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
- 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
docs.json contra el esquema de Mintlify.
Modo visual
.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.
.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
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 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.
Previsualización en tu editor
.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.
Envolver contenido en componentes
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
Extensiones en conflicto
.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
Los componentes se reportan como desconocidos
Los componentes se reportan como desconocidos
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.El autocompletado y el resaltado se comportan de forma inconsistente
El autocompletado y el resaltado se comportan de forma inconsistente
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.La previsualización no se inicia
La previsualización no se inicia
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 connpm 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 archivodocs.jsoncomo tu espacio de trabajo.Invalid docs.json: Ejecutamint validatepara encontrar el error de configuración.
Las importaciones de snippets se reportan como sin resolver
Las importaciones de snippets se reportan como sin resolver
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.