Site header

SiteDocument

SiteDocument

Documentation

The persisted root configuration for a Quail Pages site. This document is saved as site.config.json at the root of a complete Quail Pages site source. A complete site source is organized around site.config.json with supporting authored content in sibling directories: - pages/ contains authored PageDocument JSON files. - components/ contains reusable Component JSON files. - assets/ contains static files copied into the generated site's public root. - plugins/ contains site plugin resources and configuration owned by plugins. - themes/{theme-id}/ may contain a private site-local Theme Extension Contract and optional theme resources. A local theme uses the same theme.config.json variable contract and optional style.config.json package identity/display/preload metadata as a shared theme. Shared themes resolve first; a matching local theme is the fallback. QP composes either source with Base through the same compiler. Compiled CSS, copied fonts, and copied theme assets are generated deployment artifacts, not authored theme truth. Source directory names are not necessarily part of their public paths. For example, assets/favicon.svg is published as /favicon.svg. Every page manifest source is relative to pages/; its independent path explicitly maps that PageDocument to a public URL.

Kind

Site

Required fields

pages, theme, title, url

Authoring guidance

Use when

Authoring site.config.json or packaging a complete Quail Pages site source.

Avoid when

Authoring an individual page or reusable component; use a PageDocument or Component instead.

Properties

authors

SiteAuthors

Author profiles keyed by the page-authored display name.

branding

SiteBranding

Browser, installed-app, and publisher-logo presentation.

description

string

Summary used by content or metadata.

footer

SiteFooter

Site footer content.

generatedPages

PageRoute[]

Machine-generated page sources beneath pages/ and their independent public paths. Uses the same manifest contract as pages; the distinction is ownership, not routing or rendering behavior. Generators may replace this collection. Sources remain relative to the site's pages/ directory.

Use when: A generator owns reusable or reference pages that coexist with authored pages.

header

SiteHeader

Site header content.

identity

SiteIdentity

Structured organization and brand identity used by discovery metadata.

imageBaseUrl

string

Optional image-service base URL used to expand site-relative images.

imageDefaults

SiteImageDefaults

Site-wide defaults for authored images.

*

pages

PageRoute[]

Page sources beneath pages/ and their independent public paths.

plugins

SitePlugins

Site-wide plugin configuration keyed by registered plugin ID.

socials

SiteSocials

References site social definitions.

*

theme

string

Theme identifier resolved from shared themes first, then themes/{theme-id}/ within this site source. A site-local theme stays private to its site and is not registered in the public theme catalog.

*

title

string

Visible heading or display name.

*

url

string

Canonical public base URL.

variables

SiteVariables

Values available to inline interpolation.

Example

Required

{ "pages": [], "theme": "example", "title": "Example", "url": "https://example.com" }

Full

{ "authors": { "Jane Smith": { "profileUrl": "/authors/jane-smith/" }, "John Doe": { "profileUrl": "/authors/john-doe/" } }, "branding": { "appleTouchIcon": "example", "appTitle": "example", "faviconIco": "example", "faviconSvg": "example", "manifest": "/site.webmanifest", "publisherLogo": "example", "themeColor": "#0f172a" }, "description": "A representative Quail Pages example used to demonstrate this authored JSON contract in generated documentation.", "footer": { "sections": [ { "id": "footer-navigation", "title": "Footer navigation", "elements": [ { "type": "menu", "class": "qp-menu--footer", "navId": "qp-footer-menu", "ariaLabel": "Footer navigation", "items": [ { "label": "About", "link": { "href": "/about/" } }, { "label": "Privacy", "link": { "href": "/privacy/" } } ] } ] } ] }, "generatedPages": [ { "path": "/", "source": "root/index.json" } ], "header": { "sections": [ { "id": "site-header", "title": "Site header", "titleSrOnly": true, "elements": [ { "type": "image", "src": "/branding/logo.svg", "alt": "Acme Home", "loading": "eager", "fetchPriority": "high", "link": { "href": "/" }, "class": "site-logo" }, { "type": "menu", "navId": "qp-primary-nav", "mobileCollapse": true, "ariaLabel": "Primary navigation", "items": [ { "label": "Home", "link": { "href": "/" } }, { "label": "Pricing", "link": { "href": "/pricing/" } } ] } ] } ] }, "identity": { "brand": { "id": "example", "identifiers": [ { "propertyID": "example", "value": "example" } ], "name": "example" }, "legalName": "example", "name": "example", "organizationId": "example" }, "imageBaseUrl": "https://example.com", "imageDefaults": { "lightbox": true }, "pages": [ { "path": "/", "source": "root/index.json" } ], "plugins": { "events": {}, "featherquest/newsletter": {}, "google-analytics": {} }, "socials": {}, "theme": "example", "title": "Example", "url": "https://example.com", "variables": { "annualPrice": "$290", "contactEmail": "hello@example.com", "monthlyPrice": "$29" } }

examples are generated from the schema.