Qué es MDX y cuándo usarlo

Markdown fue diseñado para una sola cosa —escribir prosa con formato mínimo— y la hace de maravilla, pero se detiene justo donde empieza la interactividad. MDX borra esa frontera: es Markdown que entiende JSX, un formato donde un párrafo y un componente conviven en el mismo fichero sin cambiar de lenguaje. En Astro 7, activar MDX es añadir una integración; entenderlo es asumir que un documento puede ser, a la vez, texto que se lee y programa que se ejecuta.

De Markdown a MDX: qué se añade

Markdown es un lenguaje deliberadamente pobre, y esa pobreza es su virtud. Su gramática cabe en una cuartilla —almohadillas para títulos, asteriscos para énfasis, guiones para listas— y por eso cualquiera la escribe sin manual y cualquier herramienta la procesa sin sorpresas. El precio de esa simplicidad es un techo: en cuanto necesitas algo que no sea texto con formato —un aviso destacado, un gráfico, un contador que reaccione al clic— Markdown no tiene vocabulario para expresarlo y te empuja a incrustar HTML crudo, que ni compone ni reutiliza.

MDX rompe ese techo por el único sitio por el que se puede romper sin traicionar el formato: dejando entrar el lenguaje de componentes. Un fichero .mdx es Markdown normal hasta que aparece una etiqueta en mayúscula o una llave, y en ese punto pasa a ser JSX. No hay dos zonas separadas ni una sintaxis de escape: prosa y programa se entrelazan en la misma línea, y el compilador sabe en todo momento cuál está leyendo. Tres capacidades concretas nacen de esa unión:

• Componentes. Importas una pieza .astro o de framework y la usas como una etiqueta más entre tus párrafos, con sus props y su contenido anidado.
• Expresiones. Cualquier expresión JavaScript entre llaves se evalúa y su resultado se inserta en el texto, como {new Date().getFullYear()}.
• Imports y exports. El documento se comporta como un módulo: puede import de otros ficheros y export de valores hacia quien lo consuma.

---
title: Notas de la versión
---
import Aviso from '../components/Aviso.astro';

# Novedades de {new Date().getFullYear()}

<Aviso tipo="info">Esta versión cambia la configuración por defecto.</Aviso>

El resto sigue siendo Markdown normal, con **negritas** y listas.

Lo revelador de ese ejemplo es cuánto sigue siendo Markdown. MDX no te obliga a reescribir tu prosa en JSX: el noventa por ciento del fichero se teclea igual que siempre, y solo las islas de componente o de expresión adoptan la sintaxis nueva. Es una extensión, no un reemplazo, y esa continuidad es justo lo que hace que adoptarlo cueste tan poco.

Conviene matizar una creencia extendida: MDX suele describirse como un superconjunto de Markdown, pero no lo es al pie de la letra. Al reservar < y { como sintaxis, MDX rompe algunos usos que Markdown toleraba —un signo de menor que suelto, una llave literal en medio de un párrafo— que ahora hay que escapar o entrecomillar. Los bloques de código indentados con cuatro espacios tampoco se admiten: en MDX se usan siempre vallas de tres acentos graves. Y el HTML incrustado se parsea como JSX, así que cada etiqueta debe cerrarse. Son diferencias pequeñas, pero explican por qué un .md que funcionaba puede protestar al renombrarlo a .mdx: no has cambiado de dialecto, has cambiado a un parser más estricto.

Instalar la integración @astrojs/mdx

Astro no entiende .mdx de fábrica; la capacidad llega como una integración oficial. La vía recomendada es el asistente, que instala el paquete y edita la configuración por ti en un solo paso:

npx astro add mdx

Ese comando hace tres cosas: añade @astrojs/mdx a las dependencias, lo registra en el array integrations de tu configuración y confirma los cambios antes de escribirlos. Si prefieres el control manual, el resultado equivalente es instalar el paquete y declararlo tú mismo:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

A partir de ese registro, cualquier fichero .mdx en src/pages se convierte en una ruta y cualquier .mdx en una colección se compila con el pipeline de MDX. La integración no vive aislada: por defecto hereda tu configuración de Markdown —los plugins de remark y rehype, el resaltador de sintaxis, las opciones de shiki— de modo que .md y .mdx comparten el mismo tratamiento base y no divergen sin que tú lo pidas.

Por debajo, ese pipeline no produce una cadena de HTML, sino un módulo de JavaScript. Cada .mdx se compila a un componente de Astro que exporta un Content renderizable y cualquier valor que hayas exportado en el cuerpo, más los metadatos del frontmatter. Esa es la razón profunda de que MDX pueda importar, computar y exportar: el resultado de compilarlo no es un documento pasivo, sino código que se ejecuta como cualquier otro módulo del proyecto. Lo verás con detalle en las lecciones siguientes, pero conviene fijar la idea desde ya, porque de ella se derivan casi todas las capacidades de MDX.

.md o .mdx: cuándo cada uno

Tener MDX instalado no significa usarlo en todas partes. La regla es económica: .mdx cuesta más de compilar y activa un parser más exigente, así que se reserva para cuando de verdad necesitas su potencia. La pregunta que decide es simple: ¿este documento necesita componentes, expresiones o imports? Si la respuesta es no, .md es la elección correcta y más barata.

Ambos formatos comparten casi todo: los dos aceptan frontmatter YAML, los dos sirven como páginas en src/pages y como entradas de una colección, y los dos se consultan con la misma API de contenido. La diferencia no está en cómo se leen, sino en qué admiten dentro. Por eso migrar de .md a .mdx es trivial —renombras la extensión y sigue funcionando— mientras el fichero no use nada exclusivo de MDX.

Esa equivalencia se nota en las content collections: el glob loader que registra una colección recoge por igual los .md y los .mdx de una carpeta, así que una misma colección puede mezclar entradas de prosa pura y entradas con componentes sin ninguna configuración especial. Cada autor elige la extensión según lo que su documento necesita, y el esquema y la consulta tipada se aplican idénticos a ambos. La decisión .md frente a .mdx es, por tanto, por fichero, no por colección: conviven sin fricción bajo el mismo contrato.

flowchart TD
MD[archivo punto md] --> BASE[prosa y HTML plano]
MDX[archivo punto mdx] --> BASE
MDX --> C[componentes JSX]
MDX --> E[expresiones con llaves]
MDX --> I[import y export ESM]
style MDX fill:#89b4fa,color:#11111b
style MD fill:#a6e3a1,color:#11111b

El coste de la potencia

MDX no es Markdown gratis con superpoderes: cada capacidad que añade estrecha un poco la tolerancia del parser. En Markdown, un < suelto o una llave perdida son texto inofensivo; en MDX son sintaxis significativa —el inicio de una etiqueta o de una expresión— y un signo mal cerrado detiene la compilación con un error. Ese rigor es el mismo que te protege de un componente mal escrito, pero exige disciplina: en MDX, los caracteres < y { dejan de ser inertes.

Las asperezas concretas que encontrarás al escribir MDX se reducen a unas pocas, todas con la misma raíz —el parser espera JSX válido allí donde Markdown esperaba texto—:

• Un < o un { literal en la prosa debe ir entre acentos graves, como a < b, o el compilador lo tomará por sintaxis.
• Toda etiqueta HTML incrustada tiene que cerrarse; un <br> suelto rompe, y se escribe <br/>.
• Los bloques de código deben usar vallas de tres acentos graves, nunca la indentación de cuatro espacios de Markdown clásico.
• El Markdown anidado dentro de un componente solo se procesa si lo separas con líneas en blanco, un detalle que verás a fondo más adelante.

Verlo junto fija el hábito: lo que es un signo literal se entrecomilla, y lo que es un componente de verdad no.

En prosa, un `<` o una llave `{` sueltos deben ir entre acentos graves para ser texto.

Un componente real como <Aviso /> se escribe sin acentos graves y sí se renderiza.

Ninguna de estas reglas es gratuita: todas nacen de que MDX espera JSX válido allí donde antes había texto libre. Interiorizarlas de una vez evita horas de desconcierto, porque convierte un error críptico del compilador en un descuido que reconoces al instante.

Hay además un coste de rendimiento real. Compilar .mdx implica arrancar el pipeline de JSX, resolver imports y evaluar el módulo, un trabajo que un .md de pura prosa se ahorra por completo. En un sitio con miles de documentos, convertirlos todos a .mdx por comodidad infla el tiempo de build sin dar nada a cambio en las páginas que no usan ni un componente. La elección de extensión es, en el fondo, una decisión de coste que se paga en cada compilación.