piazambuja/sitio-github-pages

Sitio personal en GitHub Pages

Objetivo: un sitio personal rápido y accesible en https://<cuenta>.github.io/, construido desde un único archivo de contenido que el usuario puede editar, publicado por GitHub Actions en cada push a main. Sin framework ni dependencias de npm, por lo que se compila en cualquier lugar.

Funciona para cualquier persona, en cualquier campo. Escribe el sitio en el idioma del usuario.

Reglas estrictas

• El repositorio debe llamarse exactamente <cuenta>.github.io, donde <cuenta> es el nombre de usuario de GitHub (u organización) que lo posee, en minúsculas. Solo ese nombre publica en la raíz (https://<cuenta>.github.io/). Cualquier otro nombre publica en una subruta (https://<cuenta>.github.io/<repo>/), y un error tipográfico o un propietario diferente significa que la URL raíz seguirá devolviendo un 404. Cada cuenta tiene un sitio de este tipo.
• Nunca inventes contenido. Sin empleadores, fechas, títulos, métricas, proyectos o enlaces inventados. Los datos faltantes se convierten en un marcador visible como [año en que empezaste] y una pregunta al usuario.
• Los datos personales son públicos una vez enviados, incluso en el historial de git. Pregunta antes de publicar un número de teléfono, dirección particular, correo electrónico personal o fecha de nacimiento; prefiere ciudad/región, un enlace de contacto y LinkedIn. Nunca comprometas secretos ni archivos .env.
• Ejecuta comandos que creen o modifiquen cosas en GitHub (crear repositorio, habilitar Pages, hacer push) solo después de mostrar al usuario lo que harán, la primera vez. Todo lo demás puede ejecutarse directamente.

Requisitos previos

La CLI de GitHub, instalada e iniciada sesión. Verifica primero y soluciona lo que falle:

gh --version                        # instalar: https://cli.github.com
gh auth status                      # ¿con sesión iniciada? ¿qué cuenta? ¿qué ámbitos?
gh auth login -h github.com -p https -w          # si no hay sesión iniciada (flujo del navegador)
gh auth refresh -h github.com -s workflow        # enviar .github/workflows/* necesita el ámbito workflow
gh api user --jq .login             # el nombre de la cuenta: el repositorio es <esto>.github.io
git --version
node --version                      # 18+; solo se necesita para ejecutar la compilación localmente

Si el sitio pertenece a una organización, <cuenta> es el nombre de la organización y el usuario necesita permiso para crear repositorios en ella (gh repo create <org>/<org>.github.io).

Paso 1: verificar el punto de partida

ACCOUNT=$(gh api user --jq .login | tr '[:upper:]' '[:lower:]')
REPO="$ACCOUNT.github.io"
gh repo view "$ACCOUNT/$REPO" --json name,visibility,url 2>/dev/null || echo "el repositorio aún no existe"
gh api "repos/$ACCOUNT/$REPO/pages" 2>/dev/null || echo "Pages no está habilitado"

• El repositorio existe con un sitio: preguntar si reemplazarlo, conservarlo o migrar su contenido. Nunca sobrescribir sin un sí.
• El repositorio existe con otro nombre (ej. portfolio, MyName.github.io bajo otra cuenta): ofrecer renombrarlo (gh repo rename <cuenta>.github.io -R <propietario>/<antiguo>) en lugar de crear otro.
• En el plan gratuito, el repositorio debe ser público para que Pages funcione.

Paso 2: recopilar contenido (preguntar solo lo que falta, en un mensaje)

1. Nombre, rol o título, ciudad/región (opcional), y el idioma del sitio.
2. Dos o tres frases sobre lo que hace y para quién, luego un "acerca de" más extenso si lo desea.
3. Experiencia o proyectos: título, organización, período, una o dos líneas cada uno. Un CV, exportación de LinkedIn o una página existente es la fuente más rápida.
4. Enlaces: GitHub (completado automáticamente), LinkedIn, correo electrónico o formulario de contacto, otros perfiles.
5. Apariencia en pocas palabras, y cualquier cosa a evitar. Sin preferencia, usar la apariencia sobria por defecto en assets/style.css.

Poner las respuestas en content/profile.json (forma en assets/profile.example.json). Mostrar al usuario el JSON antes de compilar, y marcar cada marcador.

Paso 3: crear el proyecto

Estructura recomendada (el mismo diseño funciona para cualquier generador estático):

<cuenta>.github.io/
  AGENTS.md                    instrucciones para cualquier agente de código (plantilla: assets/AGENTS.md)
  CLAUDE.md -> AGENTS.md       enlace simbólico opcional, para que Claude Code lea el mismo archivo
  README.md                    cómo editar, compilar y publicar
  content/profile.json         todo el texto del sitio
  build.mjs                    generador, solo Node, sin dependencias (assets/build.mjs)
  static/style.css             tokens en :root, modo oscuro mediante prefers-color-scheme
  .github/workflows/deploy.yml compilar + desplegar en Pages (assets/deploy.yml)
  .gitignore                   dist/ y node_modules/

Copiar los archivos de la carpeta assets/ de esta habilidad, luego adaptarlos. scripts/ contiene la configuración del repositorio utilizada en el paso 4. Mantener AGENTS.md neutral para el agente: describe el proyecto, los comandos y las reglas de diseño, no una herramienta específica.

mkdir "$REPO" && cd "$REPO" && git init -b main
mkdir -p content static .github/workflows
# copiar assets/: build.mjs, style.css -> static/, deploy.yml -> .github/workflows/,
#               AGENTS.md, profile.example.json -> content/profile.json
ln -s AGENTS.md CLAUDE.md          # opcional
printf 'dist/\nnode_modules/\n' > .gitignore
node build.mjs && python3 -m http.server 4321 -d dist   # previsualizar en http://localhost:4321

Extras opcionales, solo si el usuario lo pide: una página de proyectos, un blog (archivos Markdown renderizados en tiempo de compilación), un dominio personalizado, o un mercado de complementos/habilidades en el mismo repositorio (.claude-plugin/marketplace.json + plugins/<complemento>/, con el sitio listándolos; validar con claude plugin validate . cuando Claude Code esté instalado).

Paso 4: crear el repositorio y habilitar Pages

Crear siempre el repositorio con gh, nunca escribiendo el nombre en la interfaz web: scripts/create-site-repo.sh toma el nombre de la cuenta con sesión iniciada, por lo que siempre es exactamente <cuenta>.github.io. Ejecutarlo desde la carpeta del sitio, primero con --dry-run y mostrar la salida al usuario:

bash <directorio-de-habilidad>/scripts/create-site-repo.sh --dry-run      # verifica gh, inicio de sesión, ámbitos; imprime lo que hará
bash <directorio-de-habilidad>/scripts/create-site-repo.sh                # crea el repositorio público, habilita Pages (Actions), configura origin
# sitio de organización:       ... --org <org>
# repositorio ya existe:     ... --existing   (solo después de verificar con el usuario qué contiene)

Se detiene si falta gh o no ha iniciado sesión, advierte cuando el token carece del ámbito workflow, y se niega a tocar un repositorio existente sin --existing. Los mismos pasos a mano:

gh repo create "$ACCOUNT/$REPO" --public --description "Sitio personal"
gh api -X POST "repos/$ACCOUNT/$REPO/pages" -f build_type=workflow   # PUT si Pages ya existe
git remote add origin "https://github.com/$ACCOUNT/$REPO.git"
gh api "repos/$ACCOUNT/$REPO/pages" --jq '{url: .html_url, source: .build_type}'

La configuración de Pages también se encuentra en la interfaz web en Configuración → Pages → Compilación y despliegue → Origen: GitHub Actions.

Paso 5: desplegar

git add -A && git commit -m "Sitio personal"
git push -u origin main
gh run watch "$(gh run list --workflow deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')" --exit-status
curl -sI "https://$REPO/" | head -1      # esperar HTTP/2 200; el primer despliegue puede tardar uno o dos minutos

A partir de entonces, cada push a main recompila y publica. gh workflow run deploy.yml redepliega sin un commit.

Paso 6: verificar antes de dar por terminado

• Abrir la URL en vivo, no solo la vista previa local. Los enlaces funcionan, no hay 404 en CSS ni páginas.
• Tomar capturas de pantalla a 1280px y 390px de ancho, en modo claro y oscuro. Sin desplazamiento horizontal a 390px.
• Teclado: Tab llega a cada enlace con un anillo de enfoque visible. El contraste de texto cumple WCAG AA en ambos temas.
• <title>, meta description y lang están configurados; las imágenes tienen alt.
• No quedan marcadores como [año] en la página publicada, a menos que el usuario haya decidido mantenerlos por ahora (entonces listarlos).

Solución de problemas

Síntoma	Causa y solución
https://<cuenta>.github.io/ devuelve 404, el sitio aparece en /<repo>/	El nombre del repositorio no es exactamente <cuenta>.github.io para la cuenta propietaria. Renombrar: gh repo rename <cuenta>.github.io.
404 en todas partes después de una ejecución verde	El origen de Pages sigue siendo "Desplegar desde una rama", o repositorio privado en el plan gratuito. Re-ejecutar la llamada build_type=workflow; hacer público el repositorio (gh repo edit --visibility public --accept-visibility-change-consequences).
Push rechazado: "refusing to allow an OAuth App to create or update workflow"	El token carece del ámbito workflow: gh auth refresh -s workflow.
Trabajo de despliegue: "Branch is not allowed to deploy to github-pages"	El entorno github-pages solo permite la rama por defecto. Desplegar desde main, o agregar la rama en Configuración → Entornos.
gh api .../pages devuelve 409 o 422	Pages ya existe: usar -X PUT en lugar de -X POST.
Faltan CSS solo en el sitio en vivo	Las rutas absolutas asumen la raíz. Para un sitio de proyecto (/<repo>/), prefijar las rutas con la base; assets/build.mjs hace esto desde GITHUB_REPOSITORY.
Aún se muestra la versión anterior	Caché de CDN, hasta ~10 minutos. Verificar que la ejecución haya terminado y hacer una recarga forzada.

Dominio personalizado (opcional)

gh api -X PUT "repos/$ACCOUNT/$REPO/pages" -f cname=www.example.com
# DNS: CNAME www -> <cuenta>.github.io ; apex: registros A a las IPs de GitHub Pages (ver documentación de GitHub)
gh api -X PUT "repos/$ACCOUNT/$REPO/pages" -F https_enforced=true   # una vez emitido el certificado

Salida

Terminar con: la URL en vivo, la URL del repositorio, qué archivo editar para cada tipo de cambio (content/profile.json para texto, static/style.css para apariencia), la lista de marcadores aún pendientes, y el comando único para previsualizar localmente.