Architecture overview
How a Basker theme renders the live site — the lifecycle from request to rendered HTML
A Basker theme is a self-contained set of Liquid templates, blocks, layouts, and assets that turns CMS content into the live site. This page is the one-page mental model for how it all hangs together; the rest of this section drills in.
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. Decide how a page, event, post, or other record's content is structured. | 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; a template renders content and may call {% stageblocks %} to draw editor-placed blocks inline; blocks may {% 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 — a page, event, post, or any other content type with a public route. The record's collection (page, event, post, etc.) is the input to template selection.
Pick a template
Basker picks a base template for the content type, such as templates/page.liquid, templates/event.liquid, or templates/post.liquid. If a record has a per-record template chosen on it, Basker uses that template instead — and falls back to the content-type default when the chosen file isn't in the theme.
See Template references for the full collection list.
Pick a layout
The template's {% layout %} tag (or default.liquid if absent) decides which layout wraps the page.
Build the template context
The CMS record is flattened into Liquid-friendly data and exposed as the variable matching the collection: page, event, post, and so on. Global drops like tenant, navigation, and settings are also made available.
See Template context for the full set of variables.
Render template + blocks + layout
Liquid runs the template. {% stageblocks %} calls produce per-block HTML inline. The result is injected into the layout's {{ content_for_layout }} placeholder. Header injections (preview banner, generator meta, preconnect hints) go into {{ content_for_header }}.
Cache and serve
The final HTML is cached and served. Editor changes invalidate affected URLs automatically; the next request rebuilds the cached version.
The theme manifest
When you upload a theme ZIP, Basker doesn't just store the files. Every .liquid file's {% schema %} block is parsed and consolidated into a manifest — the structured data that drives the editor experience. Block fields, template settings, and theme-wide settings all flow from manifest entries.
Editors don't see the manifest directly; they see the controls it produces. As a developer, the manifest is what determines whether your theme presents the right options to editors.
See The theme manifest for what the manifest looks like and how it's built 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.