From eba93eac795a285d26efc5e26b64941ba9f8ceb7 Mon Sep 17 00:00:00 2001
From: Luke Taylor <luke@deentaylor.com>
Date: Wed, 28 Jan 2026 16:45:50 -0500
Subject: [PATCH 1/5] Allow passing user options to pagefind.createIndex

---
 packages/starlight/components/Search.astro  |  3 ++-
 packages/starlight/integrations/pagefind.ts |  3 ++-
 packages/starlight/schemas/pagefind.ts      | 18 ++++++++++++++++++
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/packages/starlight/components/Search.astro b/packages/starlight/components/Search.astro
index d8c80d82699..0750d558138 100644
--- a/packages/starlight/components/Search.astro
+++ b/packages/starlight/components/Search.astro
@@ -75,6 +75,7 @@ if (project.trailingSlash === 'never') dataAttributes['data-strip-trailing-slash
 
 <script>
 	import { pagefindUserConfig } from 'virtual:starlight/pagefind-config';
+	const { index: _, ...pagefindClientConfig } = pagefindUserConfig;
 
 	class SiteSearch extends HTMLElement {
 		constructor() {
@@ -139,7 +140,7 @@ if (project.trailingSlash === 'never') dataAttributes['data-strip-trailing-slash
 					// @ts-expect-error — Missing types for @pagefind/default-ui package.
 					const { PagefindUI } = await import('@pagefind/default-ui');
 					new PagefindUI({
-						...pagefindUserConfig,
+						...pagefindClientConfig,
 						element: '#starlight__search',
 						baseUrl: import.meta.env.BASE_URL,
 						bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/pagefind/',
diff --git a/packages/starlight/integrations/pagefind.ts b/packages/starlight/integrations/pagefind.ts
index ca271bb2f54..4334834d181 100644
--- a/packages/starlight/integrations/pagefind.ts
+++ b/packages/starlight/integrations/pagefind.ts
@@ -1,6 +1,7 @@
 import type { HookParameters } from 'astro';
 import { fileURLToPath } from 'node:url';
 import * as pagefind from 'pagefind';
+import { pagefindUserConfig } from 'virtual:starlight/pagefind-config';
 
 /** Run Pagefind to generate search index files based on the build output directory. */
 export async function starlightPagefind({
@@ -14,7 +15,7 @@ export async function starlightPagefind({
 		const now = performance.now();
 		logger.info('Building search index with Pagefind...');
 
-		const newIndexResponse = await pagefind.createIndex();
+		const newIndexResponse = await pagefind.createIndex(pagefindUserConfig.index);
 
 		const { index } = assertPagefindResponse<pagefind.NewIndexResponse>(newIndexResponse, options);
 
diff --git a/packages/starlight/schemas/pagefind.ts b/packages/starlight/schemas/pagefind.ts
index 2f3e1fc2442..29c08903253 100644
--- a/packages/starlight/schemas/pagefind.ts
+++ b/packages/starlight/schemas/pagefind.ts
@@ -71,6 +71,22 @@ const pagefindIndexOptionsSchema = z.object({
 	ranking: pagefindRankingWeightsSchema.default({}),
 });
 
+const pagefindIndexSchema = z
+	.object({
+		rootSelector: z.string().optional(),
+		excludeSelectors: z.array(z.string()).optional(),
+		forceLanguage: z.string().optional(),
+		// verbose, logfile omitted as they don’t affect the output index
+		// keepIndexUrl omitted for framework convention
+	})
+	// convert value-optional types to strictly property-optional types to satisfy exactOptionalPropertyTypes when passing to pagefind
+	// TODO: once zod>=4.3.0 is available we can use .exactOptional() instead, and remove this
+	.transform(({ rootSelector, excludeSelectors, forceLanguage }) => ({
+		...(rootSelector ? { rootSelector } : {}),
+		...(excludeSelectors ? { excludeSelectors } : {}),
+		...(forceLanguage ? { forceLanguage } : {}),
+	}));
+
 const pagefindSchema = z.object({
 	/**
 	 * Configure how search results from the current website are weighted by Pagefind
@@ -103,6 +119,8 @@ const pagefindSchema = z.object({
 			})
 		)
 		.optional(),
+
+	index: pagefindIndexSchema.optional(),
 });
 
 export const PagefindConfigSchema = () => pagefindSchema;

From 12201465606a6d39c80f0446c2d91281ac0b8887 Mon Sep 17 00:00:00 2001
From: Luke Taylor <luke@deentaylor.com>
Date: Wed, 28 Jan 2026 16:52:15 -0500
Subject: [PATCH 2/5] Update documentation

---
 docs/src/content/docs/reference/configuration.mdx | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
index 05f980d8878..3d1a53605a2 100644
--- a/docs/src/content/docs/reference/configuration.mdx
+++ b/docs/src/content/docs/reference/configuration.mdx
@@ -503,6 +503,7 @@ Set `pagefind` to an object to configure the Pagefind search client:
 
 - See [“Customize Pagefind's result ranking”](https://pagefind.app/docs/ranking/) in the Pagefind documentation for more details about using the `pagefind.ranking` option to control how search result ranking is calculated
 - See [“Searching multiple sites”](https://pagefind.app/docs/multisite/) in the Pagefind documentation for more details about using the `pagefind.mergeIndex` option to control how to search across multiple sites
+- See [“pagefind.createIndex”](https://pagefind.app/docs/node-api/#pagefindcreateindex) in the Pagefind documentation for more details about using the `pagefind.index` option to customize what content is indexed.
 
 #### `PagefindOptions`
 
@@ -529,6 +530,10 @@ interface PagefindOptions {
 			termSimilarity?: number;
 		};
 	}>;
+	index?: Pick<
+		pagefind.PagefindServiceConfig,
+		'rootSelector' | 'excludeSelectors' | 'forceLanguage'
+	>;
 }
 ```
 

From 24b07510b243a6c9e774127681ddcd662b1e87fe Mon Sep 17 00:00:00 2001
From: Luke Taylor <luke@deentaylor.com>
Date: Wed, 28 Jan 2026 17:01:41 -0500
Subject: [PATCH 3/5] changeset

---
 .changeset/hip-emus-punch.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/hip-emus-punch.md

diff --git a/.changeset/hip-emus-punch.md b/.changeset/hip-emus-punch.md
new file mode 100644
index 00000000000..48437412ee5
--- /dev/null
+++ b/.changeset/hip-emus-punch.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Allow passing user options to pagefind.createIndex

From 3a6c667efb6b1ef6b89c972fef34f931a8495974 Mon Sep 17 00:00:00 2001
From: Luke Taylor <luke@deentaylor.com>
Date: Wed, 28 Jan 2026 17:33:26 -0500
Subject: [PATCH 4/5] fix passing user config to pagefind integration

---
 packages/starlight/index.ts                 | 2 +-
 packages/starlight/integrations/pagefind.ts | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index 4af0f925548..50f0fde45b2 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/index.ts
@@ -148,7 +148,7 @@ export default function StarlightIntegration(
 
 			'astro:build:done': async (options) => {
 				if (!userConfig.pagefind) return;
-				return starlightPagefind(options);
+				return starlightPagefind(options, userConfig.pagefind);
 			},
 		},
 	};
diff --git a/packages/starlight/integrations/pagefind.ts b/packages/starlight/integrations/pagefind.ts
index 4334834d181..748b035988a 100644
--- a/packages/starlight/integrations/pagefind.ts
+++ b/packages/starlight/integrations/pagefind.ts
@@ -1,13 +1,13 @@
 import type { HookParameters } from 'astro';
 import { fileURLToPath } from 'node:url';
 import * as pagefind from 'pagefind';
-import { pagefindUserConfig } from 'virtual:starlight/pagefind-config';
+import type { StarlightConfig } from '../types';
 
 /** Run Pagefind to generate search index files based on the build output directory. */
 export async function starlightPagefind({
 	dir,
 	logger: starlightLogger,
-}: PagefindIntegrationOptions) {
+}: PagefindIntegrationOptions, userConfig: Extract<StarlightConfig['pagefind'], object>) {
 	const logger = starlightLogger.fork('starlight:pagefind');
 	const options = { dir, logger };
 
@@ -15,7 +15,7 @@ export async function starlightPagefind({
 		const now = performance.now();
 		logger.info('Building search index with Pagefind...');
 
-		const newIndexResponse = await pagefind.createIndex(pagefindUserConfig.index);
+		const newIndexResponse = await pagefind.createIndex(userConfig.index);
 
 		const { index } = assertPagefindResponse<pagefind.NewIndexResponse>(newIndexResponse, options);
 

From 697254dd5b8bf3ea6d167fb9f045b8b13aeb56dd Mon Sep 17 00:00:00 2001
From: Luke Taylor <luke@deentaylor.com>
Date: Thu, 29 Jan 2026 12:47:20 -0500
Subject: [PATCH 5/5] type fix

---
 packages/starlight/__tests__/basics/pagefind.test.ts | 4 ++--
 packages/starlight/integrations/pagefind.ts          | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/starlight/__tests__/basics/pagefind.test.ts b/packages/starlight/__tests__/basics/pagefind.test.ts
index 3e4ac3a2e85..572604800c4 100644
--- a/packages/starlight/__tests__/basics/pagefind.test.ts
+++ b/packages/starlight/__tests__/basics/pagefind.test.ts
@@ -15,7 +15,7 @@ async function runStarlightPagefind(outputDir: URL) {
 
 	vi.mocked(pagefind.createIndex).mockResolvedValue({ index, errors: [] });
 
-	await starlightPagefind({ dir: outputDir, logger: new TestAstroIntegrationLogger() });
+	await starlightPagefind({ dir: outputDir, logger: new TestAstroIntegrationLogger() }, {});
 
 	return index;
 }
@@ -61,7 +61,7 @@ test('logs Pagefind errors and closes Pagefind', async () => {
 		errors: [errorMessage],
 	});
 
-	await expect(starlightPagefind({ dir: outputDir, logger })).rejects.toThrow();
+	await expect(starlightPagefind({ dir: outputDir, logger }, {})).rejects.toThrow();
 
 	expect(logger.error).toHaveBeenCalledWith(`Pagefind error: ${errorMessage}`);
 
diff --git a/packages/starlight/integrations/pagefind.ts b/packages/starlight/integrations/pagefind.ts
index 748b035988a..f38b63fe877 100644
--- a/packages/starlight/integrations/pagefind.ts
+++ b/packages/starlight/integrations/pagefind.ts
@@ -4,10 +4,10 @@ import * as pagefind from 'pagefind';
 import type { StarlightConfig } from '../types';
 
 /** Run Pagefind to generate search index files based on the build output directory. */
-export async function starlightPagefind({
-	dir,
-	logger: starlightLogger,
-}: PagefindIntegrationOptions, userConfig: Extract<StarlightConfig['pagefind'], object>) {
+export async function starlightPagefind(
+	{ dir, logger: starlightLogger }: PagefindIntegrationOptions,
+	userConfig: Pick<Extract<StarlightConfig['pagefind'], object>, 'index'>
+) {
 	const logger = starlightLogger.fork('starlight:pagefind');
 	const options = { dir, logger };