A persisted Quail Pages page document.
Page documents define the content and metadata for individual pages in a Quail Pages site. They are conventionally stored beneath the site's pages/ directory. Each SiteDocument.pages[].source is relative to that directory.
A page document's source location does not determine its public URL. SiteDocument.pages[].path explicitly maps each authored page source to its public URL, allowing source organization and website routing to remain independent.
Authoring guidance
✅
Use when
Use as the root of an authored page JSON file beneath pages/.
❌
Avoid when
Defining site-wide configuration or reusable content; use a
SiteDocument or Component instead.
Properties
string
Optional styling hook.
string
Summary used by search, social, and structured metadata.
min length: 70 · max length: 155
Recommended: Supply a useful description between 70 and 155 characters
for indexable production pages.
string
Stable document, section, or region identifier.
object
Metadata used by discovery and derived artifacts.
author — string
Author display name and optional key into the site's authors definitions. If no matching site author exists, this value is still used as the author name.
location — string
Location where the page's subject or event occurred.
noIndex — boolean
Excludes the page from indexing-oriented output and listings by default.
noRss — boolean
Excludes the page from RSS output.
publishDate — string
Date the page was originally published.
socialImage — Image
Explicit image for social and Open Graph metadata. When omitted, QP derives the image from the page Hero, the first eligible authored content image, or the site's publisher logo.
updateDate — string
Date of the most recent meaningful content update.
Visible page heading presentation.
Page-owned presentation settings used when this page appears in PageList.
These values are used only when this page is represented as a generated card by PageList. They allow the card representation to differ from the page's normal title, description, hero, and other page presentation without changing the page itself.
string
Browser and metadata title for the page.
Used as the canonical page title for browser, search, social, and structured metadata. Visible heading presentation is owned separately by pageHeader.
Recommended: Supply a focused title for indexable production pages.
Sections forming the page body.
string
Page classification used for routing, metadata, and page-aware integrations.
Example
Required
{
"id": "example",
"pageHeader": {
"title": "Birding in Utah"
},
"pageTitle": "Example Page",
"sections": []
}
Full
{
"class": "example",
"description": "A representative Quail Pages example used to demonstrate this authored JSON contract in generated documentation.",
"id": "example",
"meta": {
"author": "example",
"location": "example",
"noIndex": false,
"noRss": false,
"publishDate": "example",
"socialImage": {
"alt": "The Acme team working together",
"aspectRatio": "16:9",
"badge": "example",
"caption": {
"credit": "example",
"subtitle": "example",
"title": "Example"
},
"centerOffset": {
"x": 50,
"y": 40
},
"class": "example",
"fetchPriority": "high",
"lightbox": false,
"link": {
"href": "/example",
"newTab": false,
"nofollow": false,
"sponsored": false
},
"loading": "lazy",
"maxWidth": 0,
"src": "/images/team.jpg",
"width": 0
},
"updateDate": "example"
},
"pageHeader": {
"hero": {
"alt": "Birds above a Utah wetland",
"aspectRatio": "example",
"badge": "example",
"caption": {
"credit": "example",
"subtitle": "example",
"title": "Example"
},
"centerOffset": {
"x": 0,
"y": 0
},
"class": "example",
"fetchPriority": "high",
"lightbox": false,
"link": {
"href": "/example",
"newTab": false,
"nofollow": false,
"sponsored": false
},
"loading": "lazy",
"maxWidth": 0,
"src": "/images/utah-birds.jpg",
"width": 0
},
"subtitle": "Field notes and practical guides",
"title": "Birding in Utah"
},
"pageListItemSettings": {
"badge": "example",
"ctaText": "example",
"description": "A representative Quail Pages example used to demonstrate this authored JSON contract in generated documentation.",
"image": {
"alt": "The Acme team working together",
"aspectRatio": "16:9",
"badge": "example",
"caption": {
"credit": "example",
"subtitle": "example",
"title": "Example"
},
"centerOffset": {
"x": 50,
"y": 40
},
"class": "example",
"fetchPriority": "high",
"lightbox": false,
"link": {
"href": "/example",
"newTab": false,
"nofollow": false,
"sponsored": false
},
"loading": "lazy",
"maxWidth": 0,
"src": "/images/team.jpg",
"width": 0
},
"subtitle": "example"
},
"pageTitle": "Example Page",
"sections": [
{
"appearance": "default",
"class": "example",
"elements": [
{
"cardClass": "example",
"cards": [
{
"title": "Getting Started",
"elements": [
{
"type": "paragraph",
"text": "Learn the basics of birding."
}
]
},
{
"title": "Field Skills",
"elements": [
{
"type": "paragraph",
"text": "Practice identifying birds outdoors."
}
]
}
],
"class": "example",
"columns": 2,
"type": "card-list"
}
],
"id": "example",
"subtitle": "example",
"title": "Example",
"titleSrOnly": false,
"type": "section",
"width": "default"
}
],
"type": "example"
}
examples are generated from the schema.
