Assets & SRI
“Assets” means everything that isn’t written content: the stylesheets, scripts, fonts, icons, and images that make the site and the admin interface look right. Chinaski splits these into two tracks with different rules; a public-site track (processed by the builder) and an admin-app track (protected with integrity hashes). This page explains both, plus the one rule worth memorizing: the reload rule.
The reload rule (memorize this one)
After editing any of the admin app’s five self-hosted asset files on disk, restart the application.
The admin interface ships its own stylesheet, fonts, the editor’s files, and its settings script; five files, all checksummed (SRI) at process startup. The hash in each page is computed when the app starts; if you replace one of those files while it keeps running, the browser gets a file that no longer matches the checksum the page promised, and it refuses to load it. Result: an unstyled admin or a broken editor.
- Under systemd:
systemctl restart chinaski@<instance> - The startup log confirms when hashes are fresh: “SRI hashes computed for 5 admin assets.”
- If instead a file is missing at startup, that asset loads without verification and the log says so; restore the file and restart.
The site’s public pages don’t have this lifecycle; the reload rule applies to the five admin-bundle files only.
Theme assets and how they reach the site
Custom themes are templates plus references, not asset bundles:
- Your CSS/JS is authored in the theme’s
_head.ttpartial, and its classes must style the shared class sets used by blocks (see the Template Reference). - Fonts are self-hosted, never from a CDN. The shipped font set (TTF/WOFF2, with per-language subsets) is copied into every language’s output on each build: themes reference them via the provided stylesheet.
- Images: nothing bundles here. Pages use images from the media library (which generates the responsive sizes), the site logo, and the favicon set.
- The site logo: set a logo file in settings; the file must exist in the app’s
assets/directory, and the builder copies it to the site root on every build (a missing one warns in the build log). - Color and type changes without touching templates: Design Tokens (Settings) are the supported way to recolor a theme: they become CSS custom properties in the generated output at build time.
- No minifier or bundler: files ship as authored. If you minify, you minify by hand or ship pre-minified files; the builder just copies and references.
The cache behavior (at the proxy layer) defaults to: pages 5 minutes, other assets 1 day, fonts a year (they’re content-hashed, so caching them forever is safe). The app itself also emits correct headers, so caching behaves even if you re-author a proxy config.
Favicons and app icons
You don’t hand-edit icon files; you upload one source image in settings, and the system generates the whole set:
- Upload a square-ish image (PNG/JPEG/SVG/ICO, up to 5 MB; aspect ratio beyond 1.25 is rejected since cropping a wide banner makes a useless icon).
- The fixed output set is generated server-side: the browser favicon, the apple-touch icon, and the two app-manifest sizes (192/512 px), plus favicon.ico.
- When enabled, every build copies that set into the site root. The generated names are shared constants between the settings and the builder, so they can’t fall out of sync.
- Same for the site logo: choose its file in settings and every build places it at the site root for your theme’s header to reference.
Fonts
Fonts never come from a CDN: the shipped faces (including per-script subsets) are local files copied to every language’s output as fonts/. Your theme’s _head.tt pulls them from there. If you need a different typeface, add files to the fonts directory; they’re synced to every language on the next build.
Quick reference: what gets processed, and how
| Asset type | What happens on build/upload |
|---|---|
| Theme CSS/JS | Authored in templates; shipped unchanged (no minification) |
| Admin CSS/JS | SRI-hashed at startup; the reload rule applies |
| Fonts | Synced verbatim into every language’s output; admin’s wrapped in fonts.css |
| Media images | Derivative sizes + WebP generated at upload (see Media Library) |
| Favicons/icons | Generated from one source image via settings |
| Design tokens | Converted to CSS custom properties at build time |
The short version
Public-site assets are boring copies: files in, files out, cache rules at the proxy. The one moving part is the admin bundle’s SRI hashes: change one of its five files, restart the app, and if you see an integrity failure in the browser console on an admin page, that stale-hash loop is exactly what happened (see the CSS Blocked (SRI) page for the one-step fix).