The four built-in layout templates (Default, Wide, Landing, Minimal) cover most channels. When you need the public pages to be exactly your markup — your own HTML, your own structure, your own classes — switch the channel to Custom layouts and write the templates yourself.
This is the advanced end of the customization stack. Most channels never need it; the theme presets plus widgets get you there with no code. Reach for custom layouts only when the structural shape of the page itself has to change.
Two modes: Default appearance vs Custom layouts
Open Theme from the dashboard left rail. At the top is an Appearance mode switch with two buttons and a "Currently live:" line so you always know which one visitors are seeing:
- Default appearance — the built-in templates, styled by the preset / colours / fonts / header / footer editor. This is what every channel starts on, and what the rest of the customization guide describes.
- Custom layouts — your public pages render from HTML templates you write. The preset / header / footer editor is hidden (it doesn't apply); the page instead shows your layout and partial library.
Switching is one click and takes effect immediately — the saved mode is the live state, there's no separate publish step. You can flip back to Default appearance at any time; your custom layouts are kept, just not used while you're in Default mode.
{{{theme.cssBlock}}} in your layout's <head> and reference var(--brand-primary), var(--brand-font-heading), etc. To change those colours, switch to Default appearance, edit them, switch back.
Layouts are just templates
A layout is a named HTML template written in Handlebars. It is not tied to a particular kind of page — the same flat list of layouts is offered for the channel home, asset pages, and individual articles and pages. What data a layout receives depends on where it ends up being used, not on the layout itself. Tokens that don't apply on a given surface simply render empty.
There are three public surfaces, and each one resolves a layout like this:
- Channel home — uses the layout bound to "Channel home" in the Theme page's layout settings. There's no per-item override; this binding is the only control. (Exception: if the channel home is a pinned static page, that page's own layout wins instead.)
- Asset page — uses the layout bound to "Asset page". Also binding-only; assets have no per-item picker.
- Article / page detail — each article or page can pick a layout from the Layout dropdown in its editor. If it doesn't, the channel's default article/page layout (the "Advanced" binding) applies. If that's unset too, the built-in view renders.
So: bind a layout to a surface on the Theme page, or pick one per article/page in that item's editor. One template, used anywhere you point it.
Partials — reusable fragments
A partial is a named HTML snippet a layout pulls in with {{> partialId}}. Use them for anything shared across layouts — a site header, a footer, a left menu, a card. Edit the partial once and every layout that includes it updates. Partials see the same data as the layout that calls them, and a partial can include other partials.
Creating and binding a layout
- Theme → switch Appearance mode to Custom layouts.
- Under Layouts, type a name and click New. The layout opens in the editor pre-filled with a generic skeleton that already handles article, list, and asset data — keep the parts you need, delete the rest.
- Write your HTML. The token sidebar on the right lists every available token; click one to insert it at the cursor. Use Preview (a sandboxed window) to see it rendered with sample data before you ship.
- Save layout.
- Back on the Theme page, bind it: set it as the Channel home / Asset page / default article layout, or open an article/page and pick it from that item's Layout dropdown.
- Theme → Custom layouts. Under Layouts, create one called "My home". It opens in the editor with the skeleton.
- Change the
<title>line to something obvious and hit Preview — the sandboxed preview renders with sample article + list + asset data. - Save. Back on the Theme page, set Channel home to "My home" and Save layout settings.
- Open the public channel home in another tab. It should render your template, with the sample list replaced by the channel's real articles.
- Open an article's editor — its Layout dropdown now lists "My home" too (built-in Default/Wide/Landing/Minimal are hidden while custom mode is on). Pick it, save, view the article: it renders your template with that one article's data.
When a layout breaks
Rendering is fail-soft. If a saved layout throws (a typo, a bad {{> partial}} reference), the public page does not break — it falls back to the built-in view, and the Theme page shows a banner telling you which surface is failing and why. Fix the template and the banner clears.
Every save also snapshots the previous state of the whole library. If an edit goes wrong you can Roll back library from the Theme page to the prior version in one click.
A note on trust
Custom layouts are raw HTML — <script> is allowed, so you can wire in analytics or embeds. That also means a layout can do anything a web page can; treat the editor like production code. The Preview runs in a sandboxed frame specifically so a work-in-progress template can't touch your admin session.
Migration note
Earlier versions tagged each layout with a page type (article / home / asset). That tag is gone — layouts are now a single flat list usable anywhere. Any layouts you created before this change still work and are now selectable on every surface; you don't need to do anything.
Keep going
- Layout tokens — the full reference: every token, where each one resolves, and the
{{{theme.cssBlock}}}helper. - Layout recipes — copy-paste starting points for an article page, a list home, an asset page, and shared header/footer partials.
- Customizing your channel — the full stack: theme, widgets, layouts, and channel CSS, and when to reach for which.