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
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

### Changed

- `toc` is a key the build owns now (the table of contents): a layout's schema that declares it must rename it.
- **A storefront page's "last changed" date is the author's, never git's.** Git's last commit counts a typo fix or a
reformat as a change, so it is no longer used for anything a reader or a search engine sees. A page sets
`updated: YYYY-MM-DD` for a real change instead. What changes for an existing site:
Expand Down Expand Up @@ -36,6 +37,17 @@

### Added

- **Regions.** A layout declares regions besides the body on `page.regions` (`"x-pd-regions": ["sidebar"]`) and writes
each as `{{{page.regions.sidebar}}}`, null when the page puts nothing there. A placed component goes into one with
`region="sidebar"` on its tag, or its schema's `"x-pd-region"`; components keep the page's order there. A region
another layout has is left out without a message; one no layout has stops the page with a "did you mean". `<body>`
names the filled regions (`data-pd-regions="sidebar"`), so a skin's grid can collapse an empty one. `header`,
`footer`, `nav` and `main` are the layout's own landmarks and can't be regions, and a component in a region can't
bring a main, banner or contentinfo.
- **The table of contents in a region:** the skin's `components/toc`, with `items: [{ text, href, level }]`.
`toc: true` in a page (or `x-pd-toc` on its layout) shows it with the page's headings of level 2 and 3; `toc: false`
keeps it out. `<pd-toc>` places it in the markdown, with the derived items or a list of links of its own, whose
`#anchors` must be headings of the page. The starter has a `doc` layout with a sidebar and a `components/toc`.
- **Search with Pagefind.** `pd build` indexes each page's own content (its markdown and placed components, never the
layout's header, navigation or listings) and writes the index into the site at `_pd/search/`, under the site's path,
with `section`, `tag` and `category` filters by label. Pagefind is the project's own
Expand Down
70 changes: 69 additions & 1 deletion docs/guide/storefront.md
Original file line number Diff line number Diff line change
Expand Up @@ -212,10 +212,11 @@ lede: Three folders make a site.
| `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) |
| `toc` | `true` shows the table of contents in its region; `false` keeps it out, whatever the layout says. See [The table of contents](#the-table-of-contents) |
| any other key | Must be declared by the layout's schema |

`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
`sort`, `view` and `toc` 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 Down Expand Up @@ -416,6 +417,73 @@ it: a new commit is seen on restart. Two limits:
- **A page moved into the pages folder from outside it** counts as created at the move: the history read
is limited to the pages folder, so that move reads as an add.

### Regions

A layout can have regions besides the body: places, such as a sidebar, that a page's placed components go into. A page
with nothing for a region has an empty one, so the layout leaves it out: the sidebar is there or not by what the page
holds.

**A layout declares them** on `page.regions` in its schema, and writes each where it wants it:

```json
"page": { "properties": { "regions": { "x-pd-regions": ["sidebar"], "x-pd-toc": true } } }
```

```handlebars
{{#if page.regions.sidebar}}<div class="doc-sidebar">{{{page.regions.sidebar}}}</div>{{/if}}
```

- `page.regions.<name>` is the region's HTML, or null when the page puts nothing there.
- `x-pd-toc` (optional) shows the [table of contents](#the-table-of-contents) on the layout's pages.
- **CSS is told what is filled:** a page whose layout declares regions names the filled ones on its `<body>`,
`<body data-pd-regions="sidebar">` (empty when none), so a skin switches its grid without `:has()`:

```css
body[data-pd-regions~="sidebar"] .doc { grid-template-areas: "content sidebar"; }
```

**A component goes into a region** by its tag, `region="sidebar"` on the `pd-` tag, or by its default, `"x-pd-region":
"sidebar"` at its schema's root. The tag wins. Inside a region, components keep the page's order, and each is checked
against its schema wherever it ends up.

- A region another layout of the skin has, and this page's layout doesn't: the component is left out, with no
message. Some layouts have a sidebar, some don't.
- A region no layout of the skin declares stops the page, with a "did you mean".
- `region` on a tag is Pattern Dump's: a component whose schema declares a `region` property can't be placed with it.

**The layout's own landmarks are not regions:** `header`, `footer`, `nav` and `main` (the body itself). A layout may use
them as grid-area names for its own markup, but declaring one as a region stops its pages, and so does a tag or a
default region naming one (the message lists the regions the layout offers). A component in a region may not bring a
landmark of its own either: a `<main>`, or a `<header>` or `<footer>` outside `article`, `aside`, `nav` and `section`
(a banner or contentinfo). axe still checks the page's landmarks as a whole.

### The table of contents

The table of contents is the skin's `components/toc`, given `items: [{ text, href, level }]`. Its schema's
`x-pd-region` says which region it goes into.

- `toc: true` in a page's frontmatter, or `x-pd-toc` on its layout, shows it with the page's headings of level 2 and 3,
first in its region. `toc: false` keeps it out. A page with no such heading gets none.
- `<pd-toc></pd-toc>` in the markdown places it where the tag is, or in its region, with the same items. With a list of
links inside, it shows those instead, the nesting giving the level:

```md
<pd-toc>
- [Install](#install)
- [Options](#options)
- [About](/about/)
</pd-toc>
```

Each item is one link. An `#anchor` must be a heading of the page (as it finally is, a suffixed anchor included),
or the page stops with a "did you mean"; any other link is checked by the link check, as everywhere. A page with a
`<pd-toc>` gets no derived one besides.
- Asking for it without a `components/toc` in the skin is a problem naming it.

The starter (`pd init --storefront`) has a `doc` layout with a sidebar that collapses to one column when it is empty,
and a `components/toc`: the about page uses `toc: true`, the guide lists its own links, and the search page has
neither.

### Declared navigations

Besides the nav built from the pages folder, `storefront.site.navigations` holds named lists of links a
Expand Down
17 changes: 15 additions & 2 deletions packages/cli/src/init/starter.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -174,8 +174,8 @@ describe("the starter project with a website (--storefront, no examples)", () =>
const { graph } = await runDiagnosticsAudit(config, siteDir);
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"], ["components/search", "ok"],
["layouts/article", "ok"], ["layouts/categories", "ok"], ["layouts/category", "ok"], ["layouts/home", "ok"], ["layouts/listing", "ok"], ["layouts/page", "ok"],
[["components/compact-card", "ok"], ["components/feature-card", "ok"], ["components/grid-card", "ok"], ["components/listing-card", "ok"], ["components/note", "ok"], ["components/search", "ok"], ["components/toc", "ok"],
["layouts/article", "ok"], ["layouts/categories", "ok"], ["layouts/category", "ok"], ["layouts/doc", "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 @@ -207,9 +207,22 @@ describe("the starter project with a website (--storefront, no examples)", () =>
// 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.
// Regions: the doc layout's sidebar. About asks for the derived table of contents; the guide lists its own links
// and places a note there; the search page has neither, so it has no sidebar.
const about = await onHost(server.port, "live.localhost", "/about/");
expect(about.body).toContain(`<body data-pd-regions="sidebar">`);
expect(about.body).toMatch(/<div class="doc-sidebar"><nav class="toc" aria-label="On this page">\s*<ul class="toc-list">\s*<li class="toc-level-2"><a href="#what-is-where">What is where<\/a><\/li>\s*<li class="toc-level-2"><a href="#settings">Settings<\/a><\/li>/);
const guide = await onHost(server.port, "live.localhost", "/guide/");
expect(guide.status).toBe(200);
expect([...guide.body.matchAll(/<li class="toc-level-(\d)"><a href="([^"]+)">/g)].map(m => `${m[1]} ${m[2]}`))
.toEqual(["2 #write-a-page", "2 #place-a-component", "3 #in-the-sidebar", "2 /about/"]);
expect(guide.body).toMatch(/<div class="doc-sidebar"><nav class="toc"[\s\S]*<\/nav>\s*<aside class="note"[^>]*>[\s\S]*This note is in the sidebar/);
expect(guide.body).not.toMatch(/<div class="page-body">[\s\S]*This note is in the sidebar[\s\S]*<\/article>/);
// The search page: the search component, its script, and a link to it in the navigation.
const search = await onHost(server.port, "live.localhost", "/search/");
expect(search.status).toBe(200);
expect(search.body).toContain(`<body data-pd-regions="">`);
expect(search.body).not.toContain(`class="doc-sidebar"`);
expect(search.body).toMatch(/<search class="search" data-search>\s*<form class="search-form" method="get">\s*<label class="search-label" for="search-field">Search this site<\/label>/);
expect(search.body).toMatch(/<script type="module" src="\/_pd\/scripts\/site-search\.js[^"]*"><\/script>/);
expect(home.body).toContain(`<a href="/search/">Search</a>`);
Expand Down
8 changes: 8 additions & 0 deletions packages/cli/templates/storefront/pages/about.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,13 @@
---
title: About
description: What is in this starter, and where it lives.
layout: doc
toc: true
order: 1
---

## What is where

The pages are in `pages/`. What they look like is the skin, written as ordinary components so the
workbench shows each part of it:

Expand All @@ -12,8 +16,12 @@ workbench shows each part of it:
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/layouts/doc`: a page with a sidebar, which this page uses: its table of contents (`toc: true`) is there
- `src/patterns/components/note`: a component the pages show
- `src/patterns/components/toc`: the table of contents
- `src/patterns/components/search`: the site's search, on the search page; `pd build` writes its index once the
project has Pagefind (`npm install --save-dev pagefind`)

## Settings

The site's name and footer are `storefront.site` in `pattern-dump.config.ts`.
38 changes: 38 additions & 0 deletions packages/cli/templates/storefront/pages/guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: Guide
description: A page with a table of contents of its own.
layout: doc
order: 4
---

<pd-toc>
- [Write a page](#write-a-page)
- [Place a component](#place-a-component)
- [In the sidebar](#in-the-sidebar)
- [What is where](/about/)
</pd-toc>

## Write a page

Every markdown file in `pages/` is a page. This one uses the doc layout, so it has a sidebar, and lists its table of
contents itself with `<pd-toc>`: the links in it are checked, so an `#anchor` that is no heading of the page stops the
build.

## Place a component

A page places a component with a `pd-` tag, such as `<pd-components-note>`. It goes where the tag is, unless the tag
names a region of the layout:

```md
<pd-components-note heading="Beside the text" region="sidebar">
In the sidebar.
</pd-components-note>
```

### In the sidebar

<pd-components-note heading="Beside the text" region="sidebar">
This note is in the sidebar, under the table of contents.
</pd-components-note>

A page with nothing for the sidebar, such as the search page, has none: the layout is one column.
1 change: 1 addition & 0 deletions packages/cli/templates/storefront/pages/search.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: Search
description: Search every page of this site.
layout: doc
order: 3
---

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<nav class="toc" aria-label="On this page">
<ul class="toc-list">
{{#each items}}
<li class="toc-level-{{level}}"><a href="{{href}}">{{text}}</a></li>
{{/each}}
</ul>
</nav>
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"items": [
{ "text": "Install", "href": "#install", "level": 2 },
{ "text": "Configure", "href": "#configure", "level": 2 },
{ "text": "Options", "href": "#options", "level": 3 }
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
title: Table of contents
---

The page's table of contents. It goes into the layout's sidebar (`"x-pd-region": "sidebar"` in its schema).

- `toc: true` in a page's frontmatter shows it with the page's headings of level 2 and 3.
- `<pd-toc></pd-toc>` in a page's markdown does the same; with a list of links inside, it shows those instead:

```md
<pd-toc>
- [Install](#install)
- [Options](#options)
- [About](/about/)
</pd-toc>
```

An `#anchor` must be a heading of the page, or the build stops and names the closest one.
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Table of contents",
"description": "The page's table of contents, in the sidebar: toc: true in a page's frontmatter, or <pd-toc> in its markdown.",
"type": "object",
"x-pd-region": "sidebar",
"properties": {
"items": {
"type": "array",
"description": "Filled by Pattern Dump: the page's headings of level 2 and 3, or the links a <pd-toc> lists",
"items": {
"type": "object",
"properties": {
"text": { "type": "string" },
"href": { "type": "string" },
"level": { "type": "integer", "description": "2 for a top item, 3 for one under it" }
}
}
}
}
}
13 changes: 13 additions & 0 deletions packages/cli/templates/storefront/src/patterns/layouts/doc/doc.hbs
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{{#> partials-base }}
<div class="doc">
<article class="doc-content">
<h1 class="page-title">{{title}}</h1>
{{#if description}}<p class="page-description">{{description}}</p>{{/if}}
<div class="page-body">{{{body}}}</div>
{{#if page.next}}<p class="page-next"><a rel="next" href="{{page.next.route}}">Next: {{page.next.title}}</a></p>{{/if}}
</article>
{{#if page.regions.sidebar}}
<div class="doc-sidebar">{{{page.regions.sidebar}}}</div>
{{/if}}
</div>
{{/partials-base}}
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"title": "Getting started",
"description": "What a page with a sidebar looks like.",
"body": "<h2 id=\"install\">Install</h2><p>Text of the page.</p><h2 id=\"configure\">Configure</h2><p>More text.</p>",
"page": {
"next": null,
"regions": {
"sidebar": "<nav class=\"toc\" aria-label=\"On this page\"><ul class=\"toc-list\"><li class=\"toc-level-2\"><a href=\"#install\">Install</a></li><li class=\"toc-level-2\"><a href=\"#configure\">Configure</a></li></ul></nav>"
}
}
}
11 changes: 11 additions & 0 deletions packages/cli/templates/storefront/src/patterns/layouts/doc/doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
title: Doc
---

A page with a sidebar: `layout: doc`. The sidebar is the layout's region (`page.regions` with
`"x-pd-regions": ["sidebar"]`), written as `{{{page.regions.sidebar}}}`. It holds the table of contents
(`toc: true` in a page's frontmatter, or `<pd-toc>` in its markdown) and any component the page places with
`region="sidebar"`.

A page that puts nothing there has no sidebar: the region is null, so the layout leaves it out, and the grid has
one column. `<body data-pd-regions="sidebar">` names the filled regions, which is what the CSS switches on.
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Doc",
"description": "A page with a sidebar beside it: the table of contents, and whatever the page places there. Without either, one column.",
"type": "object",
"x-pd-prose-images": { "widths": [480, 672, 1344], "sizes": "(min-width: 44rem) 42rem, calc(100vw - 2rem)" },
"required": ["title"],
"properties": {
"title": { "type": "string", "description": "The page's heading, its title in the navigation and in search results" },
"description": { "type": "string", "description": "One sentence under the heading, and the page's description for search results" },
"page": {
"type": "object",
"description": "What the storefront works out for the page",
"properties": {
"next": { "description": "The page after this one in the navigation" },
"regions": { "description": "The layout's regions: the sidebar, empty when the page puts nothing there", "x-pd-regions": ["sidebar"] }
}
}
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
@use "../base/tokens";

.toc { position: sticky; top: tokens.$space-md; font-size: 0.875rem; }
.toc-list { margin: 0; padding: 0; list-style: none; }
.toc-list li { margin-block: tokens.$space-xs; }
.toc-level-3 { padding-inline-start: tokens.$space-md; }
14 changes: 14 additions & 0 deletions packages/cli/templates/storefront/src/styles/layouts/doc.scss
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
@use "../base/tokens";

// One column; a second beside it when the page fills the sidebar (<body data-pd-regions="sidebar">).
.doc { display: grid; gap: tokens.$space-lg; grid-template-areas: "content"; grid-template-columns: minmax(0, 1fr); }
.doc-content { grid-area: content; }
.doc-sidebar { grid-area: sidebar; }
body[data-pd-regions~="sidebar"] .doc { grid-template-areas: "content" "sidebar"; }

@media (width >= 56rem) {
body[data-pd-regions~="sidebar"] .doc { grid-template-areas: "content sidebar"; grid-template-columns: minmax(0, 1fr) 14rem; }
}
.doc-content .page-title { margin-block: 0 tokens.$space-sm; line-height: 1.2; }
.doc-content .page-description { margin-block: 0 tokens.$space-lg; color: var(--color-text-muted, #4b5563); }
.doc-content .page-body iframe { width: 100%; border: 0; }
Loading
Loading