From 980e14e254ca02d613da7c3aefb079d16404c8df Mon Sep 17 00:00:00 2001 From: Lorenzo Lewis Date: Thu, 19 Sep 2024 15:10:25 +0200 Subject: [PATCH 1/9] add pagefind weight --- packages/starlight/components/Page.astro | 7 ++++++- packages/starlight/schema.ts | 10 ++++++++-- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/packages/starlight/components/Page.astro b/packages/starlight/components/Page.astro index 0ab90d1bac..bd9f008d3b 100644 --- a/packages/starlight/components/Page.astro +++ b/packages/starlight/components/Page.astro @@ -31,10 +31,14 @@ import '../style/asides.css'; // Important that this is the last import so it can override built-in styles. import 'virtual:starlight/user-css'; +const pagefindConfig = Astro.props.entry.data.pagefind; + const pagefindEnabled = Astro.props.entry.slug !== '404' && !Astro.props.entry.slug.endsWith('/404') && - Astro.props.entry.data.pagefind !== false; + pagefindConfig !== false; + +const pagefindWeight = typeof pagefindConfig === 'object' && pagefindConfig.weight; ---
diff --git a/packages/starlight/schema.ts b/packages/starlight/schema.ts index f4dd175a90..e7ae1297f4 100644 --- a/packages/starlight/schema.ts +++ b/packages/starlight/schema.ts @@ -101,8 +101,14 @@ const StarlightFrontmatterSchema = (context: SchemaContext) => }) .optional(), - /** Pagefind indexing for this page - set to false to disable. */ - pagefind: z.boolean().default(true), + /** + * Pagefind configuration for this page - set to false to disable indexing or set + * as an object with a "weight" key between 0.0 and 10.0 to adjust the ranking where + * a larger number is a higher ranking. + * + * More information about Pagefind weighting: https://pagefind.app/docs/weighting/ + */ + pagefind: z.union([z.boolean(), z.object({ weight: z.number().min(0).max(10) })]).default(true), /** * Indicates that this page is a draft and will not be included in production builds. From f2673135e2f9087ab1a6873d3be7b4aaee9afc48 Mon Sep 17 00:00:00 2001 From: Lorenzo Lewis Date: Thu, 19 Sep 2024 15:10:37 +0200 Subject: [PATCH 2/9] add weight test --- docs/src/content/docs/guides/site-search.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/src/content/docs/guides/site-search.mdx b/docs/src/content/docs/guides/site-search.mdx index 0de34add47..7a5a26c293 100644 --- a/docs/src/content/docs/guides/site-search.mdx +++ b/docs/src/content/docs/guides/site-search.mdx @@ -1,6 +1,8 @@ --- title: Site Search description: Learn about Starlight’s built-in site search features and how to customize them. +pagefind: + weight: 7.5 --- import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; From 87aefc7feb3dee90ac8b6f3436a5a5c8ab588010 Mon Sep 17 00:00:00 2001 From: Lorenzo Lewis Date: Thu, 19 Sep 2024 15:12:06 +0200 Subject: [PATCH 3/9] add additional check --- packages/starlight/components/Page.astro | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/starlight/components/Page.astro b/packages/starlight/components/Page.astro index bd9f008d3b..b11346149d 100644 --- a/packages/starlight/components/Page.astro +++ b/packages/starlight/components/Page.astro @@ -38,7 +38,8 @@ const pagefindEnabled = !Astro.props.entry.slug.endsWith('/404') && pagefindConfig !== false; -const pagefindWeight = typeof pagefindConfig === 'object' && pagefindConfig.weight; +const pagefindWeight = + pagefindEnabled && typeof pagefindConfig === 'object' && pagefindConfig.weight; --- Date: Thu, 19 Sep 2024 16:21:01 +0200 Subject: [PATCH 4/9] add e2e tests --- .../fixtures/pagefind/astro.config.mjs | 10 +++++++ .../__e2e__/fixtures/pagefind/package.json | 9 ++++++ .../fixtures/pagefind/src/content/config.ts | 6 ++++ .../src/content/docs/custom-weight.mdx | 7 +++++ .../src/content/docs/ignored-page.mdx | 6 ++++ .../pagefind/src/content/docs/pagefind.mdx | 5 ++++ packages/starlight/__e2e__/pagefind.test.ts | 28 +++++++++++++++++++ 7 files changed, 71 insertions(+) create mode 100644 packages/starlight/__e2e__/fixtures/pagefind/astro.config.mjs create mode 100644 packages/starlight/__e2e__/fixtures/pagefind/package.json create mode 100644 packages/starlight/__e2e__/fixtures/pagefind/src/content/config.ts create mode 100644 packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/custom-weight.mdx create mode 100644 packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/ignored-page.mdx create mode 100644 packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/pagefind.mdx create mode 100644 packages/starlight/__e2e__/pagefind.test.ts diff --git a/packages/starlight/__e2e__/fixtures/pagefind/astro.config.mjs b/packages/starlight/__e2e__/fixtures/pagefind/astro.config.mjs new file mode 100644 index 0000000000..c283ef876c --- /dev/null +++ b/packages/starlight/__e2e__/fixtures/pagefind/astro.config.mjs @@ -0,0 +1,10 @@ +import starlight from '@astrojs/starlight'; +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'Pagefind', + }), + ], +}); diff --git a/packages/starlight/__e2e__/fixtures/pagefind/package.json b/packages/starlight/__e2e__/fixtures/pagefind/package.json new file mode 100644 index 0000000000..f8ccab78b9 --- /dev/null +++ b/packages/starlight/__e2e__/fixtures/pagefind/package.json @@ -0,0 +1,9 @@ +{ + "name": "@e2e/pagefind", + "version": "0.0.0", + "private": true, + "dependencies": { + "@astrojs/starlight": "workspace:*", + "astro": "^4.15.3" + } +} diff --git a/packages/starlight/__e2e__/fixtures/pagefind/src/content/config.ts b/packages/starlight/__e2e__/fixtures/pagefind/src/content/config.ts new file mode 100644 index 0000000000..45f60b0154 --- /dev/null +++ b/packages/starlight/__e2e__/fixtures/pagefind/src/content/config.ts @@ -0,0 +1,6 @@ +import { defineCollection } from 'astro:content'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ schema: docsSchema() }), +}; diff --git a/packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/custom-weight.mdx b/packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/custom-weight.mdx new file mode 100644 index 0000000000..c8fd3e36a9 --- /dev/null +++ b/packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/custom-weight.mdx @@ -0,0 +1,7 @@ +--- +title: Index +pagefind: + weight: 5.5 +--- + +This page has a custom weight of 5.5. \ No newline at end of file diff --git a/packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/ignored-page.mdx b/packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/ignored-page.mdx new file mode 100644 index 0000000000..b4c3282b24 --- /dev/null +++ b/packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/ignored-page.mdx @@ -0,0 +1,6 @@ +--- +title: Index +pagefind: false +--- + +This page will NOT be indexed. \ No newline at end of file diff --git a/packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/pagefind.mdx b/packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/pagefind.mdx new file mode 100644 index 0000000000..a788e39c3f --- /dev/null +++ b/packages/starlight/__e2e__/fixtures/pagefind/src/content/docs/pagefind.mdx @@ -0,0 +1,5 @@ +--- +title: Index +--- + +This is a page that should be indexed with no special weight. \ No newline at end of file diff --git a/packages/starlight/__e2e__/pagefind.test.ts b/packages/starlight/__e2e__/pagefind.test.ts new file mode 100644 index 0000000000..a08a443f26 --- /dev/null +++ b/packages/starlight/__e2e__/pagefind.test.ts @@ -0,0 +1,28 @@ +import { expect, testFactory } from './test-utils'; + +const test = testFactory('./fixtures/pagefind/'); + +test('page has pagefind data attribute', async ({ page, getProdServer }) => { + const starlight = await getProdServer(); + await starlight.goto('/pagefind'); + + const main = page.locator('main'); + await expect(main).toHaveAttribute('data-pagefind-body'); +}); + +test('page has no pagefind data attribute', async ({ page, getProdServer }) => { + const starlight = await getProdServer(); + await starlight.goto('/ignored-page'); + + const main = page.locator('main'); + await expect(main).not.toHaveAttribute('data-pagefind-body'); +}); + +test('page has custom weighting', async ({ page, getProdServer }) => { + const starlight = await getProdServer(); + await starlight.goto('/custom-weight'); + + const main = page.locator('main'); + await expect(main).toHaveAttribute('data-pagefind-body'); + await expect(main).toHaveAttribute('data-pagefind-weight', '5.5'); +}); From b1c6d1a6f0c5c4ab926a7f983afa70fe7807bbf1 Mon Sep 17 00:00:00 2001 From: Lorenzo Lewis Date: Thu, 19 Sep 2024 16:37:12 +0200 Subject: [PATCH 5/9] update lockfile --- pnpm-lock.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index ad10a53cf4..d84ee9b4a0 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -277,6 +277,15 @@ importers: specifier: ^4.15.3 version: 4.15.3(@types/node@18.16.19)(typescript@5.4.5) + packages/starlight/__e2e__/fixtures/pagefind: + dependencies: + '@astrojs/starlight': + specifier: workspace:* + version: link:../../.. + astro: + specifier: ^4.15.3 + version: 4.15.3(@types/node@18.16.19)(typescript@5.4.5) + packages/starlight/__e2e__/fixtures/ssr: dependencies: '@astrojs/node': From 9784394577712fa135939580ed4c182917f29a24 Mon Sep 17 00:00:00 2001 From: Lorenzo Lewis Date: Thu, 19 Sep 2024 16:42:53 +0200 Subject: [PATCH 6/9] add changeset --- .changeset/eighty-zoos-burn.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/eighty-zoos-burn.md diff --git a/.changeset/eighty-zoos-burn.md b/.changeset/eighty-zoos-burn.md new file mode 100644 index 0000000000..646e9dec7c --- /dev/null +++ b/.changeset/eighty-zoos-burn.md @@ -0,0 +1,5 @@ +--- +'@astrojs/starlight': patch +--- + +Adds the `pagefind.weight` frontmatter property for customizing how a page ranks in Pagefind search results. \ No newline at end of file From 8f611d381409a182b0edb8edcfd6ed014fe58566 Mon Sep 17 00:00:00 2001 From: Lorenzo Lewis Date: Thu, 19 Sep 2024 16:43:02 +0200 Subject: [PATCH 7/9] Revert "add weight test" This reverts commit f2673135e2f9087ab1a6873d3be7b4aaee9afc48. --- docs/src/content/docs/guides/site-search.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/src/content/docs/guides/site-search.mdx b/docs/src/content/docs/guides/site-search.mdx index 7a5a26c293..0de34add47 100644 --- a/docs/src/content/docs/guides/site-search.mdx +++ b/docs/src/content/docs/guides/site-search.mdx @@ -1,8 +1,6 @@ --- title: Site Search description: Learn about Starlight’s built-in site search features and how to customize them. -pagefind: - weight: 7.5 --- import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; From 2d7ba3ab29cb53c742bec44179f2ee0903d3b7f1 Mon Sep 17 00:00:00 2001 From: Lorenzo Lewis Date: Thu, 19 Sep 2024 16:59:36 +0200 Subject: [PATCH 8/9] update guide docs --- docs/src/content/docs/guides/site-search.mdx | 38 ++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/src/content/docs/guides/site-search.mdx b/docs/src/content/docs/guides/site-search.mdx index 0de34add47..994dcd328a 100644 --- a/docs/src/content/docs/guides/site-search.mdx +++ b/docs/src/content/docs/guides/site-search.mdx @@ -42,6 +42,44 @@ This text will be hidden from search. ``` +## Adjust ranking in search results + +Pagefind's index ranking can be adjusted using the [`data-pagefind-weight`](https://pagefind.app/docs/weighting/#ranking-content-higher-or-lower) attribute. This can be used to [adjust a whole page](#adjust-whole-page-rank) or [individual sections of a page](#adjust-individual-section-rank). + +Learn more about about how the weight value impacts search results in the [Pagefind Weighting content guide](https://pagefind.app/docs/weighting/). + +### Adjust whole page rank + +To adjust where a page is listed in the Pagefind search results, add the [`pagefind.weight`](/reference/frontmatter/#pagefind) property to the page's frontmatter: + +```md title="src/content/docs/important-doc.md" ins={3,4} +--- +title: Content to hide from search +pagefind: + weight: 2 +--- +``` + +### Adjust individual section rank + +Pagefind will use the [`data-pagefind-weight`](https://pagefind.app/docs/weighting/#ranking-content-higher-or-lower) attribute to adjust the ranking of search results. + +In this example, the + +```md title="src/content/docs/custom-weighted-page.md" ins="data-pagefind-weight=\"5.0\"" +--- +title: Custom Weighted Page +--- + +This text will be ranked normally. + +
+ +This text will be ranked higher in search results. + +
+``` + ## Alternative search providers ### Algolia DocSearch From 820161be493474171c9902c724fa280e9ca40be7 Mon Sep 17 00:00:00 2001 From: Lorenzo Lewis Date: Thu, 19 Sep 2024 17:06:55 +0200 Subject: [PATCH 9/9] update references guide --- .../src/content/docs/reference/frontmatter.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index 75b564442b..a39795cf26 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -255,10 +255,12 @@ next: false ### `pagefind` -**type:** `boolean` +**type:** `boolean | { weight: number; }` **default:** `true` -Set whether this page should be included in the [Pagefind](https://pagefind.app/) search index. Set to `false` to exclude a page from search results: +Set the weighting of a page in the [Pagefind](https://pagefind.app/) search index or whether the page should be included. + +Set to `false` to exclude a page from search results: ```md --- @@ -268,6 +270,19 @@ pagefind: false --- ``` +Set to `pagefind.weight` with a number between 0 and 10 (inclusive) to adjust the ranking a page in search results: + +```md +--- +# src/content/docs/example.md +# Adjust the ranking of a page +pagefind: + weight: 4.0 +--- +``` + +Learn more about about how the weight value impacts search results in the [Pagefind Weighting content guide](https://pagefind.app/docs/weighting/). + ### `draft` **type:** `boolean`