Configuración global de Markdown en astro.config

Todo lo que ocurre cuando Astro compila un Markdown —qué sintaxis extendida entiende, cómo afina la tipografía, quién colorea el código, cómo cruza del árbol de contenido al de HTML— se gobierna desde un solo lugar: el objeto markdown de astro.config. No es una colección de ajustes sueltos, sino el panel de control del pipeline que en las lecciones anteriores viste por dentro. Conocer sus cuatro perillas centrales —gfm, smartypants, syntaxHighlight y remarkRehype— y, sobre todo, cómo conviven con los plugins que tú añadas, es lo que te da mando pleno sobre cómo se procesa cada documento del sitio.

gfm: la sintaxis extendida de GitHub

Por defecto, Astro no procesa Markdown a secas, sino GitHub Flavored Markdown. La opción gfm, activa de fábrica, incorpora al parser las extensiones que popularizó GitHub: tablas con barras verticales, texto tachado con dobles virgulillas, listas de tareas con casillas, y la autoconversión de URL sueltas en enlaces. Sin ellas, una tabla escrita con barras se serviría como texto plano.

// astro.config.mjs
export default {
  markdown: {
    gfm: true, // valor por defecto; ponlo en false para desactivarlo
  },
};

Que sea el comportamiento por defecto significa que casi nunca lo tocarás, pero saber que existe explica de dónde salen capacidades que el Markdown original no tenía. Desactivarlo con gfm: false es una decisión deliberada —querer un Markdown estricto y minimalista— y su efecto es retirar del pipeline el plugin remark-gfm que Astro añade por ti.

Conviene tener presente el inventario concreto de lo que aporta, porque son cosas que das por sentadas hasta que faltan: tablas delimitadas por barras, listas de tareas con casillas marcables, texto tachado, y la conversión automática de una URL suelta en un enlace pinchable. Si algún día una tabla aparece como un amasijo de barras y guiones en la página, la primera hipótesis es que gfm se apagó en algún punto de la configuración. La extensión es tan ubicua que su ausencia se nota antes que su presencia.

smartypants: la tipografía fina

La segunda perilla, smartypants, también activa por defecto, se ocupa de la ortotipografía. Convierte las comillas rectas en comillas tipográficas curvas, los tres puntos seguidos en puntos suspensivos de un solo carácter, y los guiones dobles y triples en rayas de longitud correcta. Es el toque que separa un texto que parece salido de un editor de código de uno que parece compuesto para imprenta.

export default {
  markdown: {
    smartypants: true, // convierte comillas rectas en curvas, -- en raya...
  },
};

Hay un motivo real para desactivarlo: cuando el contenido es técnico y esas sustituciones estorban. Una raya donde escribiste dos guiones, o una comilla curva dentro de un fragmento que copiarás a una terminal, pueden traicionar el significado. En documentación de código conviven ambas necesidades, y smartypants: false es la salida cuando la fidelidad del carácter pesa más que la elegancia tipográfica.

Un matiz tranquilizador atenúa el dilema: la ortotipografía solo actúa sobre la prosa, nunca sobre el código. Un bloque vallado o un fragmento en línea entre acentos graves quedan intactos, con sus comillas rectas y sus guiones literales, porque el pipeline sabe que ahí el carácter es dato, no texto. Así que el conflicto real se reduce a los raros casos en que necesitas una comilla recta dentro de la prosa —un ejemplo inline de sintaxis, una medida en pulgadas—; para todo lo demás, smartypants embellece sin romper nada.

syntaxHighlight: quién colorea el código

Los bloques de código vallados se resaltan durante el build, y syntaxHighlight decide cómo. Su valor por defecto es 'shiki', un resaltador que aplica temas reales de editor y produce colores fieles. Alternativas: 'prism', que emite clases CSS para que tú aportes el tema; y false, que desactiva el resaltado y deja los bloques como código pelado.

export default {
  markdown: {
    syntaxHighlight: 'shiki',
    shikiConfig: { theme: 'catppuccin-mocha', wrap: false },
  },
};

En Astro 7, syntaxHighlight admite además una forma de objeto que resuelve un choque real. Si usas un componente de diagramas —Mermaid, por ejemplo— cuyos bloques van vallados como código, no quieres que el resaltador los coloree, porque su contenido lo consume otro renderizador. La opción excludeLangs excluye esos lenguajes del resaltado y deja su texto intacto para quien lo procese después.

export default {
  markdown: {
    syntaxHighlight: { type: 'shiki', excludeLangs: ['mermaid'] },
  },
};

remarkRehype: ajustar el puente

La cuarta perilla es la más profunda porque toca el punto exacto que viste en la lección anterior: el paso de mdast a hast. remarkRehype recibe las opciones que Astro pasa a ese puente, y con ellas controlas detalles de cómo el árbol de contenido se traduce al árbol de HTML —cómo se etiquetan las notas al pie, si se conserva HTML crudo incrustado, qué texto acompaña a ciertos elementos generados.

export default {
  markdown: {
    remarkRehype: {
      footnoteLabel: 'Notas al pie',
      footnoteBackLabel: 'Volver al texto',
    },
  },
};

No es una perilla de uso diario, y ese es precisamente su valor: está ahí para el momento en que necesitas gobernar la traducción entre planos con precisión —traducir las etiquetas por defecto de las notas al pie, ajustar el manejo del HTML embebido— sin tener que escribir un plugin para algo que el puente ya sabe hacer, solo que con otros parámetros.

Una advertencia cierra el cuadro: si defines remarkRehype, tus opciones se fusionan con las que Astro ya pasa al puente, no las sustituyen a ciegas, de modo que ajustar la etiqueta de una nota al pie no desactiva el resto de la traducción por defecto. Es el mismo principio de gradualidad que gobierna gfm y smartypants: intervienes en un punto concreto y todo lo sensato que no tocaste sigue en pie.

flowchart TD
CFG[objeto markdown en config] --> GFM[gfm extensiones github]
CFG --> SP[smartypants tipografia]
CFG --> SH[syntaxHighlight resaltado]
CFG --> RR[remarkRehype puente]
GFM --> PIPE[pipeline de compilacion]
SP --> PIPE
SH --> PIPE
RR --> PIPE
PIPE --> OUT[html final coherente]
style CFG fill:#89b4fa,color:#11111b
style OUT fill:#a6e3a1,color:#11111b

Las cuatro perillas, junto con remarkPlugins y rehypePlugins, forman una sola configuración coherente: no son ajustes independientes sino puntos de intervención en fases distintas del mismo proceso. gfm y smartypants afinan el parseo; remarkRehype gobierna el puente; syntaxHighlight decide la serialización del código. Verlas como un mapa del pipeline, y no como una lista de opciones, es lo que convierte la configuración en una herramienta de diseño.

Vistas juntas, las cuatro perillas y los dos arrays de plugins componen un único objeto que se lee como un mapa del proceso entero:

// astro.config.mjs — el objeto markdown al completo
export default defineConfig({
  markdown: {
    gfm: true,
    smartypants: true,
    syntaxHighlight: { type: 'shiki', excludeLangs: ['mermaid'] },
    shikiConfig: { theme: 'catppuccin-mocha', wrap: false },
    remarkPlugins: [remarkReadingTime],
    rehypePlugins: [rehypeSlug, rehypeAutolinkHeadings],
    remarkRehype: { footnoteLabel: 'Notas al pie' },
  },
});