MDX, Markdown con JSX

MDX es un formato que permite combinar Markdown con componentes JSX de React dentro del mismo documento. La idea es sencilla: aprovechas la rapidez de Markdown para redactar el texto y, cuando necesitas algo más sofisticado (un gráfico, un formulario, un componente animado), insertas un componente de React sin salir del archivo.

Esta misma web está escrita en MDX. Cada página que ves en tutorialmarkdown.com es un archivo .mdx que mezcla la prosa habitual con componentes propios como editores interactivos, tarjetas y tablas dinámicas. Si nunca habías visto cómo encaja Markdown con un framework moderno, esta es la combinación que probablemente ya estás usando sin saberlo.

Qué es MDX

MDX es una extensión de Markdown que añade tres capacidades nuevas: la posibilidad de importar componentes de cualquier librería de React, la posibilidad de renderizar esos componentes en línea dentro del documento y la posibilidad de exportar datos desde el propio archivo para que otros módulos los consuman.

Un archivo .mdx se parece a un .md corriente, pero el procesador lo trata como un componente de React que se monta en el árbol de la aplicación. Así, los párrafos, listas y enlaces se convierten en HTML como en cualquier procesador, pero las etiquetas JSX se ejecutan como código real:

import { Grafico } from '../components/Grafico'

Este es un párrafo normal escrito en Markdown.

<Grafico datos={[1, 2, 3, 4, 5]} color="purple" />

Y aquí sigue más texto en Markdown, con un [enlace interno](/sintaxis) o **texto en negrita**.

Al renderizarse, el procesador convierte los párrafos y enlaces en HTML estándar, y el <Grafico> se ejecuta como cualquier otro componente de React, recibiendo sus props y manteniendo el estado interno si lo tuviera.

Sintaxis básica

A continuación verás las tres capacidades fundamentales de MDX con ejemplos concretos.

Importar componentes

La sintaxis de importación es idéntica a la de JavaScript moderno. Las importaciones se sitúan en la parte superior del archivo, antes de cualquier contenido Markdown.

import { MiComponente } from '../components/MiComponente'
import Layout from '../layouts/Layout'

Puedes importar tanto componentes propios como de librerías externas, e incluso utilidades que no sean componentes (funciones, constantes, hojas de estilo, etc.).

Usar componentes en el contenido

Una vez importado, el componente se utiliza con la misma sintaxis JSX que en un componente de React. Puede ir intercalado con el resto del contenido Markdown, en línea o como bloque.

# Título del artículo

Texto narrativo en Markdown.

<MiComponente prop="valor" activo={true} />

Más texto que sigue al componente, sin perder el formato Markdown.

Si necesitas pasar contenido Markdown como hijos del componente, deja una línea en blanco después de la etiqueta de apertura y antes de la de cierre. El procesador interpretará entonces el contenido interno como Markdown en lugar de como texto plano.

Exportar datos

Los archivos .mdx también pueden exportar valores que otros módulos del proyecto consumirán. El uso más típico es exportar metadatos (título, fecha, autor) que luego un sistema de plantillas utilizará para componer la página.

const meta = {
  titulo: 'Mi artículo',
  fecha: '2026-05-12',
  autor: 'Edu'
}

# {meta.titulo}

Publicado por {meta.autor} el {meta.fecha}.

Fíjate en cómo se interpolan los valores dentro del Markdown con la sintaxis { } propia de JSX.

Ventajas de MDX

Estas son las razones más habituales para escoger MDX frente a Markdown plano:

Componentes reutilizables: defines un componente una vez y lo usas en cualquier documento, manteniendo coherencia visual y de comportamiento en todo el sitio.
Interactividad real: puedes incluir gráficos, formularios, sandboxes de código, reproductores de vídeo o cualquier elemento interactivo sin abandonar el documento.
Tipado estricto: si trabajas con TypeScript, las props de tus componentes mantienen su tipado dentro del MDX.
Ecosistema React completo: acceso directo a librerías como Recharts, Framer Motion, Headless UI o cualquier otra del ecosistema.
Frontmatter o exports: puedes seguir usando frontmatter YAML para metadatos sencillos, o el bloque export cuando necesitas algo más programático.

Cuándo conviene usar MDX

MDX brilla cuando estás construyendo un sitio web con un framework moderno y quieres mezclar contenido estático con elementos dinámicos. Es la opción habitual en:

Documentación técnica con ejemplos ejecutables y sandboxes en vivo.
Blogs personales con embeds interactivos, gráficos o componentes propios.
Páginas de producto con tarjetas, comparadores y testimonios reutilizables.
Cursos online con ejercicios interactivos integrados en la lección.

En cambio, si lo que buscas es un formato portable que funcione fuera de un proyecto React, MDX no es la opción adecuada. En esos casos lo natural es ceñirse a CommonMark, GFM o, si necesitas funcionalidades editoriales, Pandoc Markdown.

Versiones de MDX

Es importante saber que MDX no es una única especificación, sino que ha evolucionado a lo largo del tiempo:

MDX 1: la primera versión estable. Es la que utiliza esta web. Tiene limitaciones conocidas: el parser se confunde con líneas en blanco dentro de elementos HTML, no procesa Markdown correctamente dentro de algunos componentes y no admite expresiones JSX dentro de bloques de código.
MDX 2: reescritura completa publicada en 2022. Resuelve la mayoría de problemas de MDX 1, mejora el rendimiento y exige un parser más estricto. Es la versión recomendada para proyectos nuevos.
MDX 3: publicada en 2024, mantiene la compatibilidad con MDX 2 y añade mejoras menores en el manejo de errores y el rendimiento del build.

Si trabajas con un proyecto antiguo en MDX 1, ten presente que la migración a MDX 2 o 3 requiere ajustar la sintaxis en bastantes archivos, sobre todo en las mezclas de HTML y Markdown.

Herramientas compatibles con MDX

Los frameworks y herramientas con soporte de MDX son cada vez más numerosos. Estos son los más utilizados en la actualidad:

Next.js con el plugin @next/mdx. Es la combinación que utiliza esta web.
Astro con soporte nativo a través de @astrojs/mdx. Es probablemente la opción más cómoda en 2026 para sitios estáticos con contenido.
Docusaurus con soporte nativo. Perfecto para documentación técnica.
Gatsby con gatsby-plugin-mdx. En decadencia, pero todavía con base instalada.
Remix con @mdx-js/rollup.
VitePress y Nextra, generadores especializados en documentación que aceptan MDX.

Limitaciones a tener en cuenta

MDX no es la respuesta universal. Antes de adoptarlo en un proyecto conviene considerar algunos puntos:

No es portable fuera del ecosistema React. Un archivo .mdx no se renderizará en GitHub, en un editor de texto plano o en una plataforma de Markdown estándar.
La curva de aprendizaje es mayor que la de Markdown puro, sobre todo cuando aparecen errores del parser o conflictos entre JSX y Markdown.
El parser puede ser estricto y romper en construcciones que en Markdown normal pasarían sin problema, como líneas en blanco dentro de bloques HTML.
Requiere un proceso de build, lo que añade complejidad frente a abrir un .md y verlo renderizado al instante.

Si estos puntos te frenan, valora si en realidad necesitas shortcodes o extensiones de Markdown menos invasivas antes de pasar a MDX.

Recursos relacionados

Sitio oficial de MDX: documentación, guía de uso y referencia completa de la sintaxis.
Versiones de Markdown: comparativa con CommonMark, GFM, MultiMarkdown y Pandoc Markdown.
Sintaxis avanzada de Markdown: otras extensiones que pueden cubrir tus necesidades sin saltar a MDX.
Next.js como generador: la combinación de framework que usa MDX en este propio sitio.