Add Pagefind weight frontmatter

.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.

docs/src/content/docs/guides/site-search.mdx

@@ -42,6 +42,44 @@ This text will be hidden from search.
 </div>
 ```
 
+## 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.
+
+<div data-pagefind-weight="5.0">
+
+This text will be ranked higher in search results.
+
+</div>
+```
+
 ## Alternative search providers
 
 ### Algolia DocSearch

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`  

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',
+		}),
+	],
+});

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"
+  }
+}

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() }),
+};

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.

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.

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.

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');
+});

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;
 ---
 
 <html
@@ -85,6 +90,7 @@ const pagefindEnabled =
 				<PageSidebar slot="right-sidebar" {...Astro.props} />
 				<main
 					data-pagefind-body={pagefindEnabled}
+					data-pagefind-weight={pagefindWeight}
 					lang={Astro.props.entryMeta.lang}
 					dir={Astro.props.entryMeta.dir}
 				>

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.