Saltearse al contenido
Astro Astro

@astrojs/mdx

Esta integración de Astro permite el uso de componentes MDX y te permite crear páginas como archivos .mdx.

¿Por qué MDX?

MDX te permite usar variables, expresiones JSX y componentes dentro del contenido Markdown en Astro. Si tienes contenido existente escrito en MDX, esta integración te permite traer esos archivos a tu proyecto de Astro.

Instalación

Instalación rápida

La herramienta de línea de comandos astro add automatiza la instalación por ti. Ejecuta uno de los siguientes comandos en una nueva ventana de terminal. (Si no estás seguro de qué gestor de paquetes estás usando, ejecuta el primer comando.) Luego, sigue las instrucciones y escribe “y” en la terminal (es decir, “sí”) para cada uno.

Terminal window
# Usando NPM
npx astro add mdx
# Usando Yarn
yarn astro add mdx
# Usando PNPM
pnpm astro add mdx

Si tienes algún problema, no dudes en informarnos en GitHub y prueba los pasos de instalación manual a continuación.

Instalación Manual

Primero, instala el paquete @astrojs/mdx usando tu gestor de paquetes. Si estás usando npm o no estás seguro, ejecuta lo siguiente en la terminal:

Terminal window
npm install @astrojs/mdx

Luego, aplica esta integración a tu archivo astro.config.* usando la propiedad integrations:

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


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

Integración del Editor

Para soporte en VS Code, instala la extensión oficial de MDX.

Para otros editores, usa el servidor de lenguaje MDX.

Uso

Con la integración MDX de Astro, puedes añadir páginas MDX a tu proyecto añadiendo archivos .mdx dentro de tu directorio src/pages/. También puedes importar archivos .mdx en archivos .astro.

La integración MDX de Astro agrega características adicionales a MDX estándar, incluyendo el frontmatter estilo Markdown. Esto te permite utilizar la mayoría de las características de Markdown incorporadas en Astro, como una propiedad especial de frontmatter layout.

Consulta cómo funciona MDX en Astro con ejemplos en nuestra guía de Markdown y MDX.

Visita la documentación de MDX para aprender sobre el uso de las características estándar de MDX.

Configuración

Una vez que la integración MDX esté instalada, no es necesario ninguna configuración adicional para utilizar archivos .mdx en tu proyecto Astro.

Puedes configurar cómo se renderiza tu MDX con las siguientes opciones:

Opciones heredadas de la configuración de Markdown

Todas las opciones de configuración de markdown excepto drafts pueden ser configuradas por separado en la integración MDX. Esto incluye plugins de remark y rehype, resaltado de sintaxis y más. Las opciones se establecerán por defecto con las de tu configuración de Markdown (consulta la opción extendMarkdownConfig para modificar esto).

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypeMinifyHtml from 'rehype-minify-html';


export default defineConfig({
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypeMinifyHtml],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});

📚 Consulta la referencia de opciones de Markdown para ver una lista completa de opciones.

extendMarkdownConfig

  • Tipo: boolean
  • Por defecto: true

Por defecto, MDX extenderá la configuración de Markdown existente en tu proyecto. Para anular opciones individuales, puedes especificar su equivalente en la configuración de MDX.

Por ejemplo, digamos que necesitas desactivar el Markdown con formato de GitHub y aplicar un conjunto diferente de plugins de remark para archivos MDX. Puedes aplicar estas opciones de la siguiente manera, con extendMarkdownConfig habilitado de forma predeterminada:

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


export default defineConfig({
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // `syntaxHighlight` se hereda de Markdown


      // Markdown `remarkPlugins` ignorados,
      // Solo se aplicó `remarkPlugin2`.
      remarkPlugins: [remarkPlugin2],
      // `gfm` se anuló y se estableció en `false`
      gfm: false,
    }),
  ],
});

También es posible que necesites deshabilitar la extensión de configuración markdown en MDX. Para ello, establece extendMarkdownConfig en false:

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


export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // La configuración de Markdown ahora se ignora
      extendMarkdownConfig: false,
      // No se aplicaron `remarkPlugins`
    }),
  ],
});

recmaPlugins

Estos son plugins que modifican directamente la salida estree. Esto es útil para modificar o inyectar variables JavaScript en tus archivos MDX.

Sugerimos utilizar AST Explorer para experimentar con las salidas de estree y probar estree-util-visit para buscar entre nodos de JavaScript.

optimize

  • Tipo: boolean | { customComponentNames?: string[] }

Esta es una configuración opcional para optimizar la salida de MDX y acelerar las compilaciones y el renderizado mediante un plugin interno de rehype. Esto puede ser útil si tienes muchos archivos MDX y notas que las compilaciones son lentas. Sin embargo, esta opción puede generar HTML no escapado, por lo que asegúrate de que las partes interactivas de tu sitio sigan funcionando correctamente después de habilitarla.

Esto está desactivado de forma predeterminada. Para habilitar la optimización de MDX, agrega lo siguiente a la configuración de integración de MDX:

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});

customComponentNames

  • Tipo: string[]

Una propiedad opcional de optimize para evitar que el optimizador de MDX maneje cualquier componente personalizado pasado al contenido de MDX importado a través de la prop components.

Deberás excluir estos componentes de la optimización, ya que el optimizador convierte el contenido en una cadena estática de forma anticipada, lo cual romperá los componentes personalizados que necesitan ser renderizados de forma dinámica.

Por ejemplo, la salida de MDX prevista para lo siguiente sería <Heading>...</Heading> en lugar de cada "<h1>...</h1>":

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<Content components={{ ...components, h1: Heading }} />

Para configurar la optimización de esto utilizando la propiedad customComponentNames, especifica un arreglo de nombres de elementos HTML que deben tratarse como componentes personalizados:

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
  integrations: [
    mdx({
      optimize: {
        // Evita que el optimizador maneje los elementos `h1`
        // Estos serán tratados como componentes personalizados
        customComponentNames: ['h1'],
      },
    }),
  ],
});

Ten en cuenta que si tu archivo MDX configura componentes personalizados usando export const components = { ... }, entonces no necesitas configurar esta opción manualmente. El optimizador los detectará automáticamente.

Ejemplos

Solución de problemas

Para obtener ayuda, consulta el canal #support en Discord. ¡Nuestros amables miembros del Equipo de Soporte están aquí para ayudar!

También puedes consultar nuestra documentación de integración de Astro para obtener más información sobre las integraciones.

Contribuyendo

Este paquete es mantenido por el equipo central de Astro. ¡Estás invitado a enviar un issue o una PR!

Changelog

Consulta el CHANGELOG.md para un historial de cambios en esta integración.

Otros

Frameworks UI

Adaptadores SSR

Otros