Markdown en Astro: frontmatter, layout y slugs

Astro trata el Markdown como un ciudadano de primera: un .md en src/pages no es un dato que haya que cargar, sino una página que existe por el hecho de estar ahí. El mismo enrutado por ficheros que publica un .astro publica un .md, y el compilador se encarga del resto: parsea el frontmatter, transforma el cuerpo en HTML, lo envuelve en el layout que le indiques y le cuelga identificadores estables a cada encabezado. Entender esa cadena —de fichero a ruta, de cabecera a datos, de texto a documento maquetado— es la base sobre la que se apoya todo lo demás de este nivel.

El archivo .md como página de pleno derecho

En Astro, el enrutado no es una tabla que mantienes: es una consecuencia de dónde pones los ficheros. Todo lo que vive bajo src/pages y sabe producir HTML se convierte en una ruta, y el Markdown sabe producir HTML. Un src/pages/acerca.md publica /acerca sin que declares nada, igual que lo haría un .astro. No hay un paso de importación ni un registro central; el fichero es la página.

Esa equivalencia tiene una consecuencia conceptual fuerte: el Markdown deja de ser un formato de datos que otro código consume y pasa a ser una unidad de publicación autónoma. El compilador de Astro lo reconoce como un módulo de página, extrae su frontmatter, compila su cuerpo a HTML y emite el fichero estático correspondiente. Lo que escribes en prosa llana termina siendo un documento navegable, y el único requisito es la ubicación.

La misma mecánica cubre dos extensiones. Un .md es Markdown puro; un .mdx añade la capacidad de importar y usar componentes dentro del contenido, entrelazando prosa y JSX. Para el enrutado y el layout no hay diferencia: ambos se autopublican desde src/pages y ambos aceptan la propiedad layout. La elección depende de si el documento necesita componentes e interactividad —entonces .mdx— o le basta con texto enriquecido —entonces .md—. Esta misma guía está escrita en .mdx, y por eso puede intercalar tarjetas y diagramas entre los párrafos sin salir del documento.

Que sea una unidad autónoma tiene una cara muy concreta en el build: cada Markdown de src/pages produce su propio fichero HTML estático, listo para servirse desde cualquier CDN sin un servidor detrás. Nadie interpreta el Markdown al vuelo cuando alguien pide la página; la interpretación ocurrió una vez, al compilar, y lo que queda es un .html inerte y rapidísimo. El Markdown es la fuente; el HTML estático, el producto.

---
title: "Sobre este sitio"
layout: ../layouts/Base.astro
---

# Sobre este sitio

Este párrafo se compila a HTML y se sirve en `/acerca`.

Conviene separar este caso —Markdown como página— del Markdown como contenido de una colección, que verás gobernado por getCollection. En src/pages el fichero se autopublica; en una colección el fichero es un dato que consultas y decides dónde mostrar. Son dos modos legítimos y complementarios: la página suelta para lo estático y singular, la colección para lo que se repite y se lista.

La regla para elegir es simple: si el documento es único y su URL debe reflejar dónde lo guardas, es una página; si pertenece a un conjunto homogéneo que vas a ordenar, filtrar o paginar, es una colección. Confundirlos no rompe nada, pero te hace nadar contra corriente: paginar páginas sueltas es incómodo, y publicar una colección exige escribir la ruta que la recorre. Cada modo brilla en su terreno.

Frontmatter: datos en la cabecera

El frontmatter es el bloque delimitado por dos líneas de tres guiones al principio del fichero, escrito en YAML. No es contenido: es metadato. Ahí declaras el título, la fecha, las etiquetas o cualquier campo que tu maquetación necesite. Astro lo parsea y lo expone como un objeto, separando limpiamente los datos sobre el documento del cuerpo del documento.

Esa frontera importa porque son dos naturalezas distintas. El cuerpo se compila a HTML y se ve; el frontmatter se lee como estructura y alimenta decisiones —qué layout usar, qué título poner en la pestaña, cómo ordenar una lista—. Mezclarlos sería como confundir las columnas de una tabla con el texto de una celda: relacionados, pero de planos diferentes.

En una página suelta, ese frontmatter es libre: escribes los campos que tu layout necesite y nadie los valida. Es a la vez su comodidad y su fragilidad, porque un title mal escrito no se detecta hasta que la plantilla lo lee vacío. Es justo la carencia que las colecciones resuelven con un esquema de Zod, capaz de rechazar en el build un frontmatter que no cumpla el contrato. Para lo singular, la libertad del frontmatter suelto compensa; para lo que se repite cien veces, la red del esquema evita cien errores callados.

El layout mágico de las páginas Markdown

Una página Markdown, por sí sola, solo produce el HTML de su cuerpo: unos encabezados, unos párrafos, sin <html>, sin <head>, sin cabecera ni pie. La propiedad especial layout del frontmatter cierra ese hueco. Apúntala a un componente .astro y Astro envolverá automáticamente el HTML compilado dentro de ese componente, entregándotelo por su <slot />.

Lo que hace “mágico” a este mecanismo es cuánto te da sin pedir nada a cambio. El componente de layout recibe props que Astro rellena solo: frontmatter, con todos los campos de la cabecera ya parseados; url, con la ruta pública de la página; file, con su ruta en disco; y headings, con la lista de encabezados del documento. El cuerpo compilado llega por el <slot />.

---
// src/layouts/Base.astro
const { frontmatter, headings } = Astro.props;
---
<html lang="es">
  <head><title>{frontmatter.title}</title></head>
  <body>
    <h1>{frontmatter.title}</h1>
    <nav>{headings.length} secciones</nav>
    <slot />
  </body>
</html>

El reparto es nítido y merece grabarse: el Markdown aporta el contenido y los datos; el layout aporta el armazón del documento y decide cómo presentarlos. El autor escribe prosa y una cabecera mínima; la maquetación vive centralizada en un componente que cien páginas comparten. Cambiar el título de la pestaña o añadir una etiqueta al <head> es tocar un fichero, no cien.

La ruta que pones en layout se resuelve como cualquier importación: relativa al propio Markdown, con ../ para subir de carpeta hasta src/layouts. Y es opcional: un Markdown sin layout se sirve igual, solo que como el HTML desnudo de su cuerpo, sin <html> ni <head>. Esa opcionalidad es coherente con la filosofía del framework —nada es obligatorio hasta que lo necesitas—, pero en la práctica casi toda página quiere su marco, y declarar el layout es el primer gesto tras crear el fichero.

Slugs e id de encabezado

Dos identificadores se generan de forma determinista y conviene saber de dónde salen. El primero es el slug de la página: en src/pages proviene de la ruta del fichero. src/pages/blog/guia.md publica /blog/guia; el nombre del fichero, sin la extensión, es el último segmento de la URL. No hay aleatoriedad ni configuración: la estructura de carpetas es la estructura de rutas.

src/pages/acerca.md         ->  /acerca
src/pages/blog/guia.md      ->  /blog/guia
src/pages/blog/index.md     ->  /blog
src/pages/docs/api/v2.md    ->  /docs/api/v2

Un caso especial afina la regla: un fichero llamado index.md no aporta su nombre a la URL, sino que representa la raíz de su carpeta. src/pages/blog/index.md publica /blog, no /blog/index. Así, las carpetas construyen la jerarquía de rutas y el index marca su punto de entrada, exactamente como haría un .astro. El slug no es más que la traducción literal del árbol de ficheros al árbol de URL.

El segundo son los id de los encabezados. Al compilar el Markdown, Astro recorre cada #, ##, ### y le asigna un id derivado de su texto mediante github-slugger: pasa a minúsculas, sustituye espacios por guiones y descarta la puntuación. Así, ## Mi Sección se convierte en <h2 id="mi-seccion">, y esa ancla existe sin que muevas un dedo, lista para enlazarse desde una tabla de contenidos o desde fuera con un #mi-seccion.

## Mi Sección
### Detalles Finos

se traduce, en el HTML generado, a encabezados con ancla propia:

<h2 id="mi-seccion">Mi Sección</h2>
<h3 id="detalles-finos">Detalles Finos</h3>

flowchart LR
MD[archivo punto md] --> FM[frontmatter parseado]
MD --> BODY[cuerpo compilado a html]
FM --> LAY[layout via propiedad layout]
BODY --> IDS[ids de encabezado via slugger]
BODY --> LAY
LAY --> PAGE[pagina final servida]
style MD fill:#89b4fa,color:#11111b
style PAGE fill:#a6e3a1,color:#11111b

Que ambos identificadores sean deterministas es una garantía, no un detalle. Significa que puedes enlazar a /blog/guia#mi-seccion con la certeza de que la ancla existirá mientras el encabezado exista, sin inventar id a mano ni temer colisiones arbitrarias. Cuando dos encabezados comparten texto, github-slugger desambigua añadiendo un sufijo numérico, de modo que la unicidad se mantiene incluso en documentos repetitivos.

Esa doble determinación —slug de página y slug de encabezado— es el cimiento del deep linking: enlazar no ya a una página, sino a un punto exacto dentro de ella. Un índice lateral que salta a cada sección, un enlace compartido que abre justo donde importa, una cita anclada desde otro artículo: todo se sostiene sobre identificadores que existen y no cambian por capricho. Lo que aquí parece un detalle de implementación es la base sobre la que la próxima lección levantará tablas de contenido enteras a partir de la lista de encabezados que Astro ya calculó.