Security rules
A template runs on the same origin as the editor, so the compiler holds it to a few rules. Here they are, with the reason for each.
Why there are rules
The editor and the public site share one origin. An unescaped variable in a template is therefore a way into the editor: a script on the site origin can act as the signed-in editor.
So the compiler enforces, rather than recommends, where raw may be used and what a page may load.
Where raw is allowed
Only the five fragments head, content, jsonld, badge and guest_script may be output with | raw. The compiler holds to these rules:
The five fragments are wrapped in a
SafeHtmlmarker before rendering.| rawaccepts only aSafeHtmlvalue. On anything else ({{ page.title | raw }},{% echo site.name | raw %},{% cycle x | raw %}, anassigned string) the engine throwsTemplateError: "| rawis only allowed on head, content, jsonld, badge, guest_script".{% assign t = content %}{{ t }}keeps the fragment safe. The marker travels with the value, so it is output unescaped. This is intended.A filter after
rawturns the fragment into a plain string, which is escaped again.{{ content | raw | upcase }}prints visible<SECTION ...text, never markup.Using a fragment without
| rawas the last filter ({{ content }},{{ content.size }},{{ content | upcase }}) is rejected before rendering, with a message saying so.guest_scriptcontaining</script(any case) or<!--is rejected.Rendering is limited to 2 seconds and 1M memory units. Runaway loops fail with
TemplateError.
Content Security Policy
Every compiled page starts its head fragment with <meta http-equiv="Content-Security-Policy" content="…">. The policy is CSP_POLICY from @piglet/core:
default-src 'self'; script-src 'self' 'sha256-<guest script hash>'; connect-src 'self'; img-src 'self' blob:; style-src 'self' 'unsafe-inline'; frame-src https://www.google.com; object-src 'none'; base-uri 'self'; form-action 'self'The policy is what stops an escaping mistake in a template from letting a foreign script run on the site origin. In production the same policy also arrives as a response header, plus frame-ancestors 'none'. A browser enforces both, so a template cannot loosen the header by editing the meta.
What it means for you as a template author:
Inline styles are fine.
<style>blocks andstyle="…"attributes are allowed ('unsafe-inline'instyle-src).Inline scripts are blocked. No
<script>…</script>with code, noonclick=oronload=attributes, nojavascript:URLs. Only the guest script, allowed by its hash, runs inline.<script type="application/ld+json">is data, not code, and is not affected.External scripts must be same-origin. Third-party CDNs (analytics, widgets) are blocked, so vendor a library into the template's
public/folder and load it with<script src="/_assets/<id>/lib.js" defer>. A template script runs on the editor's origin and can reach its write token: ship only code you have reviewed.Images, fonts and stylesheets are same-origin too (
default-src 'self'). Ship fonts in the template'spublic/directory rather than loading Google Fonts. Nodata:images.No
<object>or<embed>, no<base>to another origin, and forms post only to the site itself.Cloudflare features that inject scripts (Web Analytics auto-inject, Rocket Loader, Zaraz) are blocked by the policy. Leave them off.
To allow more, say a font CDN, the site owner must change the policy in both places: the header rule and the compiler. There is no per-template switch, on purpose.
Fonts and images
Ship fonts, images, scripts and stylesheets in packages/templates/<id>/public/. Deploy uploads them to _assets/<id>/<path>, and the layout references them as /_assets/<id>/fonts/a.woff2. Do not load a font or library from a CDN: the policy blocks it. Accepted types are woff2, webp, avif, png, jpg, jpeg, ico, js, mjs and css.
Images and links in content
All content strings (alt, caption, attribution, titles, bodies, icons, ids) are escaped by the renderers.
Images (an Image block, and images inside rich text) must match exactly
/gallery/{folder}/{hash}.{ext}, with a folder of[a-z0-9-]{1,64}, a hash of[a-f0-9]{16}and an extension ofwebp,jpgorpng. The path is at most 512 characters, with no%anywhere. Anything else is removed from rich text, or gives the empty figure.Rich text JSON is sanitised before rendering: only known nodes, marks and attributes survive, and unknown types are dropped.
Links keep only
http:,https:(with no username or password, sohttps://[email protected]/is dropped),mailto:,/site-relative,#fragmentor?queryhrefs, up to 2048 characters. Otherwise the link is removed and the text kept. Links always getrel="noopener", andtargetis only ever_blank.