Allow passing user options to pagefind.createIndex

.changeset/hip-emus-punch.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Allow passing user options to pagefind.createIndex

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

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}`);
 

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/',

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

packages/starlight/integrations/pagefind.ts

@@ -1,20 +1,21 @@
 import type { HookParameters } from 'astro';
 import { fileURLToPath } from 'node:url';
 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) {
+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 };
 
 	try {
 		const now = performance.now();
 		logger.info('Building search index with Pagefind...');
 
-		const newIndexResponse = await pagefind.createIndex();
+		const newIndexResponse = await pagefind.createIndex(userConfig.index);
 
 		const { index } = assertPagefindResponse<pagefind.NewIndexResponse>(newIndexResponse, options);
 

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;