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
| Sim | Não |
|---|---|
| "Crie uma página com esta lista / esta tabela", galeria, dashboard de dados | aplicaçã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
- 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.
- 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). - Respeitar as proteções de acesso.
robots.txtque proíbe crawlers, desafio Cloudflare/bot → não contornar. Buscar uma API oficial, uma chave, ou degradar para um simples link externo. - Sempre verificar em um navegador real antes de dizer "está pronto" (screenshot + teste de clique).
- Não publicar sem confirmação do nome do repositório / da conta se houver ambiguidade.
- 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, gradeauto-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.
GET /zones?name=<domínio raiz>→zone.id. Se zero zonas: o domínio não está nesta conta, perguntar.GET /zones/{zone_id}/dns_records?name=<fqdn>→ se um CNAME idêntico já existir, não recriar nada (idempotência).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.
- 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
| Sintoma | Causa | Correção |
|---|---|---|
| 403 "Just a moment…" | desafio Cloudflare | documentar o limite, API oficial ou link externo; não tentar contornar |
| Página truncada "Making sure you're not a bot" | PoW Anubis | resolver o desafio (veja reference) ou pedir um export ao usuário |
| Seletor que retorna 0 resultados para todos os itens | padrã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 correto | camada <a> coberta por um filho posicionado | pointer-events: none em elementos decorativos; testar com elementFromPoint |
| GitHub Pages 404 nos primeiros minutos | build em andamento | polling até 90 s |
| Dados de uma coluna vazios | ró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 emitido | aguardar https_certificate.state = approved (5-20 min), o script faz loop |
| Domínio personalizado com 404 após 30 min | CNAME ausente / proprietário errado / arquivo CNAME faltando no repositório | dig para confirmar o CNAME, reexecutar set-pages-domain.sh |
| HTTPS quebrado após ativação do proxy | registro passou para Proxied | voltar 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 conta | um 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 raiz | caminhos relativos (styles.css) |
Referências
reference/data-and-ethics.md— extração, PoW Anubis, Cloudflare, licenças, hotlink de imagensreference/design-and-verify.md— sistema de design mínimo, testes no navegador, a11yreference/publish-gh-pages.md— comandosgh, nomenclatura, domínios, solução de problemasscripts/publish-gh-pages.sh— publicação + ativação Pagesscripts/set-pages-domain.sh— domínio personalizado + Enforce HTTPS (após o CNAME Cloudflare)scripts/verify-site.shtemplates/{index.html,styles.css,script.js,build.py}