Procedimiento para Páginas de Contenido
Procedimiento paso a paso para crear páginas impulsadas por contenido usando Astro Content Collections (Content Layer API) con enrutamiento dinámico.
Requisitos previos
src/styles/global.cssexiste con tokens de diseño (creado por css-procedure)docs/stitch/reference.mdexiste (información de campos de las pantallas de Stitch)
Entrada / Salida
[Entrada] [Salida]
docs/stitch/reference.md ──┐
(Información de campos de pantalla) │
progress.md notas ──────────┼──→ src/content/config.ts (esquema)
(Estructura de sección, │ src/content/<colección>/<slug>/index.mdx (datos)
decisiones de diseño) │ src/pages/<colección>/[...slug].astro (enrutamiento)
│ src/components/*.astro (componentes de sección)
Pasos
Paso 1: Definición del esquema (src/content/config.ts)
Astro 5 Content Layer API usa el cargador glob.
1-1. Definir la colección
import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";
const miColeccion = defineCollection({
loader: glob({ pattern: "**/index.mdx", base: "./src/content/mi-coleccion" }),
schema: ({ image }) =>
z.object({
title: z.string(),
// ... define los campos
heroImage: image(), // Usa el helper image() para imágenes
}),
});
export const collections = { miColeccion };
1-2. Directrices de diseño del esquema
- Empieza mínimo, extiende incrementalmente. Define solo los campos necesarios para el renderizado de la página actual; agrega más al implementar componentes.
- Usa el helper
image()para campos de imagen para habilitar la validación y optimización de rutas en tiempo de compilación. - Usa
.optional()para campos que no son requeridos en cada entrada. - Usa arrays opcionales para datos a nivel de sección para controlar la visibilidad de la sección por página:
// Esquema moments: z.array(z.object({ title: z.string(), ... })).optional()<!-- Plantilla de página: renderizado condicional --> {data.moments && <MomentsSection moments={data.moments} />}
1-3. Errores comunes de YAML Frontmatter
- Los nombres de meses (March, May, etc.) y Yes/No son convertidos automáticamente por YAML. Ponlos entre comillas si deben ser cadenas de texto:
date: "March" - Las rutas de imagen son relativas al archivo MDX:
heroImage: ./hero.jpg
Paso 2: Crear datos de contenido
2-1. Estructura de directorios
src/content/<colección>/<slug>/
├── index.mdx # frontmatter + cuerpo MDX
├── hero.jpg # Imágenes ubicadas junto al contenido
└── ...
2-2. Estructura del archivo MDX
---
title: "Título de la página"
heroImage: ./hero.jpg
description: "Texto de descripción"
---
## Cuerpo MDX
El contenido del cuerpo se recupera mediante `render()` y se renderiza como `<Content />`.
2-3. Gestión de imágenes
- Almacena las imágenes dentro de
src/content/junto a su contenido (no enpublic/) - Redimensiona las imágenes de más de 2560px antes de añadirlas al repositorio.
- Al usar el helper
image()en el esquema, las rutas de imagen en frontmatter se resuelven al tipoImageMetadata. UsaImageMetadatatambién en las Props del componente.
Paso 3: Página de enrutamiento dinámico
Crea src/pages/<colección>/[...slug].astro:
---
import type { GetStaticPaths } from "astro";
import { getCollection, render } from "astro:content";
export const getStaticPaths = (async () => {
const items = await getCollection("miColeccion");
return items.map((item) => ({
params: { slug: item.id },
props: { item },
}));
}) satisfies GetStaticPaths;
const { item } = Astro.props;
const { Content } = await render(item);
---
Puntos clave
getCollection()obtiene todas las entradas;getStaticPathsgenera las rutas estáticas.render()devuelve el cuerpo MDX como un componenteContent.item.dataproporciona acceso type-safe a los campos de frontmatter.- Renderizado condicional para campos opcionales:
{data.field && <Componente ... />}.
Paso 4: Archivos de datos de página (src/data/<página>.md)
El contenido editable por el usuario (texto, etiquetas, URLs) para cada página debe definirse en archivos Markdown con frontmatter YAML dentro de src/data/. Esto mantiene el formato consistente con las Colecciones de Contenido y facilita que los usuarios encuentren y editen su contenido.
Nota: El directorio
src/data/no es creado por la habilidad de scaffold. Créalo en este paso.
4-1. Crear un archivo de datos para cada página
src/data/
├── index.md # Contenido de la página de inicio (Works)
├── about.md # Contenido de la página Acerca de mí
└── skills.md # Contenido de la página de Habilidades
4-2. Definir contenido editable como frontmatter YAML
---
# ==============================
# Contenido de la página de inicio
# Edita este archivo para personalizar tu página.
# ==============================
hero:
headingPrefix: "Hola, soy"
highlightedText: "Desarrollador Web."
description: "Construyo aplicaciones escalables y centradas en el usuario..."
badgeText: "Disponible para nuevos proyectos"
cta:
heading: "¿Listo para construir algo juntos?"
description: "Actualmente estoy abierto a oportunidades freelance..."
buttons:
- label: "Contactar"
href: "mailto:[email protected]"
variant: "primary"
- label: "Descargar CV"
href: "#"
variant: "secondary"
---
- Pon solo texto editable por el usuario en el YAML (cadenas, etiquetas, URLs, arrays de texto).
- Mantén los datos no editables (rutas de iconos SVG, etc.) como constantes de TypeScript en el archivo
.astrode la página.
4-3. Importar datos en la página
Usa import.meta.glob() para cargar el frontmatter:
---
const content = Object.values(
import.meta.glob("../data/index.md", { eager: true })
)[0] as { frontmatter: Record<string, unknown> };
const { hero, cta } = content.frontmatter;
---
Paso 5: Implementación de componentes de sección
Crea cada sección (hero, moments, etc.) como un componente independiente en src/components/.
Sigue las directrices de desarrollo para la estructura de componentes y las reglas CSS.
Visualización de imágenes: <Picture> vs <img>
| Método | Cuándo usarlo | Ejemplo |
|---|---|---|
<Picture> | Imágenes estáticas conocidas en tiempo de compilación | Fondos de héroe, imágenes de entrada |
<img> | Imágenes intercambiadas dinámicamente por JS del cliente | Presentaciones de diapositivas de galería modal |
<Picture> se renderiza en tiempo de compilación, por lo que no se puede usar cuando src es intercambiado por JS del cliente.
JavaScript del lado del cliente
Las etiquetas <script> en componentes Astro se ejecutan como JS del cliente. Las funciones interactivas se pueden construir sin frameworks (React, etc.).
Patrón de paso de datos: Usa atributos data-* para pasar datos de frontmatter al JS del cliente. <script> no puede referenciar directamente variables de frontmatter.
Accesibilidad: Modal / Superposición
Lista de verificación para la implementación de diálogos modales:
| Requisito | Implementación |
|---|---|
| Semántica | role="dialog" + aria-modal="true" + aria-label |
| Abrir/cerrar | Alternar atributo hidden + transición CSS opacity |
| Bloqueo de scroll | Abrir: document.body.style.overflow = "hidden" / Cerrar: restaurar a "" |
| Teclado | Escape para cerrar, teclas de flecha para navegación |
| Trampa de foco | Tab/Shift+Tab cicla entre botones dentro del modal |
| Restauración de foco | focus() en el elemento que activó el modal al cerrar |
| Cierre con fondo | Cerrar cuando el clic no está en un elemento interactivo |
| z-index | Mayor que elementos fijos existentes (ej. header 50 → modal 60) |
Paso 6: Verificación de compilación
npm run build
Los errores de validación del esquema de Content Collections aparecen en tiempo de compilación con mensajes claros.
Errores comunes
| Error | Causa | Solución |
|---|---|---|
Expected type "string", received "object" | YAML convirtió automáticamente un valor (nombre de mes → Date, etc.) | Pon el valor entre comillas |
Could not find image | Ruta de imagen incorrecta | Verifica la ruta relativa desde el archivo MDX |
does not match collection schema | Campo faltante o tipo incorrecto en frontmatter | Verifica contra el esquema en config.ts |
Paso 7: Verificación del servidor de desarrollo
npm run dev
- Los cambios en el esquema pueden requerir reiniciar el servidor de desarrollo (limpiar el almacén de contenido).
- Si los errores persisten después de reiniciar, elimina el directorio
.astro/y reinicia.
Lista de verificación
-
src/content/config.tstiene el esquema definido - El frontmatter MDX cumple con el esquema
- Las imágenes están dentro de
src/content/y redimensionadas a ≤2560px -
[...slug].astrodevuelve todas las entradas degetStaticPaths - Las secciones de campos opcionales usan renderizado condicional
-
npm run buildse ejecuta correctamente - Confirmación visual en el navegador para todas las secciones (incluyendo ancho móvil)