Rutas del sitio: las URL y los 301 que controla markeup-routes

La skill markeup-routes —«Mapea y anade rutas sin romper enlaces ni el SEO tecnico»— es una de las habilidades que el sistema MarkeUP tiene escritas para Hermes Agent y para Cline. Esta página es su ficha pública: lo que sabe hacer, cuándo se usa y qué comandos ejecuta.

Cada página tiene una dirección y una forma de llegar a ella: la skill evita que se rompan al mover una categoría de sitio.

El texto de la sección «Instrucciones del canon» está transcrito del fichero fuente —que se escribe sin tildes por convención de su propio gate—, así que es exactamente lo que lee el agente cuando le pides algo. La cabecera y esta entradilla sí están redactadas para leerlas.

Dato	Valor
Skill	`markeup-routes`
Responsabilidad	Mapea y anade rutas sin romper enlaces ni el SEO tecnico.
Versión	1.1.0
Autoría	uriszarernesto-blip · licencia MIT
Plataformas	linux · macos
Tags del canon	rutas · redirects · cloudflare · navegacion · sitemap · markeup
Skills relacionadas	markeup-context · markeup-seo · markeup-cli · markeup-graphs
Fuente	`~/.hermes/skills/markeup/markeup-routes/SKILL.md`

Responsabilidad unica: el mapa de URLs del sitio (no el de archivos del vault: eso es markeup-context): que pagina produce cada ruta, como se anade una nueva y como se renombra sin romper enlaces.

Mapa completo y ejemplos de redirect: references/route-map.md · doc de sistema: AGENTS.md § Rutas (multiblog).

Se anade una seccion o una pagina nueva (y por tanto una URL).
Se renombra una ruta: hay que dejar su 301 en public/_redirects.
Se toca el header (data-nav), el contexto ?from=<Categoria> o los botones de grafo.
Se revisa public/_headers (CSP) o una ruta con mayusculas (Cloudflare Pages las distingue).

Los grafos de cada seccion tienen su propio contrato: eso es markeup-graphs.

Ruta	Pagina	Que muestra
`/`	`index.astro`	Portada
`/posts`	`posts/index.astro`	Todos los posts · navegacion global
`/posts/<slug>`	`posts/[...slug].astro`	Un articulo (`?from=<Categoria>` acota la seccion)
`/category/<Cat>`	`category/[category]/index.astro`	Solo esa seccion (+ botones a sus grafos)
`/category/<Cat>/Grafo2D` · `Grafo3D`	`category/[category]/Grafo*.astro`	Grafo solo de esa seccion
`/Grafo2D` · `/Grafo3D`	`Grafo2D.astro` · `Grafo3D.astro`	Grafo del vault completo
`/podcasts`	`podcasts.astro`	Todos los audios del vault (miniatura + reproductor)
`/documentales`	`documentales.astro`	Los vídeos-documental del vault (tag + embed de YouTube)
`/libros`	`libros.astro`	Los libros del vault (un post con `bookIsbn` por libro, con portada y ficha)
`/categories` · `/tags` · `/tags/<tag>`	`categories/` · `tags/`	Indices
`/search`	`search.astro`	Busqueda (Pagefind)
`/faq` · `/privacy` · `/terms` · `/animated-sections` · `/admin`	paginas sueltas	Estaticas / internas
`/404`	`404.astro`	No encontrado (lista las secciones)
`/feed.xml` · `/sitemap.xml` · `/llms.txt`	`feed.xml.ts` · `sitemap.xml.ts` · `llms.txt.ts`	Canales derivados
`/api/posts.json` · `/api/search-graph.json`	`api/*.ts`	Datos para el tooltip y la busqueda del grafo

Las secciones se generan, no se listan. /category/<Cat> y sus dos grafos salen de getAllCategories() (src/lib/posts.ts): anadir una categoria crea su blog y sus grafos sin tocar plantillas. Igual /podcasts, desde getAllPodcasts() (src/lib/podcasts.ts) leyendo los bloques audio: publicar un audio lo anade solo. Y /documentales, desde getAllDocumentales() (src/lib/documentales.ts), que cruza el tag documental con los bloques embed de YouTube: publicar un documental lo anade solo. Y /libros, desde getAllLibros() (src/lib/libros.ts), leyendo el bookIsbn del frontmatter: publicar un libro lo anade solo.
La seccion viaja como contexto ?from=<Categoria>. Con el, anterior/siguiente, backlinks y grafo quedan acotados a la seccion; sin el (home, Google) la navegacion es global. No se inventa una ruta por seccion para el articulo.
La forma canonica es la capitalizada. Cloudflare Pages distingue mayusculas: /Grafo2D es la URL; /grafo2d no es “la misma ruta en minusculas”, es un 404.

Crear la pagina nueva (o renombrar el archivo) y dejar el enlace en el header (src/components/common/Header.astro, atributo data-nav: inicio, blogs, secciones). El boton activo que ilumina el header sale de ahi.
Anadir el 301 en public/_redirects, con el comentario de por que y la fecha.
Comprobar que ninguna regla casa su propio destino (seria un bucle). Los comodines son codiciosos y no pueden ir en medio: para un segmento variable se usa un placeholder (/category/:cat/graphify /category/:cat/Grafo2D 301).
Actualizar el mapa de aqui y AGENTS.md § Rutas si cambio la forma de una ruta canonica.

# public/_redirects (formato Cloudflare Pages: origen  destino  codigo)
/graph-2d    /Grafo2D    301
/graphify    /Grafo2D    301
/graph       /Grafo3D    301
/category/:cat/graphify    /category/:cat/Grafo2D    301

npm run og genera las tarjetas Open Graph en public/img/og/ (no se editan a mano; sync:images nunca las toca).
npm run build:search corre Pagefind sobre dist/ y versiona su ruta (stamp-pagefind-version.mjs): el service worker y el _headers van sincronizados con esa copia versionada.
npm run build:stamp (al final de build) sella el numero de build.
public/_headers define el CSP por ruta (el frame-src de los medios embebidos va sincronizado con PROVIDERS: lo comprueba validate:media).

cd ~/markeup
npm run validate:share     # metadata de compartir (OG/Twitter) por pagina
npm run validate:icons     # iconos y rutas de assets
npm run build              # valida ademas el frame-src del CSP
npm run preview            # sirve dist/ para probar los 301 en local

Los 301 de /public/_redirects no los aplica astro dev (astro dev no ejecuta ese archivo): en local se comprueban con npm run preview o en Cloudflare.

Una ruta nueva = una pagina en src/pages/ + enlace en el header (data-nav) + entrada en el mapa de esta skill. Si renombra a otra, tambien el 301.
No escribir a mano la lista de secciones en una plantilla: se deriva de getAllCategories().
No mezclar esto con los grafos: el comportamiento de las vistas es de markeup-graphs.
/posts/<slug> usa el slug del frontmatter, no el nombre del archivo: ver markeup-frontmatter y markeup-cli (validate:slugs).

references/route-map.md — mapa completo, endpoints, redirects y checklist.
markeup-seo — title/description y por que el canibalismo bloquea.
Codigo: src/pages/, public/_redirects, public/_headers.

¿Quieres saber cómo se piden estas cosas? La guía completa está en skills de Hermes Agent, con la chuleta de objetivos y los casos paso a paso.

Rutas del sitio

Rutas del sitio: las URL y los 301 que controla markeup-routes

Posts que enlazan a este artículo