Site header

PageList

PageList

Documentation

Generates cards from existing page documents in the site manifest. PageList is a page-aware convenience primitive. It selects real QP pages, adapts their page content and metadata into cards, and renders the resulting cards through CardList. Pages can be selected in one of two ways: - Path discovery: omit pages and use path to select pages beneath a site path. When path is omitted, the current page path is used. By default only direct children are included; set recursive to include all descendants. - Explicit selection: provide pages to select specific page documents and control their order. When pages is present, path discovery is not used. Each selected PageDocument remains the source of truth. PageList selects and adapts those pages into normal CardList and Card structures, then delegates final rendering to those existing primitives rather than owning parallel card markup. PageCard represents an explicit page selection and any selection-local configuration it owns. Each selected page's pageListItemSettings may provide page-owned presentation settings such as image, subtitle, description, badge, and CTA text without changing the page's normal presentation.

Kind

Built Content

Required fields

type

Style Guide

PageList

Used by

Element

Authoring guidance

Use when

Use when cards represent existing QP page documents, especially for indexes, landing pages, related-page collections, or navigation derived from the site's page structure. Prefer PageList when the page documents should remain the source of truth.

Avoid when

Use card-list when cards are independent content rather than representations of existing pages, or when their content should be authored directly in the current document.

Properties

class

string

Optional styling hook.

columns

number

Requested number of card-grid columns. Valid values are integers from 1 through 4; defaults to 3.

ctaText

string

List-wide CTA label for generated page cards. Individual page references may override it with their own CTA text.

detail

object

Adds a metadata detail row to each generated card by resolving the specified field from that card's page document.

class — string

Optional styling hook.

field — string [REQUIRED]

Dot/path reference to a value in the source page document.

format — enum

Optional canonical formatting applied to the resolved scalar value.

"date" | "number" | "currency"

icon — Icon

Optional icon displayed with the detail value.

limit

number

Maximum number of successfully generated cards. Invalid or non-positive values are ignored.

pageImageStyle

enum

Image treatment applied to every generated page card.

"default" | "full-bleed" | "inset"

pages

PageCard[]

Explicit page references rendered in the authored order. When provided, explicit selection replaces path-based discovery.

path

string

Base site path used for automatic page discovery. Defaults to the current page path when omitted. Ignored when pages is provided.

recursive

boolean

Controls path-based discovery. False/omitted selects only direct children of path. True includes all descendant pages. Has no effect when pages is provided.

*

type

string

Identifies the Element type represented by this object.

"page-list"

Example

Required

{ "type": "page-list" }

Full

{ "class": "example", "columns": 3, "ctaText": "example", "detail": { "class": "example", "field": "meta.publishDate", "format": "date", "icon": { "ariaLabel": "Search", "class": "example", "name": "search" } }, "limit": 6, "pageImageStyle": "default", "pages": [ { "badge": "example", "page": "example" } ], "path": "/stories/", "recursive": true, "type": "page-list" }

examples are generated from the schema.