@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

Astro incluye un comando astro add para automatizar la configuración de las integraciones oficiales. Si lo prefieres, puedes instalar las integraciones manualmente en su lugar.

Ejecuta uno de los siguientes comandos en una nueva ventana de terminal.

npx astro add mdx

pnpm astro add mdx

yarn astro add mdx

Instalación Manual

Primero, instala el paquete @astrojs/mdx:

npm install @astrojs/mdx

pnpm add @astrojs/mdx

yarn add @astrojs/mdx

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

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
extendMarkdownConfig
recmaPlugins
optimize

Opciones heredadas de la configuración de Markdown

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

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:

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:

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 | { ignoreElementNames?: 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:

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

`ignoreElementNames`

Tipo: string[]

Agregado en: @astrojs/mdx@3.0.0

Anteriormente conocido como customComponentNames.

Una propiedad opcional de optimize para prevenir que el optimizador MDX maneje ciertos nombres de elementos, como componentes personalizados pasados al contenido MDX importado a través de la propiedad 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 ignoreElementNames, especifica un arreglo de nombres de elementos HTML que deben tratarse como componentes personalizados:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // Evita que el optimizador maneje los elementos `h1`
        ignoreElementNames: ['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.