Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,11 @@
- `updated` and `categories` are now keys the build owns: a layout's schema that declares either must rename it.
- `childLayout` and `view` are keys the build owns too, so the same holds for them.

### Deprecated

- `site.collections`. It keeps working, and a skin whose `partials/base` lists it gets one warning per build, naming
the query to declare instead (`x-pd-query` on a sub-key of `page`). It goes in a later release.

### Added

- `childLayout:` on a folder's `index.md`: the layout of the pages under it that name none. The nearest folder that
Expand All @@ -37,14 +42,28 @@
pages as `entries`, and names its card, so each view's required fields are checked on their own. A view that
doesn't exist, a listing that names none and a view on a page with no listing are problems.
- The website starter (`pd init --storefront`) ships four plain views with their cards: `list`, `grid`, `featured`
and `compact`. Its articles listing uses `view: list`.
and `compact`.
- `updated:` on a storefront page, its last real change: `page.updated`, JSON-LD `dateModified`,
`article:modified_time` on an article, and the sitemap's `lastmod`. Checked: a real date, not before `date`.
- Categories, independent of folders: `storefront.categories` declares them (key, label, optional description, and
old keys as `aliases` after a rename), a page names them in `categories:`. An undeclared value fails the page with
a "did you mean"; an old key builds as the new category, with a warning naming the page. Layouts get
`page.categories`, listing entries carry them, and `site.categories` lists every one when `partials/base` lists it.
- Listing entries carry `updated`, `categories` and `scheduled` (true in `pd dev` for a page dated after today).
- Queries: one way to list pages anywhere but a folder's own listing, such as related pages and a home page's latest
articles. A layout declares one as a sub-key of `page` with `x-pd-query` and its defaults: hand-picked `pages`
first, then the pages of `collections` (or `same`, the page's own folder) matching `categories` and `tags`
(`match`: any or all), by `sort` (relevance, date or title) and `order`, to `limit`, through a `view`. The layout
gets `{ entries, listing }`. A page changes options in a block under the query's name, with the same option names (`related:` with
`limit: 5` indented under it), or turns the
query off with `<name>: false`. The current page, drafts and scheduled pages never appear, and a page never comes
twice. Every value is checked, at the page's line or in the layout, with a "did you mean" where it fits.
- A page's frontmatter takes one level of keys indented under a key, for a query's options. Under any other key, and
any deeper, it is a problem with its line, as before.
- A layout's default view for its listing: `x-pd-view` on `page.listing`. An `index.md`'s `view:` wins.
- The website starter has an article layout, which its articles take from their folder, listing three related
articles in the compact view, and a home layout listing the three newest articles in the list view. Its listing
layout shows the list view by default, so `articles/index.md` names no view.
- Shell code is highlighted: `bash`, `sh`, `shell` and `zsh`, and `console` or `shell-session` for a prompt with its
output. `text` stays plain.

Expand Down
82 changes: 77 additions & 5 deletions docs/guide/storefront.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,10 +227,12 @@ page fails when:
- it sets a key the layout does not declare (with a suggestion for a likely typo)
- a value does not have its declared type. Values are text, read as numbers or booleans only where the
schema declares `number`, `integer` or `boolean`
- the frontmatter cannot be read: a line that is not `key: value` or a list item, a nested value, a
duplicate key, an unclosed block or quote
- the frontmatter cannot be read: a line that is not `key: value` or a list item, a value nested deeper
than one level, a duplicate key, an unclosed block or quote
- keys indented under a key that is not one of the layout's [queries](#queries)

Frontmatter is a small fixed grammar, not full YAML: one level of `key: value` pairs and lists.
Frontmatter is a small fixed grammar, not full YAML: `key: value` pairs and lists, and, for a query's options only,
one level of keys indented under a key.

### A folder's default layout

Expand Down Expand Up @@ -499,7 +501,9 @@ With `sort: date`, a page with no date at all (no `date` and no commit, such as
`pd build` and a note in `pd dev`, where it is listed last. From a shallow clone, a date git would give is
refused by `pd build`, as for `page.created`.

**On any page.** `partials/base`'s schema lists the collections the skin shows under
**On any page (deprecated).** Use a [query](#queries) instead: it lists pages on any page, with a limit and a
view. `site.collections` keeps working for now, and a skin that lists it gets one warning per build.
`partials/base`'s schema lists the collections the skin shows under
`site.properties.collections.properties`, by the folder's path (`articles`, or `blog/news` for a nested folder,
read as `site.collections.[blog/news]`), each with a description at most, as it lists navigations. Every page
gets `site.collections.<name>`: the folder's entries, sorted as above. A listed name the site has no folder for is
Expand Down Expand Up @@ -542,8 +546,10 @@ them like any component.

So views are separate components with cards of their own, not variants of one card: a grid's card can require an
image while a list's doesn't.
- **A default view.** The layout can name the view its listings take when the `index.md` names none, with
`x-pd-view` on `page.listing`: `"listing": { "x-pd-view": "list" }`. The `index.md`'s `view:` wins.
- **Checked:** a view that doesn't exist fails the page with the views there are (and a "did you mean"); a listing
page whose layout shows `page.listing` must name its view; a `view:` on a page whose layout shows no listing, or on
page whose layout shows `page.listing` must name its view, unless the layout names a default; a `view:` on a page whose layout shows no listing, or on
a page that is not a folder's `index.md`, is a problem; a view whose schema names no card is a problem.
- **Sample data:** a view's may set only `entries`, each an entry; its card's only an entry's fields.
- **Styles and scripts** of the view and its card load on the page as those of a placed component do.
Expand All @@ -552,6 +558,72 @@ The starter (`pd init --storefront`) ships four plain views, each with its card
date, teaser and tags), `grid` (cards with an image; every page needs one), `featured` (the first page large, the
rest as the grid: with `sort: date`, the newest first) and `compact` (title and date only).

### Queries

Every list of pages that isn't a folder's own listing is a query: related pages under an article, the latest
articles on the home page. A layout declares it as a sub-key of `page`, with `x-pd-query` and its defaults:

```json
"page": { "properties": {
"related": { "x-pd-query": { "collections": "same", "sort": "relevance", "limit": 3, "view": "compact" } }
} }
```

The layout gets `page.related` as `{ entries, listing }`: the pages, each an entry (the table above), and the same
rendered through the query's view, as HTML. `listing` is `null` without a view, or when no page matched, so
`{{#if page.related.listing}}` leaves out an empty section:

```hbs
{{#if page.related.listing}}<section><h2>Related articles</h2>{{{page.related.listing}}}</section>{{/if}}
```

A layout that writes its own markup loops over `page.related.entries`, and can name a card for them with
`x-pd-card` on the query's `entries` (`"properties": { "entries": { "x-pd-card": "components/card" } }`), so each
page is checked against it. A query's name is letters and digits, starting with a lowercase letter, and is none of
the sub-keys Pattern Dump fills.

| Option | Value | Default |
|---|---|---|
| `pages` | Pages picked by hand, by their path in the pages folder (`articles/a.md`): listed first, in this order | none |
| `collections` | Folders' paths (`articles`, `blog/news`), or `same` for the page's own folder | every folder |
| `categories` | Declared categories (an old key works, with a warning) | none |
| `tags` | Tags | none |
| `match` | `any`: a page needs one of the listed tags, and one of the categories; `all`: every one | `any` |
| `sort` | `relevance` (the number of tags and categories a page shares with the current one, then the date), `date` or `title` | `date` |
| `order` | `asc` or `desc`; not with `relevance`, which always lists the most relevant first | newest first; A to Z |
| `limit` | How many pages in all, picked ones included: a whole number from 1 | no limit |
| `view` | A view (`views/<name>`), as for a listing | none |

With both `tags` and `categories`, a page must match both. A page with no date sorts last. Always: the current page
is left out, a page never comes twice (a picked page isn't repeated), and drafts and scheduled pages never appear,
in `pd dev` either.

**A page changes options** in its frontmatter, in a block under the query's name, with the same option names:

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

Each option given replaces that one of the layout's; the rest stay. `related: false` turns the query off for that
page, and `related: true` keeps the layout's as it is. The key is the build's: the layout never gets it. It is the
one place a page's frontmatter nests: one level of keys under a key, each a value or a list.

**Every value is checked**, at the page's line or in the layout's schema: an option there isn't, a picked page that
doesn't exist (with a "did you mean"), a folder that isn't one, a category that isn't declared, a tag no page has, an
unknown `sort`, `match` or `order`, `order` with `relevance`, a `limit` that isn't a whole number from 1, more picked
pages than the limit, a page picked twice, and a view that isn't one; every page is checked against the view's card.
A picked draft or scheduled page fails `pd build`; in `pd dev` it is a warning, and left out.

In `pd dev`, an edit to what a query reads of a page (its date, tags, categories, title or draft) reloads every open
page, as for a listing.

The starter (`pd init --storefront`) shows both: the article layout's `related` (three, from the same folder, by
relevance, in the compact view) and the home layout's `latest` (the three newest articles, in the list view).

### Categories

Categories say what a page is about, apart from the folder it is in: a page changes category without moving, so
Expand Down
16 changes: 12 additions & 4 deletions packages/cli/src/init/starter.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ describe("the starter project with a website (--storefront, no examples)", () =>
expect(graph.occurrences).toEqual([]);
expect(graph.components.map(c => [c.id, c.render]).sort()).toEqual(
[["components/compact-card", "ok"], ["components/feature-card", "ok"], ["components/grid-card", "ok"], ["components/listing-card", "ok"], ["components/note", "ok"],
["layouts/listing", "ok"], ["layouts/page", "ok"], ["partials/base", "ok"], ["partials/head", "ok"],
["layouts/article", "ok"], ["layouts/home", "ok"], ["layouts/listing", "ok"], ["layouts/page", "ok"], ["partials/base", "ok"], ["partials/head", "ok"],
["views/compact", "ok"], ["views/featured", "ok"], ["views/grid", "ok"], ["views/list", "ok"]]);
}, 120_000);

Expand All @@ -189,17 +189,24 @@ describe("the starter project with a website (--storefront, no examples)", () =>
expect(home.body).toContain(`<aside class="note note-tip" role="note">`);
expect(home.body).toContain(`<iframe src="/preview/components/note"`);
expect(home.body).toContain(`<a rel="next" href="/about/">Next: About</a>`);
// The latest articles: a query of the home layout (articles, newest first, three), in the list view.
expect(home.body).toMatch(/<h2 id="home-latest-title">Latest articles<\/h2>\s*<ul class="view-list" role="list">\s*<li>\s*<article class="listing-card">\s*<h2 class="listing-card-title"><a href="\/articles\/related\/">Related articles<\/a><\/h2>/);
expect([...home.body.matchAll(/<h2 class="listing-card-title"><a href="([^"]+)"/g)].map(m => m[1])).toEqual(["/articles/related/", "/articles/hello/"]);
expect((await onHost(server.port, "live.localhost", "/about/")).status).toBe(200);
// The articles collection: its listing names the example article with its date, and the article shows its tags.
const articles = await onHost(server.port, "live.localhost", "/articles/");
expect(articles.status).toBe(200);
// Shown through the list view its index.md names: one listing card per page, and the view's and card's styles.
expect(articles.body).toMatch(/<ul class="view-list" role="list">\s*<li>\s*<article class="listing-card">\s*<h2 class="listing-card-title"><a href="\/articles\/hello\/">Hello, articles<\/a><\/h2>\s*<p class="listing-card-date"><time datetime="2026-11-14">/);
expect(articles.body).toMatch(/<ul class="view-list" role="list">\s*<li>\s*<article class="listing-card">\s*<h2 class="listing-card-title"><a href="\/articles\/related\/">Related articles<\/a><\/h2>\s*<p class="listing-card-date"><time datetime="2026-11-15">/);
expect(articles.body).toContain(`<a href="/articles/hello/">Hello, articles</a></h2>\n <p class="listing-card-date"><time datetime="2026-11-14">`);
expect(articles.body).toContain(`href="${componentCssUrl("views/list").replace(/\.css$/, "")}`);
expect(articles.body).toContain(`href="${componentCssUrl("components/listing-card").replace(/\.css$/, "")}`);
const hello = await onHost(server.port, "live.localhost", "/articles/hello/");
expect(hello.status).toBe(200);
expect(hello.body).toContain(`<ul class="page-tags" aria-label="Tags"><li>getting-started</li><li>notes</li></ul>`);
// Its related articles: the article layout's query (the same folder, by relevance, three), in the compact view.
expect(hello.body).toMatch(/<h2 id="article-related-title">Related articles<\/h2>\s*<ul class="view-compact" role="list">\s*<li><p class="compact-card"><a href="\/articles\/related\/">Related articles<\/a> <time class="compact-card-date" datetime="2026-11-15">/);
expect(hello.body).toContain(`href="${componentCssUrl("views/compact").replace(/\.css$/, "")}`);
const missing = await onHost(server.port, "live.localhost", "/no-such-page/");
expect(missing.status).toBe(404);
expect(missing.body).toContain("Page not found");
Expand All @@ -215,7 +222,7 @@ describe("the starter project with a website (--storefront, no examples)", () =>
const config = await loadConfig(siteDir);
const server = await startDevServer(config, siteDir, { port: 0, wsPort: 0 });
try {
for (const id of ["views/list", "views/grid", "views/featured", "views/compact", "components/listing-card", "components/grid-card", "components/feature-card", "components/compact-card"]) {
for (const id of ["layouts/article", "layouts/home", "views/list", "views/grid", "views/featured", "views/compact", "components/listing-card", "components/grid-card", "components/feature-card", "components/compact-card"]) {
const d = await (await fetch(`http://127.0.0.1:${server.port}/api/component/${id}`)).json() as ComponentDetailResponse;
expect(d.diagnostics, id).toEqual([]);
expect(d.doc, id).toBeTruthy();
Expand All @@ -231,10 +238,11 @@ describe("the starter project with a website (--storefront, no examples)", () =>
const config = await loadConfig(siteDir);
const server = await startDevServer(config, siteDir, { port: 0, wsPort: 0 });
try {
await save(index, before.replace("view: list", "view: grid"));
await save(index, before.replace("layout: listing\n", "layout: listing\nview: grid\n"));
const page = await onHost(server.port, "live.localhost", "/articles/");
expect(page.status).toBe(500);
expect(page.body).toContain(`articles/index.md: articles/hello.md has no image, which the card of view "grid" (components/grid-card) requires`);
expect(page.body).toContain(`articles/index.md: articles/related.md has no image, which the card of view "grid" (components/grid-card) requires`);
} finally {
await save(index, before);
await server.close();
Expand Down
10 changes: 7 additions & 3 deletions packages/cli/templates/storefront-fills/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,17 +25,21 @@ returns by itself. How `pd-` tags work:
|---|---|
| `pages/` | the pages, in markdown (`pages/` is the website; `src/patterns/pages/`, if you have it, holds page-sized components) |
| `src/patterns/layouts/page/` | the layout every page renders with; its schema is what a page's frontmatter may set |
| `src/patterns/layouts/home/`, `layouts/article/` | the home page's layout, with the latest articles, and an article's, with its related articles |
| `src/patterns/partials/base/` | the frame around every page: header, navigation, footer |
| `src/patterns/partials/head/` | what the skin adds to every page's `<head>` (the icon) |
| `src/patterns/components/note/` | the component the home page shows |
| `src/patterns/views/` | the ways a listing can be shown: `list`, `grid`, `featured`, `compact` |
| `src/patterns/components/*-card/` | the card each view shows a page as; its schema says which fields a page needs |
| `pattern-dump.config.ts` | `storefront`: the website's name and footer (`site`), and where it is published |

`pages/articles/` is a collection: its `index.md` (layout `listing`, `view: list`, `sort: date`) lists every page
in the folder, newest first, by its `date`. Copy `hello.md` to write another; `draft: true` keeps one out of the
`pages/articles/` is a collection: its `index.md` (layout `listing`, `sort: date`) lists every page in the folder,
newest first, by its `date`, in the listing layout's default view (`list`). Copy `hello.md` to write another; `draft: true` keeps one out of the
build. Each page is checked against the view's card: switch to `view: grid` and the listing names every article
without an `image:`. `childLayout: <layout>` on a folder's `index.md` gives its pages a layout of their own.
without an `image:`. `childLayout: article` on its `index.md` gives its pages the article layout, which lists each article's related
articles; the home page lists the latest ones. Both are queries, declared in the layout's schema (`x-pd-query`)
and changed per page under the query's name (`related:`, with `limit: 5` indented under it), or turned off with
`related: false`.

A page that doesn't exist shows a built-in 404 page; write `pages/404.md` to change it. A page that moved
can forward from its old address (`redirectFrom: [/old/]`), and `index: false` keeps a page out of search
Expand Down
4 changes: 3 additions & 1 deletion packages/cli/templates/storefront/pages/about.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ order: 1
The pages are in `pages/`. What they look like is the skin, written as ordinary components so the
workbench shows each part of it:

- `src/patterns/layouts/page`: the layout every page renders with
- `src/patterns/layouts/page`: the layout every page renders with, unless it names another
- `src/patterns/layouts/home` and `src/patterns/layouts/article`: the home page's, with the latest articles, and an
article's, with its related articles
- `src/patterns/partials/base`: the frame around it, with the header, navigation and footer
- `src/patterns/partials/head`: what the skin adds to every page's `<head>`
- `src/patterns/components/note`: a component the pages show
Expand Down
6 changes: 4 additions & 2 deletions packages/cli/templates/storefront/pages/articles/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,12 @@
title: Articles
description: Everything written here, newest first.
layout: listing
view: list
childLayout: article
sort: date
order: 2
---

This page is `pages/articles/index.md`. Every page in this folder is listed below, newest first, in the list view
(`view: list`). Add a markdown file with a `date` and it shows up here, with no link to write.
(the listing layout's default; `view: grid` here would change it). Add a markdown file with a `date` and it shows up
here, with no link to write. Each article takes the article layout (`childLayout: article`), which lists its related
articles.
Loading
Loading