Astro Markdown avanzado: 7 trucos prácticos para que tu blog sea 10 veces más profesional

Acabas de montar tu blog con Astro y empiezas a escribir tu primer artículo técnico. ¿Quieres resaltar una línea concreta de código? No se puede. ¿Añadir un aviso plegable para alertar al lector? Tampoco. ¿Incluir una fórmula matemática en una explicación de algoritmos? Ni idea por dónde empezar.

Yo también pasé por esa situación incómoda. Tras escribir varios artículos en Markdown puro, me di cuenta de lo limitado que era. En otros blogs técnicos, los bloques de código marcan lo importante, muestran comparativas antes/después e incluso incrustan componentes interactivos; yo solo podía pegar código a secas.

Por suerte, Astro ofrece MDX, un «Markdown mejorado». En pocas palabras, MDX te permite usar componentes y escribir JSX mientras redactas, y de golpe puedes hacer muchísimas cosas más.

En este artículo comparto 7 usos avanzados de Astro Markdown/MDX, desde la configuración básica hasta resaltado de código, componentes personalizados, fórmulas matemáticas y diagramas de flujo. Cada truco incluye código y pasos de configuración completos. Al terminar, tu blog técnico pasará de «se puede leer» a «se ve profesional».

Parte 1: actualización básica — de Markdown a MDX

¿Por qué usar MDX?

La diferencia entre Markdown y MDX es como la de una bicicleta y una bici eléctrica: ambas te llevan, pero la experiencia no tiene nada que ver.

El Markdown puro solo admite contenido estático: texto, bloques de código e imágenes. ¿Quieres un recuadro de aviso? Toca codificar HTML a mano. ¿Incrustar un componente interactivo? Casi imposible.

MDX es otra cosa: es la combinación de «Markdown + JSX». Puedes:

• Importar y usar componentes: importar cualquier componente de Astro, React o Vue directamente en un archivo .mdx
• Escribir expresiones JSX: usar {variable} para insertar variables, e incluso bucles y condicionales
• Personalizar estilos de elementos: sustituir un <h1> estándar por tu propio componente con estilo

Un ejemplo concreto. Para añadir un aviso, con Markdown puro harías esto:

<div class="warning">
  <p>Atención: esta operación borrará todos los datos.</p>
</div>

Con MDX, así:

import Alert from '@/components/Alert.astro';

<Alert type="warning">
  Atención: esta operación borrará todos los datos.
</Alert>

¿Ves la diferencia? Con MDX, el artículo se siente más como «montar piezas» que como «escribir código».

Configurar MDX en 5 minutos

Configurar MDX es muy sencillo: tres pasos.

Paso 1: instalar la integración

Abre la terminal en tu proyecto Astro y ejecuta:

npx astro add mdx

La CLI de Astro instalará @astrojs/mdx y actualizará la configuración. Te hará unas preguntas (¿actualizar config?, ¿instalar dependencias?); responde Yes a todo.

Paso 2: verificar la configuración

Tras la instalación, abre astro.config.mjs. Deberías ver algo así:

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

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

Si no se añadió solo, hazlo manualmente.

Paso 3: probar que MDX funciona

Crea un archivo test.mdx en src/pages/ o src/content/:

---

title: Prueba MDX

---

# Esta es una prueba MDX

Texto Markdown normal.

export const greeting = "Hola";

¡Ya puedes usar variables: {greeting}!

<div style="padding: 1rem; background: #f0f0f0;">
  Este es un elemento JSX
</div>

Ejecuta npm run dev, visita la página correspondiente y, si la variable y el elemento JSX se muestran bien, MDX está configurado correctamente.

Convivencia de archivos .md y .mdx

Tras instalar la integración MDX, los archivos .md siguen funcionando con normalidad. Astro elige el procesamiento según la extensión:

• Archivos .md: Markdown estándar
• Archivos .mdx: MDX, con componentes y JSX

Mi recomendación: .md para artículos normales, .mdx cuando necesites componentes. No todos los artículos requieren MDX.

Parte 2: trucos avanzados de resaltado de código

Configurar el tema de resaltado (Shiki)

Astro usa Shiki por defecto para resaltar código, y ya va muy bien. Pero el tema por defecto es github-dark; quizá quieras uno que encaje mejor con el estilo de tu blog.

¿Shiki o Prism?

Sinceramente, recomiendo Shiki. Es la opción por defecto de Astro, soporta más de 100 lenguajes y temas, y se renderiza en el servidor sin JavaScript extra. Prism también vale, pero exige importar CSS y la configuración es un poco más laboriosa.

Cambiar el tema integrado

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Abre astro.config.mjs y añade shikiConfig en la sección markdown:

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

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'dracula', // Opciones: github-dark, nord, monokai, dracula, etc.
    },
  },
});

Shiki ofrece muchísimos temas. Los que más uso:

• github-dark / github-light — estilo GitHub
• dracula — clásico morado y negro
• nord — estilo nórdico frío
• one-dark-pro — tema oscuro por defecto de VSCode

Puedes elegir el que prefieras en la vista previa de temas de Shiki.

Tema claro/oscuro dual

Si tu blog alterna modo claro y oscuro, Shiki puede configurar dos temas:

markdown: {
  shikiConfig: {
    themes: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
},

Así Shiki aplicará el tema de resaltado según prefers-color-scheme o tu lógica personalizada de cambio de tema.

Resaltar líneas concretas y anotar código

En tutoriales suele hacer falta marcar «esta línea importa» o mostrar «qué cambió en el código». Los Transformers de Shiki lo permiten.

Resaltar líneas clave

Primero instala los transformers de Shiki:

npm install shiki

Luego activa transformerNotationHighlight en la configuración:

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

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
      transformers: [transformerNotationHighlight()],
    },
  },
});

Ahora puedes marcar líneas con el comentario // [!code highlight]:

`

```javascript
function hello() {
  console.log('Esta línea es normal');
  console.log('Esta línea se resaltará'); // [!code highlight]
}

`

**Mostrar cambios de código (estilo diff)**

Para comparar código «antes/después», usa `transformerNotationDiff`:

```javascript
import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers';

markdown: {
  shikiConfig: {
    theme: 'github-dark',
    transformers: [
      transformerNotationHighlight(),
      transformerNotationDiff(),
    ],
  },
},

Uso:

`

```javascript
function calculate(a, b) {
  return a + b; // [!code --]
  return a * b; // [!code ++]
}

`

Las líneas con `--` aparecen en rojo (eliminadas) y las de `++` en verde (añadidas). Muy útil en tutoriales de código.

**Enfocar código concreto**

También existe `transformerNotationFocus`, que «apaga» el resto del código y destaca solo la parte que quieres:

```javascript
import { transformerNotationFocus } from '@shikijs/transformers';

// Añadir al array transformers
transformers: [
  transformerNotationFocus(),
],

Marca con // [!code focus]:

`

```javascript
function process() {
  console.log('Esta línea se atenúa');
  console.log('Esta línea se muestra normal'); // [!code focus]
  console.log('Esta línea también se atenúa');
}

`

### Pasar a Expressive Code (opcional)

Si Shiki te queda corto, prueba Expressive Code. Es una solución comunitaria con más funciones listas para usar:

- Títulos en bloques de código
- Botón de copiar con un clic
- Numeración de líneas
- Estilo de ventana de terminal
- Comparación de código lado a lado

**Instalación sencilla**

```bash
npx astro add astro-expressive-code

La CLI de Astro lo configura todo. Tras instalarlo, los bloques de código ganan esas funciones sin configuración extra.

¿Cuándo usar Expressive Code?

Al principio usé Shiki por defecto; luego vi que los lectores querían copiar código con facilidad y cambié a Expressive Code. Si tu blog es sobre tutoriales y código, mejora mucho la experiencia.

Si solo incluyes código de vez en cuando, Shiki + Transformers basta; no hace falta otra dependencia.

Parte 3: incrustar componentes personalizados

Importar y usar componentes en MDX

Lo más potente de MDX es usar componentes directamente en el artículo. Yo lo uso para avisos, comparativas de código, secciones plegables, etc.

Crear un componente de aviso

Primero crea Alert.astro en src/components/:

---

interface Props {
  type?: 'info' | 'warning' | 'error';
}

const { type = 'info' } = Astro.props;

const styles = {
  info: 'bg-blue-50 border-blue-200 text-blue-800',
  warning: 'bg-yellow-50 border-yellow-200 text-yellow-800',
  error: 'bg-red-50 border-red-200 text-red-800',
};

---

<div class={`border-l-4 p-4 ${styles[type]}`}>
  <slot />
</div>

Usarlo en un artículo MDX

Importa y úsalo en tu archivo .mdx:

---

title: Mi artículo técnico

---

import Alert from '@/components/Alert.astro';

# Título del artículo

Contenido normal del artículo.

<Alert type="warning">
  Atención: haz una copia de seguridad antes de ejecutar este comando.
</Alert>

<Alert type="info">
  Consejo: dentro del componente también puedes usar **sintaxis Markdown**, muy cómodo.
</Alert>

¿Lo ves? Dentro de <Alert> puedes seguir usando Markdown (negrita, enlaces, etc.) y MDX lo procesa automáticamente.

Usar componentes React/Vue

MDX no solo admite componentes Astro, también React, Vue y otros. Recuerda la directiva client::

import Counter from '@/components/Counter.tsx';

<Counter client:load initialCount={0} />

client:load indica que el componente se ejecutará en el cliente al cargar la página. Sin eso, solo se renderiza en el servidor y la interactividad no funciona.

Organización de componentes

Suelo poner los componentes habituales del blog en src/components/mdx/:

src/
├── components/
│   ├── mdx/
│   │   ├── Alert.astro
│   │   ├── CodeCompare.astro
│   │   ├── Callout.astro
│   │   └── Tabs.astro
│   └── ...otros componentes

Mapear sintaxis Markdown a componentes personalizados

Esta función tiene algo de «magia»: puedes sustituir elementos estándar de Markdown (h1, a, img) por tus propios componentes.

¿Para qué sirve?

Por ejemplo, quieres un icono de ancla en todos los títulos o marcar enlaces externos con «↗»; hacerlo uno a uno es tedioso. Con mapeo de componentes, escribes Markdown normal y se aplican tus estilos solos.

Práctica: componente de encabezado personalizado

Crea CustomHeading.astro:

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

---

interface Props {
  level: 1 | 2 | 3 | 4 | 5 | 6;
  id?: string;
}

const { level, id } = Astro.props;
const Tag = `h${level}` as any;

---

<Tag id={id} class="group relative">
  <slot />
  {id && (
    <a href={`#${id}`} class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity">
      #
    </a>
  )}
</Tag>

Usar el mapeo en MDX

En tu .mdx, exporta un objeto components:

---

title: Título del artículo

---

import CustomHeading from '@/components/CustomHeading.astro';

export const components = {
  h2: (props) => <CustomHeading level={2} {...props} />,
  h3: (props) => <CustomHeading level={3} {...props} />,
};

## Este es un encabezado de nivel 2

Al pasar el ratón por el título aparece el enlace de ancla #.

### Este es un encabezado de nivel 3

Todos los h2 y h3 usan el estilo personalizado automáticamente.

Práctica: icono en enlaces externos

Crea ExternalLink.astro:

---

interface Props {
  href?: string;
}

const { href } = Astro.props;
const isExternal = href?.startsWith('http');

---

<a href={href} target={isExternal ? '_blank' : undefined} rel={isExternal ? 'noopener noreferrer' : undefined}>
  <slot />
  {isExternal && <span class="ml-1 text-xs">↗</span>}
</a>

Uso del mapeo:

import ExternalLink from '@/components/ExternalLink.astro';

export const components = {
  a: ExternalLink,
};

[Enlace interno](/about)
[Enlace externo](https://example.com) ← añade el icono ↗ automáticamente

Configuración global del mapeo (avanzado)

Si quieres el mismo mapeo en todos los MDX, puedes configurarlo en astro.config.mjs, pero requiere un plugin MDX personalizado; yo suelo configurarlo archivo por archivo.

Parte 4: fórmulas matemáticas e integración de diagramas

Integrar KaTeX para fórmulas matemáticas

Si escribes sobre algoritmos, matemáticas o ciencia de datos, necesitas mostrar fórmulas. KaTeX es hoy la mejor opción: mucho más rápido que MathJax y con renderizado en servidor.

Instalar KaTeX

Hace falta instalar tres paquetes:

npm install remark-math rehype-katex katex

• remark-math: analiza sintaxis LaTeX
• rehype-katex: renderiza fórmulas a HTML
• katex: biblioteca principal de KaTeX

Configurar Astro

Abre astro.config.mjs y añade estos plugins:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

Incluir estilos de KaTeX

Este paso es importante; sin él las fórmulas no se ven. En el layout (por ejemplo src/layouts/MarkdownLayout.astro), añade en <head>:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
  crossorigin="anonymous"
/>

Usar fórmulas en artículos

Tras configurar, puedes escribir fórmulas en Markdown/MDX.

Fórmulas en línea (con un solo $):

Ecuación masa-energía: $E = mc^2$

Solución de la ecuación cuadrática: $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

Fórmulas en bloque (con doble $$):

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

Problema frecuente: las fórmulas no se muestran

Si no aparecen o el estilo falla, revisa:

1. Si el CSS de KaTeX está bien enlazado (pestaña Network en F12)
2. Si la versión de rehype-katex es compatible (prueba bajar a 6.x)
3. Si la sintaxis de la fórmula es correcta (lista de soporte de KaTeX)

Integrar Mermaid para diagramas de flujo

Mermaid permite dibujar diagramas de flujo, secuencia, Gantt, etc. con código; ideal para documentación técnica.

Comparativa de tres enfoques

La comunidad ofrece varias integraciones; resumen rápido:

Recomiendo rehype-mermaid: renderizado en servidor, bueno para SEO y genera SVG estático.

Instalar rehype-mermaid

npm install rehype-mermaid

Configuración

Añade en astro.config.mjs:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    rehypePlugins: [
      [rehypeMermaid, { strategy: 'img-svg' }]
    ],
  },
});

strategy: 'img-svg' genera imágenes SVG; es el enfoque más estable.

Dibujar en artículos

Basta con bloques de código mermaid:

Ejemplo de diagrama de flujo:

`

```mermaid
graph TD
    A[Inicio] --> B{¿MDX instalado?}
    B -->|Sí| C[Configurar resaltado de código]
    B -->|No| D[Instalar MDX]
    D --> C
    C --> E[Listo]

`

**Ejemplo de diagrama de secuencia**:

`

```markdown
```mermaid
sequenceDiagram
    Usuario->>Navegador: Visitar página
    Navegador->>Servidor: Solicitar HTML
    Servidor->>Navegador: Devolver página renderizada
    Navegador->>Usuario: Mostrar contenido

`

**Generación en el build**

Al ejecutar `npm run build`, los diagramas Mermaid se generan como SVG en la fase de compilación. La página final lleva imágenes estáticas: carga rápida y sin JavaScript en el cliente.

**Notas importantes**

Si el build falla con «Puppeteer not found», puede hacer falta configuración extra. Prueba a instalar playwright:

```bash
npm install -D playwright

O cambia a astro-diagram, que trae entorno de navegador integrado.

Parte 5: técnicas avanzadas y buenas prácticas

Optimización de MDX en Content Collections

Si gestionas el blog con Content Collections de Astro (muy recomendable), los MDX ganan mejor tipado y experiencia de desarrollo.

¿Qué son Content Collections?

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

En resumen: pones los artículos en src/content/, Astro los reconoce, valida el frontmatter y ofrece APIs tipadas para leer contenido.

Configurar Content Collections

Define la colección en src/content/config.ts:

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content', // archivos de contenido (Markdown/MDX)
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()).optional(),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

Usar en MDX

El frontmatter del MDX se valida automáticamente:

---

title: Tutorial avanzado de Astro MDX
description: Aprende usos avanzados de MDX
pubDate: 2025-12-02
tags: [Astro, MDX, Tutorial]

---

import Alert from '@/components/Alert.astro';

# {frontmatter.title}

<Alert type="info">
  Fecha de publicación: {frontmatter.pubDate.toLocaleDateString()}
</Alert>

Generar tabla de contenidos automáticamente

Content Collections ofrece getHeadings() para obtener todos los encabezados y armar un índice:

---

import { getEntry } from 'astro:content';

const entry = await getEntry('blog', 'my-mdx-article');
const { Content, headings } = await entry.render();

---

<aside>
  <h2>Índice</h2>
  <ul>
    {headings.map(h => (
      <li style={`margin-left: ${(h.depth - 1) * 1}rem`}>
        <a href={`#${h.slug}`}>{h.text}</a>
      </li>
    ))}
  </ul>
</aside>

<article>
  <Content />
</article>

Muy útil en artículos largos: el lector salta directo al apartado que le interesa.

Rendimiento y trampas habituales

MDX es potente, pero mal usado también ralentiza el sitio. Algunos puntos a vigilar.

Evita abusar de componentes en el cliente

En MDX puedes usar React/Vue, pero no olvides las directivas client:*. Sin ellas, solo hay renderizado en servidor y la interactividad no funciona; si abusas de client:load, añades mucho JavaScript y la página carga peor.

Mis recomendaciones:

• Contenido estático con componentes Astro (Alert, Callout)
• Interactividad con client:visible (al ser visible) o client:idle (en idle)
• client:load solo si hace falta

Optimización de imágenes

En MDX, no uses <img alt=""> directamente; usa el componente Image de Astro:

---

title: Mi artículo

---

import { Image } from 'astro:assets';
import cover from './cover.jpg';

<Image src={cover} alt="Imagen de portada" width={800} height={600} />

Astro optimiza automáticamente (compresión, WebP, lazy loading, etc.) y el rendimiento mejora mucho.

Opción optimize de MDX

Si tienes muchos MDX y el build es lento, prueba optimize:

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

Optimiza la salida MDX con plugins rehype internos y acelera el build. Puede cambiar la estructura HTML generada; prueba antes en tu proyecto.

Errores frecuentes y soluciones

Conclusión

Resumen de lo esencial:

Repaso rápido de los 7 trucos:

1. Configurar entorno MDX — un comando, 5 minutos
2. Cambiar tema de resaltado — configura Shiki a tu gusto
3. Resaltar y anotar código — Transformers para marcar lo importante y los cambios
4. Incrustar componentes personalizados — del Alert al demo interactivo
5. Mapear elementos Markdown — personalizar títulos, enlaces, etc. en bloque
6. Mostrar fórmulas matemáticas — KaTeX para explicaciones de algoritmos más profesionales
7. Dibujar diagramas de flujo — Mermaid con código y renderizado en servidor

Ruta de aprendizaje sugerida:

No hace falta dominarlo todo de golpe. Mi consejo:

• Paso 1: configura MDX e importa un componente sencillo
• Paso 2: configura resaltado de código si escribes mucho código
• Paso 3: si tratas algoritmos o arquitectura, añade KaTeX y Mermaid
• Paso 4: cuando domines lo básico, prueba el mapeo de componentes

Lista de comprobación:

Tras configurar, verifica que funcione:

• Los archivos MDX se renderizan bien
• Los bloques de código tienen resaltado correcto
• Los componentes personalizados se muestran
• Las fórmulas se renderizan (si las configuraste)
• Los diagramas Mermaid se generan (si los configuraste)
• La velocidad de build es aceptable

Próximos pasos:

• Explora Astro Integrations para más plugins
• Revisa bibliotecas de componentes MDX de la comunidad
• Prueba View Transitions de Astro para transiciones fluidas entre páginas

Elige la función que más te interese y pruébala en tu blog. Si algo falla en la configuración, no te agobies: la documentación oficial y la comunidad suelen tener la respuesta.

Al fin y al cabo, lo más importante de un blog técnico es el contenido. Estas herramientas solo hacen tu mensaje más claro y profesional; lo que atrae de verdad a los lectores son tus ideas y tu experiencia. ¡Que tu blog Astro siga mejorando!