HOC SiteDocumentation

The design model

Pages, chrome, page components, and email chrome are design documents made of blocks. Saves create revisions; publishing and caching decide when visitors see them.

Design documents

There are four kinds of design document:

  • Page — a routed page, static or bound to an object type.
  • Page component — a reusable block tree embedded by pages.
  • Chrome — the site header and footer.
  • Email chrome — the header and footer of email templates.

A document is a block tree. Every block has an id, a type, and props. Blocks carry a shell group for decoration and visibility (background, border, spacing, breakpoints) that is documented once in Decoration and visibility.

Reading and writing

Reads default to a compact summary and offer a full tree, a single subtree, or a translation-gap view. Writes are either a sparse merge by block id or a full replace. Ops let you set, reset, insert, remove, and move without resending the whole tree.

A saved block without an id receives one. Block arrays match by id, so unlisted blocks survive a merge.

Revisions

Every save appends a revision. You can list revisions, read one, compare publish status, and restore a previous revision. Restoring writes a new revision rather than rewinding history, so nothing is lost.

Publishing and cache

Public HTML can serve the previous data-request result for up to about 60 seconds after a save. The save response includes expectedLiveBy. publishStatus answers the narrower question: is this revision the one currently served for this path?

Warnings

Design warnings catch problems before they reach a visitor: unknown block types, unknown button actions, misplaced data requests, missing request names, unmapped form fields, translation gaps, props that belong to another block type, and a flex list left at its implicit row default.