static-site-publish

Gera um pequeno site estático em HTML/CSS/JS puro a partir de dados, verifica em um navegador headless e publica no GitHub com GitHub Pages.

O que é static-site-publish?

Esta skill automatiza o fluxo completo de criação de um site estático auto-contido (HTML/CSS/JS puro, sem frameworks ou build tools) a partir de dados fornecidos pelo usuário, como listas, galerias, dashboards ou portfólios. Ela primeiro coleta os dados em um arquivo JSON, gera a página a partir de templates pré-definidos, e então verifica o resultado em um navegador headless (Chrome) para garantir que o layout, links e dados estejam corretos. Após a verificação, publica o site no GitHub Pages usando a CLI do GitHub (`gh`) e, se solicitado explicitamente pelo usuário, configura um domínio personalizado via Cloudflare (CNAME DNS-only) e ativa o HTTPS forçado no GitHub Pages. A skill também documenta como manter o site atualizável no futuro. Ela inclui regras éticas rigorosas: não copiar design de terceiros, não contornar proteções de acesso (como Cloudflare challenges ou robots.txt), e só criar registros DNS com confirmação explícita do usuário.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Site estático → GitHub Pages

Fluxo completo: dados → página HTML/CSS/JS autônoma → verificação no navegador → publicação no GitHub Pages.

Alvo: páginas de 1 a algumas centenas de itens, um único autor, zero dependências em tempo de execução.

Quando usar

SimNão
"Crie uma página com esta lista / esta tabela", galeria, dashboard de dadosaplicação com backend, autenticação, banco de dados → perguntar antes
"Publique no GitHub / GitHub Pages"site gerado por um framework (Next, Astro, Hugo) → seguir o fluxo do framework
reprodução de uma página existente em dados (títulos, datas, preços…)cópia do design/CSS/HTML de um site de terceiros → recusar, refazer um design próprio

Regras inegociáveis

  1. Design próprio. Nunca copiar o CSS, o HTML ou os assets de um site de terceiros. Inspirar-se na estrutura da informação é OK; copiar a identidade visual não.
  2. Fatos sim, obras não. Títulos, datas, preços, notas, links = dados factuais, reutilizáveis. Textos editoriais, descrições, visuais = protegidos: não copiar. Para imagens, usar hotlink do CDN de origem em vez de commitá-las (ver reference/data-and-ethics.md).
  3. Respeitar as proteções de acesso. robots.txt que proíbe crawlers, desafio Cloudflare/bot → não contornar. Buscar uma API oficial, uma chave, ou degradar para um simples link externo.
  4. Sempre verificar em um navegador real antes de dizer "está pronto" (screenshot + teste de clique).
  5. Não publicar sem confirmação do nome do repositório / da conta se houver ambiguidade.
  6. Não criar domínio personalizado sem confirmação. Se o usuário não especificou, perguntar se ele quer um redirecionamento Cloudflare e em qual domínio (etapa 6). Nunca inventar um subdomínio nem criar um por conta própria: o DNS é um efeito colateral visível externamente.

Fluxo de trabalho

1. Definir o escopo (30 s)

  • Qual dado, quantos itens, atualização única ou recorrente?

  • Saída esperada: uma página? busca/ordenação? quais regras de exibição de negócio?

  • Onde publicar: conta GitHub, nome do repositório, público/privado (Pages exige repositório público em contas gratuitas).

  • Domínio personalizado — perguntar explicitamente se não especificado. Fazer a pergunta de uma vez, com a proposta padrão:

    Você quer um redirecionamento Cloudflare para <owner>.github.io (CNAME, proxy desativado)? Se sim, qual subdomínio/seção?

    O nome é livre do lado da skill, mas o domínio é público desde sua criação: não criar nada sem resposta explícita. Se o usuário responder não, parar na URL https://<owner>.github.io/<repo>/ e não criar entrada DNS.

2. Obter os dados

Uma única execução de script → um data.json = fonte da verdade, separado da renderização.

python3 fetch_data.py     # → data.json

Polidez: 0,3–0,7 s entre requisições, User-Agent explícito, retry em 429/5xx. Detalhes e casos problemáticos (PoW Anubis, Cloudflare, correspondência difusa, API sem chave): reference/data-and-ethics.md.

3. Gerar a página

Partir dos templates, não do zero:

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: pequeno gerador Python (f-string + html.escape) que injeta os dados em uma grade de cartões. Sem runtime JS para os dados.
  • styles.css: tema escuro padrão, grade auto-fill minmax(), variáveis CSS.
  • script.js: busca instantânea + ordenação + regras de exibição calculadas na abertura (para que a página permaneça atual sem reconstrução).
  • Tudo que é calculável na exibição (status, datas relativas) deve ser feito em JS: evita reconstruir o site diariamente.
  • O HTML deve permanecer legível sem JS, e o JS deve ser progressivo.

4. Verificar

.dsh/skills/static-site-publish/scripts/verify-site.sh ./site/index.html

Abre a página no Chrome headless, escreve /tmp/site-shot.png, e executa o teste de sobreposição de cliques. Olhar o screenshot (ferramenta read_image) antes de concluir. Checklist: renderização desktop + mobile, dados completos (contar os itens), links corretos, nenhuma sobreposição.

5. Publicar

.dsh/skills/static-site-publish/scripts/publish-gh-pages.sh ./site meu-nome-de-repo

O script: gh auth status → git init/commit → gh repo create --source --push → gh api POST /pages → polling da URL até 200 → exibe a URL final.

O tempo de Pages é de 20 a 90 s: não concluir "não funciona" antes de ter obtido um 200. Verificar também gh api repos/{owner}/{repo}/pages/builds/latest --jq .status = built.

6. Domínio personalizado + Cloudflare

Apenas se o usuário solicitou (veja etapa 1). O DNS é público: não reinterpretar um "sim" vago como um nome de domínio escolhido pela IA.

Ordem obrigatória: DNS primeiro, certificado depois, Enforce HTTPS por último. O site já deve responder com 200 em *.github.io antes de começar.

a. Redirecionamento DNS no Cloudflare (MCP Cloudflare)

Pré-requisito token: escopos zone.read + dns.write (Zone Read / DNS Edit). Se faltar, parar e solicitar a ampliação — não contornar.

  1. GET /zones?name=<domínio raiz> → zone.id. Se zero zonas: o domínio não está nesta conta, perguntar.
  2. GET /zones/{zone_id}/dns_records?name=<fqdn> → se um CNAME idêntico já existir, não recriar nada (idempotência).
  3. POST /zones/{zone_id}/dns_records:
{ "type": "CNAME", "name": "<subdomínio>", "content": "<owner>.github.io",
  "proxied": false, "ttl": 1 }
  • proxied: false = DNS only, não negociável: o proxy Cloudflare impede o GitHub de emitir o certificado.
  • O alvo é <owner>.github.io, sem barra final e sem nome de repositório (jamesdadams.github.io, não .../meu-repo).
  • ttl: 1 = Auto.
  1. Verificar na resolução pública, não apenas via 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. Domínio + Enforce HTTPS no GitHub Pages

.dsh/skills/static-site-publish/scripts/set-pages-domain.sh <owner>/<repo> <domínio> ./site

O script: escreve o arquivo CNAME no site (ele sobrevive a reimplantações e evita perder o domínio) → PUT /repos/{owner}/{repo}/pages com cname → aguarda https_certificate.state = approved → ativa https_enforced: true.

⚠️ https_enforced: true retorna 400 enquanto o certificado não existir. Tempo real: 5 a 20 min após a criação do CNAME. Por isso o script faz um loop em vez de falhar. Não marcar "Enforce HTTPS" manualmente antes da emissão, e não concluir falha durante essa janela.

c. Verificação final

curl -sI https://<domínio>/ | head -5      # 200 + header server: GitHub.com

Depois reabrir a página no navegador (etapa 4) na URL personalizada: um 200 não prova que os caminhos relativos (styles.css, script.js) resolvem — essa é a armadilha clássica das project pages servidas na raiz de um domínio.

7. Tornar a atualização possível

  • Colocar a pasta git no diretório de projetos do usuário (não em /tmp, apagado na reinicialização).
  • Documentar no README.md: de onde vêm os dados, como reexecutar a extração, o que é fixo (dados) vs. vivo (regras calculadas em JS).
  • Sinalizar explicitamente ao usuário o que não será atualizado automaticamente.

Armadilhas já encontradas

SintomaCausaCorreção
403 "Just a moment…"desafio Cloudflaredocumentar o limite, API oficial ou link externo; não tentar contornar
Página truncada "Making sure you're not a bot"PoW Anubisresolver o desafio (veja reference) ou pedir um export ao usuário
Seletor que retorna 0 resultados para todos os itenspadrão errado (ex.: /games/lib/genre: vs /games/lib/popular/genre:)imprimir uma amostra do HTML e testar a regex em 1 página antes de fazer loop
Clique em um card que não abre o link corretocamada <a> coberta por um filho posicionadopointer-events: none em elementos decorativos; testar com elementFromPoint
GitHub Pages 404 nos primeiros minutosbuild em andamentopolling até 90 s
Dados de uma coluna vaziosrótulo variável na origem ("Released" vs "Early Access")padrão tolerante + log por item, nunca except: pass silencioso
https_enforced com 400 "certificate does not exist"certificado ainda não emitidoaguardar https_certificate.state = approved (5-20 min), o script faz loop
Domínio personalizado com 404 após 30 minCNAME ausente / proprietário errado / arquivo CNAME faltando no repositóriodig para confirmar o CNAME, reexecutar set-pages-domain.sh
HTTPS quebrado após ativação do proxyregistro passou para Proxiedvoltar para DNS only (proxied: false), o certificado GitHub não pode ser validado através do proxy
"Domain is already in use"domínio já declarado em outro repositório da contaum domínio personalizado por repositório; liberar o antigo antes de reatribuir
CSS/JS com 404 no domínio personalizado mas OK em *.github.io/repo/caminhos absolutos (/styles.css) em uma project page servida na raizcaminhos relativos (styles.css)

Referências

  • reference/data-and-ethics.md — extração, PoW Anubis, Cloudflare, licenças, hotlink de imagens
  • reference/design-and-verify.md — sistema de design mínimo, testes no navegador, a11y
  • reference/publish-gh-pages.md — comandos gh, nomenclatura, domínios, solução de problemas
  • scripts/publish-gh-pages.sh — publicação + ativação Pages
  • scripts/set-pages-domain.sh — domínio personalizado + Enforce HTTPS (após o CNAME Cloudflare)
  • scripts/verify-site.sh
  • templates/{index.html,styles.css,script.js,build.py}

Habilidades Relacionadas