Episodio 018 — SEO y búsqueda profunda
Serie: bitácora de ingeniería — caprini.dev
Enfoque: que el marketing técnico viva en el mismo sistema que las specs y los episodios, no como un apéndice olvidado.
El problema: ingeniería visible pero invisible en búsqueda
Un sitio estático bien construido puede ser excelente para quien ya te conoce y aún pobre en intención de búsqueda si los títulos y descripciones se dejan al azar del render por defecto. La búsqueda profunda —la que hace alguien que quiere entender procesos, pipelines o storytelling técnico— necesita señales explícitas: qué promete la página y con qué palabras la gente podría encontrarla.
Separar “lo técnico” de “lo de marketing” en silos distintos suele terminar en contenido desalineado o en metatags genéricos. La apuesta aquí es gobernanza unificada: los mismos archivos Markdown que ya alimentan el blog y La Odisea declaran también su capa SEO.
Qué entra en el Content Layer
En src/content.config.ts la colección docs y la colección series incorporan campos opcionales (para no romper entradas antiguas) y recomendados para todo lo nuevo:
seoTitle: título pensado para resultados de búsqueda y pestañas.metaDescription: hasta 160 caracteres, con tono que invite al clic.keywords: lista de términos que anclan tema y sinónimos útiles.
Así el contrato de contenido y el contrato de descubrimiento comparten origen: menos drift entre “lo que publicamos” y “lo que indexamos”.
Regla del agente: .cursor/rules/10-seo-standards.mdc
La regla aplica a src/content/docs/**/*.md y src/content/series/**/*.md: cualquier contenido nuevo debe incluir esos tres campos y, antes de cerrar, revisar que el título SEO sea atractivo y la descripción merezca el clic sin engañar. Eso acopla marketing técnico al flujo de Spec Driven + Vibecoding: el agente no solo escribe Markdown, valida intención de descubrimiento en el mismo paso.
Marketing técnico sin postureo
Marketing técnico aquí no significa slogans vacíos: significa claridad de promesa (qué aprenderá el lector), vocabulario alineado al problema real y coherencia con DOC_ROUTER.md y AGENT_PERSISTENT_MEMORY.md. Si un episodio habla de despliegue SFTP, las keywords deben reflejar hosting estático, FTP/SFTP, Astro, no buzzwords desconectados.
Primer capítulo de La Odisea y el puente al layout
El fichero src/content/series/001-la-revolucion-del-latido.md materializa la serie con frontmatter SEO completo y un relato que conecta historia de la automatización con el taller Caprini. Los metatags en HTML del layout pueden consumir estos campos en un paso posterior; mientras tanto, los datos ya están gobernados en el esquema y en la regla.
Cierre
SEO deja de ser un checklist posterior y pasa a ser parte de la gobernanza: mismo repositorio, mismas convenciones, misma responsabilidad de cierre. El siguiente ajuste natural es renderizar seoTitle y metaDescription en MainLayout (o layouts de blog/odisea) para que buscadores y redes vean lo que ya decidimos en el frontmatter.