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.

  • width and height are emitted only when they are positive integers.

  • An invalid src renders <figure><!-- invalid image src --></figure>.

  • A block with align set to left or right gets one more class on the section, pg-image--left or pg-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 other align value 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-lightbox per item, in item order. All lightboxes follow the <ul>.

  • The thumbnail shows the item's thumb when it is a valid gallery path, otherwise its src. It has no width or height, so the template sizes the grid cells. The lightbox image always uses src, with width and height when they are positive integers.

  • The first item has no pg-lightbox-prev link and the last has no pg-lightbox-next.

  • The three links have no text. Their aria-label values are fixed English words, because the renderer does not know the site language.

  • An item whose src is 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 no id attributes, 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>
  • src must be an https://www.google.com/maps/embed?… URL: https, exactly that host, no port, no credentials, exactly that path, and at most 2048 characters. It is the src of the iframe code Google Maps gives under Share, Embed a map. Any other value, including the empty src of a new block, renders <!-- invalid map src --> inside the section and no iframe.

  • title is the accessible name of the frame. It may be empty.

  • The iframe has no width, height or style, 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.com only. 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 its title, 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.

  • excerpt adds <div class="pg-post-body"> with the first two paragraphs of the post's rich text; full adds 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

pg-block

Every block section

pg-block--richtext

A rich text block

pg-block--image

An image block

pg-image--left, pg-image--right

An image block with align set; the template decides what the alignment looks like

pg-block--list

A content list block

pg-block--gallery

A gallery block

pg-block--folder-gallery

A folder gallery block (it also has pg-block--gallery)

pg-block--map

A map block; size its <iframe>

pg-list--faq

A content list shown as questions and answers, as <details> elements

pg-list--features

A content list shown as a grid of items

pg-list--cards

A content list shown as a grid of items; also the fallback for an unknown variant

pg-list--news

A content list shown as dated <article> elements

pg-news-older

The <details> holding the sixth and later items of a news list

pg-grid

The <ul> of a features or cards list

pg-icon

The icon span of a list item; left out when the item has no icon

pg-gallery

The <ul> of thumbnails in a gallery block

pg-lightbox

The full-size view of one gallery photo; hide it and show it on :target

pg-lightbox-close, pg-lightbox-prev, pg-lightbox-next

The empty links inside a lightbox

pg-attribution

The attribution span inside an image caption

pg-badge

The attribution anchor that the badge fragment outputs on the free tier

pg-richtext-error

The placeholder paragraph shown when a rich text block cannot be rendered

pg-block--posts, pg-posts--dek, pg-posts--excerpt, pg-posts--full

A post list block and the template's display

pg-post, pg-dek, pg-post-body

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 has more than 500 items

Nav depth

3 levels (root items are level 1); deeper fails with nav deeper than 3 levels

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.