Caprini Dev

sagas/odisea-del-blog-maestro/002-galeria-dinamica-y-content-layer.md

2026-03-24 published

Episodio 002 — Galería dinámica y Content Layer

Episodio 002 — Galería dinámica y Content Layer

Serie: bitácora de ingeniería — caprini.dev
Slug: 002-galeria-dinamica-y-content-layer
Resumen narrativo: cómo convertimos documentos de texto (specs, router, branding) en una web dinámica con rutas estables y metadatos explícitos.

Reto central: sustituir ímport.meta.glob sobre archivos sueltos por la **Content Layer** de Astro (getCollection, render, esquema Zod) para ganar **robustez**: fallos de frontmatter en build, tipos coherentes y un solo lugar (src/content/config.ts`) donde vive el contrato del contenido.

Qué cambió en el producto

La galería en /specs sigue siendo el escaparate, pero el detalle /specs/[slug] deja de depender de rutas relativas frágiles al árbol de docs/ en la raíz. Todo el corpus documental vive bajo src/content/docs/, con colección docs y campos obligatorios title, description y status. El humano (y el agente) ve los planos publicados en el mismo sitio que el resto del blog: misma tipografía, mismo neón, misma voz.

Resumen Técnico

  • Stack: Astro ^6, ástro:contentcondefineCollection y esquema **Zod** (title, description, statuscomostring`).
  • Rutas de contenido: src/content/docs/projects/*/spec.md (galería /specs), src/content/docs/system/episodes/*.md (bitácora); router y branding bajo src/content/docs/system/.
  • Páginas: src/pages/specs.astro usa getCollection('docs') filtrando projects/*/spec; src/pages/specs/[slug].astro usa getEntry + render.
  • Archivos tocados: src/content.config.ts (colección docs + glob loader; Astro 6 ya no admite el config legado en src/content/config.ts sin flag de compatibilidad), migración de docs/ → src/content/docs/, DOC_ROUTER.md, episodio 002 (este archivo), memoria del agente.

Errores Encontrados

  • Operaciones de archivos en Windows: mover carpetas completas puede chocar con permisos, locks (OneDrive, IDE) o comandos mal escapados; conviene validar el árbol tras un movimiento masivo.
  • Referencias rotas: enlaces en router, reglas Cursor y episodios que apuntaban a docs/ deben alinearse con src/content/docs/ para no desorientar a quien lee solo markdown en el editor.

Solución de la IA

  • Definir una colección docs con esquema mínimo y frontmatter en cada .md bajo src/content/docs/.
  • Filtrar en la galería solo entradas projects/*/spec.md para no mezclar episodios ni router con specs en /specs.
  • Actualizar DOC_ROUTER.md y la memoria persistente para que el camino “obligatorio” al router sea el nuevo path físico.
  • Tras el hito, registrar el episodio 002 con el formato estándar (incl. Vibe Check).

Vibe Check (Sensaciones del humano)

La sensación de ver tus planos (specs) publicados por primera vez: no es solo un PDF olvidado en una carpeta; es el mismo sitio que enseñas, con la misma estética synthwave, donde el router y el branding son ciudadanos de primera clase. El salto de glob a Content Layer se siente como pasar de “funciona en mi máquina” a “el build te avisa si te olvidaste del description”.

Fin del episodio 002.