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 settings ( | escaped |
| safe view of the site settings: | escaped |
|
| escaped |
|
| escaped |
| string: |
|
| string: JSON for the body of a |
|
| string: the rendered blocks |
|
| string: attribution anchor, empty with a valid licence |
|
| string: the editor guest script (no |
|
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 |
|---|---|
| The CSP meta, title, description, canonical, Open Graph and the |
An element with | The overlay finds the editable page through it |
An element with the | The overlay replaces its |
| Informational; the authoritative id is the |
| 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
innerHTMLof[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-pageis informational only.The
<h1>lives outside the wrapper. The overlay updates it throughtextContentwhen 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 theContent-Security-Policymeta, then<title>,meta description,link rel="canonical",meta robots(noindex,nofollow, only when the page isnoindex), Open Graph tags (og:typeiswebsitefor the home page andarticleotherwise, plusog:title,og:description,og:url,og:site_name,og:locale, andog:imagewith width, height and alt when the hero image is a valid gallery image), and thepiglet:page-idandpiglet:templatemetas 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,LocalBusinessorOrganization(only whensite.businessis 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.templatediffers frommanifest.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 ofheadonly governs what follows it);the layout lacks an element with
id="piglet-content"or an element with thedata-piglet-blocksattribute;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).