@astrojs/ mdx

Esta integración de Astro habilita 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 de Markdown en Astro. Si tienes contenido existente escrito en MDX, esta integración te permite llevar 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.

npm

npx astro add mdx

pnpm

pnpm astro add mdx

Yarn

yarn astro add mdx

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

Instalación manual

Primero, instala el paquete @astrojs/mdx:

npm

npm install @astrojs/mdx

pnpm

pnpm add @astrojs/mdx

Yarn

yarn add @astrojs/mdx

Luego, aplica la 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 con el editor

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

Para otros editores, utiliza el servidor de lenguaje de MDX.

Uso

Visita la documentación de MDX para aprender a utilizar las funciones estándar de MDX.

MDX en Astro

Añadir la integración de MDX mejora tu escritura en Markdown con variables, expresiones y componentes JSX.

También añade funciones adicionales al MDX estándar, incluido el soporte para frontmatter al estilo de Markdown en MDX. Esto te permite usar la mayoría de las funciones integradas de Markdown en Astro.

Los archivos .mdx deben estar escritos en sintaxis MDX en lugar de la sintaxis similar a HTML de Astro.

Uso de MDX local con colecciones de contenido

Para incluir tus archivos MDX locales en una colección de contenido, asegúrate de que tu cargador de colecciones esté configurado para cargar contenido desde archivos .mdx:

src/content.config.ts

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  })
});

export const collections = { blog };

Uso de variables exportadas en MDX

MDX admite el uso de declaraciones export para agregar variables a tu contenido MDX o para exportar datos a un componente que lo importe.

Por ejemplo, puedes exportar un campo title desde una página o componente MDX para usarlo como un encabezado con {expresiones JSX}:

/src/blog/posts/post-1.mdx

export const title = 'My first MDX post'

# {title}

O puedes usar ese title exportado en tu página usando declaraciones import e import.meta.glob():

src/pages/index.astro

---
const matches = import.meta.glob('./posts/*.mdx', { eager: true });
const posts = Object.values(matches);
---

{posts.map(post => <p>{post.title}</p>)}

Propiedades exportadas

Las siguientes propiedades están disponibles para un componente .astro al usar una declaración import o import.meta.glob():

• file - La ruta absoluta del archivo (por ejemplo, /home/user/projects/.../file.mdx).
• url - La URL de la página (p. ej., /es/guides/markdown-content).
• frontmatter - Contiene cualquier dato especificado en el frontmatter YAML/TOML del archivo.
• getHeadings() - Una función asíncrona que devuelve un array de todos los encabezados (<h1> a <h6>) en el archivo con el tipo: { depth: number; slug: string; text: string }[]. El slug de cada encabezado corresponde al ID generado para un encabezado dado y se puede usar para enlaces de anclaje. Los encabezados de los archivos importados no están incluidos.
• <Content /> - Un componente que devuelve el contenido completo y renderizado del archivo.
• (cualquier valor de export) - Los archivos MDX también pueden exportar datos con una declaración export.

Uso de variables de frontmatter en MDX

La integración Astro MDX incluye soporte para usar frontmatter en MDX por defecto. Agrega propiedades de frontmatter tal como lo harías en archivos Markdown, y estas variables estarán disponibles para usar en la plantilla, y como propiedades con nombre al importar el archivo en otro lugar.

/src/blog/posts/post-1.mdx

---
title: 'My first MDX post'
author: 'Houston'
---

# {frontmatter.title}

Written by: {frontmatter.author}

Uso de componentes en MDX

Después de instalar la integración de MDX, puedes importar y usar tanto componentes de Astro como componentes de frameworks de interfaz de usuario en archivos MDX (.mdx) tal como los usarías en cualquier otro componente de Astro.

¡No olvides incluir una directiva client:directive en tus componentes de frameworks de interfaz de usuario, si es necesario!

Consulta más ejemplos de uso de declaraciones de importación y exportación en la documentación de MDX.

src/blog/post-1.mdx

---
title: My first post
---
import ReactCounter from '../components/ReactCounter.jsx';

I just started my new Astro blog!

Here is my counter component, working in MDX:
<ReactCounter client:load />

Asignar componentes personalizados a elementos HTML

Con MDX, puedes mapear la sintaxis de Markdown a componentes personalizados en lugar de sus elementos HTML estándar. Esto te permite escribir en sintaxis Markdown estándar, pero aplicar estilos de componentes especiales a los elementos seleccionados.

Por ejemplo, puedes crear un componente Blockquote.astro para proporcionar estilos personalizados para el contenido de <blockquote>:

src/components/Blockquote.astro

---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- Be sure to add a `<slot/>` for child content! -->
</blockquote>

Importa tu componente personalizado en tu archivo .mdx, luego exporta un objeto components que mapee el elemento HTML estándar a tu componente personalizado:

src/blog/posts/post-1.mdx

import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> This quote will be a custom Blockquote

Visita el sitio web de MDX para ver a una lista completa de los elementos HTML que se pueden sobrescribir como componentes personalizados.

Nota

Los componentes personalizados definidos y exportados en un archivo MDX siempre deben importarse y luego pasarse de regreso al componente <Content /> a través de la propiedad components.

Pasar components al contenido MDX

Al renderizar contenido MDX importado con el componente <Content />, incluyendo el renderizado de entradas MDX usando colecciones de contenido, se pueden pasar componentes personalizados a través de la prop components. Estos componentes primero deben importarse para que estén disponibles para el componente <Content />.

El objeto components mapea nombres de elementos HTML (h1, h2, blockquote, etc.) a tus componentes personalizados. También puedes incluir todos los componentes exportados desde el propio archivo MDX utilizando el operador de propagación (...), que también debe importarse desde tu archivo MDX como components.

Si estás importando MDX directamente desde un solo archivo para usarlo en un componente de Astro, importa tanto el componente Content como cualquier componente exportado de tu archivo MDX.

src/pages/page.astro

---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- Creates a custom <h1> for the # syntax, _and_ applies any custom components defined in `content.mdx` -->
<Content components={{...components, h1: Heading }} />

Si tu archivo MDX es una entrada de colecciones de contenido, entonces usa la función render() de astro:content para acceder al componente <Content />.

El siguiente ejemplo pasa un encabezado personalizado al componente <Content /> a través de la prop components para que se use en lugar de todos los elementos HTML <h1>:

src/pages/blog/post-1.astro

---
import { getEntry, render } from 'astro:content';
import CustomHeading from '../../components/CustomHeading.astro';
const entry = await getEntry('blog', 'post-1');
const { Content } = await render(entry);
---
<Content components={{ h1: CustomHeading }} />

Configuración

Una vez instalada la integración de MDX, no es necesaria ninguna configuración para usar archivos .mdx en tu proyecto de Astro.

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

• Opciones heredadas de la configuración de Markdown
• processor
• extendMarkdownConfig
• recmaPlugins
• optimize

Opciones heredadas de la configuración de Markdown

Todas las opciones de configuración de Markdown se pueden configurar por separado en la integración de MDX, incluyendo el procesador de Markdown, el resaltado de sintaxis y más. Las opciones tendrán por defecto las de tu configuración de Markdown (consulta la opción extendMarkdownConfig para modificar esto).

astro.config.mjs

import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';
import mdx from '@astrojs/mdx';
import { myMdastPlugin } from './my-satteri-plugin.mjs';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      processor: satteri({
        mdastPlugins: [myMdastPlugin()],
        features: { gfm: false },
      }),
    }),
  ],
});

Consulta la referencia de Opciones de Markdown para obtener una lista completa de opciones.

processor

Tipo: MarkdownProcessor
Predeterminado: heredado de markdown.processor

Agregado en: @astrojs/mdx@6.0.0

Por defecto, los archivos .mdx se renderizan a través del mismo procesador de Markdown que tus archivos .md. Establece processor para usar un procesador diferente, o el mismo procesador con diferentes opciones, solo para archivos .mdx.

Por ejemplo, para mantener el procesador Sätteri predeterminado para archivos .md mientras renderizas archivos .mdx con remark y rehype usando @astrojs/markdown-remark:

astro.config.mjs

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import mdx from '@astrojs/mdx';

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

extendMarkdownConfig

Type: boolean
Default: true

Agregado en: @astrojs/mdx@0.15.0

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

Por ejemplo, supongamos que necesitas un resaltador de sintaxis diferente y un conjunto diferente de plugins para archivos .mdx. Puedes aplicar estas opciones de esta manera, con extendMarkdownConfig habilitado por defecto:

astro.config.mjs

import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    processor: satteri({ mdastPlugins: [mdastPlugin1] }),
  },
  integrations: [
    mdx({
      // Markdown `syntaxHighlight` overridden,
      // `.mdx` files use Shiki instead.
      syntaxHighlight: 'shiki',

      // `markdown.processor` gets overridden for `.mdx` files by this option
      processor: satteri({ mdastPlugins: [mdastPlugin2] }),
    }),
  ],
});

Es posible que también necesites deshabilitar la extensión de configuración de Markdown en MDX. Para ello, establece extendMarkdownConfig en false:

astro.config.mjs

import { defineConfig } from 'astro/config';
import { satteri } from '@astrojs/markdown-satteri';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    processor: satteri({ mdastPlugins: [mdastPlugin] }),
  },
  integrations: [
    mdx({
      // Markdown config now ignored
      extendMarkdownConfig: false,
      // Default `satteri()` processor used
    }),
  ],
});

recmaPlugins

Type: PluggableList
Default: []

Agregado en: @astrojs/mdx@0.11.5

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

Desde Astro v7, el procesador de Markdown por defecto no admite plugins de Recma. Si tu proyecto depende de ellos, puedes usar el procesador unified().

Sugerimos usar AST Explorer para jugar con las salidas de estree, y probar estree-util-visit para buscar a través de los nodos de JavaScript.

optimize

Type: boolean | { ignoreElementNames?: string[] }
Default: false

Agregado en: @astrojs/mdx@0.19.5

Esta es una opción de configuración opcional para optimizar la salida de MDX para compilaciones y renderizados más rápidos a través de un plugin interno de rehype. Esto puede ser útil si tienes muchos archivos MDX y notas compilaciones lentas. Sin embargo, esta opción puede generar algo de HTML sin escapar, así que asegúrate de que las partes interactivas de tu sitio sigan funcionando correctamente después de habilitarla.

Esto está deshabilitado por defecto. Para habilitar la optimización de MDX, añade lo siguiente a la configuración de tu integración de MDX:

astro.config.mjs

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

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

ignoreElementNames

Type: string[]

Agregado en: @astrojs/mdx@3.0.0

Anteriormente conocido como customComponentNames.

Una propiedad opcional de optimize para evitar que el optimizador de MDX maneje ciertos nombres de elementos, como componentes personalizados pasados al contenido MDX importado a través de la prop de componentes.

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

Por ejemplo, la salida MDX prevista para lo siguiente es <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 usando la propiedad ignoreElementNames, especifica un array de nombres de elementos HTML que deben ser tratados como componentes personalizados:

astro.config.mjs

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

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // Prevent the optimizer from handling `h1` elements
        ignoreElementNames: ['h1'],
      },
    }),
  ],
});

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

Ejemplos

• La plantilla de inicio de Astro MDX muestra cómo usar archivos MDX en tu proyecto de Astro.

Más integraciones

Frameworks de front-end

• 

  @astrojs/alpinejs

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

Adaptadores

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

Otras integraciones

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap