Anatomy of a page
A page holds sections; each section has a kind, a shell and one Section type, and the Section type holds a head, its items and a preview.
Every page @mdxui/site renders is one JSON record. Read it from the outside in, and each level answers one question: which brand, which bands, which design, which words.
pagetheme, frame, title, description and an ordered list of sections- 1
sectionkind "section", shell { inset "contained", density "section" } - 2
blocktype "feature-split" - 3
headeyebrow, title - 4
itemsexactly 3: icon, title, text - 5
previewspecimen.blocks: one terminal
Harbor tides › home, section 6 · open the render · the record
The page
A Page names its Theme, its frame, a title of 64 characters, a description of 320, and three to twenty sections in order. An optional Template names the kind of page it is, such as api-product or contact. Change theme and every section redraws in the other brand; nothing else in the record moves.
| Field | Type | Req | Bounds | Refusal |
|---|---|---|---|---|
theme | "certificate" | "vaultline" | "quaypoint" | "callboard" | "directory" | yes | — | |
template | "api-product" | "article" | "blog" | "post" | "contact" | "directory-list" | "directory-product" | — | ||
title | string ≤64 | yes | 1–64 | |
description | string ≤320 | yes | 1–320 | |
meta | object | — | ||
meta.canonical | string ≤160 | 1–160 | ||
meta.type | "website" | "article" | — | ||
meta.icon | string ≤160 | 1–160 | ||
meta.iconFallback | string ≤160 | 1–160 | ||
meta.appleTouchIcon | string ≤160 | 1–160 | ||
meta.image | object | — | ||
meta.image.url | string ≤160 | yes | 1–160 | |
meta.image.width | integer 200–2400 | yes | 200–2400 | |
meta.image.height | integer 200–2400 | yes | 200–2400 | |
meta.noindex | boolean | — | ||
jsonLd | 0–4 × object | ≤4 | ||
frame | "none" | "sheet" | "split" | yes | — | |
sections | 3–20 × object | yes | 3–20 |
The section
A section is three fields. kind says what the band is to the page: nav, hero, band, section, article, closing or footer, or bar for the slim bar of an inner page. The kind decides the landmark the band lands in and the divider the Theme draws beside it.
shell paints and paces the band: its inset and density, and optionally its surface, background, sticky and aside. block is the Section type itself, named by type.
| Field | Type | Req | Bounds | Refusal |
|---|---|---|---|---|
kind | "nav" | "bar" | "hero" | "band" | "section" | "article" | "closing" | "footer" | yes | — | |
shell | object | yes | — | |
shell.id | string (pattern) | — | ||
shell.inset | "contained" | "bleed" | "article" | "listing" | yes | — | |
shell.density | "none" | "section" | "compact" | "hero" | "closing" | "footer" | "access" | "article" | "listing" | yes | — | |
shell.surface | "paper" | "tint" | "plate" | "glass" | — | ||
shell.background | "none" | "dots" | "grain" | "glow" | — | ||
shell.sticky | boolean | — | ||
shell.aside | boolean | — |
The Section type
Inside the block, most Section types share three parts. The head is an eyebrow, a title and a lede. The items are the list the type was drawn for, at the counts it was drawn at. The preview is a slot, specimen in the record, that holds one to three other Section types, so a page nests a code window inside a feature split without holding markup.
Each field has a maximum, and every list a designed count. A record past either is refused at its path; see Why the design holds.
What a record never holds
No markup, no class names, no colors, no sizes and no fonts. The Theme supplies every one of those, so an agent that writes the record writes words and choices only. The Section types show each design the words fill.