diff --git a/CHANGELOG.md b/CHANGELOG.md index 625bfdc..64577c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index fbdf50c..cf1b6bf 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -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//` 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 diff --git a/docs/guide/storefront.md b/docs/guide/storefront.md index 2910666..5ebfd5d 100644 --- a/docs/guide/storefront.md +++ b/docs/guide/storefront.md @@ -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 `_pd/search/pagefind.js` (the site's path is in + ``) 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 +`` 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, @@ -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 diff --git a/package-lock.json b/package-lock.json index 4e12f8c..a17d6cd 100644 --- a/package-lock.json +++ b/package-lock.json @@ -39,6 +39,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", @@ -2363,6 +2364,104 @@ "node": ">= 10" } }, + "node_modules/@pagefind/darwin-arm64": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@pagefind/darwin-arm64/-/darwin-arm64-1.6.0.tgz", + "integrity": "sha512-611gl64aqN12UcMyKPtZ8+vRWBKlJFSh2JgO8uScxa1Eyjo1dXz9r4wZuRno0yCUE/KN0FauEoKZ3KEwUYHCCg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@pagefind/darwin-x64": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@pagefind/darwin-x64/-/darwin-x64-1.6.0.tgz", + "integrity": "sha512-rd3ZbtuxyYqjASKZAPuIV7eeQQHJ7VYpoNKKG8CvglaD3g30eT5Nb7XGNLYwVReBsCccpkURwrGwWjSwr8nyQQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@pagefind/freebsd-x64": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@pagefind/freebsd-x64/-/freebsd-x64-1.6.0.tgz", + "integrity": "sha512-d+sXqsaThszmPWGVDSRKqIz9GpZcj/bAksNZfg19asSxU0ogNPOMND4kV4giQvOjPFMsltUFf6hQJfoHQ6+hSQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@pagefind/linux-arm64": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@pagefind/linux-arm64/-/linux-arm64-1.6.0.tgz", + "integrity": "sha512-SLB2I+XqCZma8NvIGIH8nyKblgKIxw5PmqsVtofWOKxNHhEtOEsddbqU+hsrNcT3EV0faM6UmKDHVIxcPYq29w==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pagefind/linux-x64": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@pagefind/linux-x64/-/linux-x64-1.6.0.tgz", + "integrity": "sha512-IbMSx/+Vr/Xk0TTBlLkjgK+rvnbOXGmmb2/MKxQu99AR5DsqQoV3NKEA9PQz2tAhuCZjeD5xJBp4w5N5DHIC7Q==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@pagefind/windows-arm64": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@pagefind/windows-arm64/-/windows-arm64-1.6.0.tgz", + "integrity": "sha512-wUrniW3REr7VWJHz6xE6F/p/AQgHDFpGZiY9sbWT71KfEijDE5Jnc37V8zc7cilV9h/QkwJGXoEP2+ZLwDmhtw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@pagefind/windows-x64": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@pagefind/windows-x64/-/windows-x64-1.6.0.tgz", + "integrity": "sha512-cUA2+yXfbymdJllyMjY5YTBwuOgh0/H53Pn5fYKjDnDjk154Ft4U5RVj3TenWySPL/jG6zJfARUWSlyUyXHlZw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, "node_modules/@parcel/watcher": { "version": "2.5.6", "resolved": "https://registry.npmjs.org/@parcel/watcher/-/watcher-2.5.6.tgz", @@ -7325,6 +7424,25 @@ "resolved": "package-bench", "link": true }, + "node_modules/pagefind": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/pagefind/-/pagefind-1.6.0.tgz", + "integrity": "sha512-yeOd9EA0TUE1PUfbQIluBxzPadBG5/0BV48FAxwMVLkhZcOvwCz6TX4/a/Ofz97pF9/FwwT7CVbTC97BfmI+LQ==", + "dev": true, + "license": "MIT", + "bin": { + "pagefind": "lib/runner/bin.cjs" + }, + "optionalDependencies": { + "@pagefind/darwin-arm64": "1.6.0", + "@pagefind/darwin-x64": "1.6.0", + "@pagefind/freebsd-x64": "1.6.0", + "@pagefind/linux-arm64": "1.6.0", + "@pagefind/linux-x64": "1.6.0", + "@pagefind/windows-arm64": "1.6.0", + "@pagefind/windows-x64": "1.6.0" + } + }, "node_modules/parent-module": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz", diff --git a/package.json b/package.json index 896aaff..c57d798 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/packages/cli/src/init/run.spec.ts b/packages/cli/src/init/run.spec.ts index 87dcf33..5fc062b 100644 --- a/packages/cli/src/init/run.spec.ts +++ b/packages/cli/src/init/run.spec.ts @@ -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 () => { diff --git a/packages/cli/src/init/run.ts b/packages/cli/src/init/run.ts index d6678f6..d983b31 100644 --- a/packages/cli/src/init/run.ts +++ b/packages/cli/src/init/run.ts @@ -136,6 +136,7 @@ export async function runInit(cmd: InitCommand, io: InitIO): Promise { 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`); } diff --git a/packages/cli/src/init/starter.spec.ts b/packages/cli/src/init/starter.spec.ts index 21243c8..469216c 100644 --- a/packages/cli/src/init/starter.spec.ts +++ b/packages/cli/src/init/starter.spec.ts @@ -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"]]); @@ -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(``); // 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(/\s*
\s*