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
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,25 @@
clock), with every page under a folder whose `index.md` is dated so. A site with such a page builds without it
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.

### Added

- `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
workbench lists a layout's pages in its Relationships tab, each with where its layout came from, and `/api/pages`
gives `layoutFrom`.
- A listing's card: `x-pd-card` names the component each page of a listing is shown as (on a layout's
`page.children`, or a view's `entries`). Every page in the listing is checked against the card's schema: a field
the card requires that a page doesn't have fails the listing, naming the page. A card declares only fields a
listing's page has, and its sample data may set only those.
- Listing views: `view: grid` on a folder's `index.md` shows its listing through `views/grid`, a component in the
skin's style guide (Pattern Dump has none of its own). The layout writes `{{{page.listing}}}`; the view gets the
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`.
- `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
Expand Down
6 changes: 6 additions & 0 deletions apps/dev-ui/src/inspector/panel.ts
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,12 @@ export async function renderPanel(): Promise<void> {
// Top-level composition groups.
appendComponentGroup("Uses", relAvail.uses, section);
appendComponentGroup("Used by", relAvail.usedBy, section);
// A layout of a project with a website: the pages that render with it, and where each got its layout.
if (relAvail.pages) {
appendPlainGroup("Pages", relAvail.pages.map(p => `${p.path} (${
p.source === "own" ? "its own layout" : p.source === "default" ? "the default layout" : `childLayout of ${p.from ?? "its folder"}`
})`), section);
}

// Style umbrella: groups Style uses + Style modules under a shared heading.
const styleUmbrella = document.createElement("div");
Expand Down
95 changes: 89 additions & 6 deletions docs/guide/storefront.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,8 @@ lede: Three folders make a site.

| Key | |
|---|---|
| `layout` | The layout the page renders with: `layouts/<name>` in the skin. `page` when it has none |
| `layout` | The layout the page renders with: `layouts/<name>` in the skin. Without it, its folder's `childLayout`, else `page`. See [A folder's default layout](#a-folders-default-layout) |
| `childLayout` | On a folder's `index.md` only: the layout of the pages under it that name none. See [A folder's default layout](#a-folders-default-layout) |
| `order` | Its position in the navigation, see [Pages](#pages) |
| `image` | Its link-preview image: a raster file in the assets (PNG, JPEG, GIF or WebP), such as `/assets/images/setup.png`. An SVG, or any file that isn't one of those (read from its bytes, not its name), is a problem. Without it, `storefront.image` |
| `index` | `false` keeps the page out of search engines: `noindex`, and no sitemap entry |
Expand All @@ -210,10 +211,11 @@ lede: Three folders make a site.
| `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 |
| `view` | On a folder's `index.md` only: the view its listing is shown in, `views/<name>` in the skin. See [Listing views](#listing-views) |
| any other key | Must be declared by the layout's schema |

`layout`, `order`, `image`, `index`, `redirectFrom`, `date`, `updated`, `tags`, `categories`, `draft` and `sort`
belong to the build: they never reach the layout as keys of their own, and a layout's schema may not declare any of
`layout`, `childLayout`, `order`, `image`, `index`, `redirectFrom`, `date`, `updated`, `tags`, `categories`, `draft`,
`sort` and `view` belong to the build: they never reach the layout as keys of their own, and a layout's schema may not declare any of
them (a layout shows them through `page.date`, `page.updated`, `page.tags` and `page.categories`).

**The layout's schema is the frontmatter contract.** A layout is a component, and its
Expand All @@ -230,6 +232,32 @@ page fails when:

Frontmatter is a small fixed grammar, not full YAML: one level of `key: value` pairs and lists.

### A folder's default layout

With many pages in a folder, `childLayout` on its `index.md` saves writing `layout:` on each, and a forgotten line
can no longer give a page the wrong layout:

```md
---
title: Articles
layout: listing
childLayout: article
---
```

- **A page without its own `layout:`** takes the `childLayout` of the nearest folder above it that sets one; without
any, `page`. Its own `layout:` always wins.
- **A folder's `index.md` is a page of its parent folder:** its own `childLayout` is for the pages under it, and it
takes its layout from its parent's, as any page there does.
- **Checked:** a `childLayout` that names no layout fails on the `index.md`, at its line, and on every page that
takes it. Each page is checked against the schema of the layout it ends up with, and a problem about that layout
names where it came from: `"subtitle" is required by layout "article" (the childLayout of articles/index.md)`.
- `404.md` is not a page of the site, so it takes no `childLayout`.

**Which layout a page got:** in the workbench, a layout's Relationships tab lists its **Pages**, each with where its
layout came from ("its own layout", "childLayout of articles/index.md", "the default layout"). `/api/pages` on the
website's host gives each page's `layout`, and `layoutFrom` when it came from a folder.

### Problems

In `pd dev` a page with a problem is replaced by the list of its problems, every one with its file and
Expand Down Expand Up @@ -348,6 +376,7 @@ keys below, at any depth.
| `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 `[]` |
| `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
{{#each page.headings}}<a href="#{{anchor}}">{{text}}</a>{{/each}}
Expand Down Expand Up @@ -447,9 +476,24 @@ To show an entry's image with its variants, pass it to a component with an image
{{#each page.children}}<li>{{> components-card }}</li>{{/each}}
```

where `components/card` declares `image` with `x-pd-image` and writes `{{pd-image image alt=""}}`. A component
a layout includes may not have sample data of keys the layout doesn't declare; give it a variant
(`card~article.json`) to show it filled in the workbench.
where `components/card` declares `image` with `x-pd-image` and writes `{{pd-image image alt=""}}`.

**The card.** Name that component in the layout's schema, and every page of the listing is checked against the
card's schema:

```json
"page": { "properties": { "children": { "x-pd-card": "components/card" } } }
```

- **A field the card requires** (`required`) that a page doesn't have, `null` or an empty list, fails the listing
page, once per page, naming it and what to add: `articles/index.md: articles/plain.md has no image, which the
listing's card (components/card) requires: give it one (image: ...)`.
- **A value a page has** is checked against the type the card declares.
- **A card declares only fields of an entry** (the table above). The entry's shape is Pattern Dump's and the base
every card shares: a page can't add fields to it, so a card says which of them it shows and which it needs.
- **Its sample data** may set only an entry's fields, since the card renders with an entry as its context. Without
`x-pd-card`, a component the layout includes may only have sample data of keys the layout declares; give it a
variant (`card~article.json`) to show it filled in the workbench.

With `sort: date`, a page with no date at all (no `date` and no commit, such as a new file) is a problem in
`pd build` and a note in `pd dev`, where it is listed last. From a shallow clone, a date git would give is
Expand All @@ -469,6 +513,45 @@ set `site.collections`.
In `pd dev` an edit to what a listing shows of a page (its date, description, first paragraph, image, tags,
categories or draft) reloads every open page, as a title edit does.

### Listing views

One listing, several ways to show it. A folder's `index.md` names its view:

```md
---
title: Articles
layout: listing
view: grid
sort: date
---
```

A **view** is a component directly under `views/` in the skin's style guide (`views/grid`), as a layout is under
`layouts/`. Pattern Dump has no views of its own: every skin defines its own, and the workbench shows and documents
them like any component.

- **The layout** declares `page.listing` and writes it unescaped where the listing goes: `{{{page.listing}}}`.
- **The view** is rendered once per listing with `entries`, the folder's pages in its sort order (each an entry, as
above), and nothing else.
- **The view names its card** in its schema, and that card's `required` are the fields the view needs. Every page
of the listing is checked against that card, as for `x-pd-card` on `page.children`:

```json
{ "properties": { "entries": { "type": "array", "x-pd-card": "components/grid-card" } } }
```

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.
- **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
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.

The starter (`pd init --storefront`) ships four plain views, each with its card in `components/`: `list` (title,
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).

### Categories

Categories say what a page is about, apart from the folder it is in: a page changes category without moving, so
Expand Down
14 changes: 11 additions & 3 deletions packages/cli/src/init/plan.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ const templates: Templates = {
{ path: "src/patterns/partials/base/base.json", content: '{ "site": { "title": __PD_BRAND_JSON__ } }\n' },
{ path: "src/styles/partials/base.scss", content: ".site {}\n" },
{ path: "assets/icon.svg", content: "<svg/>\n" },
{ path: "src/patterns/views/list/list.hbs", content: "<ul>{{#each entries}}<li>{{title}}</li>{{/each}}</ul>\n" },
{ path: "src/styles/views/list.scss", content: ".view-list {}\n" },
{ path: "src/patterns/components/note/note.hbs", content: "<aside>{{heading}}</aside>\n" },
{ path: ".github/workflows/pages.yml", content: "name: Pages\n" },
],
Expand Down Expand Up @@ -67,7 +69,7 @@ describe("planInit — a new folder", () => {

describe("planInit — the storefront", () => {
const SKIN = ["src/patterns/layouts/page/page.hbs", "src/patterns/partials/base/base.hbs", "src/patterns/partials/base/base.json",
"src/styles/partials/base.scss", "assets/icon.svg"];
"src/styles/partials/base.scss", "assets/icon.svg", "src/patterns/views/list/list.hbs", "src/styles/views/list.scss"];
const REST = ["pages/index.md", "src/patterns/components/note/note.hbs", ".github/workflows/pages.yml"];
const existing = (files: string[]): ExistingProject => ({ packageJson: null, exists: p => files.includes(p) });

Expand Down Expand Up @@ -103,8 +105,14 @@ describe("planInit — the storefront", () => {
const paths = p.writes.map(w => w.path);
for (const s of SKIN) expect(paths, s).not.toContain(s);
expect(paths).toEqual(expect.arrayContaining(REST));
expect(p.skipped).toEqual([{ path: "src/patterns/partials/base/base.hbs", reason: "already exists: the storefront skin (5 files in src/patterns/layouts, "
+ "src/patterns/partials and their styles) was left out as a whole, so it isn't mixed with the skin already here" }]);
expect(p.skipped).toEqual([{ path: "src/patterns/partials/base/base.hbs", reason: "already exists: the storefront skin (7 files in src/patterns/layouts, "
+ "src/patterns/partials, src/patterns/views and their styles) was left out as a whole, so it isn't mixed with the skin already here" }]);
});

it("counts the views as the skin: a project with views of its own keeps them, and gets none of the starter's skin", () => {
const p = plan({ storefront: true }, existing(["src/patterns/views/list/list.hbs"]));
for (const s of SKIN) expect(p.writes.map(w => w.path), s).not.toContain(s);
expect(p.skipped.map(s => s.path)).toEqual(["src/patterns/views/list/list.hbs"]);
});

it("writes the skin beside the project's own other layouts and partials", () => {
Expand Down
4 changes: 2 additions & 2 deletions packages/cli/src/init/plan.ts
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ const RENAMES: Record<string, string> = { _gitignore: ".gitignore" };
* The storefront's skin: written as one unit or not at all. Mixed with a skin already in the project (its own
* `layouts/page` beside the starter's `partials/base`, say), pages would render with parts of two skins.
*/
const SKIN_PREFIXES = ["src/patterns/layouts/", "src/patterns/partials/", "src/styles/layouts/", "src/styles/partials/"];
const SKIN_PREFIXES = ["src/patterns/layouts/", "src/patterns/partials/", "src/patterns/views/", "src/styles/layouts/", "src/styles/partials/", "src/styles/views/"];
const SKIN_FILES = ["assets/icon.svg"];
const isSkin = (path: string): boolean => SKIN_PREFIXES.some(p => path.startsWith(p)) || SKIN_FILES.includes(path);

Expand Down Expand Up @@ -95,7 +95,7 @@ export function planInit(
const skinTaken = skin.map(f => renamed(f.path)).find(p => existing.exists(p));
if (skinTaken) {
skipped.push({ path: skinTaken, reason: `already exists: the storefront skin (${skin.length} files in src/patterns/layouts, `
+ `src/patterns/partials and their styles) was left out as a whole, so it isn't mixed with the skin already here` });
+ `src/patterns/partials, src/patterns/views and their styles) was left out as a whole, so it isn't mixed with the skin already here` });
}
const files = [...templates.base, ...(answers.examples ? templates.examples : []),
...storefront.filter(f => !skinTaken || !skin.includes(f))];
Expand Down
Loading
Loading