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

### Added

- **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
(`npm install --save-dev pagefind`): with `storefront.search` left out the site is indexed when the project has it;
`true` makes a build without it stop, `false` turns it off. The 404 page, tag and category pages and a page with
`index: false` are left out. `pd dev` builds no index. `pd build --browser` uses the site's search field once per
viewport and stops when it shows no result. The starter has a search page and a plain, accessible
`components/search`.
- 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.
Expand Down
1 change: 1 addition & 0 deletions docs/guide/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,6 +188,7 @@ in [storefront.md](storefront.md).
| `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.search` | boolean | on when the project has Pagefind | Search: `pd build` indexes every page's own content with Pagefind into `_pd/search/`. `true`: a build without Pagefind stops; `false`: off ([storefront.md](storefront.md#search)) |
| `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
39 changes: 39 additions & 0 deletions docs/guide/storefront.md
Original file line number Diff line number Diff line change
Expand Up @@ -747,6 +747,40 @@ belong to the skin.

---

### Search

`pd build` indexes the site with [Pagefind](https://pagefind.app/) and writes the index into it, at `_pd/search/`.
There is no server: search runs in the reader's browser, on GitHub Pages and under a path as well.

```bash
npm install --save-dev pagefind
```

- **Pagefind is the project's own**, as Playwright is for `--browser`; Pattern Dump does not depend on it.
`storefront.search` left out: the site is indexed when the project has Pagefind, and built without search, with no
message, when it has none. `true` asks for it: without Pagefind the build stops before anything is built, naming the
install. `false` turns it off.
- **What is indexed is each page's own content:** its markdown and the components it places, with its title. The
layout's markup is not: header, footer, navigation, listings and related pages (other pages' titles and teasers)
and the copy buttons never match. The written pages are unchanged; they carry no Pagefind attributes.
- **Left out:** the 404 page (it has no address of its own); tag and category pages and their indexes (their text is
other pages' labels and teasers, so each page would match twice; the filters do their job); redirect stubs; and a
page with `index: false`, which keeps it out of site search as well as search engines. `storefront.index: false`
does not: a site kept out of search engines still has its own search. Drafts and scheduled pages are never built.
- **Filters:** `section`, the label of the page's collection (the folder that lists it, by its index page's title; a
page at the top has none), `tag` and `category`, by their labels. **Meta:** `title`, and `teaser` (the listing
teaser: the description, else the first paragraph).
- **The search UI is the skin's:** a component that loads `<base path>_pd/search/pagefind.js` (the site's path is in
`<meta name="pd-base-path">`) and uses Pagefind's JavaScript API. Pagefind's own UIs are not written.
- **`pd dev` has no index,** so a save stays as fast as it is: search works on the built site, and `pd dev` says so
when it starts.

The starter (`pd init --storefront`) has a search page with a plain, accessible component, `components/search`: a
`<search>` landmark with a labelled field and a button, a status line screen readers announce (such as
`2 results for "grid".`), and the results as a list of links with their section and the passage that matched. It searches as you
type, keeps the words in the address (`?q=`), and adds a section list once the index is loaded. Without JavaScript
the form still submits and the page says that search needs JavaScript.

## Images

Every raster image on a page (JPEG, PNG, GIF, WebP and the like) is served as WebP variants, a few widths of it,
Expand Down Expand Up @@ -1129,6 +1163,11 @@ npm install --save-dev playwright
npx playwright install chromium
```

- **Search:** with a search index, on the first page that has a search field (`input[type="search"]`), at each
viewport, a word of an indexed page's title is typed and sent. A page that shows no result within 5 seconds stops
the build; the page showing its results is checked with axe again. Once per viewport, since the search component is
the skin's, the same on every page.

A page is fetched from the build itself, never from the network: images and fonts from other sites are not loaded.

**The workbench on the storefront's host.** One host can serve both: the website at its root and the
Expand Down
118 changes: 118 additions & 0 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@
"handlebars": "^4.7.8",
"husky": "^9.1.7",
"nx": "^19.0.0",
"pagefind": "^1.6.0",
"postcss": "^8.4.0",
"sass": "^1.77.0",
"stylelint": "^17.12.0",
Expand Down
3 changes: 2 additions & 1 deletion packages/cli/src/init/run.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,8 @@ describe("runInit", () => {
expect(await runInit(init(join(root, "ds"), { storefront: true, install: false, git: false }), io)).toBe(0);
expect(asked).not.toContain("Include a website (storefront)");
expect(existsSync(join(root, "ds", ".github", "workflows", "pages.yml"))).toBe(true);
expect(logs.at(-1)).toBe(" npm run dev # the website at http://live.localhost:4000/, the workbench at http://pd.localhost:4000/");
expect(logs.slice(-2)).toEqual([" npm run dev # the website at http://live.localhost:4000/, the workbench at http://pd.localhost:4000/",
" npm install --save-dev pagefind # for the site's search: pd build then writes its index"]);
});

it("--yes leaves the website out, and the next steps name the workbench only", async () => {
Expand Down
1 change: 1 addition & 0 deletions packages/cli/src/init/run.ts
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,7 @@ export async function runInit(cmd: InitCommand, io: InitIO): Promise<number> {
const dev = `npm run ${JSON.parse(plan.packageJson.content).scripts["pd:dev"] ? "pd:dev" : "dev"}`;
if (storefront) {
io.log(` ${dev} # the website at http://live.localhost:4000/, the workbench at http://pd.localhost:4000/`);
io.log(" npm install --save-dev pagefind # for the site's search: pd build then writes its index");
} else {
io.log(` ${dev} # http://localhost:4000`);
}
Expand Down
8 changes: 7 additions & 1 deletion packages/cli/src/init/starter.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ 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/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"],
["layouts/tag", "ok"], ["layouts/tags", "ok"], ["partials/base", "ok"], ["partials/head", "ok"],
["views/compact", "ok"], ["views/featured", "ok"], ["views/grid", "ok"], ["views/list", "ok"]]);
Expand Down Expand Up @@ -207,6 +207,12 @@ 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.
// 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).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>`);
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>`);
Expand Down
2 changes: 2 additions & 0 deletions packages/cli/templates/storefront-fills/config.txt
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@
categories: {
notes: { label: "Notes", description: "Short articles about this site" },
},
// Search: pd build indexes every page with Pagefind once the project has it (npm install --save-dev pagefind);
// components/search is the search field. search: true makes a build without Pagefind stop, false turns it off.
site: { title: __PD_BRAND_JSON__, footer: "Made with Pattern Dump." },
},
build: { basePath: "/workbench/" },
Expand Down
2 changes: 2 additions & 0 deletions packages/cli/templates/storefront/pages/about.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,7 @@ workbench shows each part of it:
- `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
- `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`)

The site's name and footer are `storefront.site` in `pattern-dump.config.ts`.
7 changes: 7 additions & 0 deletions packages/cli/templates/storefront/pages/search.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
title: Search
description: Search every page of this site.
order: 3
---

<pd-components-search></pd-components-search>
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<search class="search" data-search>
<form class="search-form" method="get">
<label class="search-label" for="search-field">{{#if label}}{{label}}{{else}}Search this site{{/if}}</label>
<div class="search-row">
<input class="search-field" id="search-field" type="search" name="q" autocomplete="off" spellcheck="false">
<button class="search-button" type="submit">Search</button>
</div>
</form>
<p class="search-status" role="status" data-search-status></p>
<ol class="search-results" data-search-results></ol>
<noscript><p class="search-status">Search needs JavaScript. Every page is in the navigation above.</p></noscript>
</search>
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
"label": "Search this site"
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
---
title: Search
requireScript: site-search
---

The site's search, on the search page (`pages/search.md`):

```md
<pd-components-search></pd-components-search>
```

`pd build` indexes every page's own content with [Pagefind](https://pagefind.app/) when the project has it
(`npm install --save-dev pagefind`), and writes the index into the site at `_pd/search/`. The script
(`src/scripts/site-search.ts`) loads it from there and searches in the browser:

- It searches as you type and when the form is sent, and keeps the words in the address (`?q=`), so a search can be
linked and the Back button returns to it.
- Each result is a link with its title, its section and the passage that matched.
- The status line says how many results there are, and screen readers announce it.
- A section list narrows the results, once the index is loaded.

Without JavaScript the form still works as a form and the page says that search needs JavaScript. In `npm run dev`
there is no index, so the status line says that search works on the built site.
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Search",
"description": "The site's search: a field, a status line and the results. On a page: <pd-components-search></pd-components-search>.",
"type": "object",
"properties": {
"label": { "type": "string", "description": "The field's label", "default": "Search this site" }
}
}
Loading
Loading