Sitio estático → GitHub Pages
Flujo completo: datos → página HTML/CSS/JS autónoma → verificación en navegador → publicación en GitHub Pages.
Objetivo: páginas de 1 a unos pocos cientos de elementos, un solo autor, cero dependencias en tiempo de ejecución.
Cuándo usarlo
| Sí | No |
|---|---|
| «hazme una página con esta lista / esta tabla», galería, dashboard de datos | app con backend, auth, base de datos → preguntar antes |
| «publícalo en GitHub / GitHub Pages» | sitio generado por un framework (Next, Astro, Hugo) → seguir el flujo del framework |
| reproducción de una página existente en datos (títulos, fechas, precios…) | copia del diseño/CSS/HTML de un sitio tercero → rechazar, rediseñar desde cero |
Reglas no negociables
- Diseño propio. Nunca copiar el CSS, el HTML ni los assets de un sitio tercero. Inspirarse en la estructura de información está bien; copiar la línea gráfica no.
- Hechos sí, obras no. Títulos, fechas, precios, notas, enlaces = datos factuales, reutilizables. Textos editoriales, descripciones, imágenes = protegidos: no copiarlos. Para las imágenes, enlazar directamente al CDN de origen en lugar de incluirlas en el repositorio (ver
reference/data-and-ethics.md). - Respetar las protecciones de acceso.
robots.txtque prohíbe a los crawlers, challenge Cloudflare/bot → no evadir. Buscar una API oficial, una clave, o degradar a un simple enlace saliente. - Siempre verificar en un navegador real antes de decir «está listo» (captura de pantalla + prueba de clics).
- No publicar sin confirmación del nombre del repositorio / de la cuenta si hay ambigüedad.
- No crear un dominio personalizado sin confirmación. Si el usuario no lo ha indicado, preguntarle si quiere una redirección Cloudflare y en qué dominio (paso 6). Nunca inventar un subdominio ni crearlo por iniciativa propia: el DNS es un efecto visible externamente.
Flujo de trabajo
1. Definir el alcance (30 s)
-
¿Qué datos, cuántos elementos, actualización única o recurrente?
-
Salida esperada: ¿una página? ¿orden/búsqueda? ¿qué reglas de visualización de negocio?
-
Dónde publicar: cuenta de GitHub, nombre del repositorio, público/privado (Pages requiere repositorio público en cuentas gratuitas).
-
Dominio personalizado — preguntar explícitamente si no se ha especificado. Hacer la pregunta de una sola vez, con la propuesta por defecto:
¿Quieres una redirección Cloudflare hacia
<owner>.github.io(CNAME, proxy desactivado)? Si sí, ¿qué subdominio/ruta?El nombre es libre por parte de la habilidad, pero el dominio es público desde su creación: no crear nada sin una respuesta explícita. Si el usuario responde que no, detenerse en la URL
https://<owner>.github.io/<repo>/y no crear ninguna entrada DNS.
2. Obtener los datos
Una sola ejecución de script → un data.json = fuente de verdad, separado del renderizado.
python3 fetch_data.py # → data.json
Cortesía: 0,3–0,7 s entre peticiones, User-Agent explícito, reintento en 429/5xx.
Detalles y casos complejos (PoW Anubis, Cloudflare, coincidencia difusa, API sin clave): reference/data-and-ethics.md.
3. Generar la página
Partir de las plantillas, no desde cero:
cp .dsh/skills/static-site-publish/templates/{index.html,styles.css,script.js} ./site/
cp .dsh/skills/static-site-publish/templates/build.py ./site/ # data.json → index.html
python3 ./site/build.py
build.py: pequeño generador Python (f-string +html.escape) que inyecta los datos en una cuadrícula de tarjetas. Sin JS en tiempo de ejecución para los datos.styles.css: tema oscuro por defecto, cuadrículaauto-fill minmax(), variables CSS.script.js: búsqueda instantánea + ordenación + reglas de visualización calculadas al abrir (para que la página siga siendo correcta sin reconstruir).- Todo lo que se pueda calcular al mostrar (estados, fechas relativas) debe hacerse en JS: así se evita reconstruir el sitio cada día.
- El HTML debe ser legible sin JS, y el JS debe ser progresivo.
4. Verificar
.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html
Abre la página en Chrome headless, escribe /tmp/site-shot.png y ejecuta la prueba de superposición de clics. Mirar la captura de pantalla (herramienta read_image) antes de concluir.
Checklist: renderizado desktop + móvil, datos completos (contar los elementos), enlaces correctos, ningún solapamiento.
5. Publicar
.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site mi-nombre-de-repo
El script: gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → polling de la URL hasta 200 → muestra la URL final.
El tiempo de Pages es de 20 a 90 s: no concluir «no funciona» antes de haber recibido un 200. Verificar también gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = built.
6. Dominio personalizado + Cloudflare
Solo si el usuario lo ha solicitado (ver paso 1). El DNS es público: no reinterpretar un «sí» vago en un nombre de dominio elegido por la IA.
Orden obligatorio: DNS primero, certificado después, Enforce HTTPS al final. El sitio ya debe responder con 200 en *.github.io antes de comenzar.
a. Redirección DNS en Cloudflare (MCP Cloudflare)
Requisito token: ámbitos zone.read + dns.write (Zone Read / DNS Edit). Si falta, detenerse y pedir la ampliación — no evadir.
GET /zones?name=<dominio raíz>→zone.id. Si cero zonas: el dominio no está en esta cuenta, preguntar.GET /zones/{zone_id}/dns_records?name=<fqdn>→ si ya existe un CNAME idéntico, no crear nada (idempotencia).POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<subdominio>", "content": "<owner>.github.io",
"proxied": false, "ttl": 1 }
proxied: false= DNS only, no negociable: el proxy de Cloudflare impide que GitHub emita el certificado.- El destino es
<owner>.github.io, sin barra final ni nombre de repositorio (jamesdadams.github.io, no.../mi-repo). ttl: 1= Auto.
- Verificar con resolución pública, no solo a través de la API:
dig +short <fqdn> CNAME @1.1.1.1 # → <owner>.github.io.
dig +short <fqdn> A @1.1.1.1 # → 185.199.108-111 .153
b. Dominio + Enforce HTTPS en GitHub Pages
.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <dominio> ./site
El script: escribe el archivo CNAME en el sitio (persiste en los redeploys y evita perder el dominio) → PUT /repos/{owner}/{repo}/pages con cname → espera https_certificate.state = approved → activa https_enforced: true.
⚠️ https_enforced: true devuelve 400 mientras el certificado no exista. Tiempo real: de 5 a 20 min después de crear el CNAME. Por eso el script itera en lugar de fallar. No activar «Enforce HTTPS» manualmente antes de la emisión, y no concluir que es un fallo durante esta ventana.
c. Verificación final
curl -sI https://<dominio>/ | head -5 # 200 + header server: GitHub.com
Luego volver a abrir la página en el navegador (paso 4) con la URL personalizada: un 200 no prueba que las rutas relativas (styles.css, script.js) resuelvan — es la trampa clásica de las project pages servidas en la raíz de un dominio.
7. Hacer posible la actualización
- Colocar la carpeta git en la carpeta de proyecto del usuario (no en
/tmp, que se borra al reiniciar). - Documentar en el
README.md: de dónde vienen los datos, cómo relanzar la extracción, qué es fijo (datos) vs vivo (reglas calculadas en JS). - Señalar explícitamente al usuario qué no se actualizará solo.
Errores ya encontrados
| Síntoma | Causa | Corrección |
|---|---|---|
| 403 «Just a moment…» | challenge Cloudflare | documentar el límite, API oficial o enlace saliente; no intentar evadir |
| Página truncada «Making sure you're not a bot» | PoW Anubis | resolver el challenge (ver referencia) o pedir un export al usuario |
| Selector que devuelve 0 resultados en todos los elementos | patrón incorrecto (ej. /games/lib/genre: vs /games/lib/popular/genre:) | imprimir una muestra del HTML y probar la regex en 1 página antes de iterar |
| Clic en una tarjeta que no abre el enlace correcto | capa <a> cubierta por un hijo posicionado | pointer-events: none en los elementos decorativos; probar con elementFromPoint |
| GitHub Pages 404 los primeros minutos | build en curso | polling hasta 90 s |
| Datos de una columna vacíos | etiqueta variable en la fuente («Released» vs «Early Access») | patrón tolerante + log por elemento, nunca un except: pass silencioso |
https_enforced devuelve 400 «certificate does not exist» | certificado aún no emitido | esperar https_certificate.state = approved (5-20 min), el script itera |
| Dominio personalizado da 404 tras 30 min | CNAME ausente / propietario incorrecto / archivo CNAME faltante en el repo | dig para confirmar el CNAME, relanzar set-pages-domain.sh |
| HTTPS roto después de activar el proxy | registro pasado a Proxied | volver a DNS only (proxied: false), el certificado de GitHub no puede validarse a través del proxy |
| «Domain is already in use» | dominio ya declarado en otro repositorio de la cuenta | un dominio personalizado por repositorio; liberar el anterior antes de reasignar |
CSS/JS devuelven 404 en el dominio personalizado pero funcionan en *.github.io/repo/ | rutas absolutas (/styles.css) en una project page servida en la raíz | rutas relativas (styles.css) |
Referencias
reference/data-and-ethics.md— extracción, PoW Anubis, Cloudflare, licencias, hotlink de imágenesreference/design-and-verify.md— sistema de diseño mínimo, pruebas en navegador, a11yreference/publish-gh-pages.md— comandosgh, nomenclatura, dominios, solución de problemasscripts/publish-gh-pages.sh— publicación + activación de Pagesscripts/set-pages-domain.sh— dominio personalizado + Enforce HTTPS (después del CNAME de Cloudflare)scripts/verify-site.shtemplates/{index.html,styles.css,script.js,build.py}