Theming Assets & SRI

“Assets” significa tudo que não é conteúdo escrito: os stylesheets, scripts, fontes, ícones e imagens que fazem o site e a interface de admin parecerem corretos. O Chinaski divide-os em duas trilhas com regras diferentes : uma trilha de site público (processada pelo builder) e uma trilha do app de admin (protegida com hashes de integridade). Esta página explica ambas, mais a única regra que vale memorizar: a regra do reload.

A regra do reload (memorize esta)

Após editar qualquer um dos cinco arquivos de asset auto-hospedados do app de admin no disco, reinicie a aplicação.

A interface de admin embarca seu próprio stylesheet, fontes, os arquivos do editor e seu script de configurações : cinco arquivos, todos com checksum (SRI) na inicialização do processo. O hash em cada página é computado quando o app inicia; se você substituir um desses arquivos enquanto ele continua executando, o navegador recebe um arquivo que não corresponde mais ao checksum que a página prometeu, e ele se recusa a carregá-lo. Resultado: um admin sem estilo ou um editor quebrado.

Sob systemd: systemctl restart chinaski@<instance>
O log de inicialização confirma quando os hashes estão frescos: “SRI hashes computed for 5 admin assets.”
Se em vez disso um arquivo estiver ausente na inicialização, aquele asset carrega sem verificação e o log o diz : restaure o arquivo e reinicie.

As páginas públicas do site não têm esse ciclo de vida : a regra do reload aplica-se aos cinco arquivos do bundle de admin apenas.

Assets de tema e como eles chegam ao site

Temas personalizados são templates mais referências, não bundles de assets:

Seu CSS/JS é escrito no partial _head.tt do tema, e suas classes devem estilizar os conjuntos de classes compartilhados usados pelos blocos (veja a Template Reference).
Fontes são auto-hospedadas, nunca de um CDN. O conjunto de fontes embarcado (TTF/WOFF2, com subconjuntos por idioma) é copiado para a saída de cada idioma a cada build : os temas as referenciam via a stylesheet fornecida.
Imagens: nada é empacotado aqui. Páginas usam imagens da media library (que gera os tamanhos responsivos), o logo do site e o conjunto de favicons.
O logo do site: defina um arquivo de logo nas configurações; o arquivo deve existir no diretório assets/ do app, e o builder o copia para a raiz do site a cada build (um ausente gera um aviso no log de build).
Mudanças de cor e tipografia sem tocar nos templates: os Design Tokens (Settings) são o caminho suportado para recolorir um tema : eles se tornam CSS custom properties na saída gerada em tempo de build.
Nenhum minificador ou bundler: os arquivos vão ao ar como autorados. Se você minificar, minifica à mão ou embarca arquivos pré-minificados; o builder apenas copia e referencia.

O comportamento de cache (na camada de proxy) tem como padrão: páginas 5 minutos, outros assets 1 dia, fontes um ano (são com hash de conteúdo, então cachear para sempre é seguro). O app em si também emite headers corretos, então o caching se comporta mesmo se você reautorar uma config de proxy.

Favicons e ícones de app

Você não edita arquivos de ícone à mão : faz upload de uma imagem de origem nas configurações, e o sistema gera o conjunto inteiro:

Faça upload de uma imagem aproximada de quadrado (PNG/JPEG/SVG/ICO, até 5 MB; proporção de aspecto além de 1.25 é rejeitada, já que recortar um banner largo produz um ícone inútil).
O conjunto de saída fixo é gerado no lado do servidor: o favicon do navegador, o apple-touch icon e os dois tamanhos de app-manifest (192/512 px), mais o favicon.ico.
Quando habilitado, cada build copia esse conjunto para a raiz do site. Os nomes gerados são constantes compartilhadas entre as configurações e o builder, então eles não podem ficar fora de sincronia.
O mesmo para o logo do site: escolha seu arquivo nas configurações e cada build o coloca na raiz do site para o header do seu tema referenciar.

Fontes

Fontes nunca vêm de um CDN : os tipos embarcados (incluindo subconjuntos por escrita) são arquivos locais copiados para a saída de cada idioma como fonts/. O _head.tt do seu tema os busca de lá. Se você precisa de uma tipografia diferente, adicione arquivos ao diretório de fontes; eles são sincronizados a todos os idiomas no próximo build.

Referência rápida: o que é processado, e como

Tipo de asset	O que acontece no build/upload
CSS/JS de tema	Autorados nos templates; embarcados inalterados (sem minificação)
CSS/JS de admin	Com hash SRI na inicialização; aplica-se a regra do reload
Fontes	Sincronizadas verbatim para a saída de cada idioma; as de admin embaladas no fonts.css
Imagens de mídia	Tamanhos derivados + WebP gerados no upload (veja Media Library)
Favicons/ícones	Gerados de uma imagem de origem via settings
Design tokens	Convertidos em CSS custom properties em tempo de build

A versão curta

Assets do site público são cópias sem graça : arquivos entram, arquivos saem, regras de cache no proxy. A única parte móvel são os hashes SRI do bundle de admin: mude um de seus cinco arquivos, reinicie o app : e se você vir uma falha de integridade no console do navegador em uma página de admin, esse loop de hash obsoleto é exatamente o que aconteceu (veja a página CSS Blocked (SRI) para a correção de um passo).