Assets de Theming y SRI
"Assets" significa todo lo que no es contenido escrito: las hojas de estilo, scripts, fuentes, iconos e imágenes que hacen que el site y la interfaz de administración se vean bien. Chinaski divide estos en dos vías con reglas distintas: una vía del site público (procesada por el builder) y una vía de la app de administración (protegida con hashes de integridad). Esta página explica ambas, además de la única regla que vale la pena memorizar: la regla de recarga.
La regla de recarga (memoriza esta)
Después de editar en disco cualquiera de los cinco archivos de asset auto-hospedados de la app de administración, reinicia la aplicación.
La interfaz de administración trae su propia hoja de estilos, fuentes, los archivos del editor y su script de settings: cinco archivos, todos con checksum (SRI) al arrancar el proceso. El hash en cada página se calcula cuando arranca la app; si reemplazas uno de esos archivos mientras sigue corriendo, el navegador recibe un archivo que ya no coincide con el checksum que la página prometió, y se niega a cargarlo. Resultado: un admin sin estilos o un editor roto.
- Bajo systemd:
systemctl restart chinaski@<instance> - El log de arranque confirma cuando los hashes están frescos: "SRI hashes computed for 5 admin assets."
- Si en cambio falta un archivo al arrancar, ese asset carga sin verificación y el log lo dice: restaura el archivo y reinicia.
Las páginas públicas del site no tienen este ciclo de vida: la regla de recarga aplica solo a los cinco archivos del bundle de administración.
Los assets del tema y cómo llegan al site
Los temas personalizados son plantillas más referencias, no bundles de assets:
- Tu CSS/JS se escribe en el partial
_head.ttdel tema, y sus clases deben dar estilo a los conjuntos de clases compartidos que usan los blocks (ver la Template Reference). - Las fuentes son auto-hospedadas, nunca de un CDN. El set de fuentes incluido (TTF/WOFF2, con subsets por idioma) se copia a la salida de cada idioma en cada build: los temas las referencian vía la hoja de estilos provista.
- Las imágenes: aquí no se agrupa nada. Las páginas usan imágenes de la media library (que genera los tamaños responsivos), el logo del site y el set de favicon.
- El logo del site: establece un archivo de logo en settings; el archivo debe existir en el directorio
assets/de la aplicación, y el builder lo copia a la raíz del site en cada build (si falta, lo advierte en el build log). - Cambios de color y tipografía sin tocar plantillas: los Design Tokens (Settings) son la forma soportada de recolorear un tema: se convierten en propiedades personalizadas CSS en la salida generada en tiempo de build.
- Sin minificador ni bundler: los archivos se entregan tal como se escribieron. Si minificas, minificas a mano o entregas archivos pre-minificados; el builder solo copia y referencia.
El comportamiento de caché (en la capa de proxy) por defecto es: páginas 5 minutos, otros assets 1 día, fuentes un año (tienen hash de contenido, así que cachearlas para siempre es seguro). La aplicación misma también emite las cabeceras correctas, así que el cacheo se comporta bien incluso si reescribes una configuración de proxy.
Favicons e iconos de app
No editas los archivos de iconos a mano: subes una imagen fuente en settings, y el sistema genera el set completo:
- Sube una imagen más o menos cuadrada (PNG/JPEG/SVG/ICO, hasta 5 MB; un aspecto superior a 1.25 se rechaza, porque recortar un banner ancho produce un icono inútil).
- El set fijo de salida se genera del lado del servidor: el favicon del navegador, el icono apple-touch y los dos tamaños del app-manifest (192/512 px), más favicon.ico.
- Cuando está habilitado, cada build copia ese set a la raíz del site. Los nombres generados son constantes compartidas entre settings y el builder, así que no pueden desincronizarse.
- Lo mismo para el logo del site: elige su archivo en settings y cada build lo coloca en la raíz del site para que el header de tu tema lo referencie.
Fuentes
Las fuentes nunca vienen de un CDN: los tipos incluidos (incluyendo subsets por escritura) son archivos locales copiados a la salida de cada idioma como fonts/. El _head.tt de tu tema los toma de ahí. Si necesitas un tipo distinto, añade archivos al directorio de fuentes; se sincronizan a cada idioma en el siguiente build.
Referencia rápida: qué se procesa y cómo
| Tipo de asset | Qué pasa en el build/upload |
|---|---|
| CSS/JS del tema | Escrito en las plantillas; entregado sin cambios (sin minificación) |
| CSS/JS del admin | Con hash SRI al arrancar; aplica la regla de recarga |
| Fuentes | Sincronizadas textualmente a la salida de cada idioma; las del admin envueltas en fonts.css |
| Imágenes de media | Tamaños derivados + WebP generados al subir (ver Media Library) |
| Favicons/iconos | Generados desde una imagen fuente vía settings |
| Design tokens | Convertidos a propiedades personalizadas CSS en tiempo de build |
La versión corta
Los assets del site público son copias aburridas: archivos que entran, archivos que salen, reglas de caché en el proxy. La única pieza en movimiento son los hashes SRI del bundle de administración: cambia uno de sus cinco archivos, reinicia la app: y si ves un fallo de integridad en la consola del navegador en una página de admin, ese bucle de hash obsoleto es exactamente lo que pasó (ver la página CSS Blocked (SRI) para el arreglo de un paso).