CommunityProgramación y desarrollogithub.com

publicación-de-sitio-estático

Genera un pequeño sitio estático en HTML/CSS/JS puro (sin build ni framework) a partir de datos, lo verifica en un navegador headless y lo publica en GitHub Pages con dominio personalizado opcional.

¿Qué es publicación-de-sitio-estático?

Esta habilidad permite crear y publicar sitios estáticos ligeros directamente desde datos estructurados, ideal para listas, galerías, tableros de control o portafolios de un solo autor. Genera una página HTML/CSS/JS autónoma sin dependencias de ejecución, usando un generador Python simple que inyecta datos en una plantilla. La verificación se realiza en Chrome headless para garantizar que el renderizado sea correcto (screenshot + test de clics) antes de publicar. Publica en GitHub Pages mediante un script que automatiza `git init`, `gh repo create` y la activación de Pages, con polling hasta obtener un 200. Soporta dominio personalizado a través de Cloudflare: configura un registro CNAME con proxy desactivado (DNS only) y luego activa Enforce HTTPS en GitHub Pages. El flujo completo incluye reglas éticas estrictas: no copiar diseños de terceros, respetar `robots.txt`, no eludir protecciones (Cloudflare, PoW) y siempre confirmar con el usuario el nombre del repositorio y el dominio antes de publicar.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JamesDAdams/my-skills/tree/HEAD/.apm/skills/static-site-publish

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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 datosapp 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

  1. 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.
  2. 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).
  3. Respetar las protecciones de acceso. robots.txt que prohíbe a los crawlers, challenge Cloudflare/bot → no evadir. Buscar una API oficial, una clave, o degradar a un simple enlace saliente.
  4. Siempre verificar en un navegador real antes de decir «está listo» (captura de pantalla + prueba de clics).
  5. No publicar sin confirmación del nombre del repositorio / de la cuenta si hay ambigüedad.
  6. 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ícula auto-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.

  1. GET /zones?name=<dominio raíz> → zone.id. Si cero zonas: el dominio no está en esta cuenta, preguntar.
  2. GET /zones/{zone_id}/dns_records?name=<fqdn> → si ya existe un CNAME idéntico, no crear nada (idempotencia).
  3. 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.
  1. 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íntomaCausaCorrección
403 «Just a moment…»challenge Cloudflaredocumentar el límite, API oficial o enlace saliente; no intentar evadir
Página truncada «Making sure you're not a bot»PoW Anubisresolver el challenge (ver referencia) o pedir un export al usuario
Selector que devuelve 0 resultados en todos los elementospatró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 correctocapa <a> cubierta por un hijo posicionadopointer-events: none en los elementos decorativos; probar con elementFromPoint
GitHub Pages 404 los primeros minutosbuild en cursopolling hasta 90 s
Datos de una columna vacíosetiqueta 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 emitidoesperar https_certificate.state = approved (5-20 min), el script itera
Dominio personalizado da 404 tras 30 minCNAME ausente / propietario incorrecto / archivo CNAME faltante en el repodig para confirmar el CNAME, relanzar set-pages-domain.sh
HTTPS roto después de activar el proxyregistro pasado a Proxiedvolver 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 cuentaun 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ízrutas relativas (styles.css)

Referencias

  • reference/data-and-ethics.md — extracción, PoW Anubis, Cloudflare, licencias, hotlink de imágenes
  • reference/design-and-verify.md — sistema de diseño mínimo, pruebas en navegador, a11y
  • reference/publish-gh-pages.md — comandos gh, nomenclatura, dominios, solución de problemas
  • scripts/publish-gh-pages.sh — publicación + activación de Pages
  • scripts/set-pages-domain.sh — dominio personalizado + Enforce HTTPS (después del CNAME de Cloudflare)
  • scripts/verify-site.sh
  • templates/{index.html,styles.css,script.js,build.py}

Skills relacionados