Architecture overview
How a Basker theme renders the live site: the lifecycle from request to rendered HTML
A Basker custom theme is a self-contained set of Liquid templates, blocks, layouts, and assets that turns site content into rendered HTML. It is separate from Website Builder, which uses a no-code block system instead of this Liquid file structure.
The four parts of a theme
| Part | What it does | Lives in |
|---|---|---|
| Layouts | The outer HTML shell: <html>, <head>, <body>, header, footer. Wraps every page. | layouts/ |
| Templates | Per-content-type renderers. Determine the structure of the content for a page, event, post, or other record. | templates/ |
| Blocks | Reusable composable units editors place inside pages and other content. Each block has a schema and a Liquid file. | blocks/ |
| Snippets | Liquid partials reused across templates and blocks via {% render %}. | snippets/ |
A request flows top-down. A layout wraps a template. The template renders content and can call {% stageblocks %} to draw editor-placed blocks inline. Blocks can {% render %} snippets for shared markup.
See Directory structure for the full filesystem layout.
The rendering lifecycle
When a visitor opens a URL on a Basker site:
Match the URL to content
Basker resolves the URL to a record, such as a page, event, or post. Any content type with a public route can match. The collection of the record, for example page or event, decides which template Basker picks.
Pick a template
Basker picks a base template for the content type. Examples are templates/page.liquid, templates/event.liquid, and templates/post.liquid. If a record has a per-record template, Basker uses it instead. If that file is not in the theme, Basker falls back to the content-type default.
See Template references for the full collection list.
Pick a layout
The {% layout %} tag in the template decides which layout wraps the page. A template without one renders without a layout.
Build the template context
Basker flattens the CMS record into Liquid-friendly data. Basker exposes this data as a variable named after the collection, such as page, event, or post. Basker also makes global drops available, such as tenant, navigation, and settings.
See Template context for the full set of variables.
Render template + blocks + layout
Liquid runs the template. {% stageblocks %} calls produce per-block HTML inline. Liquid injects the result into the {{ content_for_layout }} placeholder in the layout. Header injections, such as the preview banner, generator meta tag, and preconnect hints, go into {{ content_for_header }}.
Cache and serve
Basker can cache the rendered response. Publishing content or a theme triggers cache invalidation. Later requests then receive the current version.
The theme manifest
When you upload a theme ZIP, Basker validates its Liquid files. Basker also consolidates block schemas, template schemas, and theme settings into a manifest. Block fields, template settings, and theme-wide settings all flow from manifest entries.
Editors do not see the manifest directly. They see the controls it produces. As a developer, the manifest determines whether your theme presents the right options to editors.
See The theme manifest for what the manifest looks like and how Basker builds it from your files.
Where each piece is documented
Directory structure
Required and optional directories, naming conventions, file size limits.
The theme manifest
What Basker generates from your files during upload.
Template context
Every variable, global function, and collection drop available in templates.
Building
Hands-on guides for layouts, templates, blocks, and settings.