Templates: quick start
A template is two files: a manifest and one HTML layout. This page gets you from nothing to a page that compiles.
What a template is
A template is two files: a manifest, template.json, and one LiquidJS layout, layout.html. The editor compiles a page with them when you publish. It checks both files, then renders your layout into a full HTML document.
The layout is plain HTML with a few Liquid placeholders. You decide how the page looks, and the compiler fills in the content.
The smallest layout that works
The compiler rejects a layout that misses any of the pieces below. This is a layout that has them all:
<!doctype html>
<html lang="{{ site.locale }}">
<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>
<body>
<main id="piglet-content" data-piglet-page="{{ page.id }}">
<h1>{{ page.title }}</h1>
<div data-piglet-blocks>{{ content | raw }}</div>
</main>
<footer>{{ badge | raw }}</footer>
<script type="module">{{ guest_script | raw }}</script>
</body>
</html>{{ head | raw }}goes inside<head>. It carries the Content Security Policy meta, the title, the description, the canonical link, the Open Graph tags and two metas the editor reads. You never write those yourself.An element with
id="piglet-content"is how the editor overlay finds the editable page.An element with the
data-piglet-blocksattribute holds the page content, and only{{ content | raw }}. The overlay replaces what is inside it with freshly rendered blocks.<script type="module">{{ guest_script | raw }}</script>starts the editor session probe. Nothing else may sit inside the script tags.
Every one of these has rules of its own. They are all in the layout reference.
The manifest
This is the complete template.json of the template that runs this site:
{
"id": "default",
"name": "pigletCMS Sumi-e",
"version": "1.0.0",
"pageSettingsSchema": {
"type": "object",
"properties": {
"heroImage": {
"type": "string",
"format": "uri"
}
}
},
"allowedBlocks": [
"RichText",
"Image",
"SimpleContentList"
]
}id,name,version: identity and display.allowedBlocks: the block types (RichText,Image,SimpleContentList) pages using this template may contain. Other types fail compilation.pageSettingsSchema: a JSON Schema object describing the extra page settings the editor offers for this template.
Where the files go
Create
packages/templates/<id>/withtemplate.jsonandlayout.html. The id uses[a-z0-9-], is up to 64 characters long, and must equal the manifestid. Inline your CSS, and avoid external fonts and scripts.Deploy with
pnpm --filter @piglet/deploy cli -- --only templates. The files land at_piglet/templates/<id>/template.jsonand_piglet/templates/<id>/layout.html. Only.htmland.jsonfiles are uploaded, and templates are overwritten on every deploy.Put the fonts, images, scripts and stylesheets the layout needs in
packages/templates/<id>/public/. Deploy uploads them to_assets/<id>/<path>, outside the Access-gated_piglet/prefix, so the layout references them as/_assets/<id>/fonts/a.woff2. Accepted types arewoff2,webp,avif,png,jpg,jpeg,ico,js,mjsandcss; no SVG or HTML. They are cached for a day, so rename a file to replace it sooner.Pages select the template through
page.template. The template id must equal the manifestid, or compilation fails.
Which template a page uses
The admin's New page dialog always creates pages with the template default. There is no template picker in v0.1.0. To use a custom template you either change page.template in the page JSON, or replace the files of the default template.
Next
Layout reference: every variable a layout can use, and every error the compiler can give.
Block markup: the HTML each block produces and the classes to style.
Security rules: what a template may and may not do, and why.