Theming & Design

A Chinaski theme is a directory of Template Toolkit files that the static builder renders into every public page: the complete control point for how a site looks. This section covers the shipped theme, every template file it’s made of, how to create and clone your own, and the variables/blocks/assets lands that make output safe.

The template model (start here)

• Template Files: the site-template set (page.tt, post.tt, blog_index.tt, 404, search, offline, and the _-prefixed partials), the theme-first search order with built-in fallbacks, and how per-page templates pick their file.
• The per-base templates: the raw.tt unbranded shell, documents.tt listings, search.tt, and offline.tt: each with its own page.

Building your theme

• Create & Clone Themes: the upload path (archive rules, required files, the security scan), cloning any theme (what cloning the default means: an empty directory with fallback behavior), and export.
• The Letterbox Theme: the shipped default, as your reference/debug base.
• Variables & Helpers: what every template gets in the stash (content fields, site settings, nav trees, hreflang, JSON-LD…).
• Blocks in Themes: how {{block:name​}} shortcodes and block templates render inside any theme.
• Assets & SRI: static asset handling; the cache-busting and integrity behavior for admin CSS (and how the static output ships its own).
• Design Tokens and Design Briefs: setting brand values once (tokens) and the AI-assisted generation flow for a new theme from a brief.

What you should know before starting

• Fallbacks make it safe. An active theme’s directory is searched first, built-ins second. A theme only ships the files it changes; a theme missing standard files still builds (it just uses the built-ins unchanged). A clone from the default theme starts as an empty theme directory for exactly this flow.
• Everything is .tt files. Template Toolkit basics (escaping (| html/| uri), INCLUDE/PROCESS, whitespace chomp) are in the security/variables pages, with the rules of what must be escaped (everything user-supplied except body and json_ld).
• Errors don’t kill builds. Per-template render failures record an error in the build log and continue; the dashboard names the first few failing templates.

Security bottom line

The theme editor only accepts safe templates (the scan runs on upload), and the educative content in the built-in Theme Authoring doc covers the escaping rules; treat those rules (escape user data, minimal inline scripts, treat snippet editors carefully) as standing advice for your own theme files.