Skip to content

feat(storefront): queries for lists of pages (related pages, latest articles) - #65

Merged
StfBauer merged 6 commits into
mainfrom
feat/query
Nov 15, 2026
Merged

StfBauer merged 6 commits into
mainfrom
feat/query

Conversation

@StfBauer

Copy link
Copy Markdown
Contributor

One mechanism for every list of pages that isn't a folder's own listing: related pages under an article, the latest
articles on the home page, and later tag and category pages.

What it does

  • A layout declares a query as a sub-key of page with x-pd-query and its defaults:
    "related": { "x-pd-query": { "collections": "same", "sort": "relevance", "limit": 3, "view": "compact" } }.
    The layout gets page.related as { entries, listing }: the pages in the entry shape, and the same through the
    view as HTML (null without a view, or when no page matched).

  • Options: pages (hand-picked, first), collections (folder paths, or same), categories, tags,
    match (any or all), sort (relevance, date, title), order (asc, desc; not with relevance), limit, view.

  • A page overrides options in a block under the query's name, with the same option names:

    related:
      pages: [articles/tokens-explained.md]
      tags: [css]
      limit: 5

    related: false turns it off. For this, page frontmatter reads one level of keys under a key; anywhere else a
    block is a problem with its line.

  • Always: the current page is left out, a page never comes twice, drafts and scheduled pages never appear. A
    picked draft or scheduled page fails pd build (a warning in pd dev).

  • Every value is checked, at the page's line or in the layout, with a "did you mean" where it fits; each page is
    checked against the view's card.

  • A layout's default view for its listing: x-pd-view on page.listing; the index.md's view: wins.

  • site.collections is deprecated: unchanged, plus one warning per build naming the query to declare.

  • Starter: an article layout with three related articles (compact view) and a home layout with the three newest
    articles (list view); the listing layout defaults to the list view.

  • Bench: a compact view and card; related pages on the article and doc layouts, the home page's latest as a
    query. storefront-query.spec.ts covers every option and every failing value; e2e/query.spec.ts covers the
    rendered result in pd dev and on the built site.

Checks

Gates on Node 24 green: E2E 354 / 190 / 155 / 7. The workbench snapshot golden is unchanged (344 files).

…rticles)

A layout names a query as a sub-key of page with x-pd-query and its
defaults; a page overrides one option with <name>-<option>, or turns it
off with <name>: false. Hand-picked pages first, then the pages of the
collections that match the categories and tags, sorted by relevance,
date or title, to the limit. Every value is checked. site.collections
keeps working, with a deprecation warning.

The bench lists related pages on its article and doc layouts through a
compact view, and its home page's latest articles come from a query.
…ries

An article layout (childLayout of articles/) lists three related
articles in the compact view; a home layout lists the three newest in
the list view. The listing layout shows the list view by default.
…name

related: with the option names of x-pd-query indented under it replaces
the flat related-<option> keys. Each option given replaces the layout's,
the rest stay; related: false turns it off, true keeps the default.

For it, frontmatter reads one level of keys under a key: values and
lists, kept apart from the plain values, each line named with its parent
(related.limit). Deeper nesting, a stray list item and a duplicate key
in a block are errors with their line; a block under any key but one of
the layout's queries is a problem.
@StfBauer
StfBauer merged commit bed9a96 into main Nov 15, 2026
9 of 18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant