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
22 changes: 22 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,14 @@
now. `pd dev` shows it, and the report names it: `scheduled: 1 held back (articles/launch.md until 2026-12-01)`.
- `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.
- **A tag is an object now, not a string:** `page.tags` and every listing entry's `tags` are
`{ key, label, description, route }`, as categories are (which gain `route` too). A template that writes a tag as
text (`{{#each page.tags}}{{this}}{{/each}}`) stops the page, naming the template, its line and the fix: write
`{{label}}`. A card whose schema declares `tags` as a list of strings stops its listing the same way. The starter's
layouts and cards write `{{label}}`, linked to the tag's page.
- `article:tag` and the JSON-LD `keywords` write a tag's label, not its key (the same for an undeclared tag).
- A skin with `layouts/tag` or `layouts/category` gets tag or category pages without asking (see Added): a page of the
pages folder at `/tags/` or `/categories/` then stops the build, naming the fix.

### Deprecated

Expand All @@ -28,6 +36,20 @@

### Added

- Tag declarations: `storefront.tags`, declared as categories are (label, description, old keys). Optional: without it
any tag works, labelled with its key. With it, a tag that isn't declared stops the page with a "did you mean", and an
old key builds with a warning. A query's `tags` are checked against the declarations.
- Tag and category pages: a page for every tag and every category a published page has (`/tags/<key>/`,
`/categories/<key>/`), and an index of each (`/tags/`, `/categories/`), through the skin's `layouts/tag`,
`layouts/tags`, `layouts/category` and `layouts/categories`. A term page gets `page.term` and lists its pages
through a query; an index gets `page.terms`. Drafts and scheduled pages never count. `storefront.tagPages` and
`storefront.categoryPages` turn them off (`false`), ask for them (`true`: a missing layout is a problem), or set the
path and the index's title. An old key's route forwards to the new one. They are in the sitemap, with JSON-LD
`CollectionPage`. The starter has plain layouts for all four.
- `same` for a query's `tags` and `categories`: the current page's own (on a tag page, its tag).
- Categories in search and link previews: `article:section` (the first category's label) and the `Article`'s
`articleSection`.

- `childLayout:` on a folder's `index.md`: the layout of the pages under it that name none. The nearest folder that
sets one wins, and a page's own `layout:` wins over it. A `childLayout` that names no layout fails the `index.md`
and each page that takes it, and every problem about a page's layout names where the layout came from. The
Expand Down
3 changes: 3 additions & 0 deletions docs/guide/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,6 +185,9 @@ in [storefront.md](storefront.md).
| `storefront.image` | string | (none) | The link-preview image of every page that names none: a PNG, JPEG, GIF or WebP file in the assets, such as `/assets/images/share.png` |
| `storefront.images` | object | (none) | The site's own `quality` and `effort` for its images, over `images` (above) |
| `storefront.categories` | object | (none) | The categories a page's `categories:` may name, by key (lowercase letters, digits and hyphens): `{ guides: { label: "Guides", description: "…", aliases: ["how-to"] } }`. `label` is required; `aliases` are old keys kept after a rename. Independent of the folders, so a page changes category without changing its URL ([storefront.md](storefront.md#categories)) |
| `storefront.tags` | object | (none) | The tags a page's `tags:` may name, declared as categories are: `{ css: { label: "CSS", aliases: ["styles"] } }`. Without it any tag works, labelled with its key ([storefront.md](storefront.md#tags)) |
| `storefront.tagPages` | boolean or object | on when the skin has `layouts/tag` | A page per tag at `/tags/<key>/` and an index at `/tags/`. `false`: off; `true` or `{ path, title }`: on, and a missing layout is a problem ([storefront.md](storefront.md#tag-and-category-pages)) |
| `storefront.categoryPages` | boolean or object | on when the skin has `layouts/category` | The same for categories, at `/categories/` |
| `storefront.site` | object | (none) | Values every page shares, such as the site's title or footer line. Every layout gets them as `site`, and a page cannot set them. Their keys and types are what the `site` property of `partials/base`'s schema declares, and they are checked against it. One key is Pattern Dump's: `navigations`, named lists of links ([storefront.md](storefront.md#declared-navigations)) |

## When changes take effect
Expand Down
89 changes: 76 additions & 13 deletions docs/guide/storefront.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ lede: Three folders make a site.
| `redirectFrom` | Old routes that forward to the page, one or a list: `redirectFrom: [/setup/, /start/]`. See [Redirects](#redirects) |
| `date` | The page's date, a real calendar date written `YYYY-MM-DD`: what a listing sorts and shows, and its JSON-LD `datePublished`. Without it, the day git first saw the page. A date after today holds the page back from `pd build` until that day, see [Scheduled pages](#scheduled-pages). See [Collections](#collections) |
| `updated` | The page's last real change, `YYYY-MM-DD`, set by its author: not before `date`. The only "last changed" date a reader or a search engine sees, see [Dates](#dates) |
| `tags` | One tag or a list, each lowercase letters, digits and hyphens, none twice: `tags: [css, design-systems]` |
| `tags` | One tag or a list, each lowercase letters, digits and hyphens, none twice: `tags: [css, design-systems]`. When the config declares tags (`storefront.tags`), each is a declared one (or an old key of one). See [Tags](#tags) |
| `categories` | One category or a list, each declared in `storefront.categories` (or an old key of one), none twice: `categories: [guides]`. See [Categories](#categories) |
| `draft` | `true` shows the page in `pd dev` and leaves it out of `pd build`. See [Drafts](#drafts) |
| `sort` | On a folder's `index.md` only: `date` lists the folder's pages newest first; `order`, the default, in the folder's order |
Expand Down Expand Up @@ -376,8 +376,10 @@ keys below, at any depth.
| `updated` | The page's `updated`, `YYYY-MM-DD`, else `null`. Never git's last commit, see [Dates](#dates) |
| `children` | On a folder's `index.md`: the folder's pages, an entry each, sorted as its `sort` says (see [Collections](#collections)); `[]` on any other page |
| `date` | The page's `date`, else the day git first saw it (`YYYY-MM-DD`), else `null` |
| `tags` | The page's `tags`, else `[]` |
| `categories` | The page's categories, in its order, each `{ key, label, description }` (`description` `null` when the config gives none), else `[]` |
| `tags` | The page's tags, in its order, each `{ key, label, description, route }` (see [Tags](#tags)), else `[]` |
| `categories` | The page's categories, in its order, each `{ key, label, description, route }` (`description` `null` when the config gives none, `route` the category's page or `null`), else `[]` |
| `term` | On a tag or category page: the tag or category, `{ key, label, description, route, count }` (see [Tag and category pages](#tag-and-category-pages)), else `null` |
| `terms` | On the index of the tags or the categories: every one with a page, by label, each as `term`, else `null` |
| `listing` | On a folder's `index.md`: the folder's pages rendered through the view its `view:` names, as HTML for `{{{page.listing}}}` (see [Listing views](#listing-views)); `null` on any other page |

```hbs
Expand Down Expand Up @@ -463,8 +465,8 @@ has the same fixed shape:
| `date` | The page's `date`, else the day git first saw it, else `null` |
| `updated` | The page's `updated`, or `null` |
| `image` | The page's `image`, a path in the assets, or `null` |
| `tags` | The page's `tags`, or `[]` |
| `categories` | The page's categories, each `{ key, label, description }`, or `[]` |
| `tags` | The page's tags, each `{ key, label, description, route }`, or `[]` |
| `categories` | The page's categories, each `{ key, label, description, route }`, or `[]` |
| `draft` | `true` for a draft in `pd dev` |
| `scheduled` | `true` in `pd dev` for a page dated after today |

Expand Down Expand Up @@ -586,15 +588,16 @@ the sub-keys Pattern Dump fills.
|---|---|---|
| `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 |
| `categories` | Declared categories (an old key works, with a warning), or `same` for the page's own | none |
| `tags` | Tags (declared ones, when the config declares tags), or `same` for the page's own | 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
With both `tags` and `categories`, a page must match both. `same` is the current page's own tags (categories); on a page
with none the query lists no page. On a tag page it is that tag. 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.

Expand All @@ -613,7 +616,8 @@ page, and `related: true` keeps the layout's as it is. The key is the build's: t
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
doesn't exist (with a "did you mean"), a folder that isn't one, a category that isn't declared, a tag that isn't declared (or, without declared tags, 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.
Expand Down Expand Up @@ -645,10 +649,68 @@ storefront: {
builds, as the new category, with a warning that names the page and line so it can be updated. An alias that is
a key of its own, or that two categories claim, is a config problem.
- **A layout** gets `page.categories` (in the page's order) and each listing entry carries them. `site.categories`
is every declared category in the config's order, `{ key, label, description }`, on every page, when
is every declared category in the config's order, `{ key, label, description, route }`, on every page, when
`partials/base`'s schema lists `categories` under `site.properties` (no shape of its own, a description at most).
The config can't set `site.categories`.

### Tags

A tag is a URL segment a page lists in `tags:`. Without declarations any tag works, and its label is its key. The
config can declare them, as it declares categories: then they are the list, so a typo stops the page (with a "did you
mean"), and an old key builds as the tag it now is, with a warning.

```ts
storefront: {
tags: {
css: { label: "CSS", description: "Cascading style sheets", aliases: ["styles"] },
"design-tokens": { label: "Design tokens" },
},
},
```

A layout gets each tag as `{ key, label, description, route }`, as it gets a category: `label` to show it, `key` as its
URL segment, `route` its [tag page](#tag-and-category-pages) or `null`. Write `<a href="{{route}}">{{label}}</a>`.

**Tags were strings before 0.5.0.** A template that still writes one as text, `{{#each page.tags}}{{this}}{{/each}}`,
would print `[object Object]`, so the page stops instead, naming the template and line and what to write
(`{{label}}`). A card whose schema declares `tags` as a list of strings stops the listing the same way: declare the
items as objects, or leave `items` out.

### Tag and category pages

Pattern Dump makes a page for every tag and every category a published page has, and an index of each, through the
skin's layouts:

| Route | Layout | What the layout gets |
|---|---|---|
| `/tags/<key>/` | `layouts/tag` | `title` (the label), `description` (when declared), `page.term` |
| `/tags/` | `layouts/tags` | `title` ("Tags"), `page.terms` |
| `/categories/<key>/` | `layouts/category` | as a tag page |
| `/categories/` | `layouts/categories` | `title` ("Categories"), `page.terms` |

- **Their pages are a query** the layout declares, with `tags: same` (`categories: same`), so views, cards and every
check work as on any page:

```json
"pages": { "x-pd-query": { "tags": "same", "sort": "date", "view": "list" } }
```

- **Published pages only.** Drafts and scheduled pages never count, in `pd dev` either: a tag only they have gets no
page, and isn't in the index.
- **On and off:** `storefront.tagPages` and `storefront.categoryPages`. Left out, the pages are there when the skin has
the layout (`layouts/tag`; the index when it has `layouts/tags` too), and a skin without it gets none, with no
message. `false` turns them off. `true`, or `{ path, title }`, asks for them: a missing layout is then a problem.
`path` is the URL segment (`{ path: "topics" }` gives `/topics/css/`), `title` the index's title.
- **Old keys forward.** `/tags/<old>/` of a declared tag's alias is a redirect to `/tags/<key>/`, like a page's
`redirectFrom`.
- **Checked:** a page or folder of the pages folder at a generated route, or a `redirectFrom` claiming one, is a
problem naming both; the two paths can't be the same.
- They are in the sitemap (`lastmod`: the newest change of their pages) and have JSON-LD `CollectionPage`. They are
not in the nav or any listing, and the workbench doesn't list them under a layout's pages yet.
- No pagination yet: a tag page lists every page with the tag.

The starter (`pd init --storefront`) has plain `tag`, `tags`, `category` and `categories` layouts.

### Scheduled pages

A page whose `date` is after today stays out of `pd build`, as a draft does: no page, no entry in the nav, a
Expand Down Expand Up @@ -813,9 +875,10 @@ or with a path, such as `https://example.github.io/project/`, for a site publish

`og:type` is `website`, except on an article: a page whose frontmatter gives it a `date`, other than the home
page and a listing (a folder's `index.md` with pages under it). An article gets `og:type` `article`, with
`article:published_time` (its `date`), `article:modified_time` (its `updated`, when it has one) and one
`article:tag` per tag, and its JSON-LD graph adds an `Article`
(headline, dates, `keywords` from its tags) as the page's main entity. The date git gives a page does not make
`article:published_time` (its `date`), `article:modified_time` (its `updated`, when it has one), `article:section`
(its first category's label: Open Graph has one) and one `article:tag` per tag (its label), and its JSON-LD graph
adds an `Article` (headline, dates, `keywords` from its tags' labels, `articleSection` from its categories' labels:
one string, or a list for several) as the page's main entity. The date git gives a page does not make
it an article: every committed page has one.

and `pd build` writes `sitemap.xml`. Without it, those are left out and `pd build` says so once. In `pd dev`
Expand Down
19 changes: 17 additions & 2 deletions packages/cli/src/init/starter.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,8 @@ 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/article", "ok"], ["layouts/home", "ok"], ["layouts/listing", "ok"], ["layouts/page", "ok"], ["partials/base", "ok"], ["partials/head", "ok"],
["layouts/article", "ok"], ["layouts/categories", "ok"], ["layouts/category", "ok"], ["layouts/home", "ok"], ["layouts/listing", "ok"], ["layouts/page", "ok"],
["layouts/tag", "ok"], ["layouts/tags", "ok"], ["partials/base", "ok"], ["partials/head", "ok"],
["views/compact", "ok"], ["views/featured", "ok"], ["views/grid", "ok"], ["views/list", "ok"]]);
}, 120_000);

Expand Down Expand Up @@ -203,7 +204,21 @@ describe("the starter project with a website (--storefront, no examples)", () =>
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>`);
// Each tag by its label, linked to its tag page.
expect(hello.body).toContain(`<ul class="page-tags" aria-label="Tags"><li><a href="/tags/getting-started/">getting-started</a></li><li><a href="/tags/notes/">notes</a></li></ul>`);
// The tag and category pages, and their indexes, through the starter's plain layouts.
const notes = await onHost(server.port, "live.localhost", "/tags/notes/");
expect(notes.status).toBe(200);
expect(notes.body).toContain(`<h1 class="page-title">notes</h1>`);
expect([...notes.body.matchAll(/<h2 class="listing-card-title"><a href="([^"]+)"/g)].map(m => m[1])).toEqual(["/articles/related/", "/articles/hello/"]);
const tags = await onHost(server.port, "live.localhost", "/tags/");
expect(tags.body).toContain(`<li><a href="/tags/getting-started/">getting-started</a> (1)</li>`);
expect(tags.body).toContain(`<li><a href="/tags/notes/">notes</a> (2)</li>`);
const category = await onHost(server.port, "live.localhost", "/categories/notes/");
expect(category.status).toBe(200);
expect(category.body).toContain(`<h1 class="page-title">Notes</h1>`);
expect(category.body).toContain(`<p class="page-description">Short articles about this site</p>`);
expect((await onHost(server.port, "live.localhost", "/categories/")).body).toContain(`<li><a href="/categories/notes/">Notes</a> (2)</li>`);
// 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$/, "")}`);
Expand Down
6 changes: 6 additions & 0 deletions packages/cli/templates/storefront-fills/config.txt
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@
// Or a subfolder, such as a GitHub project page: the site is then served under the path, in `npm run dev` too,
// and the workbench goes under it as well (workbenchUrl and build.basePath "/<repository>/workbench/").
// url: "https://<owner>.github.io/<repository>/",
// What a page can be about, independent of its folder: a page names them in `categories:`. Each category and each
// tag gets a page (layouts/category, layouts/tag) and an index (/categories/, /tags/). Tags can be declared the
// same way (tags: { ... }), so a typo fails the build; undeclared, any tag works.
categories: {
notes: { label: "Notes", description: "Short articles about this site" },
},
site: { title: __PD_BRAND_JSON__, footer: "Made with Pattern Dump." },
},
build: { basePath: "/workbench/" },
Expand Down
Loading
Loading