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-blocks attribute 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

  1. Create packages/templates/<id>/ with template.json and layout.html. The id uses [a-z0-9-], is up to 64 characters long, and must equal the manifest id. Inline your CSS, and avoid external fonts and scripts.

  2. Deploy with pnpm --filter @piglet/deploy cli -- --only templates. The files land at _piglet/templates/<id>/template.json and _piglet/templates/<id>/layout.html. Only .html and .json files are uploaded, and templates are overwritten on every deploy.

  3. 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 are woff2, webp, avif, png, jpg, jpeg, ico, js, mjs and css; no SVG or HTML. They are cached for a day, so rename a file to replace it sooner.

  4. Pages select the template through page.template. The template id must equal the manifest id, 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.