You are not stuck with a starter

You can:

  • Replace the theme stylesheet with your own CSS
  • Build a custom layout (page chrome, navigation, footer, and content areas)
  • Keep using the visual editor for page content inside those areas

Every plan, including Building, can go Live on a keelpage.com address; a custom domain needs a paid plan. It does not lock you into a template look. You can design a fully custom site while it is still Coming soon, then go Live when you are ready.

What is a theme vs a layout?

ThemeLayout
What it isThe site’s CSS (and optional design tokens / site script)The HTML shell around every page that uses it
ControlsColours, fonts, spacing, buttons, forms, cardsHeader, nav, footer, sidebars, and where editable content sits
Where in KeelSite → Theme (stylesheet)Site → Layouts (layout code)
How content editors workRarely touch itFill regions (named content slots) on each page

Think of the layout as the frame and the theme as the paint. Page parts (headings, text, images, forms) sit in the frame’s slots.

Before you start: pick a design idea

Write one sentence: the mood, colours, and personality (for example “closing-bell desk — navy, amber, ticker strip” or “lab notebook — kraft paper, red stamps”). Use that sentence to decide nav labels, footer lines, and CSS. If the site still looks like a generic starter with your name swapped in, keep going.

Step 1 — Theme stylesheet

  1. Open Theme and the custom stylesheet.
  2. Paste or write your CSS. Prefer CSS variables for colours and spacing, then component rules.
  3. Put a unique class on the layout body (for example theme-studio) and scope your rules under it so you do not fight leftover starter styles.
  4. Style Keel’s built-in parts with their stable classes (buttons, forms, cards, rich text). Avoid inventing fragile selectors tied to editor-only markup.
  5. Do not put style="…" on layout or page elements. In layouts and shared design parts, Keel refuses a style attribute when you save. In page text, Keel removes it when you save and tells you what it removed. An HTML part keeps it, but all styling belongs in the theme.

Fonts: use Theme font settings, @import / @font-face, or upload WOFF2 files to Media and reference them in CSS.

Save/publish the theme before you rely on it in the layout.

To choose between Keel’s look and your theme’s own look for forms, buttons and images, see Change the Theme.

Step 2 — Custom layout

  1. Open Layouts. Create a new layout or edit the one your pages already use.
  2. Paste a full HTML document that includes:
    • {% head_content %} inside <head> — this is where Keel puts your theme CSS and related head tags. If it’s missing, Keel adds them just before </head>, so the tag is recommended rather than required.
    • A body class that matches your theme scope.
    • Fixed chrome (brand, navigation, status strip, footer jokes) as normal HTML.
    • Editable slots with {% region 'name' %} — for example hero, main, aside, cta.
  3. Do not write {% endregion %}. Regions are opened only; Keel refuses a closing tag.
  4. Give regions clear names and keep them stable. Renaming a region can hide existing page content until you move it.
  5. If a region needs HTML parts, allow the HTML part in that region’s allowed parts, then publish the layout again.
  6. Optional: in Visual, open For designers under an area and tick Wrap Main for styling (named after the area), so Keel wraps its parts in a div with the classes keel-region and keel-region--main that you can target in CSS.

Example skeleton

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {% head_content %}
  <title>{{ seo.title }}</title>
</head>
<body class="theme-studio">
  <header>…brand and nav…</header>
  <main>
    {% region 'hero' %}
    {% region 'main' %}
  </main>
  <footer>…</footer>
</body>
</html>

Choose the parts each area accepts in Code

In Layouts, open Code and enter this in Regions (JSON):

[{"key":"main","label":"Main"}]

Click Save draft, then publish the layout. With no allowedBlockTypes, the area accepts every current part. Keel saves that list with the layout, so publication uses the same choices. To restrict an area, use Visual and choose the parts it accepts, or give allowedBlockTypes an explicit list such as ["heading","richText"] in Code. An invalid list is refused with the region and the allowedBlockTypes field named. Maps can be allowed separately.

Step 3 — Attach pages and fill regions

  1. Point each page at your layout (page settings / layout picker). If a page still looks like the starter, it is probably still on starter-home or another starter layout — switch it or rewrite that layout in place.
  2. Fill every region with real content. Remove leftovers like [Your business name], [Home], or placeholder Latin.
  3. Put personality in the chrome (nav labels, ticker, footer). Put sellable copy in the regions so it stays editable.
  4. Add Media images with proper alt text.

Step 4 — Publish in the right order

  1. Theme
  2. Layout (and shared design parts if you use them)
  3. Pages (parent pages before child pages)

Publishing a layout publishes only that layout, not the pages that use it. A page draft can use a layout’s new regions before the layout is published; its Publish layout and page confirmation then publishes the layout first, then the page (see Publishing).

Then open the real Live URL (your *.keelpage.com address), not only Coming soon or a short-lived preview link.

Autosave may grey out “Save draft” after it saves — that is normal.

Page addresses in layouts

A nested page keeps its full address. In a layout, {{ page.url }} gives /en/meet-us (or /en/meet-us/ when the site uses trailing slashes). {{ page.path }} gives /en/meet-us without the trailing slash. This works at every supported depth. Preview uses the draft address; Live uses the published address. Neither value contains the preview link.

page.url and page.path also work in shared design parts (include and render), region wrappers and navigation loops, and on collection item and list pages.

The home page in layouts

is_home is true on the home page and false on every other page. page.is_home is the same value. Both work in Preview, on the live site and in a launch check.

{% if is_home %}
  <p>Welcome home.</p>
{% else %}
  <p>Not the home page ({{ page.is_home }}).</p>
{% endif %}

Search details in layouts

Imported layouts receive the page’s search details even when their code leaves out {% head_content %}: Keel inserts the missing head content. This also works for a Coming soon site’s never-published pages and items. An existing title in the layout stays in Preview and Live. To follow each page’s search title, use:

<head>
  {% head_content %}
  <title>{{ seo.title }}</title>
</head>

Keel writes the description, canonical address, Open Graph and Twitter tags and automatic structured data. Leave those copies out of the layout to avoid duplicates; an earlier fixed tag can hide the draft value.

Collecting HTML in Liquid

Liquid escapes ordinary values when it prints them. A capture holds the HTML already rendered inside it:

{% capture d %}<strong>{{ page.title }}</strong>{% endcapture %}
{% assign s = '' | append: d %}
{{ s }}

This renders the strong element. The page title is escaped inside it. Both append and prepend keep captured HTML and escape any plain text joined to it. To show tags as visible text, use {{ s | escape }}. For a quoted attribute, use a plain value or | escape.

Rich-text collection fields are cleaned on save: scripts, event handlers, unsafe links and style attributes are removed. Keel checks them again when rendering, including after a field changes type. In a layout or shared design part, {{ t.quote }} outputs escaped text. Use {{ t.quote | raw }} to render its cleaned HTML. The same rule applies to {{ item.body | raw }}, list.items and collections.<key>.items. The raw filter bypasses output escaping; it does not clean an ordinary string. Use it only for a rich-text field or HTML you trust, in element content, never an attribute. To show the tags as text, use {{ t.quote | escape }}.

Google Fonts and Font Awesome

Google Fonts work with no setup on Live sites and in Preview: use fonts.googleapis.com for stylesheets and fonts.gstatic.com for font files.

Font Awesome stylesheets work with no setup on Live sites and in Preview from use.fontawesome.com and cdnjs.cloudflare.com; self-hosted font files work too. For example, use <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css"> in the layout head and <i class="fa-solid fa-house"></i> in its body.

Font Awesome kits are scripts, which Keel doesn’t run. Use the Font Awesome stylesheet link or upload the font files instead. This also applies to formatted text and HTML parts in collection items; the refusal names the field and keeps your saved content. A kit script is refused on save and publish with a 400 naming its field (for example, theme.script in PUT /design); nothing is saved. Existing stored kits show the same message in GET /status and at their location in Preview; visitors never see that message on Live.

Layouts in use

A page’s draft and live version can use different layouts; both layouts stay in use until the page is published. When Delete layout is unavailable, it names up to eight pages using its draft or live version, then “and N more”; Show all lists the rest.

Earlier saves alone never block deleting a layout. The Delete layout dialog names their pages, for example: “Earlier saves of Home used this layout. Restoring one of them keeps its content and uses the page’s current layout.” Deleting works when no current draft, live page, deleted page or collection uses the layout. Restoring an earlier save then keeps its content and the page’s current layout. Publish the restored draft when ready.

Menus, forms, and shared pieces

  • Menus: create site menus and wire them into your header when the starter header is not connected.
  • Forms: add Name, Email, and Message (and any fields you need) on the Forms screen.
  • Shared chrome: header/footer placeholders on starters often live in layout / shared design parts, not on the page canvas — edit the layout (or Site-wide details) rather than hunting on the page.

Troubleshooting

ProblemWhat to try
Theme CSS does nothing on LivePublish the theme, then the layout. Keep {% head_content %} in the layout <head>
Layout save or publish refused because of stylesRemove every style="…" from the layout and shared design parts; move the rules into the theme
Page still looks like the starterChange the page’s layout, or rewrite the starter layout HTML in place
Content vanished after a layout editYou may have renamed/removed a region — put the old region back or move the content into the new region names
Empty grey bands on the pageEmpty layout regions can still take space — fill them or remove those regions from the layout
Cannot go LivePublish the home page first and finish any item marked Needed under Go Live. Every plan can go Live on a keelpage.com address; a custom domain needs a paid plan

For developers and agents

Technical detail (API, regionSchema, Liquid rules, limits) lives in the agent guide under Custom themes and layouts. The API calls a page’s draft and published addresses path and publishedPath. GET /api/sites/{siteId}/pages includes publishedLayoutId (null without a live version) beside the draft layoutId, for example { "title": "About", "layoutId": "new-layout-id", "publishedLayoutId": "live-layout-id" }. GET /api/sites/{siteId}/layouts/{layoutId} lists earlierSavePages, and DELETE with the layout’s If-Match returns 204 when nothing current uses it. Address errors keep the API field name slug with owner wording, such as errors.slug: ["This address belongs to the item slash-test."]. Humans building in the admin can stay on this Help article.

Related Help