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 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 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` 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'); +}); diff --git a/packages/starlight/components/Page.astro b/packages/starlight/components/Page.astro index 0ab90d1bac..b11346149d 100644 --- a/packages/starlight/components/Page.astro +++ b/packages/starlight/components/Page.astro @@ -31,10 +31,15 @@ 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 = + pagefindEnabled && 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. 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':