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.