Truly theme developer docs Guides Reference (format 1)

Package format

A theme is a zip with these entries and nothing else (lowercase names; folders allowed):

Required: manifest.json, layout/theme.liquid, locales/da.json, locales/en.json.

manifest.json

Exactly the keys name, version, format_version: name and version are text of 1 to 100 characters
(version is your own, semver recommended), and format_version is 1, the current format. A new upload
must declare the current format.

Layout

layout/theme.liquid wraps every page. It prints {{ content_for_layout }} exactly once and places
{% slot 'footer' %}, both at its top level: not inside an if, for or other block, and not in a snippet.

Images and fonts

PNG, JPEG or WebP images (no SVG), at most 25 megapixels; Truly re-encodes them
as WebP and scales them to at most 1200 pixels on the longer side. Fonts are WOFF2.

Sizes

Limit Value
Zip file 10 MB
Entries 300
One file, unpacked 5 MB
All files, unpacked 20 MB
Stored versions 10 (the oldest unpublished one is deleted to make room; versions kept as consent evidence do not count)

Check report reasons

Each problem has a level (error or warning), a reason, and where known the file, line and locale key.

Reason Meaning
fixture_render The template failed when shown with sample data for the state (the key is the state and the reason). The page would fall back to the default theme.
fixture_states The template was shown with sample data for these states.
not_a_zip The file is not a readable zip archive.
zip64 Zip64 archives are not supported. Pack the theme as an ordinary zip.
multi_disk Archives split over several parts are not supported.
too_many_entries The archive has too many files.
duplicate_entry The archive holds the same file name twice.
case_collision Two file names differ only by upper and lower case.
encrypted_entry The file is encrypted or password-protected.
compression_method The file is packed with an unsupported compression method. Use ordinary zip compression.
link The archive holds a link. Only ordinary files and folders are allowed.
directory_with_data A folder entry holds data.
entry_too_large The file is too large.
inconsistent_entry The archive's file list does not match its content.
archive_too_large The unpacked theme is too large.
nested_archive The file is itself an archive or a compressed file.
corrupt_entry The file cannot be unpacked.
size_mismatch The file's size does not match the archive's file list.
crc_mismatch The file's checksum does not match. The archive may be damaged.
overlapping_entries Files in the archive overlap.
internal_error The check stopped because of an error at Truly. Try uploading again.
time_limit The check took too long.
unexpected_entry The file is not part of the theme format. Only manifest.json, layout, templates, snippets, assets and locales are allowed, with lowercase names.
missing_file A required file is missing.
invalid_text The text file is not valid UTF-8 or contains a NUL character.
invalid_json The file is not valid JSON, or a key appears twice.
manifest_keys manifest.json must have exactly the keys name, version and format_version.
manifest_value name and version in manifest.json must be text of 1 to 100 characters.
format_version format_version is not the current theme format (1).
locale_value Locale strings must be plain text in objects, with keys of lowercase letters, digits, - and _.
unknown_route The template's name is not a known page.
missing_snippet {% render %} names a snippet that is not in the theme.
content_for_layout The layout must output {{ content_for_layout }} exactly once, outside any Liquid block.
footer_slot The layout must place {% slot 'footer' %}, outside any Liquid block.
missing_slot The page requires this slot, but neither the layout, the template nor their snippets place it, so the page can never show.
missing_state_slot The page requires this slot in some states, but it is placed nowhere. Check that the template shows it when the state requires it.
slot_order This slot comes before a slot it must follow (pausing comes after cancelling a membership), so the page can never show.
slot_container This slot is not inside the container it belongs to (for example the consent inside the payment step's consents, or the withdrawal notice inside the booking's status), so the page can never show.
version_cap The library is full, and no draft can be deleted automatically. Delete a version before uploading another.
liquid_syntax The Liquid template cannot be read, or uses a tag or filter themes cannot use.
template_too_large The template is too large.
missing_english_key The English locale lacks this key; the Danish text is shown instead.
image_type The image is not the type its file name says (PNG, JPEG or WebP).
image_pixels The image has too many pixels (at most 25 megapixels).
image_invalid The image cannot be read.
font_invalid The font is not a valid WOFF2 file.
image_svg SVG images are not accepted. Save the image as PNG, JPEG or WebP.
css_too_large The stylesheet is too large (at most 512 KB).
css_too_deep The stylesheet nests parentheses and brackets too deeply (at most 32 levels).
css_syntax The stylesheet has a rule that cannot be read; it is left out.
css_at_rule This at-rule is not allowed (only @media, @supports, @container, @layer and @font-face); it is left out.
css_selector The selector is not allowed (no ids, no :has() and only [data-part=…] as an attribute); the rule is left out.
css_property The property is not allowed; the declaration is left out.
css_value The value is not allowed; the declaration is left out.
css_function The function is not allowed; the declaration is left out.
css_url url() and image-set() must name an image of the theme, and @font-face a WOFF2 file of the theme; the declaration is left out.
css_condition The condition is not allowed; the rule is left out.