Block markup
The HTML each block type produces, so you know what your stylesheet has to cover.
Every block
The block renderers in @piglet/core emit the markup on this page. The editor's live preview and the published site share it, and the editor overlay relies on the data-piglet-* attributes, so treat it as a contract. Output is compact, with no whitespace between tags, and blocks are joined with a newline.
Every block is a <section> with the classes pg-block pg-block--{kind} plus:
data-piglet-block="{block id}"(attribute-escaped)data-piglet-type="RichText | Image | SimpleContentList | Gallery | Map"
Rich text
<section class="pg-block pg-block--richtext" data-piglet-block="r1" data-piglet-type="RichText"><p>…</p></section>The inner HTML is a static render of the ProseMirror document, using the shared richTextExtensions (StarterKit, tables, image). If rendering fails you get <p class="pg-richtext-error">[unrenderable content]</p>. That placeholder appears only when the renderer throws. Tables, rows, lists and blockquotes with no valid content are dropped entirely.
Image
<section class="pg-block pg-block--image" data-piglet-block="i1" data-piglet-type="Image"><figure><img src="/gallery/f/h.webp" alt="…" width="800" height="600" loading="lazy" decoding="async"><figcaption>caption<span class="pg-attribution">credit</span></figcaption></figure></section><figcaption>appears only if there is a caption or an attribution. The attribution span appears only if one is set.widthandheightare emitted only when they are positive integers.An invalid
srcrenders<figure><!-- invalid image src --></figure>.A block with
alignset toleftorrightgets one more class on the section,pg-image--leftorpg-image--right. The renderer adds only the class. A template that wants text to flow around the image floats it, for example.pg-image--right { float: right; max-width: 40%; margin: 0 0 1em 1.5em; }. Any otheralignvalue is ignored.
Content list
The classes are pg-block pg-block--list pg-list--{faq|features|cards|news}. An unknown variant falls back to cards. There are four variants:
<!-- faq -->
<details><summary>Title</summary><div><p>Body paragraph</p></div></details>
<!-- features / cards -->
<ul class="pg-grid"><li><span class="pg-icon">★</span><h3>Title</h3><p>Body paragraph</p></li></ul>
<!-- news -->
<article><time datetime="2025-10-01">01.10.2025</time><div><h3>Title</h3><p>Body paragraph</p></div></article>
<details class="pg-news-older"><summary>Older</summary><article>…</article></details>body is plain text, and blank lines separate <p> elements. The pg-icon span is omitted when an item has no icon.
In the news variant each item is an <article>, in document order: the renderer does not sort. An item can have a date, a calendar day written YYYY-MM-DD, which is printed as DD.MM.YYYY inside <time>. <time> is left out when the date is missing or is not a real day, and <h3> when the title is empty. The icon is not printed.
The first five items are direct children of the section. The sixth and later ones go inside one <details class="pg-news-older">, which is absent when there are five items or fewer. The summary word Older is fixed, because the renderer does not know the site language. A template can replace it with CSS, for example .pg-news-older summary { font-size: 0; } .pg-news-older summary::before { content: "starsze"; font-size: 1rem; }.
Gallery
A grid of thumbnails and, for each one, a lightbox holding the full image. The markup is shown here with line breaks; the real output has none. {b} is the block id and {i} an item id.
<section class="pg-block pg-block--gallery" id="pg-{b}" data-piglet-block="{b}" data-piglet-type="Gallery">
<ul class="pg-gallery">
<li><a href="#pg-{b}-{i}"><img src="{thumb or src}" alt="…" loading="lazy" decoding="async"></a></li>
</ul>
<div class="pg-lightbox" id="pg-{b}-{i}">
<a class="pg-lightbox-close" href="#pg-{b}" aria-label="Close"></a>
<a class="pg-lightbox-prev" href="#pg-{b}-{previous i}" aria-label="Previous"></a>
<img src="{src}" alt="…" width="800" height="600" loading="lazy" decoding="async">
<a class="pg-lightbox-next" href="#pg-{b}-{next i}" aria-label="Next"></a>
</div>
</section>There is one
<li>and one.pg-lightboxper item, in item order. All lightboxes follow the<ul>.The thumbnail shows the item's
thumbwhen it is a valid gallery path, otherwise itssrc. It has nowidthorheight, so the template sizes the grid cells. The lightbox image always usessrc, withwidthandheightwhen they are positive integers.The first item has no
pg-lightbox-prevlink and the last has nopg-lightbox-next.The three links have no text. Their
aria-labelvalues are fixed English words, because the renderer does not know the site language.An item whose
srcis not a valid gallery path is left out, and its neighbours link to each other.The block id and the item ids are used in element ids and fragment links, so they must match
[A-Za-z0-9_-]+. Ids made by the editor do. If the block id or any remaining item id does not, the block renders plain thumbnails:<li><img …></li>, with noidattributes, no links and no lightboxes.A block with no items renders
<ul class="pg-gallery"></ul>.
There is no script. A lightbox opens when its id is the URL fragment, so the template must hide .pg-lightbox and show it on :target. Without such CSS every full-size image is printed below the grid. The full image is lazy and hidden, so the browser fetches it only when its lightbox opens. A sketch:
.pg-lightbox { display: none; }
.pg-lightbox:target { display: flex; position: fixed; inset: 0; z-index: 1000; background: rgba(0,0,0,.9); align-items: center; justify-content: center; }
.pg-lightbox img { max-width: 92vw; max-height: 92vh; }
.pg-lightbox-close { position: absolute; inset: 0; } /* a click outside the image closes */
.pg-lightbox-prev, .pg-lightbox-next { position: absolute; top: 0; bottom: 0; width: 20%; z-index: 1; }
.pg-lightbox-prev { left: 0; } .pg-lightbox-next { right: 0; }Closing follows the link to #pg-{b}, which scrolls the gallery back into view. Each opened photo adds a history entry, so the browser's back button steps back through them.
Map
A Google Maps embed:
<section class="pg-block pg-block--map" data-piglet-block="m1" data-piglet-type="Map"><iframe src="https://www.google.com/maps/embed?pb=…" title="…" loading="lazy" referrerpolicy="no-referrer"></iframe></section>srcmust be anhttps://www.google.com/maps/embed?…URL: https, exactly that host, no port, no credentials, exactly that path, and at most 2048 characters. It is thesrcof the iframe code Google Maps gives under Share, Embed a map. Any other value, including the emptysrcof a new block, renders<!-- invalid map src -->inside the section and no iframe.titleis the accessible name of the frame. It may be empty.The iframe has no
width,heightorstyle, so it gets the browser default of 300 by 150 pixels with an inset border until the template sizes it, for example.pg-block--map iframe { display: block; width: 100%; height: 400px; border: 0; }.The page Content Security Policy allows frames from
https://www.google.comonly. On a page with a map, Google receives the visitor's IP address and may set cookies inside its frame. No referrer is sent.
Folder gallery
Every photo of one gallery folder, chosen in the editor. The markup is the Gallery block's, with one more class and its own type, so Gallery styles apply:
<section class="pg-block pg-block--gallery pg-block--folder-gallery" id="pg-{b}" data-piglet-block="{b}" data-piglet-type="FolderGallery"><ul class="pg-gallery"><li><a href="#pg-{b}-{hash}"><img …></a></li></ul><div class="pg-lightbox" id="pg-{b}-{hash}">…</div></section>The photos are read when the page is published; the page itself only stores the folder name. They are ordered by upload time, oldest first, at most 200.
Item ids are the image hashes. Alt text is the photo's
alt, else itstitle, else empty.A block without a folder, or an empty folder, renders an empty
<ul class="pg-gallery"></ul>.After an upload, delete or alt-text change, the admin Gallery offers to republish the pages that show the folder.
Post list
The latest published pages, newest first. The block stores how many (1 to 20) and, optionally, a category. The template decides how much of each post shows with postList.display in template.json: dek (the default), excerpt or full.
<section class="pg-block pg-block--posts pg-posts--dek" data-piglet-block="p1" data-piglet-type="PostList"><article class="pg-post"><time datetime="2026-11-14">14.11.2026</time><h3><a href="https://example.com/post/">Title</a></h3><p class="pg-dek">Description</p></article></section>Listed: published pages other than the page itself, the home page, the 404 page and hidden (
noindex) pages. With a category, only pages whose category matches.<p class="pg-dek">is the page description, left out when empty.excerptadds<div class="pg-post-body">with the first two paragraphs of the post's rich text;fulladds all of its rich text and images.Pages with a post list are republished automatically whenever another page is published, unpublished or deleted.
Classes to style
These are the classes your stylesheet should cover:
Class | What it marks |
|---|---|
| Every block section |
| A rich text block |
| An image block |
| An image block with |
| A content list block |
| A gallery block |
| A folder gallery block (it also has |
| A map block; size its |
| A content list shown as questions and answers, as |
| A content list shown as a grid of items |
| A content list shown as a grid of items; also the fallback for an unknown variant |
| A content list shown as dated |
| The |
| The |
| The icon span of a list item; left out when the item has no icon |
| The |
| The full-size view of one gallery photo; hide it and show it on |
| The empty links inside a lightbox |
| The attribution span inside an image caption |
| The attribution anchor that the |
| The placeholder paragraph shown when a rich text block cannot be rendered |
| A post list block and the template's display |
| One listed post, its description and its body |
Limits
The page and site-config schemas cap sizes, so a layout can rely on them. A document over any limit fails validation: the editor refuses to save it, and compilePage throws CompileInputError.
Field | Max |
|---|---|
Page title, site name, page-index title, list item title | 300 characters |
Page and site description | 1000 characters |
Image alt, caption, attribution (blocks, gallery block items, hero, logo, gallery sidecars; also the gallery title) | 1000 characters |
List item body | 10 000 characters |
Map embed link | 2048 characters |
Nav label | 200 characters |
Tags per page | 50, each at most 64 characters (the category too) |
Blocks per page | 200 |
Items per content list, photos per gallery | 200 |
Pages in the site index | 5000 |
Social links | 20 |
Nav items per level | 100 |
Nav items in total, all levels | 500; more fails with |
Nav depth | 3 levels (root items are level 1); deeper fails with |
The compiler also stops at three levels when building nav and breadcrumbs, so a layout that recurses over children never sees a fourth level. Slugs are capped at 200 characters.