diff --git a/CHANGELOG.md b/CHANGELOG.md index defa44e..295e88a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 @@ -37,7 +42,7 @@ 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 @@ -45,6 +50,20 @@ 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 `: 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. diff --git a/docs/guide/storefront.md b/docs/guide/storefront.md index 8a33096..c6c4878 100644 --- a/docs/guide/storefront.md +++ b/docs/guide/storefront.md @@ -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 @@ -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.`: the folder's entries, sorted as above. A listed name the site has no folder for is @@ -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. @@ -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}}

Related articles

{{{page.related.listing}}}
{{/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/`), 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 diff --git a/packages/cli/src/init/starter.spec.ts b/packages/cli/src/init/starter.spec.ts index abce61c..1888cc5 100644 --- a/packages/cli/src/init/starter.spec.ts +++ b/packages/cli/src/init/starter.spec.ts @@ -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); @@ -189,17 +189,24 @@ describe("the starter project with a website (--storefront, no examples)", () => expect(home.body).toContain(`