Layout reference

Everything a layout can read, everything it must contain, and what the compiler says when it does not.

Variables

Every variable is HTML-escaped automatically. Only the five pre-rendered fragments (head, content, jsonld, badge, guest_script) are output with | raw, and the engine enforces this. Missing variables render empty. Unknown filters, include, render and layout (there is no file access) and other render errors fail the build with a TemplateError.

Key

Type

Output

page

page settings (title, description, slug, heroImage, category, tags, noindex, canonical) plus id, template, createdAt, updatedAt, publishedAt; canonical is the resolved canonical URL (http(s) or the page URL); heroImage is { src, alt, attribution?, width, height } and is only set for a valid gallery image

escaped

site

safe view of the site settings: name, description, locale, baseUrl (resolved, with trailing slash), logo (gallery images only), social (http(s) only), business; never whiteLabel

escaped

nav

{ label, href, children, current }[]; children is the same shape, nested at most 3 levels (a fourth never appears); current is true for the current page

escaped

breadcrumbs

{ name, url }[]: site name, nav ancestors, then the page

escaped

head

string: <title>, meta, canonical, Open Graph, piglet:* metas

| raw

jsonld

string: JSON for the body of a <script type="application/ld+json"> (no <, >, &); optional in the layout

| raw

content

string: the rendered blocks

| raw

badge

string: attribution anchor, empty with a valid licence

| raw

guest_script

string: the editor guest script (no </script)

| raw

nav.href for a page item is its absolute page URL. Items whose page is missing, or whose url is not http(s), are left out. Objects are not meant for output: {{ site }} prints the inert text [object Object].

What every layout must contain

compilePage rejects a layout that misses any of these:

Requirement

Why

{{ head | raw }} inside <head>

The CSP meta, title, description, canonical, Open Graph and the piglet:* metas

An element with id="piglet-content"

The overlay finds the editable page through it

An element with the data-piglet-blocks attribute, holding only {{ content | raw }}

The overlay replaces its innerHTML with freshly rendered blocks

data-piglet-page="{{ page.id }}" on the #piglet-content element

Informational; the authoritative id is the piglet:page-id meta

<script type="module">{{ guest_script | raw }}</script> with nothing else inside

Starts the editor session probe; its text is pinned by the CSP hash

The head fragment carries two metas the overlay reads: <meta name="piglet:page-id" content="…"> (the authoritative page id) and <meta name="piglet:template" content="…">. They come from the compiler, so a layout never writes them. {{ jsonld | raw }} (inside <script type="application/ld+json">), {{ badge | raw }}, site, nav and breadcrumbs are optional for the compiler. The default template uses all of them, and the badge is expected in the footer.

The editable area

The editor overlay finds the editable page through the element carrying id="piglet-content", and the blocks through the element carrying the data-piglet-blocks attribute inside it. Output both exactly once, with {{ content | raw }} as the only child of the blocks wrapper:

<main id="piglet-content" data-piglet-page="{{ page.id }}">
  <h1>{{ page.title }}</h1>
  <div data-piglet-blocks>{{ content | raw }}</div>
</main>
  • The overlay replaces the innerHTML of [data-piglet-blocks] with freshly rendered blocks. Do not put any other content inside [data-piglet-blocks]: it would be lost on the first edit.

  • The page id is read from meta[name="piglet:page-id"], which is authoritative. data-piglet-page is informational only.

  • The <h1> lives outside the wrapper. The overlay updates it through textContent when the title changes.

The markup inside the wrapper, and the CSS classes your stylesheet should cover, are on the block markup page.

Head and structured data

The compiler builds two strings for every page and passes them to the layout as Liquid variables:

  • head: first the Content-Security-Policy meta, then <title>, meta description, link rel="canonical", meta robots (noindex,nofollow, only when the page is noindex), Open Graph tags (og:type is website for the home page and article otherwise, plus og:title, og:description, og:url, og:site_name, og:locale, and og:image with width, height and alt when the hero image is a valid gallery image), and the piglet:page-id and piglet:template metas the editor overlay reads.

  • jsonld: the JSON body of one <script type="application/ld+json"> element (the layout supplies the tags), an array of schema.org objects: WebSite, LocalBusiness or Organization (only when site.business is set), WebPage, BreadcrumbList.

Output head inside <head>, unescaped, before any <script> or <link>. The compiler enforces the order, because the CSP meta only applies to what the parser meets after it. Output jsonld wrapped in its script tag. The compiler does not require it, but leaving it out drops the structured data. Do not emit your own <title>, description, canonical or Open Graph tags:

<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {{ head | raw }}
  <script type="application/ld+json">{{ jsonld | raw }}</script>
</head>

Both variables are built by the compiler from escaped values, so | raw is safe. Do not pass other content through raw.

Badge and guest script

Output the attribution badge in the footer:

<footer>
  {{ badge | raw }}
</footer>

On the free tier badge is <a class="pg-badge" href="https://pigletcms.com" rel="noopener">Built with pigletCMS</a>. Style .pg-badge as you like. With a valid white-label licence for the site's host it is the empty string, so the same template works for both.

Output the guest script at the end of <body>, as an inline module:

<script type="module">{{ guest_script | raw }}</script>

It is under 2 KB, never contains </script, and does not block paint. It only loads the editor overlay for visitors with an authenticated editor session.

Nothing may sit between the tags, not even a newline or a space. The CSP allows this one inline script by the SHA-256 of its exact text, and the compiler rejects a layout that would change it.

Compile errors

compilePage throws TemplateError before rendering when:

  • the manifest fails TemplateManifestSchema;

  • page.template differs from manifest.id;

  • a block's type is not in manifest.allowedBlocks (the message names the block);

  • the layout lacks {{ head | raw }}, {{ content | raw }} or {{ guest_script | raw }} (whitespace inside the braces and {{- or -}} are fine);

  • a <script> or <link> comes before {{ head | raw }} in the layout (the CSP meta at the start of head only governs what follows it);

  • the layout lacks an element with id="piglet-content" or an element with the data-piglet-blocks attribute;

  • the layout outputs {{ head }}, {{ content }}, {{ jsonld }}, {{ badge }} or {{ guest_script }} without | raw (it would be escaped twice, silently breaking the page);

  • {{ guest_script | raw }} is not the whole text of a <script> element: any whitespace or other text between <script …> and {{, or between }} and </script>, changes the script's CSP hash ({{- and -}} trims are fine).