Coming from another platform
If you have built themes for Shopify, Lightspeed, WordPress or a static-site generator, most of what you know carries over — the concepts do, the file types do not. This page is the translation table. Read it before you write your first template, and read it again when a refusal from the MCP names it.
The one rule
A CTXR theme is PHP shells over data. There is no template language of its own and no other template language is accepted: no Liquid, no Twig, no Blade, no Handlebars, no JSX. A file under theme/ is .php, .css, .js, .svg or .json — nothing else enters, and the MCP says so at the door. The content a template shows never lives in the template: it is an entity in data/, and the template reads it.
The translation table
| You know it as | In CTXR it is | Where to read |
|---|---|---|
a template (product.liquid, single.php, page.html) |
a shell: theme/templates/<type>.php (or per language under templates/<lang>/), chosen by the entity’s @type down a ladder to a universal floor |
How a page finds its shell |
a section or snippet ({% section %}, get_template_part(), a partial) |
section('name') and snippet('name') — includes that pull their own data |
The helpers you have |
a filter or helper ({{ title \| upcase }}, a Twig filter) |
plain PHP, plus the engine’s helpers (data(), locale_string(), v(), seo_head(), ld()) |
The helpers you have |
theme settings (settings_schema.json, the Customizer) |
theme/config.php (site constants) and theme/strings/ (interface copy per language) |
The theme layer, Strings and languages |
| a product, collection, post, page | an entity: one JSON file, data/<type>/<identifier>.json, in Schema.org vocabulary; an entity with a slug is a page |
Data in a template, Data conventions |
| a menu, a featured list, “related items” | an itemlist entity you curate — order is editorial, not a query |
Data conventions |
| a route or URL rule | the entity’s slug; a route table exists but is the exception |
Pages and languages |
a theme asset (assets/, an enqueue) |
assets/ for files, v() for cache-busting — no bundler, no build |
Styling and assets |
| a product feed, an external catalogue | a feed the site fetches into assets/ or entities generated from it — data, not template logic |
Data conventions |
What a CTXR site can be — and cannot
Visual and data: yes. A storefront’s look, its product pages, collections, filters by curated lists, the catalogue as structured data that search engines and AI can read — all of that is shells + CSS over entities. A catalogue that lives elsewhere can be mirrored in as data.
Transactional: no. A cart, a checkout, payments, customer accounts and order history are platform logic. CTXR does not have them and will not grow them (see What we deliberately leave out). A CTXR site renders the shop window and the catalogue and hands the transaction to the platform that owns it — a link, a hosted checkout, an embedded widget. If you find yourself building a cart in a shell, stop: that is the wrong layer.
The habit that saves the most time
Before writing a shell, fetch the theme listing through the MCP and follow its docs pointer — fetch "docs/theme", this section of the docs — and fetch one existing shell as the shape. Before creating an entity, fetch data/<type> for its schema. The site is data first: ask whether the change is data or form, and put it where it belongs.