Publicar o site

Antes do build, defina site.domain com o host público final e site.basePath com o prefixo público. Canonical, social, JSON-LD, sitemap, robots e llms materializam a mesma URL final usando HTTPS. As rotas emitidas terminam em /, compatíveis com os diretórios dist/<rota>/index.html sem passar pelo redirect que hosts estáticos aplicam a /rota.

Execute a imagem builder com Content/ e config.yaml read-only e dist/ gravável. O pipeline valida o Tailwind antes de limpar dist/, mas não publique a saída se o comando terminar com erro: falhas posteriores ainda podem deixar artefatos parciais.

Depois do build, confira ao menos:

index.html, 404.html e quaisquer arquivos <código>.html de páginas de erro configuradas;
o CSS com hash em assets/;
favicons;
sitemap.xml, robots.txt, llms.txt e os arquivos llms_full configurados;
fontes .mdx das Collections que habilitaram mdx_source;
uma capa para cada rota normal.

Publique somente dist/. Configure o host estático para usar 404.html para caminhos desconhecidos. Não publique Core/, Content/, storage/, vendor/ ou node_modules/.

GitLab Pages

Em um domínio Pages dedicado ao projeto, mantenha basePath: "":

site:
  domain: meu-projeto-abc123.gitlab.io
  basePath: ""

O job Pages deve publicar dist/ (ou copiá-lo para o diretório de artifact exigido pela configuração do GitLab). O pipeline deste repositório já usa o build completo para isso. GitLab Pages detecta automaticamente os sidecars .br e .gz gerados ao lado de cada arquivo textual e entrega a melhor codificação aceita pelo navegador.

No CI deste repositório, o job Pages persiste storage/framework/fonts/ e storage/framework/build-cache/ em um cache versionado do GitLab. Esse cache acelera publicações consecutivas, mas não é publicado como artifact e não substitui a reconstrução limpa de dist/.

Melhorando a performance em GitLab Pages e hospedagens semelhantes

Em uma hospedagem estática, o desempenho depende sobretudo do artefato que é publicado e da forma como o CDN/host o entrega. O build completo do BlogBlade já prepara a saída para esse cenário:

O que você precisa fazer

Configure a URL pública. Defina site.domain e site.basePath antes do build. Use basePath: "" em um domínio raiz e o prefixo do projeto (por exemplo, /meu-blog) quando o site estiver em um subcaminho.
Execute o build de produção. Rode just build (ou o recipe equivalente no CI). Não use just build-fast para publicar: essa opção omite as capas sociais.
Publique todo o diretório dist/. Preserve os arquivos originais e seus vizinhos .br e .gz; não copie apenas index.html nem remova os sidecars. Configure também 404.html como página de erro do host.
Evite arquivos desnecessariamente grandes. Prefira imagens no tamanho em que serão exibidas, mantenha fotos em formatos comprimidos e não inclua bibliotecas ou fontes externas que o site não utiliza. Fontes configuradas pelo BlogBlade devem ser baixadas no build e publicadas em dist/.
Configure o cache no provedor, quando possível. Dê cache longo aos assets cujo nome contém hash (assets/*.<hash>.*) e exija revalidação para HTML. Assim, uma publicação nova atualiza páginas sem invalidar todos os assets.
Teste o endereço publicado. Abra a home, uma rota interna, um asset e uma rota inexistente. Confirme no navegador ou com curl que o conteúdo chega comprimido e que não há redirect causado por basePath incorreto.

HTML, CSS, SVG, XML, TXT, JSON, JavaScript, source maps e web manifests recebem versões Brotli (.br) e gzip (.gz); o arquivo original continua no dist/ como fallback.
O CSS é emitido com hash no nome, como assets/main.<hash>.css. O host pode mantê-lo em cache por mais tempo sem deixar usuários com uma versão antiga depois de um novo deploy, pois uma alteração gera outra URL.
Fontes Google configuradas são baixadas e publicadas localmente como WOFF2. Assim, a página não precisa buscar a folha de estilo ou os arquivos de fonte no Google durante a navegação.
As rotas são escritas como diretórios com index.html e links com barra final. Use o basePath correto para não introduzir redirects extras nem URLs de assets incorretas em sites publicados sob um subcaminho.

Para GitLab Pages, publique o dist/ sem remover os sidecars: eles permitem que o host negocie br ou gzip conforme o cabeçalho Accept-Encoding do navegador. Em hosts que não reconhecem arquivos pré-comprimidos, mantenha os originais no deploy; o site continuará funcionando e o provedor poderá aplicar sua própria compressão.

Os cabeçalhos de cache e a distribuição por CDN pertencem ao provedor de hospedagem, não ao conteúdo de dist/. Quando a plataforma permitir regras de cache, aplique uma política longa a assets com hash e uma política mais curta ou revalidação a HTML, sitemap.xml e robots.txt. Não use cache longo para HTML sem uma estratégia de invalidação, pois suas URLs não têm hash.

Depois do deploy, valide a entrega real — e não somente os arquivos gerados — com uma requisição que aceite Brotli, por exemplo:

curl -I -H 'Accept-Encoding: br' https://meu-projeto-abc123.gitlab.io/

Confira content-encoding: br (ou gzip, se esse for o formato negociado), o content-type esperado — configure o host para servir .mdx como text/markdown ou text/plain quando necessário — e os cabeçalhos de cache oferecidos pelo host. Rode just build --profile no CI ou localmente quando o tempo de publicação for uma preocupação: ele mostra o custo de cada estágio. Reserve --fast para iteração, pois ele omite as capas sociais e não é o build de produção.

GitHub Pages

Em um site de projeto https://usuario.github.io/BlogBlade/, configure:

site:
  domain: usuario.github.io
  basePath: /BlogBlade

Gere dist/ e envie esse diretório como artifact do GitHub Pages na estratégia de deploy escolhida pelo repositório. Esta engine não cria nem exige um workflow específico. O host pode ignorar os sidecars e aplicar sua própria compressão; os arquivos originais permanecem presentes. Para um site de usuário ou organização na raiz de usuario.github.io, mantenha basePath: "".

O inventário exato está em Saída gerada. Para compreender a ordem e as falhas do pipeline, consulte Processo de build.