Publicar Site Estático
Objetivo
Publicar ou preparar a implantação de um site estático finalizado.
Esta skill é para saída HTML/CSS/JS implantável, como site/, dist/, out/, public/ ou docs/. Ela também pode publicar projetos de frameworks depois que eles produzem uma pasta de saída estática, mas não deve transformar um site estático simples em um projeto de framework apenas para implantá-lo.
Postura padrão:
- Prefira hospedagem estática simples em vez de implantação específica de framework.
- Prefira implantação baseada em Git para sites que o usuário continuará editando.
- Prefira upload direto apenas para publicação rápida e pontual.
- Não crie repositórios remotos, faça push de código, altere DNS, adicione domínios ou implante em uma conta paga, a menos que o usuário peça explicitamente essa ação.
Contrato
Entradas:
- Raiz de implantação estática, como
site/,dist/,out/,public/,docs/ou raiz do repositório. - Plataforma ou destino preferido: GitHub Pages, Cloudflare Pages, Netlify, Vercel, domínio personalizado, apenas orientação ou implantação ao vivo.
- Estado atual do Git/repositório, acesso à conta da plataforma, login CLI/navegador e quaisquer restrições de implantação.
Saídas:
- Configurações concretas de implantação: plataforma, branch, comando de build, diretório base, diretório de publicação/saída e arquivos de configuração quando necessário.
- Configuração opcional específica da plataforma, como workflow do GitHub Pages,
netlify.toml,vercel.json,.nojekyllouCNAME. - URL ao vivo e verificação pós-implantação quando a implantação for realmente realizada.
- Etapas manuais do painel quando as credenciais ou o acesso à conta não estiverem disponíveis.
Limites:
- Não construa ou redesenhe o site; direcione defeitos para a skill filha apropriada.
- Não faça push, crie repositórios/projetos, faça upload, vincule domínios, altere DNS ou use recursos pagos, a menos que explicitamente autorizado.
- Não use a implantação como solução alternativa para problemas de compatibilidade de caminho local/estático, a menos que o usuário aceite explicitamente o comportamento somente de servidor-raiz.
Portão de sucesso:
review-static-sitefoi aprovado ou os riscos não resolvidos são explícitos.- A raiz de implantação contém
index.htmle a plataforma publicará a pasta correta. - A URL online carrega página inicial, assets, navegação e subpáginas representativas após a implantação.
Se o portão falhar:
- Corrija problemas de caminho, asset, codificação ou tipo de página antes da implantação.
- Direcione problemas de conteúdo/design/importação para
personalize-site,edit-site-part,add-blog-posts,make-personal-siteoucopy-website-style. - Execute novamente
review-static-sitee repita ou atualize as configurações de implantação.
Referências
Carregue apenas a referência necessária para a plataforma ou problema escolhido:
- Estratégia de caminho e compatibilidade de abertura direta:
references/path-strategy.md. - Integração Git do Cloudflare Pages e Upload Direto:
references/cloudflare-pages.md. - Origem de branch do GitHub Pages e workflows Actions:
references/github-pages.md. - Painel Netlify e
netlify.toml:references/netlify.md. - Painel Vercel e
vercel.json:references/vercel.md.
Documentação oficial:
- Origem de publicação do GitHub Pages: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
- Workflows personalizados do GitHub Pages: https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
- HTML estático do Cloudflare Pages: https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
- Integração Git do Cloudflare Pages: https://developers.cloudflare.com/pages/get-started/git-integration/
- Upload Direto do Cloudflare Pages: https://developers.cloudflare.com/pages/get-started/direct-upload/
- Criar implantações Netlify: https://docs.netlify.com/deploy/create-deploys/
- Configuração de build Netlify: https://docs.netlify.com/build/configure-builds/overview/
- Implantações Vercel: https://vercel.com/docs/deployments
- Configuração de projeto Vercel: https://vercel.com/docs/project-configuration
Modos de Implantação
Primeiro, determine o que o usuário realmente deseja:
- Apenas orientação: explique a escolha da plataforma e as configurações exatas. Não edite arquivos, a menos que seja útil.
- Preparar repositório: adicione os arquivos de configuração necessários e informe ao usuário o que clicar no painel de hospedagem.
- Implantar agora: execute ações remotas somente se o usuário pediu explicitamente e a CLI/autenticação/sessão necessária existe.
- Verificar URL ao vivo: abra a URL implantada em um navegador e verifique-a em relação ao site local.
Se as credenciais, acesso à conta, login do navegador ou autenticação CLI estiverem ausentes, forneça etapas exatas do painel em vez de inventar uma solução alternativa.
Fluxo de Trabalho
- Identifique a pasta de saída estática e a plataforma preferida do usuário, se houver.
- Chame ou sugira o uso de
review-static-siteantes de publicar. - Confirme se a raiz de implantação contém
index.html. - Inspecione os caminhos dos assets e converta caminhos acidentais absolutos da raiz do site local antes de publicar. Carregue
references/path-strategy.mdquando o comportamento do caminho não estiver claro. - Escolha a plataforma e o modo de implantação mais simples correspondentes.
- Carregue a referência da plataforma escolhida e adicione apenas os arquivos de configuração exigidos por essa plataforma.
- Se estiver implantando via Git, verifique o status do Git e evite incluir arquivos não relacionados ou privados.
- Se o usuário autorizou ações remotas, faça push ou implante exatamente o que foi acordado.
- Após a publicação, abra a URL ao vivo e verifique o site implantado em um navegador.
Lista de Verificação Pré-implantação
Execute estas verificações antes de escrever configurações de implantação ou informar as configurações ao usuário:
- Raiz de implantação: escolha a pasta que contém diretamente
index.html. - Página de entrada:
index.htmldeve existir no nível superior da raiz de implantação. - Visualização de abertura direta: o
index.htmlraiz deve manter CSS, JS, imagens e navegação quando aberto diretamente do sistema de arquivos, a menos que o usuário tenha aceitado explicitamente o comportamento somente de servidor. - HTTP local: sirva a raiz de implantação com
python -m http.servere confirme que funciona emhttp://127.0.0.1:<porta>/. - Auditoria estática: execute ou recomende
review-static-sitepara links, legibilidade UTF-8, resíduo de placeholder, renderização do navegador, resíduo de privacidade e layout móvel. - Caminhos dos assets: inspecione
href,src,srcset,url(...)do CSS, fontes, favicons, imagens de capa, RSS, sitemap e links de manifesto. - Dados privados: certifique-se de que tokens, caminhos do sistema de arquivos local, notas de rascunho, identidades do site de origem e segredos pessoais não estão sendo publicados.
- Integridade da saída: confirme que subpáginas, postagens, imagens, fontes de fornecedores, assets KaTeX/matemática e mídia copiada estão dentro da raiz de implantação.
Trate estes como bloqueadores:
- Nenhum
index.htmlna raiz de implantação. - Caminhos de assets CSS, JS, imagem, fonte, RSS, sitemap ou fornecedor quebrados localmente.
- Arquivos de origem contêm mojibake ou codificação ilegível.
- O site pessoal gerado ainda contém identidade de origem copiada que deveria ter sido substituída.
- Caminhos acidentais absolutos da raiz do site local, como
/assets/...,/posts/...,/data/...ou/images/..., permanecem em um site estático simples gerado. - O site funciona apenas sobre HTTP local porque caminhos absolutos da raiz estão sendo servidos de
127.0.0.1, mas a abertura direta de arquivo ou implantação em subcaminho perderia CSS/JS/imagens. - Arquivos confidenciais de privacidade ou segredos seriam implantados.
- A plataforma implantaria a pasta errada.
Escolha da Plataforma
Use esta classificação padrão para sites pessoais estáticos simples:
- Integração Git do Cloudflare Pages: melhor padrão para uma pasta
site/gerada e futuras atualizações. - GitHub Pages com GitHub Actions: melhor quando o usuário quer tudo dentro do GitHub.
- Netlify: hospedagem estática simples com visualizações amigáveis e configurações de painel.
- Vercel: bom quando o usuário já usa Vercel ou pode migrar para Next.js no futuro, mas não é o padrão para HTML simples.
Regras de decisão:
- Se o usuário quiser o mínimo de atrito e tiver um repositório GitHub: Integração Git do Cloudflare Pages. Carregue
references/cloudflare-pages.md. - Se o usuário quiser hospedagem somente GitHub: GitHub Pages. Carregue
references/github-pages.md. - Se os arquivos de implantação estiverem na raiz do repositório ou em
/docs: a origem da branch do GitHub Pages é aceitável. - Se os arquivos de implantação estiverem em
site/,dist/,out/ou outra pasta personalizada: prefira GitHub Actions para GitHub Pages. - Se o usuário quiser upload manual hoje: Upload Direto do Cloudflare ou implantação manual do Netlify.
- Se o usuário já tiver uma conta/projeto Vercel: use Vercel com configurações explícitas de diretório de saída.
Saída Estática de Framework
Se o site não for HTML/CSS/JS simples:
- Inspecione
package.json, configuração do framework e scripts existentes. - Use o comando de build existente do projeto; não invente workflows npm.
- Publique a pasta de saída estática final, não a pasta de origem.
- Saídas comuns incluem
dist,out,build,.output/publicepublic, dependendo do framework. - Para exportação estática do Next.js, verifique se o projeto está realmente configurado para exportação estática antes de tratar
out/como saída final. - Para projetos estilo Vue/Vite/Astro, publique o diretório de saída configurado após um build bem-sucedido.
Se o usuário pediu publicação estática simples e nenhum arquivo de framework existe, não introduza npm.
Política de Arquivos de Configuração
Adicione apenas arquivos de configuração que correspondam à plataforma escolhida:
- Actions do GitHub Pages:
.github/workflows/pages.yml. - Domínio personalizado do GitHub Pages:
CNAMEna raiz implantada, somente quando o usuário forneceu o domínio. - Bypass Jekyll do GitHub Pages:
.nojekyllna raiz implantada quando for útil. - Netlify:
netlify.tomlsomente quando as configurações do painel não forem suficientes ou o usuário quiser a configuração no Git. - Vercel:
vercel.jsonsomente quando a Vercel precisar de configurações explícitas de saída. - Cloudflare Pages: geralmente as configurações do painel são suficientes para sites estáticos simples.
Não adicione configurações de implantação para todas as plataformas de uma vez.
Segurança Git e Remota
Antes de qualquer ação remota, declare o que acontecerá e confirme que o usuário pediu por isso:
- Criar um repositório GitHub.
- Adicionar um remote.
- Staging ou commit de arquivos.
- Push de commits para um branch remoto.
- Habilitar GitHub Pages.
- Criar projetos Cloudflare, Netlify ou Vercel.
- Fazer upload de arquivos para um provedor de hospedagem.
- Adicionar variáveis de ambiente.
- Adicionar domínios personalizados ou alterar registros DNS.
Antes de staging ou push:
- Execute
git status --short. - Identifique os arquivos de site gerados versus alterações não relacionadas do usuário.
- Não faça staging de alterações não relacionadas.
- Não publique notas privadas, credenciais, caminhos locais, capturas de tela com segredos ou arquivos temporários.
Nunca coloque segredos, tokens, notas privadas ou caminhos do sistema de arquivos local no site estático ou na configuração de implantação.
Verificação Pós-Implantação
Após a plataforma relatar uma URL ao vivo:
- Abra a URL implantada com uma ferramenta de navegador interativa realmente disponível. "Disponível" significa que está exposta na lista de ferramentas chamáveis do turno atual. No Codex, isso pode ser o plugin do Navegador/navegador no aplicativo quando roteado para o turno.
- Verifique se a página inicial não é um 404, página em branco ou listagem de diretório.
- Verifique se CSS, JavaScript, imagens, fontes, favicon, RSS, sitemap e assets de fornecedores carregam do domínio implantado.
- Clique na navegação principal e em pelo menos uma subpágina representativa por tipo de página.
- Teste larguras de desktop e dispositivos móveis.
- Verifique o console do navegador em busca de assets ausentes ou erros de JavaScript.
- Confirme metadados, título, descrição, imagem Open Graph, URL canônica, RSS, sitemap e arquivos robots quando presentes.
- Se estiver usando GitHub Project Pages, verifique especificamente as URLs de subpáginas e assets sob o subcaminho do repositório.
- Se estiver usando um domínio personalizado, verifique HTTPS e redirecionamentos entre apex e
www, se configurado.
Se nenhuma ferramenta de navegador interativa for chamável, não finja que a verificação ao vivo do navegador aconteceu. Peça ao usuário para habilitar ou invocar a ferramenta do navegador se a verificação visual ao vivo for importante; para Codex, isso pode significar enviar uma solicitação que mencione explicitamente @browser. Se o usuário não redirecionar ou o cliente não tiver tal ferramenta, recorra ao Playwright, capturas de tela, verificações HTTP ou verificações estáticas e declare a limitação.
Não use apenas Playwright ou verificação ao vivo com capturas de tela quando uma ferramenta de navegador interativa for realmente chamável. Use Playwright apenas como fallback, ou quando o usuário pedir explicitamente verificações de implantação com script.
Se o site implantado diferir da visualização local, inspecione o log de implantação, o diretório de saída e a estratégia de caminho de asset antes de alterar o código de design.
Saída
Mantenha o relatório final para o usuário conciso:
- Plataforma escolhida e por quê.
- Pasta estática publicada ou preparada.
- Modo de implantação: orientação, configuração preparada, integração Git, upload direto ou implantação ao vivo.
- Configurações usadas: branch, comando de build, diretório base, diretório de publicação/saída.
- Arquivos de configuração alterados, se houver.
- URL do guia oficial da plataforma escolhida.
- URL ao vivo, se a implantação aconteceu.
- Verificação realizada e qualquer etapa manual restante.
Se apenas a orientação foi solicitada, não finja que o site foi implantado. Forneça configurações concretas da plataforma e links de guia oficial.