Create & Clone Themes

Creating a theme is either importing one (a template archive) or cloning an existing one to modify. Both land under Themes in the admin area. This page covers the import rules, the clone flow, and the export path that gives you a clean hand-off.

Creating a theme by upload

Themes → add takes a name and an archive file:

• Accepted formats: .tar.gz, .tgz, or .zip, up to 5 MB.
• The template set must include the six required files: _head.tt, _header.tt, _footer.tt, page.tt, post.tt, blog_index.tt. Missing files fail the install with a flash naming each one.
• Only .tt files and an optional _theme.json are extracted; dotfiles are ignored; archive directory prefixes flatten regardless of the packaging style.

Security scan on import. Every uploaded template is scanned before anything lands:

• [% PERL / [% RAWPERL blocks are rejected outright.
• INSERT directives with absolute paths are rejected.
• USE directives that load system-capability modules (File, Socket, LWP, etc.) are rejected.

A single unsafe file aborts the whole upload: nothing partial is installed. Garbage tarballs are reported separately (“not a valid .tar.gz”) from missing-files errors. Symlinks and hardlinks inside an archive are ignored: a traversal vector rather than a theme feature.

Installs are atomic: files extract to a staging directory that is renamed into place, so a partially-installed theme never appears in the theme list, even after a mid-install failure. The created theme is audited with a full file manifest (filenames and sizes), then waits for you to activate it: upload never auto-activates.

Cloning

The Themes list has a Clone button per theme. Give it a new name; you get:

• A copy of the source theme’s template directory under a fresh slug (the name slugified).
• A fresh themes-table row and a file-manifest audit entry (“cloned from …; files=…”).
• A redirect to the new theme’s editor.

Guardrails: the default slug is reserved on both create and clone; clashing existing slugs (disk or DB) are refused before any copying; a partially-copied directory is removed on failure rather than left half-installed.

Cloning the default theme produces an empty theme directory: the built-in templates don’t exist on disk, so starting from default is exactly the same as starting from scratch in a bundled directory of your own. As long as a theme carries no override, the builder falls back to the built-in template set, so a blank clone works out of the box and you customize as you go.

Activate and make it live

Uploading (or cloning) doesn’t make a theme live: activation is a separate one-click action on the theme. Activating is what the build’s template search uses; an active non-default theme’s directory is consulted first, with the built-ins as fallback, so partial themes are safe to develop against (a theme only needs to ship the files it changes).

Export: hand-off packaging

Any theme exports from its detail screen as a .tar.gz of its .tt files, useful for archiving, moving a theme between instances, or handing a theme file to a colleague. The export route admin-only; exporting the shipped default theme with no custom files isn’t possible (there’s no on-disk copy to export).

The editor

Both upload and clone land you on the theme’s detail screen: its file tree with per-file edit routes, previews, and the design-brief generation side (that workflow lives in the LLM Theme Prompting doc, not on this page).