---
title: "Assets & SRI"
url: "https://docs.chinaski.net/en/theming/assets/"
type: "page"
language: "en"
description: "Understand the two asset tracks, public site and admin app, and the reload rule: restart the app after editing its five SRI-hashed files."
updated: "2026-09-29"
generated: "Markdown rendition of the HTML page at url, built by Chinaski"
---

# 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.tt` partial, 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).
